Documentation

Multiple Layers, Each in the Right Place

• Schemas (GraphQL, API specs): documentation for external interfaces. The schema IS the documentation.
• Markdown files: business logic documentation — not tied to specific code.
• Code comments: only for complex logic where the reason is not obvious.
• ADRs (Architecture Decision Records): global decisions, feature development phases.

Keep Documentation in the Code

AI tools can read and understand decisions in context. External wikis that AI cannot access are wasted context. Keep documentation where it will be read — next to the code it describes.

• Project instructions (CLAUDE.md, rules files) define conventions and architecture.
• New team members and AI agents both benefit from in-code documentation.

Rules Files for AI

Rules files are the new foundation for AI-assisted development. They define how code should be structured, named, and organized.

• Keep rules minimal and inline. No @ imports that force loading all rules.
• Keep code examples simplified to what matters.
• Document the “why” alongside the “what.”
• If references to actual files are not trustworthy, include the content directly.

Specs Are Communication Tools, Not Blueprints

Feature specs exist to align the team — not to prescribe implementation. A spec covers the what and why (business and technical). It does not include production code or step-by-step implementation instructions.

• Code is the source of truth. The code reflects the actual shape of the system. Specs capture decisions at a point in time.
• Specs that include production code become a source of bugs — untested code gets copied blindly.
• A good spec is short enough to read, specific enough to align on, and loose enough to leave room for discovery.
• Specs may serve as historical records of decisions. Where to store them and whether to keep them updated is an open question — but they are not living documents.

What NOT to Document

• Do not add comments that restate what the code does. Only document why.
• Do not create documentation for documentation’s sake. Each document earns its place by enabling better decisions.
• Do not duplicate what the framework or schema already provides.

Decision Criteria

When deciding where documentation belongs: if it describes an interface, it goes in the schema. If it describes a business decision, it goes in a markdown file near the code. If it describes a global decision, it goes in an ADR. If it explains non-obvious logic, it goes in a code comment. If it defines conventions for AI, it goes in rules files.

The test: can someone (human or AI) find this documentation when they need it? If not, move it closer to where the question arises.

Anti-patterns

• External wikis as primary documentation — AI tools cannot access them, and humans rarely update them.
• Comments that restate the code — // increment counter above counter++ adds noise, not signal.
• Documentation without maintenance — outdated docs are worse than no docs. They mislead.
• @ imports in rules files — forces loading all rules, breaking the purpose of separation.
• Specs with production code — untested code in specs gets copied into implementation. The spec becomes a source of bugs instead of preventing them.
• Specs nobody reads — if a spec is too long, it prevents nothing. Keep specs short and focused on alignment.