Context Decay Problem and Agent Solution
Introduction: The Context Problem in Long Sessions
When you build a production API feature with 10 tasks, you face a critical choice: execute all tasks in one long session, or break them into independent units with fresh context each time.
In a traditional approach, you might give Claude Code a complete specification and say "implement all 10 tasks." This seems efficient—one instruction, one session, done. However, there's a hidden risk: as the session progresses through tasks, the probability of specification drift increases. By task 10, important validation rules or patterns from the beginning might be forgotten.
This is both a probability problem and a technical limitation. Ten tasks mean ten opportunities to miss something. Even if each task has a 95% chance of being perfect, by task 10 the cumulative probability of at least one error is significant. Additionally, as the session progresses, you may hit context window limits, forcing earlier information to be dropped. By task 10, important validation rules or patterns from the beginning might be forgotten due to both accumulated conversation length and statistical likelihood.
With agent orchestration, you reduce this accumulated context risk. Instead of one long session, a Main Agent coordinates the work. For each task, it delegates to a fresh Subagent that starts with a clean slate—the specification is reloaded, the constitution is reloaded, and there's no accumulated context from previous tasks. This doesn't eliminate all errors (agents can still misread specs or miss constraints), but it removes the specific problem of context accumulation degrading quality over multiple tasks.
How Orchestration Works: The Main Agent Pattern
The orchestration pattern has two roles:
Main Agent (Coordinator):
- Reads the task list from
tasks.md - For each task, invokes a specialized subagent
- Receives completion reports
- Waits for human approval
- Tracks progress
- Stops at phase boundaries for review
Subagent (Executor):
- Receives one specific task instruction
- Gets fresh context: CLAUDE.md auto-loaded, specification files you specify with @, task instructions
- Implements the task following test-first workflow
- Runs self-validation
- Reports structured results
Invoking Subagents
To delegate work to a subagent, we use a specific prompt syntax that tells Claude to use the Task tool:
For example:
This syntax matches how permissions are defined in Claude Code (e.g., Task(Explore)). It explicitly tells the Main Agent to delegate to the specific agent defined in .claude/agents/agent-name.md.
Here's what a typical orchestration flow looks like:
The key insight: each subagent starts fresh. There's no accumulated context decay — though agents can still make individual errors like misreading specifications or missing edge cases.
