Context Management Is the Real Bottleneck in Agent-Assisted Development

The biggest bottleneck in agent-assisted development isn't model capability. It's context.

Give an agent a vague task and a huge codebase, and it'll produce plausible-looking code that breaks everything. Give it the right context — the architecture, the conventions, the decisions — and it'll ship production-quality work.

I've spent more time structuring context for agents than writing code. That investment pays for itself every day.

The Context Problem

AI coding agents have a fundamental constraint: limited context windows. Even with 200K tokens, you can't dump an entire codebase into a prompt.

So agents need to be selective. They read files, search for patterns, build a mental model. But their mental model is only as good as what they can find.

What goes wrong:

• Agent doesn't know your naming conventions → produces inconsistent code
• Agent doesn't know about existing utilities → reinvents them
• Agent doesn't know the architecture → puts things in the wrong place
• Agent doesn't know the "why" behind decisions → makes changes that violate design intent

The solution isn't smarter models. It's better-organized information.

How I Structure Context

1. CLAUDE.md — The Agent's Entry Point

Every project has a CLAUDE.md at the root. This is the first thing an agent reads. It contains:

• Project overview (what this is, what it does)
• Tech stack and key dependencies
• Directory structure and what lives where
• Naming conventions
• Common commands (build, test, lint)
• Important patterns to follow

Think of it as onboarding docs for a new developer. Because that's exactly what it is. Every agent session is a new developer joining the team.

2. Architecture Decision Records

My docs/ directory has numbered folders:

docs/
├── 00_project/decisions.md
├── 02_architecture/
│   ├── api_spec.md
│   └── data_model.md
├── 03_engine/
│   ├── workflow.md
│   ├── intelligence.md
│   └── memory.md
└── 07_frontend/architecture.md

The critical file: decisions.md. Every major decision gets recorded with:

• What we decided
• Why we decided it
• What we rejected and why

When an agent reads this, it understands the constraints. It won't propose solutions we've already rejected. It won't violate boundaries we set intentionally.

3. Type Contracts as Documentation

The most reliable documentation is the code itself. In my system:

Rust types define the domain model:

pub struct WorkflowExecution {
    pub id: ExecutionId,
    pub workflow_id: WorkflowId,
    pub status: ExecutionStatus,
    pub current_node: Option<NodeId>,
    pub budget_remaining: TokenBudget,
}

OpenAPI spec bridges the gap:

ExecutionStatus:
  type: string
  enum: [pending, running, paused, completed, failed]

TypeScript types are generated from the spec:

type ExecutionStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed'

An agent working on the frontend can read the generated types and know exactly what the backend expects. No guessing.

4. Inline Context at Package Boundaries

Each package has its own context cues:

• README.md in each package explaining its purpose
• Clear module structure with descriptive file names
• Exported types that describe the public API

An agent working in packages/ui/ doesn't need to understand the Rust backend. It needs to understand the component patterns in that package.

The "Why" Problem

The hardest context to convey: why things are the way they are.

An agent sees a seemingly redundant abstraction and "simplifies" it. But that abstraction exists because of a production issue three months ago.

An agent sees an unused parameter and removes it. But it's there for backward compatibility with a client integration.

How I solve this:

1. Comments on non-obvious code. Not "increment counter" comments. "This exists because SurrealDB requires..." comments.
2. Decision records for architectural choices. Why StateGraph instead of free-form agents. Why SurrealDB instead of Postgres.
3. Git blame as context. Sometimes I tell an agent to check the commit history for a file before modifying it.

Context Layering Strategy

Not all context is created equal. I think about it in layers:

Layer 1: Always Available (CLAUDE.md)

• Project structure
• Conventions
• Common commands
• ~500 tokens

Layer 2: On-Demand (Architecture docs)

• System design decisions
• API specifications
• Data models
• ~2000-5000 tokens per doc

Layer 3: Just-in-Time (Source code)

• Specific files the agent reads when working on a task
• Types, existing implementations, tests
• Variable, depends on task

Layer 4: Historical (Git history, PR discussions)

• Why things changed
• Previous attempts and failures
• Rarely needed, but critical when needed

The goal: agents load Layer 1 automatically, request Layer 2 when starting a feature, and pull Layer 3 as they work.

Anti-Patterns

Too Much Context

Dumping 50 files into context doesn't help. The agent drowns in information. Important signals get lost in noise.

Better: Give the agent a map (Layer 1), let it navigate to what it needs.

Stale Context

Docs that describe last month's architecture are worse than no docs. The agent follows outdated patterns.

Better: Keep docs in the same repo, same PR as code changes. Review docs like you review code.

Implicit Context

"Everyone knows we use camelCase for TypeScript." Agents don't know unless you tell them.

Better: Write it down. In CLAUDE.md, in linter configs, in template files.

No Context

Some teams give agents zero guidance. "Here's the repo, figure it out."

The agent figures it out. Differently every time. Inconsistent with existing code. Missing conventions.

Better: Invest 30 minutes writing good project context. It saves hours of rework.

Measuring Context Quality

How do I know if my context is good enough?

Agent rework rate. If I'm rejecting more than 20% of agent output, context is probably the issue.

Convention violations. If agents keep using the wrong patterns, those patterns aren't documented.

Architecture drift. If agents put things in the wrong places, the directory structure isn't clear enough.

Repeated questions. If I keep telling agents the same thing, it should be in CLAUDE.md.

The Paradox

Here's the thing: writing good context for agents also helps human developers.

My onboarding time for new developers dropped after I invested in agent context. The same docs that help AI agents help humans understand the system.

The architecture decision records I wrote for agents have become the go-to reference for the team.

Context management isn't just an AI problem. It's a knowledge management problem. Agents just make the problem visible because they don't tolerate implicit knowledge.

---

Your AI coding agent doesn't need a bigger context window. It needs better-organized context. Write the docs. Record the decisions. Make conventions explicit. Treat every agent session like a new team member's first day.

The teams that manage context well will get 10x productivity from AI agents. The teams that don't will get 10x frustration.