Lesson 42.1 gave you a one-page feature spec: what one piece of work is supposed to do. But a real project is more than one feature. It has users and promises, components and data, interfaces and secrets, a direction and a history of choices. No single page can hold all of that without becoming unreadable.

The answer is not more paperwork. It is a small set of files, each with one job, each readable by humans and AI alike.

A feature spec versus a project set

A feature spec answers: what should this piece do, and how do we check it? It lives close to the work and changes often.

A project set answers: what is this whole system, how does it fit together, and where is the authoritative answer to each kind of question? It changes more slowly, and it is what lets a new person — or a new AI session six months later — orient without interrogating you.

Without a project set, every question becomes archaeology: dig through chats, diffs, and half-remembered decisions. With one, the answer has an address.

The nine files and what each owns

Nine files cover nearly every small-to-medium project. Learn the table, not as a bureaucratic requirement but as a map of responsibilities:

Read the third column carefully. Each "does not replace" is a failure mode someone has lived through. A README.md stuffed with product strategy helps nobody set up the project. An ARCHITECTURE.md that lists every API field goes stale in a week — that detail belongs in API.md. A DECISIONS.md that pastes entire chat transcripts becomes unsearchable; it should record the choice and the reason in five lines.

When an AI asks "where do I put this?", the table is the answer. Authentication behavior goes in SECURITY.md and API.md, not scattered across README.md and a chat. A product-scope change goes in PRD.md first, not directly into code.

Why Markdown: because it diffs

You met this idea in Part II, and it matters more now. These are Markdown files for a practical reason: humans and AI can read them, link between them, review them, and — critically — diff them.

A spec stored in a slide deck, a screenshot, or a chat message cannot be compared across versions. A Markdown spec can. git diff PRD.md shows exactly which requirement changed, when, and alongside which commit. A pull request can show a docs change and a code change side by side, so a reviewer sees whether they agree.

Keep formatting simple: headings, short lists, tables, small code blocks. An agent can then do useful work with plain instructions like "read ARCHITECTURE.md and API.md before proposing a plan" or "list every place that mentions watchlist privacy and tell me if they agree."

One canonical home, everything else links

The most expensive documentation bug is not missing docs. It is three competing docs. Authentication described one way in README.md, another way in API.md, and a third way in a chat from March. Each AI worker picks a different one. The project now has three login behaviors.

The rule: one canonical home per question, links everywhere else.

Decide once where each truth lives — auth rules in SECURITY.md, endpoint shapes in API.md, product scope in PRD.md — and make every other file link there instead of restating it. When the truth changes, you update one file. When an agent needs it, there is exactly one address to read.

If you find two files disagreeing, treat it as a bug with the same seriousness as broken code. Stop, decide which is canonical, update or delete the other, and record the decision.

How much to write, and when

A prototype does not need all nine files on day one. Write to the responsibility you actually carry:

• Prototype with no users yet: README.md (how to run it), PRD.md (who it is for and what v1 includes), ROADMAP.md (what comes next), and a small DECISIONS.md (what you chose and why). That is enough to keep AI work coherent.
• Once user data, APIs, or infrastructure exist: add ARCHITECTURE.md, DATABASE.md, API.md, and SECURITY.md. Responsibility arrived, so the written record must arrive with it.
• Once AI agents work in the repo regularly: add AGENTS.md with read-first lists, allowed scope, must-not-change boundaries, and handoff format.

Depth follows risk. A watchlist feature touching identity and private data deserves real DATABASE.md and SECURITY.md entries. A copy change to an empty-state message does not.

For the research dashboard, the full tree looks like this:

research-dashboard/
  README.md
  PRD.md
  ARCHITECTURE.md
  DATABASE.md
  API.md
  SECURITY.md
  ROADMAP.md
  DECISIONS.md
  AGENTS.md
  src/
  tests/

Nine small files beside the code. Each one earns its place by answering questions workers actually ask.

Exercise: inventory your docs

Create a DOCS-INVENTORY.md for one real project. Make a table with one row per canonical file: does it exist, who owns it, when was it last reviewed, and what is the single most valuable missing file to write next.

Then create the minimal project-document tree: the files you have plus the one missing file that would most reduce guessing for the next AI task. For most early projects that is PRD.md or DECISIONS.md.

Finish line: a DOCS-INVENTORY.md and a minimal project-document tree with named owners.

Verify: ask an AI to answer three questions using only the files: "who is the user?", "where are the auth rules?", "what is the next milestone?" If it cannot answer from the files alone, your inventory has found real gaps.

Common failure: documenting everything at once and maintaining nothing. Recovery: keep four files current rather than nine files stale. Expand the set as the project's responsibilities grow.

Check your understanding

1. What is the difference between a feature spec and the project document set? 2. Name three files from the nine and state what each uniquely owns. 3. Why must these files be Markdown rather than screenshots or chat messages? 4. What goes wrong when two files describe the same behavior differently? 5. Which four files are enough for a prototype, and what triggers adding the rest?

---

You now have addresses for each kind of truth. But addresses alone do not prevent contradiction — decisions change, assumptions break, and quiet guesses harden into code. Lesson 42.3 teaches the decision record and the change protocol that keep the file set honest.