AI Context Coverage: The 25% Rule for Large Codebases

This is Part 1 of the Agent Memory Architecture series, based on research into scaling AI to 100k-line codebases.

You would never let a brilliant surgeon with total amnesia operate on you. But that is exactly what happens when you drop a LLM into a massive repository with nothing but a basic README.

A recent paper, Codified Context: Infrastructure for AI Agents in a Complex Codebase, puts hard numbers on how to fix this. Researchers used Claude Code as the sole code-generation tool to build a 108,000-line C# multiplayer simulation across 283 sessions. To prevent AI hallucinations and maintain architectural integrity at that scale, they had to write 25,000 lines of specifications, prompts, and constitutional rules.

That is a knowledge-to-code ratio of 24.2%. One line of context for every four lines of code.

Based on this data, here is The New Engineering Baseline:

1. Target a 25% ratio: For every 400 lines of code you merge, you owe your AI agent 100 lines of explicit instructions.
2. Write for machines: Stop writing narrative wikis. Write strict, machine-readable constraints like .cursorrules.
3. Enforce it in CI/CD: If a pull request adds 500 lines of new logic but 0 lines of context updates, fail the build.

Why context coverage is replacing test coverage

Context coverage prevents architectural drift that tests cannot catch. While test coverage ensures specific functions return expected outputs, context coverage ensures the AI understands the intent and constraints of the entire system. In 100k+ line repositories, high context coverage is what stops an AI from building the wrong thing correctly.

If your repository contains 100,000 lines of code but your context is just a 50-line project summary, your AI has no mental model of the system. It can read the syntax, but it cannot understand the trade-offs. It does not know why you chose a specific database or which design patterns you actively avoid.

When you ask an agent to build a new feature in a low-context repository, it guesses. It writes code that works locally but violates your architecture. You ask it to manage user state, and it pulls in three new libraries because it did not know you already configured a solution in a sibling directory.

The hidden cost of context debt

When you ignore this ratio, you accrue context debt. This is the gap between how your system actually works and what the AI thinks it does. Without explicit instructions, an agent defaults to the most common patterns in its training data.

If you do not document your repository pattern, the AI will write raw SQL queries directly inside a UI component. It is not being stupid. It is optimizing for the shortest path to a working feature based on generic web development tutorials. Context debt forces you to spend hours reviewing pull requests, reverting AI hallucinations, and explaining architectural boundaries that should have been codified in the first place.

How the 24% ratio works in practice

Maintaining a 100,000-line system with AI requires treating instructions as load-bearing infrastructure. As established by the Codified Context research, that 24.2% threshold is what keeps the system from collapsing under its own weight.

Those 25,000 lines act as the permanent memory for the agent. Every time a new session starts, the AI ingests those rules and instantly understands the boundaries of the system.

If that volume sounds high, consider the contents. It is not narrative text. It is a root-level .cursorrules file, component-specific prompt templates, explicit database schema references, and running logs of lessons learned that stop the agent from repeating past mistakes.

Context grows linearly with code

You do not write 25,000 lines of context before writing your first function. The ratio scales continuously alongside development.

When you merge 400 lines of new feature code, you owe the agent roughly 100 lines of system instructions. This is not a giant monolithic prompt. It is distributed, practical context — documentation acting as RAM for the model.

If you add a new authentication module, that 100-line update breaks down into specific, manageable artifacts:

• 20 lines defining the new API data contracts.
• 30 lines outlining the state management rules for active sessions.
• 50 lines appended to your project memory detailing the edge cases you already tried and the specific design patterns the agent must follow.

Scale the codebase without scaling this memory, and the agent loses track of system boundaries. Keep the knowledge-to-code ratio constant, and the agent stays aligned with the actual state of the product.

Treating documentation as executable infrastructure

Documentation must shift from a human-readable afterthought to machine-readable infrastructure for AI agents. High-context repositories use agent rules and system prompts to enforce architectural invariants in real-time, dictating how the code evolves. When context rots, the code rots immediately after.

Here is how I am applying this right now:

1. Track your context coverage. Calculate the raw line count of your instructional markdown files compared to your source code. If your ratio is under 5%, you are asking the AI to guess.
2. Write constitutional rules. Create specific files that tell the AI exactly what not to do. Write machine-readable constraints rather than long paragraphs.

 
 
 
 
 
<!-- .cursorrules : ECS Architecture Invariants -->
 
When creating or modifying Arch ECS systems Systems must be completely stateless. Store all data in Components. Network serialization must use explicit byte packing. Never use C# Reflection. Update loops must rely on the global simulation tick, not delta time. \`\`\`
 
3. **Version control your prompts.** Treat your agent instructions like code. Use specific trigger files like `MEMORY.md`. When a pattern changes in your codebase, update the corresponding rule file in the same commit.
 
You cannot expect an AI to navigate a maze if you refuse to draw it a map. Start writing the map.