Understand a codebase before changing it

---
name: "map-an-unfamiliar-codebase-agents-handbook-method"
description: "Use when you need to Understand a codebase before changing it. Build a verified map of a codebase before editing it"
---

# Build a verified map of a codebase before editing it

Job: [Understand a codebase before changing it](https://aiagents.org/canai/map-an-unfamiliar-codebase-agents-handbook)

## Need

- AI agent

## Steps

1. Write down your goal. Name the change or review you need to make. A map aimed at one goal is shorter and more accurate than a tour of everything. Check: You have one sentence that names the area and the task.
2. Start the agent in read-only mode. Use Claude Code plan mode (claude --permission-mode plan), the Codex read-only sandbox, Gemini CLI /plan, or Cursor Plan mode, so nothing changes while it explores. Check: The agent reads files and answers, and asks before any edit.
3. Get the build and test commands working first. Ask the agent to find and run the test command. If setup fails, fix it with a human who knows the stack. One writer found AI help could not replace a documented setup for a legacy Java project. Check: The test suite runs on your machine, or you know exactly why it does not.
4. Ask for the map with file references. Paste the prompt. Insist on file:line for each claim and a [GUESS] tag for anything inferred. Check: Every section has file references, and guesses are tagged.
5. Trace one request yourself. Pick the traced request and follow it with a debugger, log lines or a breakpoint. Correct the map where it is wrong. This is the step that turns a plausible map into a correct one. Check: You followed one real request through the code and it matches the map, or you fixed the map.
6. Answer the open questions. Ask a maintainer, read the tests, or run the code for each open question. Delete [GUESS] tags only when you confirm them. Check: The open questions list is short and each one has an owner.
7. Keep the agent instruction file short. Put the long map in docs/architecture.md for people. In CLAUDE.md or AGENTS.md keep only build and test commands and rules the agent would not guess. A 2026 study found repository overviews in these files did not raise agent success and added cost. Check: The instruction file has commands and non-obvious rules, not a copy of the map.
8. Commit the docs yourself. Review the diff, then commit. Note the commit SHA and date in the map so readers know when it was checked. Check: The map is in the repo with a date and the SHA it describes.
9. Optional: The source also has the mapping prompt, human checkpoints and known failures; they are linked there, not copied here.
10. Note: Steps quoted from the Agents Handbook (CC BY 4.0). Start in read-only mode so nothing changes while the agent explores.

## Credit

Method author Agents Handbook editors (CC BY 4.0)
Source: https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it