Maps & Breadcrumbs

Don't hand the agent raw files. Hand it topology to orient by, and plant the hints it will trip over on the way in.

Why this, for you: every day on a real codebase, the agent's first job is to figure out where before what — and bulk file reads are the worst way to do it. Maps, symbols, and seeded breadcrumbs are how you orient it cheaply. Pure daily-coding payoff (#1), and the retrieval-design call you make when you build a harness (#2).

A directory listing, a few file samples, and a keyword grep spend tokens on low-signal content while the agent still doesn't know which functions exist or how they connect.^[1] Four moves replace "read more files" with "give it structure": a map, seeded breadcrumbs, symbol queries, and repo-level retrieval.

1 A map, not a file dump

The repository map pattern builds a weighted structural overview fitted to a token budget. It runs in three stages: parse source with tree-sitter into AST symbols — function signatures, classes, methods, not bodies; rank those symbols with PageRank over the reference graph, so a function referenced by 20 files outranks a helper called once; fit the top-ranked tags into the budget by binary search.^[1]

PageRank surfaces the architectural spine without any query — importance propagates through the call graph, so symbols referenced by important symbols rank higher transitively. BM25 and recency weighting lack that property.^[1]

# requested before any edit — topology first src/auth/auth_service.py class AuthService def authenticate(user_id: str, token: str) -> AuthResult def refresh_token(token: str) -> TokenPair src/auth/middleware.py class AuthMiddleware def process_request(request) -> Response # 87 tokens — vs ~12,000 to read every source file

Same codebase, different budget, different detail: fewer files in context and the map expands to full type annotations; more files and it shrinks to only the most-referenced symbols.^[1]

2 Seed the breadcrumbs it'll find

Agents explore by reading — what they find shapes what they do. So plant the context where they look: AGENTS.md / CLAUDE.md files scoped to a directory, decision comments explaining why, type annotations, reference implementations, and TODO/FIXME markers at the exact edit site.^[2] Unlike a prompt, seeded context is persistent — it influences every session that touches that region.^[2]

The breadcrumbs aren't equal. Mechanical enforcement — linters, tests, CI — is the most durable, because the agent hits the constraint at the point of violation and the failing check becomes context for the next attempt.^[2] A comment can be ignored; a red test cannot.

Even accurate seeding can cost 20%+

A controlled study of AGENTS.md found repository-level context files often reduce task success versus no context while raising inference cost over 20% — broad architectural overviews pull agents into unbounded exploration, and LLM-generated files fare worst.^[2] Seed lean, specific, hand-written context, not generated bulk. And remember: stale seeding is worse than no seeding — the agent acts on false premises with high confidence.^[2]

3 Query symbols, don't read files

Semantic context loading queries the codebase through Language Server Protocol operations — symbol lookup, find-references, type hierarchy — instead of reading whole files. Each query returns only the requested symbol's definition or call sites, so token cost scales with the result, not the file size: a 400-line module becomes 20–30 lines of relevant symbols.^[3]

Grep is the baseline to beat — not file reading

The realistic alternative isn't naive whole-file reads; it's well-aimed grep, which most agents already default to. A controlled comparison found grep-based retrieval generally more accurate than vector retrieval for agentic search, with zero infrastructure and no stale results.^[3] The honest case for LSP is high-precision confirmation on top of grep's broad sweep — if a single grep pins the symbol, the round-trip rarely pays for itself.^[3]

4 Reach across files

Generating against the current file alone misses the middleware three directories away and the shared error types in a common package. Repository-level retrieval grounds generation in dependency graphs, cross-file references, and structural embeddings — and consistently beats single-file methods.^[4] The strategy hierarchy is clear:

Strategy	Captures
Lexical (grep, BM25)	keywords; misses meaning
Semantic (embeddings)	meaning; ignores structure
Graph (call graphs, ASTs)	cross-file dependencies
Hybrid (semantic + structural)	best accuracy, highest cost

Graph-based retrieval gains most on tasks whose required dependencies share no vocabulary with the task description — exactly where keyword and embedding search fail.^[4] One caution: stale retrieved snippets actively bias completions toward obsolete signatures (76.5–88.2 percentage points on a Python diagnostic). The fix isn't hard recency filtering — it's co-retrieving the current declaration of any helper a snippet references.^[4]

↪ Your win: structure over bulk, hints where they look

Prefer a map to a file dump — tree-sitter symbols, PageRank-ranked, fit to budget, before reading.
Seed breadcrumbs where agents explore — scoped AGENTS.md, why-comments, types, markers.
Make the durable ones mechanical — a failing test outlasts a comment the agent can skip.
Query symbols over whole files, but only when grep hasn't already pinned the answer.
Reach cross-file with graph retrieval, and co-retrieve current declarations so staleness can't mislead.

Retrieval practice — recall, don't peek

Question 1A repository map ranks its symbols using…

Question 2The most durable seeded breadcrumb is…

Question 3LSP symbol queries cost tokens proportional to…

Question 4Graph-based retrieval wins most when dependencies…

Question 5 · spaced recall from Lesson 13A sub-agent inherits how much of the parent's context?

Ask me anything. Want the .mcp.json snippet to wire a repo-map server into Claude Code, or how to decide between agentic grep, an LSP server, and a vector index for a given codebase? Next: Mind the Version Gap — give the agent the real environment so it stops coding against stale APIs.