how i use subagents and agent teams -- the patterns that work, the anti-patterns that waste money.
a subagent is a separate claude instance with its own context window. it can read files, search code, and optionally make changes in an isolated worktree. subagents are powerful but expensive -- each one is a full billing stream.
agent teams are a level above -- multiple independent agents working in parallel on separate tasks with their own worktrees. they coordinate through a shared task board, not conversation.
the theme: delegate substantial, independent work. do small stuff yourself.
1. can i do this with 1-3 tool calls?
yes -> do it yourself.
2. does this task need context from my current conversation?
yes -> do it yourself (subagent has no conversation context).
3. is this task independent from what i'm currently doing?
no -> do it yourself or run sequentially.
4. is this task substantial (10+ steps, complex reasoning)?
no -> probably do it yourself.
yes -> use a subagent.
5. do i need to review changes before they hit my working tree?
yes -> use isolation: "worktree".
6. are there multiple independent substantial tasks?
yes -> consider agent teams (2-5 tasks).
spawn multiple explore agents simultaneously, each focused on a different part of the codebase. they read and search but don't write. you synthesize their findings.
{"prompt": "Map all auth-related code in src/auth/ and lib/auth/. List every file and its role.", "description": "map auth subsystem"}
{"prompt": "Find all database access patterns in src/db/. Note raw SQL vs ORM usage.", "description": "map database layer"}
{"prompt": "Find all API route definitions. Note HTTP method, path, handler, middleware.", "description": "map API routes"}spawn all three at once. when they return, you have the full picture without having done any searching yourself. 2-4 agents is the sweet spot -- don't spawn 10.
open-source collections of pre-built agent configurations and team templates:
- msitarzewski/agency-agents -- curated agent patterns and workflows (~96k stars)
- VoltAgent/awesome-claude-code-subagents -- community agent pack library (~20k stars)
use these as templates for your own agent teams. many patterns (scout, specialist delegation, parallel research) have published implementations you can fork and adapt.
instead of doing everything in one context window, delegate specific work to agents with a single job.
test writer:
{
"prompt": "Write unit tests for src/auth/token-service.ts. Use vitest. Cover happy paths, edge cases, error handling. Put tests in src/auth/__tests__/token-service.test.ts.",
"description": "write token service tests"
}security reviewer:
{
"prompt": "Review changes in src/auth/ for SQL injection, missing validation, token leakage, insecure defaults. Provide structured review with severity levels.",
"description": "security review auth changes"
}key: be extremely specific. the agent can't ask clarifying questions. front-load all context it needs. specify exact file paths.
send a fast cheap agent (haiku) to explore first, then a capable agent (sonnet) to act on the findings.
step 1 -- scout with haiku:
{
"prompt": "Find all files related to user authentication. Note file path, exports, dependencies. DO NOT make changes.",
"description": "scout auth codebase",
"model": "claude-haiku-4-5"
}step 2 -- act on findings: use the scout's findings to write a targeted prompt for sonnet. haiku is ~60x cheaper than opus -- a 5-minute haiku exploration that reads 30 files costs almost nothing.
isolation: "worktree" creates a git worktree for the agent. it makes all changes there. you review the diff, cherry-pick what you want, discard the rest.
{
"prompt": "Refactor src/api/routes.ts to use the new router pattern. Update all 12 route handlers.",
"description": "refactor routes",
"isolation": "worktree"
}great for: experimental approaches, risky refactors, anything you want to review before it touches your working tree. don't use for read-only research (worktrees add overhead).
2-5 claude instances working simultaneously on the same project. each gets its own worktree -- a full, isolated copy of the repo.
| scenario | team? | why |
|---|---|---|
| refactor 3 independent modules | yes | no shared state |
| add API endpoint + write tests for it | no | tests depend on endpoint code |
| research 3 competing approaches | yes | each is self-contained |
| fix a bug then update docs about the fix | no | docs depend on knowing the fix |
rule of thumb: if you could assign the tasks to 3 developers who never talk to each other, use a team. if developer B needs to slack developer A a question, use sequential subagents.
- coordinator spawns teammates via the
Tasktool withisolation: "worktree" - each teammate gets its own worktree
- teammates can't see each other -- no shared memory, no message passing
- coordinator collects results when they finish
- you review and merge the worktree branches
if you don't need a coordinator orchestrating things, /batch is simpler:
/batch
1. add input validation to all API routes in src/routes/
2. convert utility files in src/utils/ from commonjs to esm
3. add jsdoc comments to all exported functions in src/lib/
each task runs in its own worktree. use /batch for "do these 5 things independently." use full agent teams when the coordinator needs to synthesize results.
agent teams are expensive. each teammate has its own context window.
| role | model | est. cost |
|---|---|---|
| coordinator | sonnet | ~$0.40 |
| researcher | haiku | ~$0.09 |
| implementer | sonnet | ~$2.30 |
| test-writer | sonnet | ~$1.75 |
| total | ~$4.54 |
a single sonnet doing all this sequentially might cost $3-4 bc it reuses context. teams pay the context-loading tax per teammate.
saving money:
- haiku for research teammates (~19x cheaper on input)
- sonnet for implementation
- keep teams to 2-3 (5 is almost never justified)
- scope prompts tightly -- tell teammates exactly which directories to touch
spawning agents for simple grep/glob -- if you can do it with 1-3 tool calls, just do it. spawning a subagent to search for lodash imports is like hiring a contractor to flip a light switch.
chaining dependent agents in parallel -- agent B can't see agent A's results. run them sequentially if B depends on A.
using opus for quick lookups -- don't spin up the most expensive model to read a package.json. use haiku or just read the file yourself.
over-delegating -- each subagent has startup cost and token overhead. if a task takes 30 seconds and one tool call, do it inline.
the prompt is everything bc the agent can't ask follow-up questions:
- front-load context -- the agent starts with zero knowledge
- be specific about output -- "refactor the auth module" is vague; specify exact function names and patterns
- specify file paths -- don't make the agent guess where files go
- set boundaries -- "only modify files in src/auth/. do not touch src/routes/"
- describe the end state -- "when done, all TypeScript files should compile without errors"
- example agents -- watch-tests, try-worktree, arch-review, write-pr
- official docs -- subagent reference
Agent Teams run multiple subagents in parallel with a unified manager. each teammate has its own context and role. they coordinate through task assignments from the manager session.
{
"agents": [
{
"prompt": "explore the authentication layer. map all auth patterns, list files.",
"description": "auth explorer",
"model": "claude-haiku-4-5"
},
{
"prompt": "explore the database layer. find all query patterns, ORM usage, schemas.",
"description": "database explorer",
"model": "claude-haiku-4-5"
},
{
"prompt": "explore API routes. list all endpoints, HTTP methods, handlers, middleware.",
"description": "api explorer",
"model": "claude-haiku-4-5"
}
]
}spawn all three simultaneously. they work in parallel without blocking each other. the manager session receives reports as each completes. use Agent Teams for parallel exploration where independent agents would otherwise queue sequentially.