Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 5 of 30

Repository maps

0 of 30 complete

Why it matters

An agent cannot hold a large repository in context, and blind search wastes turns on irrelevant directories. A repository map compresses structure into a fixed token budget so the agent starts near the right code. The compression is also the risk: a map that summarises behaviour can be wrong in exactly the place the task depends on, and the agent has no way to tell without reading the source.

Mental model

It is a subway map that shows topology without streets or distances. The metaphor breaks because code has no stable topology: one refactor redraws the edges, and the agent reading the map has no way to notice the line it planned to take was removed yesterday.

How it works

One task, one slice of the treeInteractive
14 nodes · 7 branches
directoryfileroottest suiteruled out or rejected

Step 1 of 6

Task arrives

The task names a symptom — EU cart totals round the wrong way on annual plans — and four identifiers: total, round, tax, annual. Nothing has been read yet; the map has 2,000 tokens to spend.

root · current

repo · HEAD 8f2c1a

Built from the working tree at the current commit, not from a nightly snapshot. The tree hash is stored with the map so a session can check it against HEAD before trusting a path. The seven files account for 680 of the 2,000 tokens; paths, signatures and the ranking header take the rest.

Root of the hierarchy

Step 1/6 · Task arrives

Figure. Four top-level branches holding six source files and one test, cut to a 2,000-token slice for a single task. The ranker keeps totals.ts and tax.ts because other files reference them; when the slice fills, the billing branch is the first candidate dropped.

What to notice. The map chooses where to read; it never carries a body. Every claim taken from a kept node is followed by a real file read, because a signature cannot say which rounding the code uses. When the slice fills, the lowest-ranked file leaves the map rather than being summarised. File names, token counts and the commit hash are illustrative for a small monorepo; the shape — package, file, test, ranked by references inside the task's package — is the mechanism.

Text version

A repository slice rendered as a hierarchy. The root is repo at HEAD 8f2c1a with a 2,000-token budget. It has four branches: apps/web, packages/pricing, packages/billing and tests. apps/web holds src/checkout with cart.ts at 118 tokens and totals.ts at 96, and src/catalog with price.ts at 74. packages/pricing holds tax.ts at 142 tokens and discounts.ts at 88. packages/billing holds refund.ts at 101 tokens. tests holds checkout.spec.ts at 61 tokens. Stepping through the trace, the task arrives, ranking lights apps/web/src/checkout and totals.ts, the reference edge moves the path to packages/pricing and tax.ts, a read step lights totals.ts and the checkout test, a drop step marks packages/billing and refund.ts as ruled out with a cross glyph and no current ring, and a branch-switch step rules out price.ts, refund.ts and discounts.ts because the slice is rebuilt from the working tree.

  1. Parse files with tree-sitter to extract definitions and references without executing the code.
  2. Build a graph from file to symbol to referencing file, then rank by in-degree inside the task's package.
  3. Render a skeleton with file paths, top-level signatures and one-line bodies only for the highest-ranked symbols.
  4. Give the map a fixed token slice and drop low-ranked files as the repository grows.
  5. Attach line ranges so the agent can jump to the real file instead of trusting the summary.
  6. Rebuild on session start or content hash, never from a snapshot taken on another branch.

Trade-offs

ChoiceGood forCostFails when
Symbol skeleton from an ASTPrecise, cheap, no model callsLittle hint about behaviourNames are cryptic or generated
Model-written file summariesReadable intentCost, drift, invented purposeRepository is large or changes often
Reference-ranked mapFocus on central codePopular utilities crowd out the targetTask lives in a leaf module
Search only, no mapAlways freshSlow orientation on big reposAgent must choose where to start
Trade-off mapInteractive

Good for

Precise, cheap, no model calls

Cost

Little hint about behaviour

Fails when

Names are cryptic or generated

  1. Names are cryptic or generated
  2. Repository is large or changes often
  3. Task lives in a leaf module
  4. Agent must choose where to start

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Symbol skeleton from an AST is good for Precise, cheap, no model calls, costs Little hint about behaviour, and fails when Names are cryptic or generated. Model-written file summaries is good for Readable intent, costs Cost, drift, invented purpose, and fails when Repository is large or changes often. Reference-ranked map is good for Focus on central code, costs Popular utilities crowd out the target, and fails when Task lives in a leaf module. Search only, no map is good for Always fresh, costs Slow orientation on big repos, and fails when Agent must choose where to start

Failure modes

  • Stale map. The agent opens a file at a line that moved and patches the wrong function. Debug: compare the map's tree hash with the current checkout before each run.
  • Invented behaviour. The map claims a function validates input when it only parses it. Debug: require a read of the definition before any edit that depends on the claim.
  • Centrality bias. The map is all framework internals and none of the feature code. Debug: check whether the target package appears anywhere in the top-ranked slice.

In production

Measure map size against the context budget and the share of map claims that survive a file read. Rebuild on branch switch and alert when map generation time exceeds the session setup budget.

Common misconceptions

People think: A map is a substitute for reading code.

Actually: It only chooses where to read; treating it as ground truth produces edits against imagined APIs.

People think: Bigger maps are better.

Actually: A map that fills the window leaves no room for the patch, so relevance beats coverage.

Interview angle

Describe what the map contains, how symbols are ranked and why line ranges matter. A strong answer explains that the map only chooses where to read and that every claim still needs a source read. Calling it a summary of the repository, without addressing staleness or token budget, is the weak version.

Sources