Series: "Writing High-Quality Code with AI: AI Werewolf Development Record." This article corresponds to version v1.3 → v1.4.1.

Preface

The previous two articles addressed two issues: ensuring that everything AI says is accurate and that the rules run on the server. By this point, the product was already playable, so I started adding features.

Then I discovered that it wasn't the code that was collapsing—it was the "requirements" that were starting to fall apart.

This article discusses SDD (Spec-Driven Development): what it is, why it can cure this problem, and where its boundaries lie.

Intro: All I Said Was "Add a Guard"

I remember clearly that day I wanted to add a new role. My exact words were roughly: "Add a Guard who can protect one person at night."

AI gave me a very complete implementation: role definition, night behavior, the resolution order with the Witch's antidote, UI prompt text, and even a rule—"the Guard cannot protect the same person two nights in a row."

This rule is correct (that's indeed how Werewolf is played), but I had never said it.

That afternoon it also did two other things:

1. I asked it to fix the speech bubbles on the match page, and it conveniently changed the field names on the settlement page as well, causing the settlement page to go blank;

2. When I started a new conversation the next day to continue, it didn't know the project already had a RoleBehavior registry and rewrote a version using if-else.

Three things, the same root cause: it doesn't know where the boundaries are, so it guesses using "the most similar way of writing."

Problem: AI's "urge to complete"

Large models are "completion machines." You give them half a sentence, and they want to give you a complete paragraph. This is an advantage when writing copy, but a disaster when writing code—

Three symptoms, essentially insufficient context plus unclear boundaries. And these two things happen to both be solvable through "documentation."

Cause of the problem: What is SDD

Figure: The difference between the two approaches is not "how fast you write," but where the rework lands. In the upper figure, you start writing with one sentence, the requirements are completed by AI, problems only surface in the code, and going back to the starting point means changing a bunch of files; in the lower figure, you write down the spec and acceptance scenarios first, rework happens in the document, and changing one sentence is enough.

One-sentence definition

SDD = write the spec first, then let AI implement according to the spec.

It's not "writing documentation for the boss to read," but turning "what you want" into something AI can read and accept. Once the spec is written, the scope of AI's output is boxed in.

The difference from "just letting AI write"

Advantages: three "saves"

1. Saves explanation: when starting a new conversation, AI reads AGENTS.md + spec.md and knows the rules, so I don't have to re-explain the project.

2. Saves rework: changing one sentence at the requirements stage is much cheaper than changing ten files at the code stage.

3. Saves disputes: the acceptance criteria are written there, and "whether it's done" doesn't depend on feelings.

What is AGENTS.md

If the spec is "what this version needs to do," then AGENTS.md is "how to work in this project." It is read by all coding Agents (Claude Code, WorkBuddy, CodeBuddy, Codex, and Cursor all recognize this filename).

In my project it is 185 lines, and the first four sections look like this:

## 2. Four red lines (violation means rework)

Analysis: These four are not "suggestions," but "violation means rework." The first two are exactly the lessons learned in articles 1 and 2—I solidified them into red lines, so that in every subsequent conversation, AI will read them first.

This is the most practical side of SDD: write the pits you've fallen into as rules, and you won't fall into them a second time.

Solution: Three steps to set up the spec system

Step 1: Integrate spec-kit

Step 2: Write the PRD in an "acceptable" form

My PRD is not prose; it's a series of tables with statuses. For example, the role library table:

That last row is very important: it honestly says "not implemented," rather than pretending it's done. Article 8 will mention that this honesty later saved me once—reviewers saw that "Dream Weaver" was gray in the role list; if the PRD had said "completed," that would have been a fatal flaw.

Step 3: What a good requirement looks like

This is the thing I most want you to take away from this article. Compare:

Counterexample (what I said on the first day): Add a Guard role who can protect one person at night.

Good example (how it's written in spec.md):

Guard

Analysis: The difference lies in three points—

1. Boundaries: "cannot protect the same person two nights in a row" is written in the requirement, so AI won't "help you complete it";

2. Exceptions: immune to wolf kill but not to poison—counterintuitive places like this must be written down, otherwise AI will definitely write according to intuition;

3. Acceptance: two executable scenarios are given. "Whether it's done" becomes judgeable, rather than "it looks done to me."

I later discovered that the act of writing acceptance scenarios itself can uncover half of the requirement holes in advance. When writing "immune to poison or not," I realized that I myself hadn't thought it through clearly.

Step 4: How the three-piece spec set works together

My approach is: keep spec.md long-term (it is the source of truth for requirements), and delete plan.md and tasks.md once done—their value lies in the "process," not in "archiving." Keeping them only lets them gather dust, expire, and then mislead the next AI.

Effect: Rework moved from code to documents

Three observable changes:

The most direct effect was the "Guard" requirement. Originally when I said "add a Guard," it added two rules I didn't ask for; after writing it as a spec, boundaries, exceptions, and acceptance were all on paper:

Guard: can protect one person each night, cannot protect the same person two nights in a row; the protected person is immune to wolf kill that night, but not immune to the Witch's poison; acceptance: construct "Guard protects A + wolf kills A" and A survives; construct "Guard protects A + Witch poisons A" and A dies.

After this was written, it never "freely improvised" again.

Figure: Game setup configuration page (the stable form of v1.5). Player count, roles, and validation rules are all on this table—what it looks like when the spec lands on the interface.

Content summary

References