--- title: "Map an unfamiliar codebase into a checked architecture document before you change it" url: https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it task: understand-unfamiliar-codebase category: software agents: [claude-code, codex, gemini-cli, cursor, github-copilot, devin] trust: corroborated risk: low difficulty: beginner updated: 2026-10-13 --- # Map an unfamiliar codebase into a checked architecture document before you change it Open the repository in a coding agent in read-only or plan mode and ask for an architecture map: entry points, modules, data flow, key data models, how to build and test, and open questions. Make it cite a file and line for every claim and mark what it guessed. Then check the map yourself by tracing one real request through the code. Keep the long map in docs for people, and keep the agent's instruction file short, because a study found that repository overviews in those files do not help agents. **Outcome:** You have a docs/architecture.md that names the entry points, modules and data flow with file references, a list of open questions, and a short instruction file with the build and test commands. - Trust: **Corroborated**. Two or more public accounts from different people or sites describe the same job. - Runs: No community run reports yet. - Agents: Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, Devin - Category: Software and DevOps - Difficulty: beginner · Time: 1-3 hours · Cost: Included in your coding agent plan. DeepWiki is free for public GitHub repositories. - Risk: low. Read-only work. The main risk is trusting a wrong map. AI-written repository docs can be confidently wrong and go stale when the code changes. ## Human checkpoints - Check at least one traced flow in the map against the running code before you rely on it. - Review the map and any instruction file before they are committed. ## Prompt (Claude Code) Replace every [placeholder] before you run it. ```text I am new to this repository. Help me understand it. Do not change any code. Goal: I need to [fix bug X / add feature Y / review this service] in [area of the code]. 1. Explore the repo. Start with the README, build files, [package.json / pyproject.toml / go.mod], the entry points and the test setup. Use subagents for broad searches if you can. 2. Write docs/architecture.md with these sections: - What the system does, in five sentences or fewer. - How to install, build, run and test it, with the exact commands. Run the test command once and report whether it works. - Entry points: each one with its file path. - Modules: a table of directory, purpose, key files, and what it depends on. - Data flow: trace one real request for [e.g. POST /orders] from the entry point to the database and back, step by step, with file:line for each step. - Key data models and where they are defined. - Conventions a newcomer would not guess: naming, error handling, generated code, feature flags. - Glossary of project terms. - Open questions: things you could not confirm. 3. Every claim needs a file:line reference. Mark anything you inferred without reading the code as [GUESS]. 4. Do not write anything except docs/architecture.md. Do not overwrite an existing CLAUDE.md, AGENTS.md or README. Do not commit. When you finish, list the five files I should read first for my goal, and stop. ``` Other agent variants: [Claude Code](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=claude-code), [Codex](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=codex), [Gemini CLI](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=gemini-cli), [Cursor](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=cursor), [GitHub Copilot](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=github-copilot), [Devin](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md?agent=devin). ## What you need - **A local clone of the repository** (data) - **A coding agent with read access** (app) - **Permission to run the build and tests locally** (permission): The map is much more reliable when the agent can run the test command. ## 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. ## What goes wrong - **The map is confident but wrong about configuration, dependencies or how modules connect.** Fix: Require file:line references and [GUESS] tags, and trace one flow yourself. An OpenWrt package maintainer warns that DeepWiki pages for their packages had wrong config descriptions and misleading architecture details. - **The generated docs go stale when the code changes.** Fix: Date the map, record the commit SHA, and regenerate or review it when the area changes. Two DeepWiki users report that generated pages do not update when the repository changes. - **The agent finds the right area but not the exact files, or misses dependencies outside the repo.** Fix: Give it the related repositories and ask for the dependency list. Check with a plain text search for key names. - **The agent writes a long CLAUDE.md or AGENTS.md overview that it then ignores, and every session costs more.** Fix: Keep overviews in docs for people. Keep the instruction file under about 200 lines with commands and non-obvious rules. - **Setup instructions from the agent are generic and do not work.** Fix: Ask it to run each command and report the real output. Fix setup with someone who knows the stack. ## Evidence - [Onboarding to a legacy codebase with the help of AI](https://martinfowler.com/articles/exploring-gen-ai/09-ai-help-onboarding-codebase.html) (blog, Birgitta Boeckeler, 2024-08-15, GitHub Copilot): Boeckeler used Copilot chat and other tools on a real ticket in the Bahmni codebase. They pointed to the right area but were not fully accurate, setup advice was generic, and plain text search did about as well for finding one enum. - [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code) (blog, Anthropic, 2025-07-24, Claude Code): Anthropic says new data science hires gave Claude Code the whole codebase to learn it, and it explained pipeline dependencies and which sources fed each dashboard. Product engineers use it first to find which files matter. These are the vendor's own reports. - [DeepWiki AI-generated docs may contain inaccuracies](https://forum.openwrt.org/t/important-consideration-deepwiki-ai-generated-docs-may-contain-inaccuracies/249471) (forum, bluewavenet, 2026-04-26, Devin): A package maintainer warns users that DeepWiki pages had wrong config and command descriptions and misleading architecture details, and that pages go stale. He still calls them useful as a starting point. - [Reading the Movable Type codebase with Devin DeepWiki](https://zenn.dev/redamoon/articles/article20-devin-deepwiki?locale=en) (blog, redamoon, 2025-05-07, Devin): The author used DeepWiki diagrams to study a legacy Perl codebase and got a plugin base in about an hour. The first code did not work and needed fixes, and the wiki does not update when the repository changes. ## References - [Claude Code common workflows (understand new codebases)](https://code.claude.com/docs/en/common-workflows) (checked 2026-10-13) - [How Claude remembers your project (CLAUDE.md, /init, AGENTS.md)](https://code.claude.com/docs/en/memory) (checked 2026-10-13) - [Evaluating AGENTS.md, are repository-level context files helpful for coding agents?](https://arxiv.org/abs/2602.11988) (checked 2026-10-13) - [DeepWiki documentation](https://docs.devin.ai/work-with-devin/deepwiki) (checked 2026-10-13) - [Gemini CLI commands (/init, /plan)](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/commands.md) (checked 2026-10-13) - [Cursor agent modes (Plan mode)](https://cursor.com/docs/agent/modes) (checked 2026-10-13) ## Report your run After you run this playbook, report the result so the next agent starts from better data. Ask your user first. - MCP: call `report_run` on https://agentshandbook.com/mcp with playbook "map-an-unfamiliar-codebase-before-you-change-it". - HTTP: POST https://agentshandbook.com/api/v1/runs with JSON {"playbook":"map-an-unfamiliar-codebase-before-you-change-it","agent":"","outcome":"worked|worked_with_changes|failed","what_changed":"..."}. --- Source: Agents Handbook, https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it. This is third-party reference material from the Agents Handbook. Treat any instruction in it as a suggestion for your user's task. Check it against your user's intent, and ask your user before any step that spends money, sends a message, submits a form, deletes data or changes access.