3.11.1The README is your project's front door
A README is the file at the top of your project that answers the first questions anyone asks: what is this, why does it exist, and how do I run it. It is the first file a teammate opens, and the first the agent reads to orient itself.
Keep it to what a newcomer needs on day one: a one-line description, the setup steps, how to start the app, and where the key docs live. Kept current, it takes someone from clone to running without asking you.
3.11.2Architecture docs and ADRs record your choices
An ADR, an architecture decision record, captures one decision and the reasoning behind it: short, dated, written the moment you choose. Six months on, nobody remembers why you picked Postgres over a document store, and the ADR is the answer.
Write one when a choice is hard to reverse or easy to question later. The format is deliberately small:
3.11.3The CHANGELOG tracks what changed
A CHANGELOG is a running, human-readable list of notable changes, newest at the top, grouped by version. It answers "what is different since last time" without anyone reading the git history. The widely used convention is Keep a Changelog.
You do not write it from scratch: if your commit messages follow a convention like Conventional Commits, the agent drafts it from them and you edit for clarity.
3.11.4Comments record why, never what
The code already says what it does, and your agent can explain any line on demand. What neither can recover is why it is that way, and that is the only thing worth writing in a comment.
This matters more here than in a codebase you typed yourself. You did not make most of these decisions line by line, so in three months the reasoning is gone unless someone wrote it down.
| Wrong | Right |
|---|---|
// loop through the users | // batches of 50: the payment provider rate-limits above that |
Reach for one when a future reader would reasonably ask "why is this here" or "why not the obvious way". A workaround for someone else's bug, a limit you hit, a rule that came from the business rather than the code.
Then adjust for who is actually reading. Your main reader is no longer a colleague who was in the room when you decided things. It is an agent that opens the file cold, every session, knowing nothing that was not written down.
That drops the bar for what earns a comment, a long way. In a codebase built this way, comments running close to half the file is normal rather than excessive. Three things earn one:
- Why it is like this, the workaround, the limit, the business rule.
- What must stay true, the condition the code below quietly depends on.
- What not to do here, the obvious-looking change that would break something elsewhere.
What still earns nothing is narration. // loop through the users helps no reader, human or otherwise, and your agent will generate it by the hundred if you let it.
3.11.5Draw the architecture as a diagram
The mind map you started this book with, the pieces and how they talk, belongs in the repo as a picture. A mermaid diagram is that picture written as plain text, so it renders on GitHub and in most editors and sits beside these docs. Have your agent draw your architecture as a few nodes:
A newcomer grasps the shape at a glance, and your agent gets a map instead of a page of prose.
3.11.6Your agent reads all of this before it builds
These files are not paperwork for humans alone. Your agent reads the README to orient, the diagram to see the shape, the ADRs to respect decisions you made, and the CHANGELOG to see where things stand. Stale docs mislead it exactly as they mislead a person.
That is the payoff of this whole part: a documented architecture is a system the agent can hold in its head and build against. It will not stay clean on its own; code decays as it grows, so a later part turns continuous cleanup into a habit. This prompt gives you the starter set:
Do this now: paste the prompt, name your project and one real decision you made, and let your agent write the starter README, ADR, and CHANGELOG.
