How to Map a Codebase Before an Agent Touches It

Start with breadth, not depth. You want a list of every module the build system recognizes, plus every place execution can begin: HTTP handlers, CLI commands, cron jobs, queue consumers, event subscribers, database triggers, and the main function if there is one.

Do this with tooling where you can and with the agent where you cannot. Ask the agent for a single deliverable: a JSON array where each element has a path, a module type, an entry-point flag, an approximate line count, and a one-sentence purpose derived from reading the code, not the folder name. Auditors who onboard new codebases weekly rely on exactly this kind of automated extraction, decomposition and representation before they read line by line (arXiv).

A worked example. Suppose the inventory returns 412 modules, 9 of which are entry points. That ratio alone is a finding: nine doors into 400 rooms means the blast radius of most changes is concentrated. On a 3 to 4 million line .NET system, the entry-point list was short enough to review in an afternoon, which is what made a four-week assessment estimate credible (Driver.ai).

Do not let the agent summarize free-form. Prose summaries drift between sessions and cannot be diffed. Force structured output:

[
  {"path": "src/billing/invoice.py", "type": "module", "entry_point": false, "loc": 480, "purpose": "Builds invoice line items from rate cards"},
  {"path": "src/api/routes.py", "type": "http", "entry_point": true, "loc": 120, "purpose": "Registers all HTTP routes"}
]

The purpose field is the agent's hypothesis, and hypotheses get checked in step 5.

The import graph is the backbone of the map, and it is the one part you should not trust the agent to eyeball. A dependency graph represents nodes (modules, packages, components) and edges (one node relies on another), and the useful analysis lives in the shape: direct versus transitive dependencies, reverse dependencies, and cycles that break the acyclic ideal (Tweag).

Parse imports with the language's own tooling. Python's built-in ast library is enough to extract imports from source without executing it, which is how Hudson River Trading built a dependency graph across a codebase of millions of lines and found tangled regions where importing a single module could transitively pull in an order of magnitude more code. In the most tangled portions, the compounding effect amounted to over 30 seconds of import time for most programs (Python Software Foundation). Their diagnosis is worth internalizing: "tangling" means many overlapping cycles and unrelated parts of the codebase coupled through indirect import paths, and a few misplaced imports can couple hundreds of modules.

Write edges to a flat CSV, one row per edge, because flat files diff and merge cleanly and every graph tool reads them:

source,target,edge_type
src/api/routes.py,src/billing/invoice.py,import
src/billing/invoice.py,src/billing/rates.py,import
src/billing/rates.py,src/billing/invoice.py,import

That third row is a cycle, and cycles are the single most useful thing the graph will tell you. Compute three derived numbers per module before moving on: fan-out (how many modules it imports), fan-in (how many import it), and whether it sits in a cycle of more than one module. High fan-in means a change there is expensive; membership in a cycle means you cannot test the module in isolation. Both belong in boundaries.md.

Then use the graph to draw tier lines. HRT's approach was to establish a layered architecture where lower layers never import from higher ones, then add dependency rules checked in continuous integration so the tangle cannot regress (Python Software Foundation). You do not need the full tool. Ten rules in CI ("billing must not import api") deliver most of the benefit.

Imports tell you who calls whom. They do not tell you who mutates what. This is where agents traditionally go wrong: they read a function, change it, and break a distant caller that depended on a side effect nobody documented.

Data flow analysis traces how values are defined, modified and consumed; control flow analysis models the execution paths through branches, loops and calls. Combined, they expose how information propagates through a system, which is exactly what you need before changing a shared structure (IN-COM).

Build a shared-state table with the agent doing the reading and you doing the verification:

Four columns do the work. Writers matter because two writers to the same field is a coupling you cannot see from imports. Readers matter because they define the blast radius. Test coverage matters because it decides whether you can change anything here at all. Risk is the decision output.

For each mutable global, ask the agent a narrow question: "List every assignment to this symbol and the conditions guarding it." When a codebase carries several historical implementations of the same pattern, as one fintech CIO described in an 8 million line Ruby monolith, this is how you find out which one is live and which is dead (Driver.ai). Dead implementations go in boundaries.md as "do not modify; candidate for deletion after logging confirms zero traffic," which is the logging application of the strangler fig pattern, where logging reveals how often old code actually runs so you can decide whether to delete or rewrite it (Wikipedia).

Everything so far is a session. Files are what make it infrastructure. Commit four artifacts at a stable path, for example docs/codemap/, and reference them from the agent's instruction file.

modules.json is the step 1 inventory, regenerated by script rather than chat.

edges.csv is the step 2 import graph, regenerated by script.

boundaries.md is the human-plus-agent judgment layer. Per boundary: name, the modules inside it, the public functions other boundaries may call, the shared state it owns, the tests that cover it, and what is off limits. The table below is the checklist I use for each boundary:

test-coverage.md is the honesty document. Per boundary: which tests exist, whether they run fast enough to loop on, and which modules have none. Feathers' change algorithm puts this first for a reason: identify change points and test points, get the targeted code under tests, then make the change, and keep refactoring inside the covered area because behavior is what users depend on (BSSw).

Characterization tests are the cheapest way to get the safety net up. You do not assert what the code should do; you assert what it does, snapshot style, then change the expected value to the actual when the test fails. DaedTech's walkthrough captures the point: once code is in the wild, "right" and "wrong" stop mattering, and documenting "what is" is what lets you notice when a change makes the system behave differently (DaedTech). Do not hand a codebase without tests to an agent. Feathers is blunt about the stakes (Tech Lead Journal).

# Regenerate the mechanical parts of the map, then review the diff
python tools/codemap/inventory.py --root src --out docs/codemap/modules.json
python tools/codemap/edges.py --root src --out docs/codemap/edges.csv
python tools/codemap/coverage.py --out docs/codemap/test-coverage.md
git diff --stat docs/codemap/

If the diff to modules.json is larger than you expect after a small change, the inventory is picking up generated code and needs an ignore list.

A map you have not checked is a set of guesses with good formatting. Errors survive review: four developers independently generated documentation from an AI and cross-checked each other, and still found mistakes (Driver.ai). Check against two independent oracles.

Static oracle: the test suite. Map each test file to the modules it imports and calls. A module marked "covered by tests/billing" that no test imports is a wrong edge in your map or a stale test. A module with fan-in of 30 and no tests is your highest-risk boundary regardless of what the map's purpose field claims.

Dynamic oracle: runtime traces. Enable request tracing or instrument a handful of entry points, exercise the top ten user journeys, and record which modules actually execute. Then compare with the edges that the import graph predicts. Three discrepancies are common and all three matter:

Do this on one boundary, not all of them, before trusting the method. Pick your target boundary, run the traces, and if two or more predicted edges were wrong, fix the extraction script before scaling. Ten lines of tracing coverage will teach you more about the map's accuracy than any amount of agent self-review.

One more validation angle comes from the research: a map that is too noisy is as useless as no map, because the clarity of the graph collapses when it is drawn at the wrong zoom level. Start with the dependency graph of the change you plan to make, and expand only when the node count exceeds what you can hold in your head (Understand Legacy Code).

The map earns its keep only when later tasks start from it. Two rules make that happen.

First, the map files are part of the repository and change by pull request, like code. When an agent changes structure, it updates the map in the same commit. When a human moves a module, they update the map. A stale map is worse than no map because the agent trusts it. Keep the mechanical files script-generated so that a stale map is impossible to miss: the regeneration diff is the alarm.

Second, every agent task names exactly one boundary and one public surface. The prompt stops being "add refunds to the codebase" and becomes "inside the Billing boundary, add apply_refund to the public surface, wire it to POST /refunds, do not edit legacy_tax.py, and update docs/codemap/boundaries.md." A practitioner thread on scaling models to larger codebases lands on a compatible loop: research the current functionality to load the right files, write a plan to a markdown file, clear context, execute the plan, then review it with tests and lint (Hacker News).

The boundary is also your sequencing unit. If the work must touch two boundaries, that is two tasks, ordered by the graph. Where the new code should run alongside the old rather than replace it, the strangler fig approach is the tested way to do it: a facade routes requests to the legacy or the new implementation, and you shift traffic incrementally as each piece is proven, which reduces migration risk and gives earlier value from each released piece (Microsoft Learn). Martin Fowler's account makes the prerequisite explicit, namely identifying the seams that let a component be split off in the first place, because well-designed systems with ready seams are unicorns (martinfowler.com). Your boundaries.md is a list of candidate seams, ranked by risk.

AWS describes the same pattern as the way to move a tightly coupled monolith forward incrementally, precisely because tightly coupled changes cannot be tested in isolation and thorough retesting is required around each one (AWS Prescriptive Guidance). That is the argument for one boundary per task in a sentence.

One note on automation level. Reports of full automated refactoring exist, but the same account puts typical client projects at 60 to 80 percent automation, with human oversight required for schema changes, data migrations and functional enhancements (InterSystems). Plan your review capacity for the difference.

Where the mapping itself needs many models (a long-context model for reading large modules, a cheaper one for summarizing hundreds of them, an embedding model for semantic search over module purposes), routing those calls through one API removes the key-management overhead, which is what Quanta Inference is for. If you would rather hand the whole mapping pass to an expert that reads context and returns finished files, see Quanta Experts.