Docs That Work

Write documentation that serves both humans and AI agents. Core principle: document only what cannot be discovered from code. Codebase structure matters more than documentation volume — a well-organized project with 10 lines of docs beats a messy one with 200.

The Discoverability Rule

Before writing any documentation line, ask: "Could an agent find this by reading code or config files?"

If yes, don't write it. Directory trees, exports, types, linter rules, commands, dependencies, test locations, env var names — all discoverable from code and config files. See references/anti-patterns.md for the full catalog.

One caveat: code reveals the actual shape of the codebase, not the intended one. Where they diverge — an anti-pattern that leaked in and spread — the divergence is undiscoverable from code and is exactly what needs documenting. See Design Intent below.

Every line you add has a maintenance cost that compounds across every session. Stale docs cause worse decisions than no docs.

CLAUDE.md Rules

Purpose: non-obvious context that AI agents cannot discover from code.

Content that belongs:

• Project purpose — 1-2 sentences on what this does and why
• Undiscoverable conventions — naming patterns, architectural decisions, gotchas
• Non-obvious constraints — "never import X from Y", "always run Z before W"
• Design Intent — the intended shape of code in a package (package-level CLAUDE.md only, see below)

Content that does NOT belong: anything that passes the discoverability rule — commands, directory trees, exports, types, config rules, dependency lists.

Structure:

• Root CLAUDE.md — project-wide context applicable everywhere
• Service-level CLAUDE.md — that module's non-obvious constraints and, where useful, its Design Intent; never repeat root content

Size: non-obvious constraints ~35 lines; Design Intent usually ~10 lines, 15 max; ≤70 combined ceiling. A CLAUDE.md without a Design Intent section should stay around 35. Past the ceiling, it's bloated. Cut ruthlessly.

See references/claude-md-guide.md for templates and examples.

Design Intent

Agents treat existing code as the strongest signal for how new code should look. When an anti-pattern leaks into a package, nothing in the code says which pattern is canonical and which is drift — so agents replicate it. A Design Intent section writes the intended shape down.

Where: package-level (i.e., service/module-level) CLAUDE.md, next to the code it shapes. The root CLAUDE.md keeps its usual project-wide content (purpose, conventions, constraints) but never a Design Intent section.

Format (usually ~10 lines, 15 max): conflict preamble + golden example pointer + 2–4 do/don't rules, plus a sanctioned exception line for any file that deviates on purpose:

# Design Intent

If existing code contradicts this section, follow this section
and flag the file as drift.

Reference: `handlers/create-order.ts` is the canonical handler — copy its structure.

- Do: validate input via schema at the top, one service call, return envelope
- Don't: raw SQL in handlers (leaked into `sales-report.ts` and others — do not replicate)
- Exception: `handlers/bulk-export.ts` streams raw SQL (perf-critical path) — not drift, do not "fix", do not replicate

The conflict rule: Design Intent outranks existing code. When existing code contradicts it, follow Design Intent and flag the contradicting file as drift — never silently replicate the drifted pattern, and never silently ignore the mismatch. To flag: name the file and the contradicted rule in your final summary or PR description — flagging is reporting, not fixing; editing the drifted file or the CLAUDE.md is a separate task (see the maintenance rules in references/design-intent.md). A file named in an Exception line is not drift — leave it alone, and never model new code on it; new code follows the golden example.

Authoring: propose from code, human confirms. Draft the golden example and rules from the dominant or best pattern, then get human confirmation before it lands — if the anti-pattern IS the majority pattern, inferring intent autonomously enshrines the drift. If no human is available: mark the heading # Design Intent (unconfirmed proposal), replace the conflict preamble with "Proposed, not confirmed. Until a human confirms this section, do not treat it as outranking existing code, and do not flag drift from it.", and write no Exception lines — only a human can sanction an exception. Never present inferred intent as confirmed. This fallback is for proposing a new section only: never rewrite, downgrade, or delete an existing confirmed section — including its Exception lines — without a human; propose changes in your summary or PR description instead.

See references/design-intent.md for the full format spec, authoring protocol, and maintenance rules.

README.md Rules

Purpose: human onboarding — get someone from zero to productive.

Content: project description, prerequisites, setup, how to run, how to test, how to contribute. Keep it executable — commands that copy-paste and work beat prose.

Root README.md = full overview + setup. Service-level = purpose + how to run independently. Don't duplicate CLAUDE.md content — different audiences, different purposes.

Grey Box Documentation

Every module is a grey box — clear public API, hidden internals. Documentation describes the interface (what it does, constraints, gotchas), NOT the implementation (file trees, data flow, internal functions).

Progressive disclosure: import from public API → read docs for context → read source only if needed.

You own the interface. AI owns the implementation. Tests keep it honest. If docs describe internal wiring, they couple consumers to implementation and break on every refactor.

Document Separation

Each document has exactly one job:

Never duplicate between them. If the same info is in two places, delete the copy in the wrong file.

When Documentation IS Needed

Some things genuinely need docs because no amount of code reading reveals them:

• "Why" decisions — architectural rationale, trade-off reasoning
• Cross-service contracts — agreements not enforced by types or schemas
• Environment gotchas — WSL quirks, VPN requirements, OS-specific steps
• Historical context — past decisions constraining current design
• Security procedures — auth flows, key rotation, access patterns
• Non-obvious flags — env vars or CLI flags with surprising behavior

If you're unsure whether something needs docs, apply the three-question test from references/anti-patterns.md.

Deep Dives