Documentation is context
Derived from: my project's document taxonomy and the master index that governs it — a seven-type classification, a register listing every active document, and one rule the whole set answers to.
The AI is only as good as what it knows about your system. If that knowledge lives in your head, or scattered across forty old chats, every session starts from zero and drifts.
So I maintain documentation as the AI's operating environment, not as an afterthought for humans. Procedures for how work gets done, specifications for what the system is, an index that says where everything lives — and the AI reads the index first, every session. Which means every session starts with the accumulated decisions of every session before it.
One rule governs the whole thing: single source of truth. Any fact lives in exactly one place. The moment the same fact lives in two documents they will disagree, and the AI will confidently build on whichever one it read last. There's no such thing as too much documentation — unless the documents compete with each other. Two files claiming the same fact isn't too much documentation, it's wrong documentation, and it's the only kind that actually hurts you.
The template
DOCUMENT TAXONOMY — every document is exactly one of these types.
| Type | Holds | Lives | Lifecycle |
|---------------|-----------------------------------------|------------|-----------|
| Design | How the system is built; interfaces | /docs | Living |
| Specification | What it must do; contracts; workflows | /docs | Living |
| Procedure | Repeatable how-to; checklists | /docs/sop | Living |
| Plan | A specific effort, with an end date | /docs/plans| Delete when done — extract value first |
| Guide | Setup, configuration, tuning, reference | /docs/guides| Living |
| Principles | The rules everything answers to | /docs | Living |
| Backlog | What isn't built yet | /docs | Living |
THE INDEX — one document registers all the others. It contains:
1. Read-first order for someone brand new (human or AI)
2. One row per document: name, location, purpose, when to read it
3. Role-based paths: "if you're doing X, read these three"
4. A common-questions table: question -> which document answers it
5. A deleted-document registry: what was removed, when, and where its
content went. Deleting is part of maintaining a single source of truth,
and the registry is how you delete without losing anything.
6. A version line, so a reader knows how stale it might be.
THE ONE RULE — single source of truth.
Any fact lives in exactly ONE document. Everything else links to it.
Hierarchy when sources disagree:
1. The code / the system itself
2. The dedicated document for that topic
3. Overview documents (which only summarize and link)
Cross-reference, don't copy:
- Bare link: "See [doc] for the run commands."
- Link + one line: "[One sentence]. See [doc] for detail."
- Short summary: 2-3 sentences maximum, then link.
If you're writing more than three sentences of summary, you're duplicating.
Link instead.
MAINTENANCE
- Updating affected documents is the last step of each piece of work,
not deferred cleanup.
- When a fact changes, change it in its one home. If you find yourself
editing it in two places, you've already got the bug.
- Before creating a document, check the index. If something covers the
topic, update that instead.
If you have nothing today, start with one page. Not the taxonomy — one page, called the rules of your product, that answers: what is this, who is it for, what must always be true, what must never happen, and what are we deliberately not doing. Load it into every AI session. That single page will do more for output quality than any prompt engineering, and the structure above is where it grows when one page stops being enough.
Adapt it to your field
This tells your AI to interrogate you rather than answer for you — which is the whole point, and the part a generic template can't do. The Copy button below takes the prompt and the template together, so you can paste once and start talking.
Help me design the documentation set for my project. I'll be feeding it to an AI assistant as context on every session, so it has to be organized for a reader who has no memory of yesterday. My field: [YOUR FIELD] What I'm building: [WHAT YOU'RE BUILDING] Where I am now: [WHERE YOU ARE NOW] Do this in four steps, and ask me questions rather than guessing: 1. Tell me which categories of knowledge a project like mine actually needs written down. Start from the seven-type taxonomy below, then add, merge, or drop types based on my field specifically. If my field has documents that are expected or required by convention, regulation, or a professional standard — a protocol, a design history file, a method statement, a care plan, a spec sheet, a runbook — name them explicitly and tell me where they fit. Do not add types just to be thorough; each one must earn its place. 2. For each type, tell me the ONE fact class that lives there and nowhere else. Then stress-test it: name the three facts in my project most likely to end up duplicated in two documents, and tell me which document should own each one. 3. Draft my one-page "rules of the product" document — what this is, who it's for, what must always be true, what must never happen, what we're deliberately not doing. Interview me for the content; do not invent the domain rules. Where I'm vague, push. 4. Give me the index: the read-first order, and one row per document I should eventually have, marked with which ones I need this week versus later. Keep the whole set as small as it can be while still having one home for every fact. I would rather have five documents I maintain than twenty I don't.
It's easy to treat documentation as a tax paid after the work. Treating it as the AI's operating environment inverts the economics: the document you write today is read by every session after it, so the payback is immediate rather than hypothetical. The single-source rule is what keeps that compounding instead of rotting.