---
title: "Repo maps, skills, MCP and the context budget"
description: "The context budget Context engineering is the discipline of putting the right information in front of the model at the right time, and nothing else. For…"
url: https://optimizeall.com/learn/agentic-coding-with-ai/repo-maps-and-context-budget
updated: 2026-10-05
---

AI-Assisted Software Development: Coding Agents in Practice · Context engineering for codebases · lesson 5 of 17 · 13 min

# Repo maps, skills, MCP and the context budget

## The context budget

Context engineering is the discipline of putting the *right* information in front of the model at the *right* time, and nothing else. For coding agents, you are managing a budget with three constraints: window size, cost per turn, and the model's attention. A focused 20,000-token context usually beats a bloated 200,000-token one.

Think in layers:

| Layer | Loaded when | Examples |
|---|---|---|
| Always-on | Every session | Instruction files (keep lean) |
| On demand | When the task needs it | Skills, docs pages, design notes, runbooks |
| Discovered | Agent searches for it | Source files, tests, grep results |
| External | Via tools | Issue tracker, database schema, browser, logs via MCP |
| Isolated | In a separate context | Subagents doing broad searches and returning summaries |

## Repo maps: giving the agent a table of contents

Agents navigate large repositories by searching. You can speed that up and improve accuracy with a **repo map**: a compact description of structure and key entry points. Some tools build symbol maps automatically (for example, the open-source Aider popularized tree-sitter based repo maps); you can also maintain a short hand-written one.

```markdown
## Repo map (docs/agents/repo-map.md)
- src/api/        HTTP handlers (thin). Route table: src/api/routes.ts
- src/domain/     Business rules. Invoices: domain/invoice/*, Tax: domain/tax/{pk,ae,gb}.ts
- src/infra/      DB (Drizzle), queues, email. No business logic here.
- test/           Mirrors src/. Fixtures in test/fixtures/. Factories in test/factories.ts
- Entry points: src/server.ts (API), src/worker.ts (background jobs)
- Hot spots: domain/tax/ae.ts changes often; read test/tax/ae.test.ts first.
```

Reference it from AGENTS.md ("For structure, read docs/agents/repo-map.md") so it loads on demand rather than every turn.

## Skills and on-demand knowledge

Several tools now support **skills**: folders with a `SKILL.md` and optional scripts that the agent loads only when relevant (Claude Code popularized the format; other tools have adopted similar ideas). Use them for procedures you repeat: "add a new API endpoint", "write a database migration", "release checklist". Each skill costs almost nothing until it is needed.

```markdown
---
name: add-endpoint
description: Use when adding a new HTTP endpoint to the invoicing API.
---
1. Add the zod schema in src/api/schemas/.
2. Add a thin handler in src/api/handlers/ that calls a domain function.
3. Register in src/api/routes.ts.
4. Add tests: test/api/<name>.test.ts (happy path, validation error, auth error).
5. Run: npm test && npm run check
```

## MCP: bringing external context in safely

The Model Context Protocol lets agents query tools such as your issue tracker, documentation, database schema or a browser. Good uses: fetch the Jira or Linear ticket, read the OpenAPI spec, inspect a read-only staging database schema, view a page in a browser to verify UI changes. Rules:

- Prefer **read-only** servers and credentials.
- Install servers only from sources you trust, pinned to versions, and review what tools they expose.
- Remember that content returned by MCP servers is **untrusted input** that can contain prompt injection (Module 5).

## Subagents: isolate noisy work

When the agent must scan hundreds of files ("find every place we format currency"), do it in a **subagent**: a separate context that does the search and returns a short summary. The main session keeps a clean window for the actual change. Claude Code, Codex and other tools offer variants of this; even without built-in support, you can run a separate session and paste its summary.

## Worked example: a migration in a 400k-line monorepo

A Riyadh fintech wanted to replace a deprecated logging library across a large TypeScript monorepo. The first attempt, one giant session, ran out of useful context and began making inconsistent edits. The second attempt:

1. A subagent produced an inventory: files using the old logger, grouped by pattern (plain calls, child loggers, custom formatters).
2. A skill described the exact replacement for each pattern, with a before/after example.
3. Separate short sessions handled one package at a time, each ending with tests and a small PR.

Same model, same repo; the difference was context design.

## Hands-on: audit your context

Run one real task and then ask the agent:

```text
Before we finish: list every file you read in this session and every command you ran.
Which of them were necessary for the change? What information did you have to search for
that should have been in AGENTS.md or the repo map?
```

Use the answer to update your repo map and instruction file.

## Pitfalls

- **Dumping whole directories into context** "just in case".
- **Stale maps.** Regenerate or review the repo map when structure changes.
- **Over-connected agents.** Ten MCP servers mean more tools to confuse the model and more attack surface.

## How to measure success

Watch tokens per completed task and the share of sessions that finish without restarts. Both should improve as context gets tighter.

## Video lecture: Repo maps, skills, MCP and the context budget

Lecture coming soon · 14 chapters · about 9 minutes. Read the full transcript below.

1. Repo maps and the context budget
2. Analogy: packing a carry-on
3. Three constraints
4. Five layers
5. Repo maps
6. Skills and MCP
7. Subagents
8. Case: Riyadh monorepo migration
9. Pitfalls
10. Example: find the tax bug
11. Common mistakes
12. Deeper: the inventory split (illustrative)
13. Watch me do it: context audit
14. Recap

## Lecture transcript

### Repo maps and the context budget

A bigger context window does not make an agent smarter. Stuffing it full of files often makes it worse. In this lecture you will learn to treat context as a budget, give the agent a map of your repository, load knowledge only when it is needed, and keep noisy work out of the main session.

### Analogy: packing a carry-on

Here is an analogy for the context budget. Imagine packing a carry-on bag for a three-day business trip to Riyadh. You could try to stuff in your whole wardrobe, but the zip will not close and you will not find your charger when you need it. The smart traveller packs exactly what the trip needs, keeps a small pouch of essentials on top, and knows the hotel has anything else. Context works the same way. Instruction files are the essentials pouch. Skills and docs are the hotel: available on demand. And the rest of your repository stays at home until the agent asks for it.

### Three constraints

Context engineering means putting the right information in front of the model at the right time, and nothing else. You are managing three constraints at once. The size of the window, the cost of resending it every turn, and the model's attention. That last one is the sneaky one. A focused context of twenty thousand tokens usually beats a bloated one ten times bigger, because the one instruction that matters is not drowned out.

### Five layers

Think in layers. Always-on context is your instruction file, loaded every session, so keep it lean. On-demand context is loaded when the task needs it, like skills, runbooks and design notes. Discovered context is what the agent finds by searching your code. External context comes through tools like MCP, for example your issue tracker or database schema. And isolated context lives in subagents, which do the messy searching elsewhere and hand back a summary.

### Repo maps

Large repositories need a map. A repo map is a compact table of contents: where handlers live, where business rules live, entry points, and hot spots. Some tools build symbol maps automatically, and you can also keep a short hand-written one in your docs, referenced from your instruction file so it loads only when needed. A line like read the tax tests before changing the Emirati tax module saves the agent ten minutes of wandering, and saves you a bad diff.

### Skills and MCP

Skills extend the same idea to procedures. A skill is a folder with a short Markdown file, and optionally scripts, describing how to do one recurring job: add an endpoint, write a migration, cut a release. The agent loads it only when relevant, so it costs almost nothing until needed. Claude Code popularized the format, and similar ideas are spreading. MCP brings in live external context, like the actual ticket or the API spec. Prefer read-only access, pin versions, and treat anything returned as untrusted input.

### Subagents

Now subagents. Suppose the agent must find every place your code formats currency across hundreds of files. Doing that in the main session floods the window with search results. Instead, a subagent does the search in its own context and returns a one-page inventory. The main session stays clean for the actual change. If your tool lacks built-in subagents, run a separate session and paste in the summary.

### Case: Riyadh monorepo migration

A story from a fintech in Riyadh. They replaced a deprecated logging library across a huge monorepo. Attempt one, one giant session, ran out of useful context and made inconsistent edits. Attempt two used a subagent to inventory every usage pattern, a skill describing the exact replacement for each pattern, and short sessions per package, each ending with tests and a small pull request. Same model. Same repository. The difference was context design.

### Pitfalls

A few pitfalls to avoid. Do not dump whole directories into the first prompt just in case. The agent can search. Do not let your repo map go stale, because a wrong map is worse than no map; regenerate or review it whenever structure changes. And resist connecting ten MCP servers because you can. Every extra tool is one more choice that can confuse the model, and one more door an attacker can knock on. Measure progress with two simple signals: tokens per completed task, and the share of sessions that finish without a restart.

### Example: find the tax bug

A simple example. You ask an agent to fix a bug in the tax module of a large repository. Without a map, it lists directories, greps for the word tax, opens eleven files, and burns through a big chunk of its window before touching code. With a three-line repo map that says tax rules live in the domain tax folder and to read the matching tests first, it opens two files and starts working. Same agent. Same bug. A fraction of the context, and a much better chance the instruction that matters is still in view when it edits the code.

### Common mistakes

Common mistakes with context. One: copying the entire architecture document into the instruction file, so every session pays for it. Two: connecting every MCP server you can find, which floods the model with tool descriptions it does not need and widens your attack surface. Three: forgetting to update the map after a big refactor, so the agent confidently opens files that no longer exist. And four: running one marathon session for a week-long task instead of short sessions that each end with a commit and a note. Which of these have you seen this month?

### Deeper: the inventory split (illustrative)

Let's deepen the Riyadh migration example. The subagent's inventory found three usage patterns for the old logger: plain calls in about two hundred files, child loggers with extra context in about sixty, and custom formatters in eight. That split mattered. The plain calls went to a codemod. The child loggers followed a skill with before and after examples. And the eight custom formatters were migrated by hand, because each was different. Numbers illustrative, but that three-way split is typical.

### Watch me do it: context audit

Watch me do it. I'm running the context audit from the lesson after a real task: fixing a rounding bug in the UAE tax module. When the fix is done, I paste the audit prompt: list every file you read and every command you ran, which were necessary, and what should have been in AGENTS dot M D or the repo map. The agent lists fourteen files read and nine commands. It marks five files as necessary: the tax module, its tests, the money helper, the rounding utility and the invoice template. The other nine were exploration: three route handlers, a queue worker and several infrastructure files it opened while searching for where tax is calculated. It also says it ran the full test suite three times because it could not find the single-file command. So I make two edits. In the repo map, I add a line: tax rules live in the domain tax folder, one file per country, read the matching test file first. In AGENTS dot M D, I add the exact single-file test command. Next time, a similar task should need roughly five files and one targeted test run, not fourteen files and three full runs. I also create a small skill called fix tax rule, with the four steps the agent actually followed, so the procedure loads only when someone works on tax.

### Recap

Recap. Treat context as a budget. Layer it: always-on, on demand, discovered, external and isolated. Give large repos a map, turn recurring procedures into skills, connect MCP servers carefully, and push noisy searches into subagents. Your next step: after your next real task, ask the agent which files and commands were actually necessary, using the audit prompt in the lesson, and fold what you learn into your map and instruction file.

## Key takeaways

- Treat context as a budget constrained by window size, cost and attention.
- Layer context: always-on, on demand (skills, docs), discovered, external (MCP) and isolated (subagents).
- A short repo map referenced from AGENTS.md speeds navigation in large codebases.
- Use subagents for noisy searches and treat MCP output as untrusted input.

## Try it

Write a 10–15 line repo map for your project, reference it from AGENTS.md, and run the context-audit prompt after your next agent task.

- [Previous: Instruction files: AGENTS.md, CLAUDE.md and friends](https://optimizeall.com/learn/agentic-coding-with-ai/agent-instruction-files)
- [Next: Writing tasks agents can finish](https://optimizeall.com/learn/agentic-coding-with-ai/writing-tasks-agents-can-finish)
- [All lessons of AI-Assisted Software Development: Coding Agents in Practice](https://optimizeall.com/learn/agentic-coding-with-ai)