The Core Difference
Traditional documentation is narrative text written for human readers — READMEs, wiki pages, Confluence docs, code comments. It explains how to use, set up, or understand a system.
Codebase Cartography produces structured, machine-readable context that lives inside the repository. It's designed for AI agents to parse and navigate, organized hierarchically to match the codebase's architecture.
The distinction matters because the audience is different. Humans read narratively and fill in gaps with intuition. AI agents parse literally and fail when context is implicit.
The Problem with Documentation
Documentation has a well-known lifecycle:
- Creation — Someone writes it, usually when the system is new
- Drift — The code changes, the docs don't
- Distrust — Engineers learn the docs might be wrong, so they stop reading them
- Abandonment — Nobody maintains what nobody reads
This cycle is devastating for AI agents. A human reading stale docs can sense when something feels off and verify against the code. An AI agent treats documentation as ground truth. Stale docs produce confidently wrong code.
Why Cartography Is Different
Codebase Cartography avoids the documentation death cycle through structural choices:
1. Co-located, Not Centralized
Intent Nodes live next to the code they describe — in the same directory, in the same repository. When you're modifying code, the context file is right there. It's harder to forget and easier to update.
Traditional docs live in wikis, Confluence, or separate repos. Out of sight, out of mind, out of date.
2. Structured, Not Narrative
Cartography produces structured declarations: this module's purpose, these patterns, these boundaries. Not prose paragraphs that bury information in sentences.
Structured content is:
- Faster to write
- Easier to maintain
- Machine-parseable
- Less likely to contain ambiguity
3. CI-Integrated, Not Manual
Cartography maps can be validated in CI — checking that referenced files exist, that boundaries are consistent, that critical modules have coverage. Documentation has no such verification.
4. Hierarchical, Not Flat
A wiki is a flat collection of pages. Cartography follows the codebase structure: root → modules → subsystems → components. This hierarchy lets AI agents load context progressively — broad first, then deep.
Side-by-Side Comparison
| Dimension | Traditional Docs | Codebase Cartography |
|---|---|---|
| Audience | Humans | AI agents + humans |
| Location | Wiki, Confluence, separate repo | Inside the codebase |
| Format | Narrative prose | Structured declarations |
| Maintenance | Manual, tends to drift | Co-located, CI-checked |
| Organization | Flat pages or loose hierarchy | Mirrors codebase structure |
| Freshness | Decays over time | Updated with code changes |
| Machine-readable | Not designed for it | Primary design goal |
What About Both?
Most teams should have both, serving different purposes:
- Traditional docs — API reference, setup guides, architecture overviews for human consumption, onboarding materials
- Codebase Cartography — Structured context for AI agents, development-time context for contributors, the "how to work on this" layer
The mistake is assuming traditional docs are sufficient for AI agents. They're not. AI agents need structure, not stories.
Making the Shift
You don't need to throw away your docs. Start by:
- Adding Intent Nodes — Place
AGENTS.mdfiles in your top 5-10 most-worked directories - Declaring intent — Write what each area is for, not just what it contains
- Linking structure — Add downlinks between parent and child nodes
- Integrating maintenance — Add a CI step or PR template that prompts updates when code changes
The first pass takes a few hours. The ongoing maintenance cost is minutes per sprint. The documentation death cycle is broken because the artifacts are lightweight, co-located, and structurally validated.