Agent Blueprint
Get started
Operations

ab-codebase-mapping

Maps an unfamiliar codebase, read-only, into structured documentation with file paths

/ab-codebase-mapping
Read SKILL.md on GitHub
Skill
ab-codebase-mapping
Phase
Operations, 7 of 9
Version
4.2.0
Arguments
[optional: focus area or module name]
Starts
When named, or on a matching request
Helpers
1 prompt file
File
skills/ab-codebase-mapping/SKILL.md

Use it when

  • When joining a project, before modifying code nobody here has worked in, when onboarding someone, after a major refactor, or when the user asks how the code is structured, how it works or for an architecture overview

Pick another skill

Not for tracking down a specific bug (use ab-systematic-debugging) or reviewing a document (use ab-document-review).

ab-systematic-debuggingRoot cause before any fix: classify, reproduce, trace, one hypothesis at a time against evidence tiers, fix test-firstab-document-reviewThree-pass review of a document (accuracy against the repository, clarity, completeness) with a verdict

Name it in your tool

Every tool also picks a skill on its own when your request matches its description. Naming it picks it for sure.

Claude Code

in a session
/ab-codebase-mapping

What it does

Maps an unfamiliar codebase, read-only, before anyone changes it: a helper (one per major module when the codebase is large) surveys the architecture, module responsibilities, data flow, conventions, tech stack and concerns, citing file paths, and the map is saved to docs/context/CODEBASE-MAP.md or a per-module map, with conventions and critical concerns carried into CONVENTIONS.md and BACKLOG.md.

  1. Dispatch the Mapper

    Hand the mapping to the codebase-mapper helper, scoped to what the user asked for: the focus area or module they named, or the full project when they named none.

  2. Review the Map

  3. Save the Map

    Save the map to docs/context/CODEBASE-MAP.md (or docs/context/MAP-[module-name].md for focused maps).

  4. Orient the Session

Helpers it starts

Each helper is a prompt file in references/agents/. Where the tool has subagents, the helper runs in its own context with only the inputs the file names; elsewhere the main session follows the file itself.

Main sessionab-codebase-mapping

Prompt files in references/agents/

SKILL.md

The instructions the agent follows, from skills/ab-codebase-mapping/SKILL.md.

Read SKILL.md on GitHubIts references/ folder

Codebase Mapping

Map an unfamiliar codebase, or one area of it, into structured documentation before making any changes. The map becomes the shared context for all subsequent development work. The run is done when the map is saved under docs/context/ and its key findings are presented to the user.

The Iron Law

Change no source code, tests or configuration until the map is complete and saved. Mapping is read-only, because an edit made mid-map changes the thing being mapped and mixes two tasks that should be reviewed apart. When you find something that needs fixing, add it to the map’s Concerns section instead of fixing it inline.

Process

Step 1: Dispatch the Mapper

Hand the mapping to the codebase-mapper helper, scoped to what the user asked for: the focus area or module they named, or the full project when they named none.

Helper step. Start a helper (subagent) for this step if you can, with the prompt file named below (its absolute path when the helper can read it, else its full text) and the listed inputs; leave its model and effort at the session’s. If you cannot start one, follow the prompt file yourself. Either way, return its Output section, and note which path ran in the run’s provenance record if there is one.

Prompt: references/agents/codebase-mapper.md. Inputs:

Task: Map the [project/module] codebase.
Focus area: [specific area if provided, or "full project"]
Save findings in the format specified by your output template.

Lower effort. This step is safe at lower effort. If your host lets you set effort for a single helper, you may start this one lower, unless the user asked for their level everywhere; otherwise it runs at the session’s level. Never switch models to save effort.

If the codebase is large, start several mapper helpers in parallel, one per major module or directory, each with the same prompt file and its own focus area. Where helpers cannot run in parallel, map the modules one after another.

Step 2: Review the Map

When the helper returns, review the map for:

  • Completeness — are all major modules covered?
  • Accuracy — do the descriptions match what you see in the code?
  • Actionability — can a developer use this to navigate the codebase?

With several helpers, merge their maps into one before this review.

Step 3: Save the Map

Save the map to docs/context/CODEBASE-MAP.md (or docs/context/MAP-[module-name].md for focused maps).

If docs/context/CONVENTIONS.md doesn’t exist yet, extract the convention findings from the map into a new CONVENTIONS.md.

Add the critical concerns to BACKLOG.md as well, so they are not lost once the session ends.

Step 4: Orient the Session

Present the key findings to the user:

  • Architecture pattern and primary data flow
  • Top concerns (ordered by severity)
  • Recommended areas to investigate further