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.

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.

When you invoke a subagent with Task(agent-name): instruction, Claude Code automatically provides:

1. CLAUDE.md: Your project constitution is auto-loaded. The subagent knows your coding standards, patterns, and conventions without you having to repeat them.

2. Files you specify: Any file you reference with @ in your instruction is loaded into the subagent's context. For example: @specs/comments/specification.md or @src/models/task.py.

3. Task instructions: The specific instruction you provide in the Task() command.

What subagents do NOT get:

• Previous agent outputs (unless you explicitly include them)
• Accumulated conversation history from the main session
• Files not explicitly referenced with @

This design is intentional—it prevents context pollution and ensures each task gets exactly the context it needs, no more, no less.

Before you can invoke a subagent, you need to define it. Agent definitions live in .claude/agents/ as markdown files with a special structure.

Every agent file starts with a YAML header that defines the agent's identity:

Field meanings:

• name: Unique identifier used to invoke the agent (e.g., Task(task-executor)).
• description: When the agent should be used.
• tools: Capabilities the agent can access (e.g., Read, Write, Bash).
• model: AI model to use (sonnet, haiku, opus, or inherit).

After the YAML header, you write the system prompt — instructions telling the agent its role and process. For example:

When a subagent finishes its task, it doesn't just say "done." It provides a structured completion report that makes human review trivial:

This report tells you immediately:

• Did the tests pass?
• Is coverage adequate?
• Are types clean?
• What files changed?
• What commit message to use?

With this information, your review takes 3 minutes instead of needing to investigate what happened.

Professional orchestration uses strategic checkpoints instead of reviewing every detail of every task:

Level 1 - Task Completion (3 minutes per task): After each agent completes, do a quick review:

• Read the completion report
• Spot-check one thing (e.g., test names make sense)
• Approve or request fix

Level 2 - Phase Checkpoint (10-15 minutes per phase): After completing a logical phase (e.g., "Foundation" with 5 tasks), stop for deeper validation:

• Run integration tests across all phase tasks
• Verify patterns are consistent
• Confirm phase goal is achieved
• Tag with git tag feature-phase-1-complete

Level 3 - Feature Complete (30-45 minutes): After all tasks are done, do comprehensive validation:

• Verify all acceptance criteria
• Security review
• Performance testing
• Documentation check

For a 10-task feature:

• Level 1: 10 × 3min = 30 minutes
• Level 2: 2 × 15min = 30 minutes
• Level 3: 45 minutes
• Total: ~1.75 hours of validation

This is predictable and efficient compared to ad-hoc review.

While preventing accumulated context decay is the primary benefit, orchestration provides additional advantages:

Modularity: Each task is an independent unit with clear inputs and outputs.

Testability: You can validate each task separately before moving to the next.

Maintainability: Clear boundaries between tasks make the codebase easier to understand.

Scalability: You can add more agents for parallel work (different features can run simultaneously).

Process Consistency: The same workflow applies to every task—no variation in execution steps.

Reproducibility: Given the same specification and tasks, the execution process is predictable (though individual agents may interpret requirements differently).

In this lesson, you learned:

• Context decay is a probability problem in long sessions executing many tasks
• Agent orchestration solves this with fresh subagents per task
• The Task(agent-name): syntax explicitly delegates work to defined agents
• Subagents automatically get CLAUDE.md, specified files, and task instructions
• Agent files use YAML frontmatter to define identity and capabilities
• Structured completion reports make validation efficient
• Three-level validation (task, phase, feature) provides systematic quality control

In the upcoming tasks, you'll experience this firsthand by executing the same feature both ways and comparing the results.