cve-dashboard/.claude/optimization.md

OPTIMIZATION.md - Token Usage & Subagent Strategy

SUBAGENT USAGE STRATEGY

Subagents run in separate contexts and preserve main conversation tokens.

When to Use Subagents

Use Subagents for:

• Large-scale codebase exploration and analysis
• Complex multi-step investigations across many files
• Detailed code pattern searches and refactoring analysis
• Gathering comprehensive information before main conversation work
• When total tokens would exceed 30,000 in main conversation

Keep in Main Conversation:

• Direct file edits (1-3 files)
• Simple code changes and debugging
• Architecture decisions
• Security reviews and approvals
• User-facing responses and recommendations
• Questions requiring reasoning about codebase
• Frontend UI work (use frontend-design skill for new components)

Subagent Types & When to Use

Explore Agent (Haiku 3.5)

• Codebase exploration and file discovery
• Pattern searching across large codebases
• Gathering information about file structure
• Finding references and relationships

General-Purpose Agent (Haiku 3.5)

• Multi-step code analysis tasks
• Summarizing findings from exploration
• Complex searches requiring multiple strategies
• Collecting data for main conversation decisions

---

MODEL SELECTION STRATEGY

Main Conversation (Sonnet 4.5)

• Always use Sonnet 4.5 in main conversation
• Direct file edits and modifications
• Architecture and design decisions
• Security analysis and approvals
• Complex reasoning and recommendations
• Final user responses

Subagent Models

Haiku 4.5 (Default for subagents)

• Code exploration and pattern searching
• File discovery and structure analysis
• Simple codebase investigations
• Gathering information and summarizing
• Task: Use Haiku first for subagent work

Sonnet 4.5 (For subagents - when needed)

• Security-critical analysis within subagents
• Complex architectural decisions needed in exploration
• High-risk code analysis
• When exploration requires advanced reasoning

---

RATE LIMITING GUIDANCE

API Call Throttling

• 5 seconds minimum between API calls
• 10 seconds minimum between web searches
• Batch similar work whenever possible
• If you hit 429 error: STOP and wait 5 minutes

Budget Management

• Track tokens used across all agents
• Main conversation should stay under 100,000 tokens
• Subagent work can extend to 50,000 tokens per agent
• Batch multiple subagent tasks together when possible

---

TOKEN PRESERVATION RULES

Best Practices for Long-Running Conversations

In Main Conversation:

1. Start with subagent for exploration (saves ~20,000 tokens)
2. Request subagent summarize findings
3. Use summary to inform main conversation edits/decisions
4. Keep main conversation focused on decisions and actions

Information Gathering:

• Use subagents to explore before asking for analysis in main conversation
• Have subagent provide condensed summaries (250-500 words max)
• Main conversation uses summary + provides feedback/decisions

File Editing:

• For <3 files: Keep in main conversation
• For 3+ files: Split between subagent (finding/analysis) and main (approval/execution)
• Simple edits (1-5 lines per file): Main conversation
• Complex refactoring (10+ lines per file): Subagent analysis + main approval

Code Review Workflow:

1. Subagent explores and analyzes code patterns
2. Subagent flags issues and suggests improvements
3. Main conversation reviews suggestions
4. Main conversation executes approved changes

Token Budget Allocation Example

• Main conversation: 0-100,000 tokens (soft limit)
• Per subagent task: 0-50,000 tokens
• Critical work (security): Use Sonnet in main conversation
• Exploratory work: Use Explore agent (Haiku) in subagent

---

DECISION TREE

Is this a direct file edit request?
├─ YES (1-3 files, <10 lines each) → Main conversation
├─ NO
└─ Is this exploratory analysis?
   ├─ YES (finding files, patterns) → Use Explore agent (Haiku)
   ├─ NO
   └─ Is this complex multi-step work?
      ├─ YES (3+ steps, many files) → Use General agent (Haiku)
      ├─ NO
      └─ Is this security-critical?
         ├─ YES → Main conversation (Sonnet)
         └─ NO → Subagent (Haiku) or Main conversation

---

SUMMARY

Main Conversation (You): Architecture, decisions, edits, reviews Subagents: Exploration, analysis, information gathering Sonnet 4.5: Security, complexity, final decisions Haiku 4.5: Exploration, gathering, analysis support