Context Optimization for AI-Agent Tooling
Separating human docs from a dense agent layer, then loading only the files each task needs, cut the context an agent reads by 62–98% on the largest projects in my knowledge base.
The Problem
My knowledge base serves two readers: me, and the AI coding agents I work with. Handing an agent everything (READMEs, every project file, old tickets) saturates its context window. That costs latency and money, and worse, it buries the few files that matter for the task under noise, so the model misses details or fills gaps with guesses.
The Engineering Solution
1. Two audiences, two layers
- Human docs: READMEs and guides, written to be read top to bottom.
- Agent layer: a single entry point,
.context.md("Read this file first"), with the rules, a session protocol, and a map of small, atomic files per project:overview,codemap,rules,api,data_model,dependencies,common_issues,examples, plus apatternsfile.
2. Load by intent, not by folder
A Context Load Matrix in .context.md decides which of those files an agent loads for the task at hand:
| File | DEBUG | DEVELOP | PR-REVIEW | UPDATE_DOCS |
|---|---|---|---|---|
| global-rules.md | ✓ | ✓ | ✓ | |
| overview.md | ✓ | ✓ | ||
| codemap.md | ✓ | ✓ | ✓ | ✓ |
| rules.md | ✓ | ✓ | ✓ | ✓ |
| api.md | ✓ | ✓ | ✓ | |
| data_model.md | ✓ | ✓ | ✓ | |
| dependencies.md | ✓ | ✓ | ✓ | |
| common_issues.md | ✓ | |||
| examples.md | ✓ | ✓ | ||
| patterns | ✓ | ✓ | ✓ | ✓ |
A debugging session reads the code map, the rules, the known issues and the examples, and skips the API reference and the data model.
3. One pack per task, with a freshness check
make pack PROJECT=<name> INTENT=<intent> consolidates the matrix's files, the global and project memory, and only the open tickets (finished ones are left out) into a single context pack. The pack's header records a SHA-256 hash of every input; make verify recomputes them and warns when a pack has gone stale.
4. Budgets keep the layer dense
make tokens estimates every project file's size (characters ÷ 4) against a per-file budget and flags any project folder over 1,500 tokens, so bloat shows up in a report instead of creeping in unnoticed. (The two largest folders below are over it, which is exactly why they need the matrix.) A unit test parses the matrix straight from .context.md, so the documented matrix and the packer can't drift apart.
Impact
Measured with the same characters ÷ 4 estimate, loading by intent versus loading a whole project folder:
| Project folder | Context per intent | Reduction |
|---|---|---|
| The two largest (~9,000 tokens each) | 189–3,292 tokens | 62–98% |
| The two smallest (~550–1,150 tokens) | 316–1,085 tokens | 5–43% |
My first estimate was "about 75%". Measured, the gain grows with the project: the bigger the folder, the more each intent can skip. Small projects barely need the matrix; large ones can't do without it.
Key Takeaway
LLMs read differently from people. Don't just hand them your docs: give them a dense layer of their own, and decide per task what they need to see.