Claude Code Field Guide: Subagents

Part of the Claude Code Field Guide series.

---

Subagents changed how I work with Claude. They're separate Claude instances that run tasks without polluting the main conversation's context.

The Context Pollution Problem

Long conversations accumulate context. Claude starts to "remember" earlier attempts, failed approaches, and irrelevant tangents. This baggage affects its responses.

Subagents start fresh. They receive only what you give them and return only results.

Research → Action Pattern

Main conversation: "I need to understand why the auth is failing"
↓
Launch subagent: "Investigate auth failures in the codebase, check logs,
                 trace the request flow, report findings"
↓
Subagent researches, reads files, runs queries
↓
Main conversation receives: "Auth fails because token refresh has a race
                            condition in SessionManager.ts:142"
↓
Main conversation: "Fix the race condition" (or launch another agent to fix)

The investigation happens in isolation. The main conversation stays clean, receiving only actionable findings.

Extended Thinking

For complex problems, signal that you want depth over speed. Instead of "think harder," describe the context:

"We have time. No rush. Quality is strongly preferred over speed.
Reconsider the approach. Validate assumptions. Challenge anything
that seems off. Back up recommendations with reasoning."

This triggers extended reasoning—Claude spends more time analyzing before responding.

I use this for:

• Architecture decisions with multiple tradeoffs
• Debugging subtle issues
• Code that requires understanding complex state

The difference is noticeable. Quick prompts get quick answers. Signaling that thoroughness matters gets thorough analysis.

Parallel Development

This is where it gets powerful. Different agents can work on different parts simultaneously:

I describe the feature once. Four agents work in parallel. Each has fresh context focused on their domain.

Fresh Context for Reviews

Code reviews benefit enormously from fresh context. An agent that wrote the code will overlook issues—it's already convinced the approach is correct.

I launch a separate review agent:

"Review the changes in this PR. You have no prior context about why
decisions were made. Evaluate the code on its own merits. Check for:
- Logic errors
- Security issues
- Missing edge cases
- Code style consistency"

The reviewer's fresh perspective catches what the author missed. I even run multiple reviews in sequence—different agents notice different things.

Git Worktree Integration

Git worktree gives each branch its own directory. Combined with subagents, this enables true parallel development:

# Create worktrees for parallel features
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-hotfix hotfix-branch

Now I have:

~/Code/project/           # main branch
~/Code/project-feature-a/ # feature-a branch
~/Code/project-feature-b/ # feature-b branch
~/Code/project-hotfix/    # hotfix branch

Each worktree is an independent working directory. Each subagent works in its own worktree. True parallel development—not simulated, actual parallel work on different features.

I can develop two features simultaneously without interference, review one while the other is being built, and merge independently when each is ready.

Practical Tips

Naming convention: Use descriptive names that indicate purpose. project-auth-refactor is better than project-feature-1.

Run setup per worktree: Each worktree needs its own npm install (or equivalent). Dependencies aren't shared.

Initialize Claude per worktree: Run /init in each worktree session so Claude understands that specific context.

Clean up after merge: git worktree remove ../project-feature-a keeps things tidy.

Management tools: CCManager and similar tools help manage multiple Claude sessions across worktrees if you're running many in parallel.

---

Next: Working Patterns: Plan Mode, Rubber Duck, and More

Back to Claude Code Field Guide