| name | codebase-cartography |
| model | sonnet |
| description | Produces a structured codebase map — directory roles, entry points, dependency graph, architectural patterns, and dragon locations — for any unfamiliar repository. Use when: 'map this codebase for me', 'I need to understand this repo before I start', 'give me a reading order for this project', 'where are the dragons in this code'. |
| license | proprietary |
| category | continuous-learning |
| triggers | ["map this codebase for me","I need to understand this repo before I start","give me a reading order for this project","where are the dragons in this code"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"repo_path","type":"string","description":"Path to the repository root to map","required":true}] |
| outputs | [{"name":"codebase_map","type":"string","description":"Structured codebase map with directory roles, entry points, dependency graph, architectural patterns, and dragon locations"}] |
Codebase Cartography
I. Philosophy
Understanding a codebase is not reading files -- it is building a mental model
that lets you predict where things are before you look. Cartography moves from
the coarsest grain (directory structure) to the finest (behavioral patterns)
in deliberate layers, each grounded in the previous.
The difference between exploration and cartography: exploration discovers what
exists; cartography produces a reusable map that accelerates future navigation
for yourself and others. A good codebase map answers three questions: Where do
I start? What depends on what? Where are the dragons?
This skill complements project-exploration (which assesses collaboration
potential) and semantic-clusters (which groups by action verbs). Cartography
produces the structural map; those skills interpret it.
II. When to Use
- Onboarding to a new codebase (first day on a project).
- Preparing to write a specification that must integrate with existing code.
- Before a major refactoring to understand what will be affected.
- When debugging and you cannot find where a behavior originates.
- When handing off a project and need to produce orientation documentation.
- After a dependency upgrade to verify the impact surface.
Do not use this skill for assessing whether to collaborate with a project (use
project-exploration). Do not use it for action-verb clustering (use
semantic-clusters).
III. Workflow
Step 1 -- Structural survey.
Map the directory tree at depth 3. Classify directories by role:
| Role | Examples |
|---|
| Source code | src/, lib/, pkg/, internal/ |
| Configuration | .claude/, config/, .github/ |
| Tests | tests/, __tests__/, *_test.go |
| Documentation | docs/, *.md |
| Build/Deploy | Dockerfile, Makefile, package.json, go.mod |
|
