Mastering Claude Code's Agent Features — From Sub-Agents to Teams
Claude Code is a command-line tool that lets you invoke AI directly from your terminal, but it's far more than a simple chat interface. It can split tasks, run multiple agents in parallel, and keep processing in the background — agent features that fundamentally change how you develop.
This article breaks down Claude Code's agent capabilities into three layers: sub-agents (task delegation), background tasks (async execution), and Agent Teams (multi-session coordination).
What Are Sub-Agents?
Sub-agents are specialized agents that handle specific tasks delegated from your main Claude Code session. Each runs in its own context window with independent permissions and tool access.
Why Sub-Agents Matter
Claude Code's context window is finite. On a large project, code exploration, test execution, and documentation searches eat into that context, leaving less room for the actual work at hand.
Sub-agents solve this problem. When you delegate investigation or search tasks to a sub-agent, all the trial-and-error and verbose output stays within that agent's context — never polluting your main conversation history. You preserve main session context while tackling complex tasks in parallel.
Built-in Sub-Agents
Claude Code comes with several pre-built sub-agents.
Explore agent. A fast, read-only agent specialized for codebase exploration. It handles file searches, code searches, and structural analysis. Claude automatically invokes it when it needs to read and understand code.
Plan agent. Used for drafting implementation plans. It explores the codebase, identifies relevant files, considers architectural trade-offs, and returns step-by-step plans.
General-purpose agent. Handles complex research and multi-step tasks with access to a wide range of tools including code search, file reading, and web search.
Creating Custom Sub-Agents
When your project has specific work patterns, you can create custom sub-agents. Use the /agents command or manually create a Markdown file with YAML frontmatter.
---
name: test-runner
description: "Run tests and analyze failures with suggested fixes"
tools: ["Bash", "Read", "Grep"]
model: sonnet
---
# Test Runner Agent
Execute the test suite and analyze the results.
If any tests fail, identify the root cause from error messages
and stack traces, then propose specific fixes.The tools field restricts which tools the agent can use. A test runner might only need Bash, Read, and Grep — no need for Write or Edit. Granting minimal permissions prevents unintended changes.
The model field lets you choose which model powers the agent. Use Haiku for fast investigation tasks, Opus for complex reasoning — matching model capability to task requirements.
Practical Pattern: Think with Opus, Execute with Sonnet
A cost-effective pattern is to run your main session on Opus for high-level design and judgment, while delegating actual code generation and test execution to Sonnet sub-agents.
[Opus] Design, review, and decision-making
├── [Sonnet] Frontend implementation
├── [Sonnet] API endpoint implementation
└── [Sonnet] Test creation and execution
Opus provides superior architectural judgment while Sonnet handles implementation details at higher speed and lower cost — optimizing both quality and efficiency.
Background Tasks
Basic Usage
Press Ctrl+B while a task is running in Claude Code to move it to the background. Your main session frees up immediately, letting you work on something else.
This is particularly powerful for time-consuming operations like builds and test runs. While tests are running in the background, you can edit other files, design the next feature, or review earlier work.
Async Sub-Agent Execution
When you spawn sub-agents, they inherently run in the background. You can launch multiple sub-agents simultaneously and collect their results later.
For example, during a refactoring task:
- Sub-agent A: Identify and fix affected tests
- Sub-agent B: Update documentation
- Sub-agent C: Verify type definition consistency
These run in parallel. Once all complete, your main session integrates the results.
Monitoring Tasks
You can check the status of background tasks at any time — pull in results from completed tasks or check progress on those still running.
Agent Teams (Experimental)
Scope of this article
Released in February 2026, Agent Teams is Claude Code's most ambitious agent feature. It orchestrates multiple Claude Code sessions working together as a team on large-scale tasks.
How They Differ from Sub-Agents
The key difference between sub-agents and Agent Teams is communication.
Sub-agents operate within a single session and can only report results back to the main agent. They can't message each other, share mid-task discoveries, or coordinate without the main agent as intermediary.
Agent Teams removes that bottleneck entirely. One session acts as the team lead, while other sessions (teammates) work independently in their own context windows — and can communicate directly with each other.
When to Use Them
Agent Teams are especially effective for:
Large-scale refactoring. Assign frontend, backend, and testing responsibilities to separate sessions. Each teammate works in parallel while sharing progress updates that inform the others' decisions.
Full-stack feature development. API design, database schema, and UI components each get their own teammate, sharing interface changes in real time as the feature takes shape.
Code review and fixes. One teammate reviews while another implements fixes immediately — a pair-programming workflow where both sides are AI-powered.
Things to Keep in Mind
Agent Teams is currently an experimental feature. Success depends on clear instructions to the team lead and well-defined roles for each teammate. Vague instructions can lead to overlapping work or conflicting changes.
Context Management Best Practices
Getting the most out of agent features requires thoughtful context management.
Use CLAUDE.md
Place a CLAUDE.md file at your project root to provide project-specific information to Claude. Coding conventions, architecture overviews, frequently used commands — all sessions including sub-agents will reference this file.
Mind Your Task Granularity
Tasks delegated to sub-agents should be self-contained. If a task depends on another task's output, you can't benefit from parallel execution.
Good decomposition:
- Refactor file A (self-contained)
- Add tests (self-contained)
- Update documentation (self-contained)
Poor decomposition:
- Change API type definitions (other tasks depend on this)
- Fix components using the API (waiting on above)
Choose Models by Task
Not every task needs the most powerful model.
- Opus: Architecture design, complex judgment, final review
- Sonnet: General coding, test creation, documentation
- Haiku: Simple searches, file reading, routine transformations
Wrapping Up
Claude Code's agent features bring a "team development" experience to solo developers.
Sub-agents conserve context. Background tasks eliminate wait times. Agent Teams tackle large-scale work. Combined, these features let a single developer achieve remarkable velocity.
Start with the built-in sub-agents, then create custom ones as you get comfortable. When you teach agents your project's specific patterns, Claude Code evolves from a simple tool into a teammate that deeply understands your codebase.