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.

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"

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 only, never repeat root content

Size: target <30 lines. If you're past 50 lines, it's bloated. Cut ruthlessly.

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

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