Codebase Mapping

Codebase mapping is the process of analyzing your project and producing documentation that Claude can load as context during feature planning and execution. This page explains the design, the parallel agent architecture, and how the output is used.

The problem it solves

When Claude writes code in a large codebase, it faces a context problem: it can read source files, but it can’t easily answer questions like:

“What’s the naming convention for database models here?”
“Is there a shared error handling pattern or does each module handle its own?”
“What’s the established pattern for adding a new API endpoint?”
“What are the known gotchas when touching the auth module?”

Answering these requires understanding the whole codebase — more context than fits in a single window, and the kind of judgment that requires reading many files and synthesizing patterns.

Codebase mapping solves this by doing that synthesis once, writing the answers to files, and making them available on every subsequent task.

The four documents

Document	Contents	Answers
`MAP.md`	Functions, types, modules, and where they live	”Where is the user authentication logic?”
`PATTERNS.md`	Code conventions, naming patterns, architectural decisions	”How do I write a new service that fits here?”
`STRUCTURE.md`	Directory layout, file naming conventions, where new code goes	”Where do I put a new utility function?”
`CONCERNS.md`	Tech debt, gotchas, known bugs, integration risks	”What will bite me when I touch the payment module?”

These are for Claude, not for humans. They’re formatted to be loaded as context at the start of a task, not read as documentation. Dense, factual, example-heavy.

Parallel agent architecture

When you run /specd.codebase.map, four agents are spawned in parallel. Each gets a fresh 200k context window with a focused mandate:

/specd.codebase.map
        │
        ├── Map Agent     → MAP.md
        ├── Patterns Agent → PATTERNS.md
        ├── Structure Agent → STRUCTURE.md
        └── Concerns Agent  → CONCERNS.md

Why parallel?

Speed — all four run simultaneously
Fresh context — no token pollution between agents
Focus — each agent reads deeply into its area without distraction

Agents write directly to .specd/codebase/. The orchestrating brain only receives confirmations, keeping its context minimal.

What each agent does

Map Agent

Reads through the codebase to produce a navigational map. Focuses on:

Module and package structure
Public functions and their signatures
Key types, interfaces, and data structures
Entry points and important call paths

Output style: Dense cross-references. “The createUser function lives in src/users/service.ts and calls db.users.insert. It’s called from src/api/routes/auth.ts:47.”

Patterns Agent

Identifies the conventions and patterns that define “code that fits here”. Focuses on:

Error handling conventions
Naming patterns (variables, functions, files, database columns)
How new features are typically structured
Library usage patterns (which libraries are used how)
Testing patterns

Output style: Examples with explanations. “New endpoints follow the handler/service/repository pattern. See src/users/ for a canonical example.”

Structure Agent

Analyzes the directory layout to produce a guide for where new code goes. Focuses on:

What each top-level directory contains
File naming conventions
Where tests live relative to source
Where new types, utilities, services, and routes should go

Output style: Prescriptive. “New API routes go in src/api/routes/. Create a matching service in src/services/. Tests go in test/unit/ with a .test.ts suffix.”

Concerns Agent

Identifies risks. Focuses on:

Known bugs or technical debt
Modules that are fragile or poorly tested
Implicit dependencies and hidden coupling
Performance bottlenecks
Security considerations
Areas where the codebase deviates from its own patterns

Output style: Warnings with context. “The payment module has a race condition in processRefund when two refunds are requested simultaneously. See issue #234.”

When context is loaded

Codebase docs are loaded automatically:

During /specd.new — Informs the first discussion and initial requirements
During research — Research agents reference patterns and concerns
During phase planning — Plans are written to match existing patterns
During execution — The implementing agent follows patterns from PATTERNS.md

If .specd/codebase/ doesn’t exist when /specd.new is run, Claude offers to run /specd.codebase.map first.

Multi-project mode

For monorepos, codebase mapping scales across sub-projects:

Four agents run per sub-project (all in parallel across all projects)
After all sub-project maps complete, an orchestrator agent produces system-level docs:

Document	Contents
`PROJECTS.md`	What each project does, its tech stack, and its purpose
`TOPOLOGY.md`	How projects communicate — APIs, events, shared databases
`CONTRACTS.md`	Cross-project interfaces and shared domain models
`CONCERNS.md`	System-level risks — cascading failures, tight coupling, deployment order

System-level docs live in the root .specd/codebase/. Sub-project docs live in each project’s .specd/codebase/.

Refreshing the map

The codebase map goes stale when the codebase changes significantly. Run /specd.codebase.map again after:

Major architectural refactors
Adding or removing significant dependencies
Reorganizing the directory structure
Introducing new patterns that should be documented

Refresh offers to overwrite existing documents. For targeted updates to specific sections, use /specd.codebase.review — it lets you confirm, edit, remove, re-map, or add new content section by section.

Output location

.specd/
└── codebase/
    ├── MAP.md
    ├── PATTERNS.md
    ├── STRUCTURE.md
    └── CONCERNS.md

All documents are committed to git automatically after generation. They should be version-controlled alongside your source code.

/specd.codebase.map — Command reference
Your first feature — How codebase maps fit into the feature workflow
Team workflow — Sharing codebase maps across a team