Working Effectively with Claude Code — Part 2: Agents, Subagents & Multi-Agent Setups

In Part 1 the whole game was keeping a single session sharp: see the context window, keep it lean, and prompt with intent. This part goes one level up. Once a task is big enough that one window can't hold it cleanly — a sprawling investigation, a review that touches everything, three independent changes at once — the move isn't to cram harder. It's to delegate.

That's what agents and subagents are for. By the end you'll know what they actually are, how to brief one so it succeeds, how to build your own, when delegating pays off, and how to run several Claudes in parallel without them clobbering each other's work.

What a subagent actually is

A subagent is a separate Claude that your main session spins up to handle one focused task. Under the hood, the main agent calls a tool (the Task tool) with a prompt; that launches a fresh Claude which works on its own until it's done, then hands back a single final message — its report. Everything in between is invisible to you.

Three properties make this worth understanding:

• Its own context window. The subagent reads files, runs commands, and reasons in a separate window. None of that lands in yours. In Part 1 we saw how every file Claude opens competes for space in one finite window; a subagent breaks that constraint by doing the expensive part somewhere else.
• Its own tools (and optionally its own model). You can hand a subagent the full toolset or a narrow slice of it, and even run it on a cheaper, faster model than your main session.
• A clean slate. It starts with no memory of your conversation — it sees only the prompt you give it, plus the always-loaded CLAUDE.md. It finishes, returns a summary, and its window is discarded.

That last property is the one people trip over. Delegation is a handoff, not a chat: the subagent can't ask you a quick follow-up and doesn't know what you two just discussed. Brief it like you'd brief a new contractor who has read your CLAUDE.md and nothing else.

Why delegate: context isolation

The clearest way to feel the difference is to watch where the tokens land. Take a routine task — "trace how auth flows through these 18 files" — and compare doing it inline versus handing it to a subagent:

Inline, those eighteen files pile into your main window and stay there, crowding everything that comes after. Delegated, the subagent burns through them in its own window and returns a paragraph. Same answer; your main session barely moves. Multiply that across a long working day and it's the difference between a session that stays crisp and one that hits auto-compaction by lunch.

So the rule of thumb is simple: if a task is read-heavy but its output is small, delegate it. Investigations, "where is X handled," "does the codebase already do Y" — all of it is summary-shaped, and summary-shaped work is exactly what subagents are for.

Briefing a subagent well

Because a subagent can't see your conversation, a vague prompt fails in a way it wouldn't in your main session — there's no shared history to fall back on. A good brief carries four things: the goal, enough context to start (paths, entry points), an explicit success criterion, and what to return. Compare:

❌  look into the auth bug
 
✅  Investigate how session tokens are validated.
    - Start from src/auth/ and middleware/.
    - Find: the validation order, and any place a token is
      trusted without being checked.
    - Read only — change nothing.
    - Return a short list, with file:line for each finding.

The second one tells the subagent where to begin, what "done" looks like, and the exact shape of the answer you want back. The tighter the brief, the more useful the summary — and the less likely you'll have to re-delegate because the first report missed the point.

The agents you get, and the ones you build

Out of the box you have a general-purpose agent — the one Claude reaches for when you ask it to go find something or run an open-ended, multi-step search. You don't configure anything; asking Claude to "investigate" or "search the codebase for…" often triggers it on its own.

The real leverage comes from custom agents. A custom agent is a Markdown file with a bit of YAML frontmatter and a system prompt in the body. It lives in one of two places:

• .claude/agents/<name>.md — project agents, checked into git and shared with your team.
• ~/.claude/agents/<name>.md — personal agents, available across all your projects.

When names collide, the project version wins. You can write these files by hand or scaffold them interactively with the /agents command, which also lets you pick tools and a model without memorizing the frontmatter. Here's a complete one:

---
name: test-author
description: Writes and runs tests for new code. Use PROACTIVELY after implementing a feature.
tools: Read, Write, Edit, Bash
model: sonnet
---
 
You write focused, high-signal tests. For any change:
1. Read the code under test and its existing tests.
2. Cover the happy path, edge cases, and error handling.
3. Run the suite and iterate until it's green.
Report only what you tested, what passed, and anything still failing.

Four fields carry all the weight:

• name — how you invoke it (use the test-author agent) and how it shows up.
• description — when to use it. Claude reads this to decide whether to delegate on its own, so write it like a trigger, not a bio. Phrases like "use PROACTIVELY" or "MUST BE USED" push it toward automatic delegation; leave them out and it mostly waits to be asked.
• tools — an allowlist. Omit it and the agent inherits every tool (including your MCP servers); narrow it and you get a safer, more predictable worker.
• model — a specific model for this agent, or inherit to match your main session. Put mechanical jobs on a cheaper, faster model and save the strong one for hard reasoning.

That tools field is more powerful than it looks. Drop Write and Edit and you've built a read-only agent that physically can't modify your code — perfect for a reviewer:

---
name: code-reviewer
description: Reviews a diff for bugs, security, and style. Use PROACTIVELY before every commit.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
You are a meticulous reviewer. Given a change:
1. Run `git diff` to see what changed.
2. Flag correctness bugs, security issues, and missing tests — most severe first.
3. Quote file:line for each point. Don't rewrite the code; report it.

When to reach for a subagent

Delegation isn't free — a subagent adds latency and spends its own tokens, and briefing it costs you a moment. So it earns its keep on some tasks and just gets in the way on others.

The common thread: delegate work whose result is small and self-contained, and keep work whose value is in the dialogue.

Running several at once: a multi-agent environment

Because each subagent is isolated, your main session can act as an orchestrator — firing off several at once and collecting their summaries as they finish. When the main agent issues multiple Task calls in a single turn, they run concurrently; a handful execute at a time and any extras queue up behind them. This is where the tool stops feeling like a chat box and starts feeling like a small team.

A concrete shape: you ask for a feature to be shipped, and the orchestrator fans the work out — one agent explores and maps the relevant code, one reviews the diff as it lands, one writes and runs the tests — each in its own window, each reporting back a summary. The orchestrator stitches those summaries together and keeps its own context clean the whole time.

Two patterns show up again and again:

• Fan-out search. Several read-only agents look for different things at once — one traces the data flow, one hunts for existing helpers, one checks the tests — and you get every answer back in the time the slowest one takes, not the sum.
• Find, then verify. One agent proposes a fix or flags a set of bugs; a second, skeptical agent is handed each claim and asked to confirm or refute it. Independent verification catches the plausible-but-wrong answers that a single pass waves through.

The catch is shared state. Isolated context windows are one thing; the filesystem is another. Point three agents at the same working directory and let them all edit, and they'll overwrite each other's changes. Reading in parallel is safe. Writing in parallel needs isolation.

Isolating parallel work with git worktrees

The clean way to get truly parallel, write-heavy work is git worktrees. A worktree is a second (third, fourth…) checkout of the same repo in its own folder, on its own branch — so each session gets a sandbox where its edits can't collide with anyone else's:

# one isolated checkout per parallel task
git worktree add ../app-auth -b auth-refactor
git worktree add ../app-perf -b perf-pass
 
# run a separate Claude Code session in each
cd ../app-auth && claude

Now two or three sessions can genuinely work at once — a refactor here, a performance pass there — and you merge each branch back when it's done. A few gotchas are worth knowing up front:

• Dependencies aren't shared. node_modules/ lives inside each worktree, so you'll typically npm install (or your equivalent) once per new worktree.
• Pick different ports. Two dev servers can't both bind :3000. Give each session its own port.
• Don't run stateful jobs in parallel. Two agents running database migrations against the same database will fight. Isolate the data too, or serialize those steps.
• Clean up when done. git worktree remove ../app-auth tidies the checkout after you've merged.

This is the difference between concurrency theater — agents that trip over each other — and real parallelism, where they structurally can't.

A worked example

Put it together and a typical "big" task flows like this:

1. Explore first. Delegate a read-only investigation — "map how notifications are sent today, and list every file involved." A summary comes back; your main window stays empty of the twenty files it read.
2. Plan from the summary. With just the distilled map in context, you and the main session agree on an approach.
3. Fan out the build. Independent pieces go to parallel sessions on separate worktrees; the test-author agent covers each as it lands.
4. Review before merge. The read-only code-reviewer agent audits each diff and reports back; a second pass verifies anything it flags.
5. Merge and clean up. Land the branches, remove the worktrees.

Notice the pattern: the heavy, lossy, read-everything work is always pushed outward to isolated windows, and your main session stays a lean control tower — exactly the Part 1 lesson, now operating at team scale.

Myths to avoid

• "A subagent remembers our conversation." It doesn't — it sees only its prompt and CLAUDE.md. Brief it fully.
• "More agents is always faster." Delegation has overhead; for trivial or tightly-coupled work, one session wins.
• "Parallel agents can share a folder." Only for reading. Parallel writes need separate worktrees, or they clobber each other.
• "A read-only agent might still edit something." Not if you leave Write/Edit out of its tools. The allowlist is a real boundary, not a suggestion.

Where to go from here

Two parts, one throughline: it was always about context. Part 1 kept a single window lean; Part 2 pushed the heavy work out to windows of its own and let a main session conduct the rest. Get comfortable with that — delegate the read-heavy, isolate the write-heavy, keep the center clean — and Claude Code stops being a tool you steer keystroke by keystroke and starts being something you direct.

Start small: write one custom agent for a job you repeat, and delegate your next big investigation instead of doing it inline. That's the whole habit. Thanks for reading — go build something.