What Codebase Cartography Is
Codebase Cartography is the process of creating a navigable map of a codebase — its architecture, patterns, relationships, and the decisions behind them. The output is a structured Intent Layer that AI agents (and humans) can use to understand and work on the system.
The name is intentional: cartography is about making territory navigable. A good map doesn't reproduce every detail of the terrain — it highlights what matters for navigation: landmarks, routes, boundaries, and hazards.
Why Codebases Need Maps
Software systems accumulate knowledge that exists nowhere in the code itself:
- Architectural intent — Why the system is structured this way, not just how
- Implicit contracts — The unwritten rules between components that everyone "just knows"
- Tribal knowledge — Context that lives in engineers' heads and Slack threads
- Historical decisions — Why you chose Postgres over DynamoDB, why the auth service is separate
Without a map, every AI agent and every new engineer starts from zero. They can read the code, but they can't understand it — not in the way needed to make safe, effective changes.
The Cartography Process
Codebase Cartography typically follows three phases:
1. Survey
Understand the system's major components, their relationships, and the current state of documentation. Identify the high-value areas — the parts of the codebase where AI agents work most, fail most, or where changes carry the highest risk.
2. Map
Create Intent Nodes at key points in the repository hierarchy. Start at the root with a system overview, then work down into major modules and critical subsystems. Each node captures the purpose, patterns, boundaries, and relationships of its area.
3. Maintain
Wire the map into your development workflow. CI checks verify that Intent Nodes stay consistent with the code. Pull request templates prompt updates when areas change. The map stays fresh because it's part of the development process, not a separate documentation effort.
Cartography vs. Documentation
Traditional documentation is written for humans, maintained manually, and tends to go stale. Codebase Cartography produces artifacts that are:
- Machine-readable — Structured for AI agents to parse and act on
- Co-located — Living next to the code they describe
- CI-integrated — Automatically checked and maintained
- Hierarchical — Navigable top-down, not one giant document
The result is context that compounds over time instead of decaying.
Who Does the Cartography
Intent Systems offers Cartography as a service — we map your codebase and set up the maintenance infrastructure. But the methodology is open and documented. Teams can also do their own cartography using the Intent Layer guide.
The first map is the hardest. Once the structure exists, keeping it current is lightweight — most updates are small and happen naturally as part of feature development.