Map an Unfamiliar Codebase Before You Change It

Tier: Foundation · Workflow area: Context & comprehension

This playbook uses a read-only agent pass to build a verified mental model in under an hour, before you edit a single line.

When to use

• •
  First meaningful change to a codebase, module, or service you did not write.
• •
  Onboarding to a new team and you want to be useful in days, not weeks.
• •
  A change request touches "scary" code — old, untested, or authored by people who have left.

Skip it for code you already know well, or for a module small enough to read top-to-bottom in 20 minutes.

Prerequisites

• •
  A coding agent or chat assistant with repo access (terminal agent, IDE assistant, or chat with files attached).
• •
  A cloned repo that builds — or at least imports — locally, so you can verify claims by running things.
• •
  One concrete change in mind (e.g., "add a credit_note type to invoicing"). Comprehension without a goal produces trivia, not a map.

The workflow

1. 1.

   State the mission, forbid edits. Open your agent at the repo root and anchor it:

   Copy

   You are in read-only mode: do not modify any files. I need to add a new
   invoice type ("credit_note") to this codebase. Explore the repo and give me:
   1. The 5-10 files most relevant to invoice creation and rendering.
   2. The end-to-end path of an invoice: entry point -> business logic ->
      persistence -> side effects (emails, webhooks, ledger entries).
   3. Any state machines, feature flags, or enums that gate invoice behavior.
   Cite file paths and line numbers for every claim.
   

2. 2.

   Demand a trace, not a tour. Generic architecture summaries are cheap. Force a request trace:

   Copy

   Trace exactly what happens when POST /api/invoices is called with
   type="standard". List every function in call order with file:line.
   Note where the transaction boundary is and what happens after commit.
   

3. 3.

   Spot-check three citations. Open three of the cited file:line locations yourself. If any citation is wrong or vague, tell the agent and make it re-verify the whole trace. Do not proceed on an unaudited map.

4. 4.

   Hunt the implicit contracts. These are what break under change:

   Copy

   For the invoice module, list implicit contracts a new invoice type could
   violate: enum exhaustiveness checks, serializers that switch on type,
   DB constraints, Celery tasks that filter by type, template conditionals,
   and any downstream consumer of the invoice webhook payload.
   

5. 5.

   Write the one-page map. Ask for a summary in your own doc format (entry points, data flow, invariants, danger zones, open questions), then edit it by hand. Paste the open questions to a teammate who knows the code — their corrections are the highest-value review you will get this week.

Tool variants

• Terminal coding agent (Claude Code, Codex CLI, etc.): best-in-class here — it greps, reads, and follows imports itself. Use its planning/read-only mode if available.
• IDE assistant (Copilot Chat, Cursor): use workspace/@codebase context; ask the same questions but expect to feed it specific files when retrieval misses.
• Chat assistant without repo access: paste the module's directory listing plus the 5-8 key files; smaller scope, same trace-and-cite prompts.

Verification

• •
  Every architectural claim you keep carries a file:line citation, and you manually opened at least three of them.
• •
  You ran the traced path once for real (local request, test, or shell) and it matched the described call order.
• •
  A teammate reviewed your one-page map and flagged fewer than three corrections.
• •
  You can answer "what breaks if I add a type?" without re-asking the model.

Pitfalls

• Accepting the guided tour. Summaries like "this service uses a layered architecture" are unfalsifiable filler. Only traces with citations count.
• Hallucinated file paths. Models invent plausible paths (services/invoice_service.py) in repos that use different conventions. This is exactly why step 3 exists.
• Letting the agent edit "while it's in there." Comprehension passes are read-only; mixing exploration with edits destroys your ability to trust the map.
• Mapping the whole monolith. Scope to the change. A perfect map of the wrong module is procrastination.

Restricted-environment variant

Client contracts often forbid sending source to external APIs. Options in order of preference:

• Client-sanctioned enterprise toolinside their tenancy (Copilot Business, Bedrock/Azure OpenAI-backed assistants); same prompts, zero change.
• Local model via Ollama (Qwen-Coder-class)good enough for file-by-file explanation; do the cross-file tracing yourself with grep/IDE navigation and use the model to explain each hop.
• Redaction-firstpaste sanitized signatures and structure (function names, docstrings, call graphs from pyan/madge) instead of bodies.

Success criteria

• •
  One-page map produced in under 60 minutes with verified citations.
• •
  Your subsequent change touched only files that appeared on the map (or you updated the map first).
• •
  No post-merge surprise from an implicit contract listed in step 4.
• •
  You reused the map in the PR description — reviewers approved faster because of it.