Repo maps, skills, MCP and the context budget

0:00 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.

0:24 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.

1:10 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.

1:42 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.

2:14 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.

2:49 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.

3:26 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.

3:56 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.

4:28 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.

5:09 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.

5:53 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?

6:34 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.

7:08 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.

8:47 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.