Code Documentation

Conventions and templates for README.md files that serve as LLM-optimized navigation documents for codebase directories.

When to Use

• After implementing code that creates or deletes files in a directory

• When a new directory is created that contains code or configuration

• When reviewing documentation freshness during development

• When /m:dev Step 8 triggers documentation updates

Purpose

README.md files are LLM-optimized navigation documents. They allow an agent to:

• Scan frontmatter across many directories to decide which are relevant (fast)

• Read full content of relevant READMEs to understand module structure (deep)

• Navigate diagrams to understand relationships, data flow, and state machines

They are NOT traditional human-only documentation. They prioritize structured, scannable content over prose.

Conventions

YAML Frontmatter

Every README.md starts with YAML frontmatter containing exactly three fields:

module: kebab-case-module-name purpose: One-sentence description of what this directory contains and why it exists last-updated: YYYY-MM-DD

• module : The directory name in kebab-case. Must match the directory it lives in.

• purpose : A single sentence an LLM can use to decide relevance. Be specific — "GraphQL resolvers and helpers for the patient-facing API" not "patient stuff."

• last-updated : The date the README was last modified. Update this whenever the README content changes.

File Listing

Include a table listing every file in the directory (excluding the README.md itself, test directories, and generated files):

Files

• One row per file

• Description should be a single sentence explaining what the file does

• Sort files by logical grouping (entry points first, then core logic, then utilities)

Mermaid Diagrams

Include as many Mermaid diagrams as needed to explain the module. Common types:

• Flowchart — how this module relates to other modules, dependency flow

• Class diagram — data structures, interfaces, types defined here

• Sequence diagram — request/response flows, lifecycle events, business processes

• State diagram — state machines, status transitions

• ER diagram — database relationships when the module owns tables

Small utility directories might only need the file listing. Complex modules might need 5+ diagrams. Use your judgment — include every diagram that helps understand the module.

Overview Paragraph

Between frontmatter and the file listing, include a 2-4 sentence overview paragraph explaining:

• What this module does

• How it fits into the broader system

• Key design decisions or patterns used

Notes Section (Optional)

If the module has important conventions, gotchas, or patterns that aren't obvious from the code, add a ## Notes section at the bottom.

Which Directories to Document

Document directories containing:

• Source code (Go, TypeScript, React components)

• Configuration files (Docker, nginx, CI/CD)

• Database migrations

• GraphQL schemas

• Shared libraries and utilities

Skip directories that are:

• Generated (node_modules/ , dist/ , build/ , coverage/ , vendor/ , .next/ )

• Version control (.git/ )

• Asset-only (images, fonts, icons with no code)

• Test directories (tests/ ) — the parent README covers what's tested

• PRD/docs (prd/ ) — these have their own document structure

When to Update

Update a directory's README.md when:

• A file is created in the directory (add to file listing)

• A file is deleted from the directory (remove from file listing)

• A file is renamed in the directory (update the listing)

• The module's public interface changes significantly (update diagrams)

Do NOT update the README on every code edit. Only structural changes (files added/removed/renamed) or significant interface changes warrant an update.

References

• README Template — blank template to copy

• README Example — realistic filled-in example