> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsoflearning.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CONTEXT MANAGEMENT

# Context Management Best Practices for Agents

**Purpose**: Proactive token usage optimization through strategic compacting and subagent isolation

## Overview

Claude Code agents have access to 200K token context windows, but long-running tasks can accumulate significant context. This guide provides strategies for managing context efficiently.

## Two Primary Strategies

### 1. Manual Compacting (`/compact` command)

Summarize and compress conversation history at strategic points

### 2. Subagent Isolation (Task tool)

Spawn independent agents with fresh context windows

***

## Strategy 1: When to Recommend `/compact`

### Trigger Points

Recommend compacting to the user when:

✅ **Transitioning Between Major Phases**

```
Example: Completed Phase 1 (design), starting Phase 2 (implementation)
```

✅ **Before Agent Handoffs**

```
Example: Backend work complete, handing off to Frontend Developer
```

✅ **After Large Code Changes**

```
Example: Major refactoring complete, starting new feature
```

✅ **Context Exceeds 100K Tokens**

```
Estimate: ~20-30 file reads + significant back-and-forth
```

✅ **Starting Complex Analysis**

```
Example: About to analyze large codebase or generate comprehensive report
```

### When NOT to Compact

❌ **Mid-Implementation** - Lose important working context
❌ **During Active Debugging** - Need full error trace history
❌ **Iterating on Specific Feature** - Context is still relevant
❌ **Just Started Session** - No accumulated context yet

### How to Recommend

Use this format when recommending:

```markdown theme={null}
💡 **Context Management Suggestion**

We've completed [phase/task] and are about to start [new phase/task].
Consider running `/compact` to optimize context before proceeding:

\`\`\`
/compact preserve the established coding patterns, architectural
decisions, and key requirements from the PRD
\`\`\`

This will:
- Free up context space for upcoming work
- Preserve important decisions and patterns
- Improve response speed and quality
```

***

## Strategy 2: Use Subagents for Context Isolation

### When to Use Subagents

Use the **Task tool** instead of continuing in same context when:

✅ **Independent Work Modules**

```
Example: "Implement authentication service" is self-contained
```

✅ **Different Agent Roles**

```
Example: Switch from backend to frontend work
```

✅ **Exploratory Analysis**

```
Example: "Search codebase for all API endpoints"
```

✅ **Isolated Testing**

```
Example: "Run test suite and analyze failures"
```

✅ **Large Document Generation**

```
Example: "Generate comprehensive API documentation"
```

### Subagent Benefits

* **Fresh Context**: Each subagent starts with clean 200K tokens
* **Focused Work**: Subagent only sees relevant task details
* **Natural Summary**: Parent gets concise summary when subagent completes
* **Parallel Potential**: Can spawn multiple subagents for different tasks
* **Automatic Cleanup**: Subagent context discarded after completion

### Subagent Usage Pattern

**Pattern 1: Isolated Implementation**

```markdown theme={null}
Instead of implementing in current context:

Use Task tool:
  subagent_type: backend-developer
  prompt: "Implement user authentication service according to
          docs/product/prds/auth-prd.md. Create all necessary files,
          write tests, and provide implementation summary."

The subagent will:
- Start with fresh context
- Focus only on auth service
- Return implementation summary
- Parent context stays clean
```

**Pattern 2: Research/Analysis**

```markdown theme={null}
For codebase exploration:

Use Task tool:
  subagent_type: Explore
  prompt: "Find all API endpoints in the codebase and document
          their authentication requirements. Provide comprehensive
          list with file locations."

The subagent will:
- Search codebase independently
- Build understanding in its own context
- Return findings summary
- Parent avoids context bloat
```

**Pattern 3: Agent Handoffs**

```markdown theme={null}
When handing off between agents:

Use Task tool instead of direct handoff:
  subagent_type: frontend-developer
  prompt: "Implement the UI components based on the design specs
          at docs/design/ui/dashboard-spec.md and the API contracts
          at docs/architecture/api-contracts/dashboard.yaml"

Benefits:
- Frontend agent starts fresh
- Parent doesn't accumulate frontend context
- Clean separation of concerns
```

***

## Context Management in Agent Workflows

### Add to All Agents

Each agent should include a context management section:

```markdown theme={null}
## Context Management

### When to Recommend Compacting

If this conversation exceeds 100K tokens (~20+ file reads) and:
- Transitioning to new major phase
- About to hand off to another agent
- Starting complex analysis or large implementation

**Recommend to user**:
💡 "Consider running `/compact preserve [key decisions and patterns]`
    before proceeding to optimize context."

### When to Use Subagents

For isolated work that could run independently:
- Use Task tool with appropriate subagent_type
- Keeps parent context clean
- Subagent returns focused summary

**Example**:
\`\`\`
Task tool:
  subagent_type: [appropriate-agent]
  prompt: "Clear, specific task description with all context needed"
\`\`\`
```

***

## Implementation Guidelines

### For Agent Developers

When updating agents with context management:

1. **Add Section**: Include "Context Management" section after main workflow
2. **Strategic Points**: Identify natural breakpoints in agent workflow
3. **Recommend, Don't Command**: Suggest `/compact`, don't require it
4. **Provide Context**: Explain WHY compacting would help
5. **Subagent Patterns**: Show WHEN to use Task tool vs continue

### Template for Agents

```markdown theme={null}
## Context Management

### Strategic Compacting Points

Consider recommending `/compact` when:
1. [Specific trigger point for this agent]
2. [Another trigger point]
3. [Third trigger point]

**Example recommendation**:
💡 "We've completed [X]. Consider `/compact preserve [Y]` before [Z]."

### Subagent Isolation

Use Task tool instead of continuing when:
1. [Scenario where subagent makes sense]
2. [Another scenario]

**Example**:
\`\`\`
Task tool:
  subagent_type: [agent-type]
  prompt: "[Clear task description]"
\`\`\`
```

***

## Measuring Context Usage

### Rough Estimates

* **Average message**: \~500-1000 tokens
* **File read (200 lines)**: \~1500-2000 tokens
* **Code generation**: \~2000-5000 tokens per feature
* **Large analysis**: \~10000-20000 tokens

### High Context Indicators

You're likely over 100K tokens if:

* Read 20+ files in conversation
* Generated multiple large features
* Had extensive back-and-forth debugging
* Performed multiple codebase searches
* Generated comprehensive documentation

***

## Best Practices Summary

### ✅ Do

* Recommend compacting at natural breakpoints
* Use subagents for isolated work
* Preserve key decisions when compacting
* Explain benefits to user
* Monitor for high context scenarios

### ❌ Don't

* Recommend compacting mid-implementation
* Overuse compacting (not every task)
* Use subagents for trivial tasks
* Interrupt user flow unnecessarily
* Mandate compacting (always suggest)

***

## Examples

### Example 1: Phase Transition

```markdown theme={null}
**Agent**: "Phase 1 (Database Schema) is complete with 8 migrations created.

💡 **Context Management Suggestion**

Before starting Phase 2 (API Implementation), consider running:
\`\`\`
/compact preserve the database schema design, table relationships,
and the RLS policies we established
\`\`\`

This will optimize context for the upcoming API work."
```

### Example 2: Using Subagent

```markdown theme={null}
**Agent**: "I need to analyze the entire codebase for security vulnerabilities.

Rather than accumulating all analysis in this context, I'll use a
dedicated subagent:

[Spawns app-security-engineer subagent with secure-push skill]

The subagent will return a focused security report without bloating
our current conversation."
```

### Example 3: Agent Handoff

```markdown theme={null}
**Agent**: "Backend API implementation is complete.

💡 **Context Management Options**

Option A (Continue): I can hand off to frontend-developer in this context
Option B (Fresh Start): Spawn frontend-developer subagent with clean context

Recommend **Option B** because:
- Frontend work is self-contained
- Keeps our context focused on backend
- Frontend agent gets targeted context only

Would you like me to spawn the frontend-developer subagent?"
```

***

## Monitoring and Optimization

### Track These Metrics

* How often compacting is recommended
* User acceptance rate of recommendations
* Subagent usage patterns
* Context-related performance issues

### Iterate Based On

* User feedback on recommendation frequency
* Actual token usage patterns
* Agent performance after compacting
* Subagent success rates

***

## Summary

**Context management is about balance:**

* Use `/compact` at strategic phase transitions
* Use subagents for naturally isolated work
* Recommend, don't mandate
* Explain the "why" to users
* Keep parent context clean and focused

**Goal**: Optimize token usage without disrupting workflow or losing important context.