Español

Index Your Docs, Don't Dump Them

Dozens of docs, one index, zero context bloat.

When you give a coding agent a library of methodology docs — testing conventions, release checklists, architecture rules, incident playbooks — the naive move is to load all of them into context on every task. That's the fastest way to blow your context budget and drown the one file that actually matters under fifty that don't. An index fixes this: the agent reads a tiny map, finds the right doc, and loads only that one.

Why dumping everything backfires

Every token of loaded context competes for the model's attention. Pack in eighty documents and three things happen at once:

• Budget burn. You spend most of the window on docs the current task will never touch, leaving less room for the actual code, diffs, and reasoning.
• Signal dilution. The relevant methodology is now one file among many. Retrieval-in-context degrades as the pile grows; the model skims instead of reads.
• Cost and latency. More tokens per turn means more money and slower responses, on every single request, whether the docs were needed or not.

The doc you needed was in there. It just couldn't be heard over the other seventy-nine.

The mechanism: a task-to-doc index

Build one lightweight index file that maps a task to the doc that covers it. It's a table of contents, not the content. The agent reads the index first, matches the task at hand, then loads the single file it points to.

# Methodology index
Read this first. Load only the doc your task needs.

| When you are...              | Load                          |
|------------------------------|-------------------------------|
| Writing or fixing tests      | testing/conventions.md        |
| Cutting a release            | release/checklist.md          |
| Adding a database migration  | data/migrations.md            |
| Handling a production incident| ops/incident-playbook.md     |
| Reviewing a pull request     | review/pr-standards.md        |

The index stays small enough to keep resident. Each linked doc stays a single hop away. This is the same principle as progressive disclosure in agent skills: expose a short entry point, defer the detail until it's asked for.

Conditional loading in practice

Conditional loading keeps the working context lean while every methodology stays reachable the moment a task calls for it. You pay for what you use, not for what you might.

Power moves

• Keep the index flat. One level of mapping, task to doc. Nested indexes reintroduce the search problem you were trying to kill.
• Make entries self-describing. The "when you are..." column should let the agent match on intent, not on guessing filenames.
• One doc per concern. If the index points at a 700-line catch-all, split it so each linked file loads focused.
• Version the index with the docs. When a doc is renamed or retired, update the index in the same change so the map never points at a dead file.
• Audit unreferenced docs. Anything not reachable from the index is either dead weight or a broken link. Grep for it periodically.

Resources

• Agent Skills — Anthropic docs (progressive disclosure)
• Effective context engineering for AI agents — Anthropic
• Retrieval-augmented generation — original paper (Lewis et al., 2020)
• Model Context Protocol — resources & tool discovery