Chapter 13: Agents and Subagents

Learning Objectives

By the end of this chapter, you will be able to:

Understand what agents are and how they differ from direct tool usage
Launch Explore, Plan, and general-purpose agents
Write effective agent prompts that produce actionable results
Coordinate parallel agents for comprehensive analysis
Manage agent context to preserve your main conversation
Know when agents help and when direct tools are faster

Quick Start (5 Minutes)

Launch an Explore Agent on Your Codebase

You will need: Any codebase (yours, open source, or a sample project)

Paste this into Claude Code:

Explore how authentication works in this project.
Report: what method is used, which files are involved, and any security concerns.

What happens next:

Claude launches an agent (you will see Using Tool: Task)
The agent works autonomously for 2-3 minutes, searching files, reading code, and tracing call paths
The agent reports back with a synthesized summary

Expected output:

Authentication System Analysis

Method: JWT-based authentication
Files involved:
- src/middleware/auth.js (token validation middleware)
- src/routes/auth.js (login/register endpoints)
- src/services/auth.js (token generation, password hashing)

Flow: POST /api/login -> validate credentials -> generate JWT -> return in HTTP-only cookie

Security concerns:
- JWT secret loaded from environment variable (good)
- Tokens expire after 7 days (consider shorter for sensitive apps)
- No rate limiting on login endpoint (should add)

What just happened? Instead of you manually reading files one by one, the agent autonomously searched the codebase, read the relevant files, traced the authentication flow, and delivered a summary. One request replaced 15-20 back-and-forth messages.

Try This Now

Understand a specific system:

Launch an Explore agent to analyze how the database layer works in this codebase.
Report: ORM or raw queries, connection management, migration strategy, and any N+1 risks.

Quick project overview:

Give me a quick overview of this codebase: tech stack, architecture, and main features.

Core Concepts (15 Minutes)

What Are Agents?

Agents are autonomous subprocesses that Claude Code can spawn to handle complex, multi-step tasks. When you ask a question that requires reading many files, tracing code paths, or synthesizing information from across a codebase, Claude launches an agent rather than making you micromanage every step.

The key mechanism is the Task tool. When Claude determines that a request requires autonomous exploration, it invokes the Task tool, which spawns a subagent with its own context window and tool access. The subagent works independently – searching, reading, analyzing – then returns a summary to your main conversation.

Why this matters for context management:

Without agents:
  You ask Claude to read file after file manually.
  Each file fills your main context.
  After 10-15 files, context is nearly full.
  No room left for actual implementation work.

With agents:
  Agent reads 30+ files in its own separate context.
  Agent returns a 1-2 page summary to your context.
  Your main context stays 85% free.
  Plenty of room for follow-up work.

Agents do not just save time. They preserve your context window for the work that matters.

Agent Types

Claude Code uses three agent types. In practice, you do not need to explicitly name them – Claude picks the right one based on your request. But understanding them helps you write better prompts.

Explore Agent – The one you will use most (roughly 70% of agent usage). Designed for reading and analyzing existing code. Use it when you need to understand how something works, find patterns, or investigate a system.

"How does caching work in this project?"
"Find all API endpoints and document their authentication requirements"
"Trace what happens when a user submits an order"

Plan Agent – For designing new features before implementation. It analyzes existing patterns in your codebase and proposes architecture, data models, and implementation steps.

"Design a notification system for this application"
"Plan a migration from REST to GraphQL for the user endpoints"

General-Purpose Agent – For multi-step implementation tasks that require both reading and writing. It can make changes across multiple files while maintaining consistency.

"Migrate all class components in src/components/ to functional components with hooks"
"Set up a complete testing infrastructure with Jest and React Testing Library"

Thoroughness Levels

When launching Explore agents, you can control the depth of investigation:

Level	Time	When to Use
Quick	1-2 min	Getting oriented, simple questions
Medium	3-5 min	Normal analysis, understanding a system (default)
Very thorough	5-10 min	Security audits, migration planning, critical systems

"Launch a quick Explore agent to find the config files"
"Use a medium Explore agent to analyze the payment processing system"
"Use a very thorough Explore agent to audit authentication security"

Start with quick to get oriented, then go medium if you need more depth. Reserve very thorough for situations where completeness matters, like security audits before a launch.

When to Use Agents vs. Direct Tools

This is the most important decision you will make daily:

Use direct tools when you know what to do:

"Read src/auth.js"                    -> Read tool (5 seconds)
"Fix the typo on line 42"            -> Edit tool (5 seconds)
"Search for all uses of validateUser" -> Grep tool (5 seconds)

Use agents when you need to explore the unknown:

"How does authentication work in this codebase?"  -> Agent (3 min)
"Find all performance bottlenecks in the API"      -> Agent (5 min)
"Audit security across the entire application"     -> Agent (8 min)

Rule of thumb: If you can name the specific file or function, use a direct tool. If you need to discover, trace, or synthesize across multiple files, use an agent.

Writing Effective Agent Prompts

The quality of your agent prompt directly determines the quality of results. A vague prompt produces a generic overview. A specific prompt produces actionable analysis.

Vague (wastes time):

"Look at the authentication code"

Specific (actionable results):

"Analyze the authentication system and report:
1. What method is used (JWT, sessions, OAuth)
2. Where are tokens stored (cookies, localStorage, headers)
3. How is password hashing implemented
4. What security best practices are followed or missing
5. List all files involved with their line numbers"

The specific prompt tells the agent what questions to answer, what details to find, and what to include in the report. Same time spent, dramatically better output.

Launching Agents

You can launch agents explicitly or let Claude decide:

Explicit launch:

"Launch an Explore agent to understand how caching works in this project"

Implicit launch (Claude decides):

"How does the payment processing system work?"

Claude recognizes this requires multi-file exploration and launches an agent automatically.

Both approaches work. Explicit launches give you control over agent type and thoroughness. Implicit launches let Claude pick the best approach.

Parallel Agent Execution

When you have multiple independent questions, launch agents in parallel instead of sequentially:

Sequential (slow):

"Audit security" -> wait 6 min -> "Audit performance" -> wait 6 min
Total: 12 minutes

Parallel (fast):

"Launch agents in parallel to analyze:
1. Security vulnerabilities
2. Performance bottlenecks
3. Code quality issues"

All 3 agents run simultaneously.
Total: 6 minutes (time of the slowest agent)

Use parallel agents when tasks are independent – they do not need each other’s results. Use sequential agents when later tasks depend on earlier results, like “find all endpoints, then generate tests for them.”

Example: Comprehensive codebase audit

You: "I need a complete codebase audit before our launch. Launch parallel agents for:
     1. Security vulnerabilities
     2. Performance bottlenecks
     3. Test coverage gaps
     4. Code quality issues"

Claude launches 4 agents simultaneously.

Results arrive in ~6 minutes:

Security: SQL injection risk in user search, JWT secret should rotate
Performance: N+1 query in user profile page, images not optimized
Test Coverage: Payment processing at 0%, auth only at 45%
Quality: Code duplication in 5 controllers, 12 functions over 50 lines

Four independent analyses completed in the time it would take to run one.

Agent Context: Why It Matters

Each agent operates in its own context window, separate from your main conversation:

Your main conversation context:
  [Your messages + Claude's responses]
  Context used: 15% (just the agent's summary)

Agent's context (separate):
  [30+ files read, patterns analyzed, code traced]
  Context used: 80% (but discarded after agent completes)

When the agent finishes, only its summary report enters your main context. The detailed file contents it read stay in the agent’s context and are discarded. This means you can investigate an entire 50-file system while keeping your main context nearly empty for implementation work.

Worktrees for Agent Isolation

When agents make code changes (general-purpose agents), you may want to isolate their work from your main branch. Claude Code supports worktrees – separate working directories on their own branches:

"Start a worktree for this refactoring task"

The agent works in the worktree without affecting your main branch. You review the changes and merge when satisfied. This is especially useful for large refactoring tasks where you want to inspect the agent’s work before committing to it.

Deep Dive (Optional)

Advanced Agent Patterns

Pattern 1: Agent Chains (Sequential)

When later tasks depend on earlier results, chain agents:

You: "First, find all API endpoints. Then generate integration tests for them."

Claude:
  Agent 1 (Explore): Finds 23 endpoints, documents methods, paths, and inputs.
  Agent 2 (General-purpose): Uses Agent 1's findings to generate tests for all 23 endpoints.

The key difference from parallel: Agent 2 needs Agent 1’s output. Claude automatically passes the findings forward.

Pattern 2: Iterative Refinement

Start broad, then narrow based on initial findings:

You: "Explore how error handling works in our codebase"

Agent reports: "Error handling is inconsistent -- some controllers use try-catch,
some use error middleware, some return errors directly."

You: "Good. Now dig deeper into the error middleware approach specifically.
     Which routes use it, what error types are handled, and what gaps exist."

Second agent provides detailed middleware analysis.

Pattern 3: Constrained Agents

Give agents specific boundaries to keep them focused:

"Analyze performance bottlenecks, but:
- Only look at the API layer (src/api/)
- Focus on database queries and caching
- Ignore frontend code
- Report top 5 issues with impact estimates"

Constraints prevent agents from going off on tangents and keep results actionable.

Effective Task Design

Break large tasks into focused agents:

Instead of:

"Audit entire application for everything"

Use:

Agent 1: "Security audit of authentication and API endpoints"
Agent 2: "Performance analysis of database queries and caching"
Agent 3: "Code quality review of business logic layer"

Each focused agent produces a clear, actionable report. One massive agent produces an overwhelming, unfocused one.

Save valuable agent reports:

Agent reports for security audits, architecture analysis, or migration plans are worth preserving:

"Save this security audit to docs/security-audit-2025-01.md"

This creates a permanent record you can share with your team, reference during implementation, and compare against future audits.

When Things Go Wrong

Agent goes off track and wastes context:

Symptoms: Agent runs for 8+ minutes, explores irrelevant directories, returns a report that does not answer your question.

Fix: Your prompt was too vague. Stop the conversation and restart with a specific prompt that lists exactly what questions to answer, which directories to focus on, and what format to use for the report. Adding constraints like “only look in src/api/” prevents wandering.

Agent returns incomplete results:

Symptoms: Agent reports “found 3 files related to authentication” when you know there are 12.

Fix: Increase thoroughness (“use a very thorough Explore agent”) and provide search hints: “Look for files containing ‘auth’, ‘login’, ‘token’, ‘session’, ‘jwt’, and ‘passport’. Search in src/, lib/, and services/ directories.”

Too many parallel agents overwhelm the system:

Symptoms: You launch 6+ agents simultaneously and responses become slow or some agents return shallow results.

Fix: Limit parallel agents to 3-4 at a time. If you need more analyses, run them in batches. Four parallel agents is the practical sweet spot – beyond that, diminishing returns set in.

Agent makes destructive changes:

Symptoms: A general-purpose agent deletes files, overwrites working code, or makes changes you did not expect.

Fix: For risky tasks, use the two-step pattern: first launch an Explore agent to analyze and report, then review the analysis before launching an implementation agent. Use worktrees for large changes so you can discard them if needed. Always run tests after agent changes before committing.

Chapter Checkpoint

You should now be able to:

Explain what agents are and how the Task tool spawns subagents with separate context
Choose between Explore, Plan, and general-purpose agents for different tasks
Write specific agent prompts that produce actionable reports instead of generic overviews
Launch parallel agents for independent tasks and chain agents for dependent ones
Recognize when direct tools are faster than agents (known files vs. unknown systems)

Competency checklist:

Launched an Explore agent and received a useful report about your codebase
Wrote an agent prompt with specific questions and format requirements
Ran parallel agents for at least two independent analyses
Used a constrained agent with directory or scope limits
Saved an agent report to a file for future reference

Try This Now

Exercise 1: Compare Agent Depths

Goal: Understand how thoroughness levels affect results.

Pick a system in your codebase (authentication, data access, routing, etc.)
Launch a quick Explore agent: “Give me a quick overview of how [system] works”
Read the report and note what is covered
Launch a medium Explore agent with the same question but add 3-4 specific sub-questions
Compare the two reports – notice the difference in depth and actionability

What to look for: The quick report gives you orientation. The medium report with specific questions gives you implementation-ready information. Neither is “better” – they serve different purposes.

Exercise 2: Parallel Audit

Goal: Experience the speed of parallel agents.

Launch 3 agents in a single message:

Launch agents in parallel:
1. Find all TODO/FIXME comments and categorize by urgency
2. Identify the 5 largest functions (by line count) that should be refactored
3. List all external API calls and whether they have error handling

Note how long all three take to complete
Review the three reports and create a prioritized action list

What to look for: All three agents should complete in roughly the same time as one agent would alone. The combined reports give you a multi-dimensional view of your codebase health.