codebase-documenter

Codebase Documenter

Generate developer-facing documentation that helps new team members become productive quickly. Produces a single docs/CODEBASE.md with architecture diagrams, component descriptions, data flow, setup instructions, and an onboarding reading path.

The Inclusion Test

Before writing any line, ask: "Would a new developer need to know this to become productive?"

• If yes → include it
• If no → cut it

Dense, specific content beats comprehensive coverage. Every section should earn its place.

Source of Truth: Code First

The codebase is the primary source of truth — not the README, not the wiki, not inline comments. Repository documentation (README.md, ARCHITECTURE.md, CONTRIBUTING.md) is frequently outdated: it describes what the project was, not what it is.

When exploring, always prioritize reading actual code over reading documentation:

• Derive architecture from imports, entry points, and module structure — not from what the README claims the architecture is
• Extract commands from Makefile, package.json scripts, CI config — not from README setup instructions that may be stale
• Identify patterns from how the code actually works — not from design docs that may describe aspirational patterns never implemented
• Get version numbers from dependency files — not from docs that forget to update them

When documentation and code disagree, trust the code. Note the discrepancy if relevant ("README says X, but the code actually does Y") but document reality.

Documentation is still useful for context that code can't express: the why behind decisions, domain terminology, and business rules. Read it — but verify against code before including any claim in the output.

Constraints

• Only describe what can be inferred from actual code, config, and git history
• Never invent undocumented behavior or hypothetical scenarios
• All file paths must point to files that exist
• All version numbers must come from dependency files, not from memory
• All commands must be real — extracted from Makefile, package.json, CI config — verified to actually exist, not copied from README without checking
• Complement existing docs (README.md, AGENTS.md), don't duplicate them