Class 41 gave your project a memory for what changed. Every commit records which files moved and when. But open a diff six weeks later and you face a harder question: what was this change *supposed* to accomplish, for whom, and what had to stay true while it happened?

Git answers "what changed." A specification answers "what it was supposed to do." You need both. Without both, a future human — or a future AI session — can see a line of code but not the decision that made it necessary.

A durable agreement, not a giant document

The word "specification" scares people. It sounds like a 60-page requirements document written before anyone is allowed to build.

Forget that image. For this course, a specification is a durable written agreement about behavior, constraints, and evidence. Durable means it lives in a file, not in a chat that scrolls away. Agreement means a human has read it and stands behind it. Behavior, constraints, and evidence means it answers three questions:

1. What should the user be able to do? 2. What must not happen while they do it? 3. How will we check that it worked?

That is it. A good spec for one feature fits on one page. It does not predict every future detail. It gives every worker — human or AI — a stable answer to: what are we building, for whom, and what must remain true?

Start every spec by completing this sentence:

If you cannot complete that sentence, you are not ready to ask an AI to implement anything. You are ready to clarify.

Why AI needs specs more than humans do

A human teammate carries context in their head. They remember last week's argument about privacy. They notice when a request contradicts an earlier decision. They ask before guessing.

AI workers do none of that reliably, for four reasons you already met in Parts II and IX:

Chats drift. A long conversation accumulates tries, errors, pasted logs, and reversed decisions. The original goal blurs. Part IX called this drift, and it starts small.

Windows fill. A model can only hold so much at once. Earlier instructions fall out of the active window. A spec file can be re-read fresh in every new session.

Models infer differently. Two models — or the same model on two days — will fill the same gap two ways. If the privacy rule lives only in your head, each worker invents its own version.

Parallel workers need the same truth. Two agents on two branches cannot compare memories. They can both read the same SPEC.md.

Think of it this way: Git protects you from an AI that changes too much too fast. A spec protects you from an AI that builds the wrong thing very efficiently.

"Stock app" is not a spec

Take the running example for Part X: the research dashboard. A user chooses a public company, sees a source-linked research brief, saves a private watchlist, and later receives a refreshed brief.

Now compare two requests:

versus a usable v1 spec:

Notice what the second version adds:

• User: a retail investor doing pre-reading, not a professional trader needing real-time data.
• Sources: only approved public-company sources, not the whole internet.
• Brief must: summary, figures, source list with dates.
• Must not: no price predictions stated as fact, no invented sources.
• Watchlist privacy: private to the signed-in user — this one line prevents a whole class of auth bugs.
• Empty and error states: what the user sees when there is nothing saved, or when a source fails.
• Success check: observable behavior, not "it works."

The first request forces the AI to guess all seven. The second lets the AI work inside your actual intent.

A living document with a change rule

A spec is not immutable. Implementation always teaches you something. A source API returns null dates. A privacy rule turns out to be harder than expected. A user flow needs a step you did not foresee.

When that happens, use the plan-change loop from Part IX: stop, state the impact, update the correct source of truth, get approval, then resume. Do not let code silently outrun the written decision.

Concretely: if the code now behaves differently from SPEC.md, one of them is wrong. Either fix the code, or update the spec and record why. What you must not do is shrug and leave two contradicting truths — because the next AI session will pick one at random.

That is the living-document rule: the spec changes when reality demands it, through a visible update, not through quiet code drift.

A starter shape you can reuse

Keep one shape for every feature spec so agents always know where to look:

# Feature: source-linked research brief

## User outcome
[A user] can [do what] so that [outcome].

## In scope / out of scope
- In scope: ...
- Out of scope: ...

## Expected behavior
- When [action], the system [response].

## Constraints and non-negotiables
- Must not ...
- Must always ...

## Edge cases
- Empty state: ...
- Error state: ...

## Acceptance checks
1. ...
2. ...
3. ...

## Open questions and owner
- [Question] — owner: [name], decided by: [date]

Seven headings. Each earns its place. User outcome prevents building for nobody. Scope prevents "while you're at it" sprawl. Expected behavior is what the builder implements. Constraints protect privacy, honesty, and money. Edge cases force you to design the empty and broken states before the AI meets them. Acceptance checks turn "done" into something testable. Open questions admit what you do not know yet — and name who will answer.

Write the shortest version that is still honest. Three acceptance checks beat ten vague ones. One named open question beats a confident guess hidden in code.

Exercise: write a one-page SPEC

Pick one vague request from your own project — "add watchlists," "improve the brief," "add sharing." Before asking any AI to build it, write SPEC.md in the project folder, one page maximum.

It must contain: one user-outcome sentence, an in-scope/out-of-scope boundary, three numbered acceptance checks you could verify in a browser or API response, and at least one open question with an owner.

Finish line: a SPEC.md with a user outcome, boundaries, three acceptance checks, and one owned open question.

Verify: hand the file to an AI and ask: "List anything in this spec a builder would still have to guess." If the list is long, tighten the spec — do not explain it in chat.

Common failure: writing implementation instructions without user behavior — "add a Postgres table with these columns, then a React component." Recovery: start each section from the user's view first, then name the technical pieces. Behavior first, files second.

Check your understanding

1. What does Git record that a spec does not, and vice versa? 2. Why do parallel AI workers need a shared spec file rather than a shared chat? 3. What three questions must every feature spec answer? 4. When code and spec disagree, what are your two legitimate options? 5. Why does a spec need an explicit open-questions section?

---

Next, one feature spec is not enough for a whole project. Lesson 42.2 gives you the small file set that explains the larger system — what each file owns, what it must not become, and where the one canonical answer to each question lives.