Agents
A single Claude Code session reads, thinks, and acts in sequence. One thing at a time.
An agent is a Claude session you delegate to — it runs its own loop, in its own context, and returns a result. Agents let you parallelize work that would otherwise run serially, and isolate complex tasks so they don't consume your main session's context.
The signal to delegate: if you catch yourself thinking "I wish I could do X while Claude does Y," that's a subagent.
Three Modes
Single session — you and Claude in one conversation. Best for most work. Context is shared, decisions are visible, you stay in control.
Subagents — you delegate a task from your session. The subagent runs in its own context, completes the work, and returns a summary. The subagent's details don't bloat your session. Use subagents for research, file scanning, code review — anything with a clear input and output that you don't need to watch step-by-step.
Agent teams — multiple subagents running in parallel, coordinating through shared tasks or a message channel. An orchestrator subagent assigns work, specialist subagents execute, results flow back. Use agent teams for large parallel workloads: scanning a codebase while generating a report while running tests.
When to Delegate
| Situation | Mode |
|---|---|
| Normal work — edit, write, review | Single session |
| One large task you want isolated | Subagent |
| Repetitive work across many files | Subagent (or loop) |
| Multiple independent tasks in parallel | Agent team |
| Codebase exploration + report generation simultaneously | Agent team |
Subagent Mechanics
In Claude Code, you can ask Claude to delegate work in any prompt. The Agent tool creates a new session. You give it a clear task and the files or context it needs. It runs. You get a result.
The Claude Code deep dive covers the full pattern: how to write a good delegation prompt, how to scope context, and how agent teams coordinate through shared task lists.
The Tradeoff
More agents mean more parallelism and less context bloat. They also mean more complexity — coordinating results, handling failures, maintaining coherent state.
Start with a single session. Add a subagent when you hit a clear bottleneck. Add coordination structure only when you need it.
Agent Design Checklist
Use this before shipping a new agent definition. Each item must earn its place or be removed.
Identity
- Define one exact job the sub-agent owns
- Write one clear success outcome for that job
- Write one sentence for when it should be invoked
- Write one sentence for when it must not be invoked
- Name it with a short, stable, lowercase, hyphenated identifier
- Choose whether it is project-level or user-level
Permissions and tools
- Give it only the minimum tools required
- Explicitly remove any risky tools it does not need
- Choose the lightest model that can do the job reliably
- Set the permission mode to the lowest level that still lets it succeed
- Add only the skills it truly needs
- Add only the MCP servers it truly needs
- Add memory only if learning across sessions improves outcomes
Execution
- Add a turn limit if the task could drift
- Enable background execution only if the task needs no mid-task clarification
- Use isolation or a worktree if parallel or safer changes matter
Prompt quality
- Start the prompt with a precise role definition
- Add a "when invoked" sequence with the first 3 actions it must take
- Add a fixed operating checklist for how it evaluates or executes work
- Add hard boundaries for forbidden actions and assumptions
- Add a required output format with named sections
- Require concise evidence, not vague claims
- Require verification steps before it declares completion
- Require it to state blockers, risks, and unknowns explicitly
- Require it to stop and escalate when confidence is low or permissions are insufficient
- Remove any vague persona language that does not change behavior
- Remove any duplicated instructions already handled elsewhere
Validation
- Test it on one easy, one normal, and one edge-case task
- Tighten the description until delegation happens correctly and consistently
- Tighten the prompt until outputs are reliable, minimal, and repeatable
- Recheck that every field, tool, permission, and instruction earns its place
- Save the final profile as a reusable template only after it passes all tests
Context
- Claude Code — detailed coverage of subagents, agent teams, and hooks in the Claude Code loop
- Skills — the complement to agents: skills handle repeatable workflows, agents handle parallel delegation
- Onboarding — start here before thinking about agents
- MCP Servers — how agents connect to external tools and services
Links
Questions
At what point does the overhead of coordinating agents cost more than the parallelism gains — and how would you know you've crossed that line?
- What's the clearest single task in your current workflow that would benefit from running in isolation while you do something else?
- How do you write a subagent prompt that gives the agent enough context to succeed without copying your entire session history into it?
- If an agent team is a small business with an orchestrator and specialists, what does good organizational design look like at the agent level?