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.

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.

Evolution

• Feb 2026 — initial version from IDENTITY.md documentation positions and code review patterns on rules quality.