Claude Code: A Practitioner's ApproachHow Product Builders Use Claude Code to Ship Faster Than Engineers
Chapter 6 · Claude Code: A Practitioner's Approach

Everything Now Passes Through Other Hands

Chain Agents Into One Command That Does an Afternoon of Work

The Floor Scrapers, Gustave Caillebotte, 1875
The Floor Scrapers (Les raboteurs de parquet), Gustave Caillebotte, 1875. Musée d'Orsay, Paris. Public domain. One floor, three men, three strips being worked at once.

On the cover: Caillebotte's The Floor Scrapers (1875), paired with Adam Smith on the pin factory. Picked because both are about the same discovery: a job that one person does in sequence gets finished in a fraction of the time when it is split into stages and handed between hands that each do one thing.

"One man draws out the wire; another straights it; a third cuts it; a fourth points it; a fifth grinds it at the top for receiving the head." Adam Smith, An Inquiry into the Nature and Causes of the Wealth of Nations, Book I

Claude Code's Agent Teams Are Insane, Multiple AI Agents Coding Together in Real Time, Cole Medin
Watch first (or come back to it): Claude Code's Agent Teams Are Insane, Multiple AI Agents Coding Together in Real Time, Cole Medin. Watching several agents work the same project at the same time does something that reading about it does not. The coordination problem becomes obvious about ninety seconds in, which is exactly the problem this chapter is about solving.

Caillebotte painted three workmen scraping the floor of an empty Paris apartment, and the jury of the 1875 Salon rejected it as vulgar subject matter. Nobody had painted urban laborers this way before, stripped to the waist, on their hands and knees, filling the whole foreground of a canvas that size. He showed it the following year at the second Impressionist exhibition instead, which tells you roughly how seriously he took the jury's opinion. The room is bourgeois and unfinished. Tall windows with an ornate iron balcony grille let in a flat white daylight that runs down the length of the boards and makes the whole floor look like a set of rails. Curled wood shavings lie everywhere. There is a hammer on the floor and, over at the right edge, a dark wine bottle with a glass beside it. One man works alone at the left on a patch that has already come up pale and clean. The other two are bent together over the strips on the right, still on the dull raw wood, backs curved into the same shape, each pulling a scraper along a different board.

What makes the picture worth looking at twice is that you can read the whole job in one glance. The floor is striped. Some boards are bright where they have been worked, others are still dull where nobody has reached them. The stages of a single task are all visible at the same instant because three men are standing at three different points of it. Nobody is waiting. Nobody is watching anyone else. The room gets finished in something close to a third of the time it would take one man with one scraper, and the only reason it works is that the boards can be divided up without any of the three needing to consult the others.

That is this chapter. In the last one you built a bench of specialists and called them one at a time, waiting for each to finish before you briefed the next. It worked, and it was still fundamentally you standing in the room doing one thing at a time, just with better help. Now the specialists stop waiting. You are going to write a single prompt that starts a chain, hands the output of each stage to the next, and where the work genuinely allows it, puts four or five of them on different boards at once. Smith noticed the same thing in a pin factory in 1776 and calculated that ten specialized workers could make forty-eight thousand pins a day where ten generalists, each making a whole pin start to finish, would manage perhaps two hundred. The arithmetic has not changed. Only the hands have.

In This Chapter

6.1 What a Pipeline Is

You ended the last chapter with three agents you could summon by name, and you summoned them the way you would summon three colleagues: one at a time, reading each result, deciding what to do next, then briefing the following one. That is a perfectly good way to work and it's also the expensive way, because the thing making every decision between stages is you, and you are the slowest component in the system.

A pipeline is what you get when you describe the whole sequence up front instead. You name the stages, you say what each one produces, and you say what the next one is supposed to do with it. Then you send that as one instruction and let Claude Code run the chain. The research agent goes and researches. Its findings become the input to the drafting stage. The draft becomes the input to the reviewer. You read the thing that comes out of the far end. Three specialists still did three jobs in order, exactly as before, but you spent your attention once instead of three times.

Three words are worth pinning down before we go further, because the rest of the chapter leans on them. A stage is one unit of work with one owner, usually a sub-agent. A handoff is the moment one stage's output becomes the next stage's input, and it is where almost every pipeline that fails, fails. An artifact is the concrete thing a stage produces, a briefing document, a draft spec, a list of findings, ideally written to a file rather than left floating in a conversation. Caillebotte's floor has all three in it. The stages are scrape, smooth, finish. The handoff is the boundary between one man's boards and the next man's. The artifact is the strip of floor itself, sitting there, visible, impossible to misremember.

The reason artifacts matter more in software than in flooring is that a scraped board stays scraped. A finding that lives only in an agent's context window does not stay anywhere at all.

6.2 Single-Prompt Multi-Agent Execution

Having named the parts, the question is how Claude Code decides to use them, because you never call a sub-agent by function name and you never write anything resembling code. You describe the work, and the matching happens on the strength of the description field you wrote in each agent file back in Chapter 5.

This is why that field is worth more care than it looks like it deserves. When you write "Use the research agent to survey the market, then draft a one-page PRD, then have the PRD reviewer critique it," Claude Code reads your sentence, reads the descriptions of the agents available to it, and works out that stage one belongs to research-agent and stage three belongs to prd-reviewer. A description that says "Researches things" gives it almost nothing to match on. A description that says "Researches competitors, market trends, or background context; use when asked to research, analyze competitors, or gather market information" gives it a decision it can actually make. The delegation is only as reliable as the labels on the doors.

Two structural facts about how the machinery runs will shape how you write these prompts, and they are worth knowing before you write a bad one.

The first is that sub-agents genuinely do run at the same time when the work allows it. Claude Code will hold up to twenty of them concurrently by default before it starts refusing to spawn more, and the ceiling is adjustable through the CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS setting if you ever have reason to move it. Twenty is far more headroom than any product manager needs. In practice you will find yourself running three to six, and the limit exists mostly so a runaway instruction cannot open a hundred sessions on your account.

The second fact is the constraint that shapes everything else: sub-agents cannot talk to each other while they are working. Each one runs in its own context, finishes, and returns its result to your main conversation. It has no idea the others exist. If researcher three finds something that would change what researcher four is looking for, there is no channel for that to happen, and no amount of prompt wording will create one. Every piece of information that needs to travel between specialists has to route through the middle, which means it has to survive a stage boundary. That single limitation is the reason section 6.4 exists, and it is also the thing Agent Teams was built to remove, which is why section 6.6 exists.

Deeper read: Claude Code Workflows: Deterministic Multi-Agent Orchestration, Alex Opalic

The clearest available treatment of the difference between letting the model decide the shape of the work and deciding it yourself. His framing is that a normal agent works out its control flow as it goes, while a workflow inverts that: you write the sequence, and each step gets a fresh specialist. Written for engineers, but the argument is a product argument, and the section on when to make stages wait for each other is the best short explanation of the tradeoff in this chapter.

6.3 Real Pipeline: Competitive Research to Reviewed Spec in One Command

Enough scaffolding. Here is the pipeline that will earn back the time you spent reading this chapter, built from the three agents you already have.

Start with the version you met at the end of Chapter 5, which runs strictly in a line:

Use the research-agent to survey the top five players in the AI meeting
notes market. Then draft a one-page PRD for our version. Then use the
prd-reviewer to critique that PRD and tell me what to fix before v1.

That works, and on a good day it takes fifteen or twenty minutes and produces something you would not be embarrassed to open in a room. It's also doing the research stage the slow way, because one researcher is reading five companies one after another, exactly like one man scraping a floor board by board.

Now split the first stage across five hands:

I am scoping a competitor for the AI meeting notes market.

Stage 1: spawn one research-agent per company for Otter, Fireflies,
Granola, Fathom, and Read AI. Each one researches only its own company:
positioning, pricing tiers, the two features they lead with, and the
complaint that shows up most often in their reviews. Have each write its
findings to docs/research/<company>.md.

Stage 2: read all five files and give me one comparison table plus the
three gaps nobody is covering.

Stage 3: draft a one-page PRD for our entry, aimed at the largest gap.

Stage 4: use the prd-reviewer on that draft. Return its three risks,
three edge cases, and the scope-creep flag.

Read what changed. Stage 1 is now five independent jobs with no dependency on each other, so they run together and the whole stage costs roughly what the slowest single company costs rather than the sum of all five. Stages 2, 3 and 4 stay strictly in order, because each one genuinely needs the finished output of the one before it. You cannot write the comparison table until all five researchers are done, you can't draft against a gap you haven't identified yet, and there's nothing to review until a draft exists.

That shape, a wide parallel stage at the front narrowing into a sequential tail, is the one you will reach for most often. Reading is wide. Deciding is narrow. Almost every useful product-manager pipeline turns out to have that silhouette, because the expensive part is nearly always gathering, and the part that must not be rushed is nearly always judgment.

The honest accounting: this replaces something that used to take most of an afternoon, and it now runs while you get a coffee. It doesn't replace your judgment about whether the gap it found is a real gap. Stage 4 exists precisely because stage 3's output should not go anywhere near a stakeholder without something adversarial having read it first.

Code companion: the five agents this pipeline calls ship with the course repo at .claude/agents/, and demos/skill-sub-multi-agent/ is a worked version of exactly this pattern, a skill and several sub-agents wired into one chain, if you want to read a finished one before writing your own.

6.4 Managing Handoffs Between Agents

The pipeline above will work, and then one day it will produce a PRD that has almost nothing to do with the research that preceded it, and you will not immediately understand why. The failure is nearly always at a handoff, and it has a single cause: the next stage did not receive what you assumed it received.

Remember the constraint from 6.2. A sub-agent finishes and hands back a summary. It does not hand back everything it read, and it shouldn't, because the whole reason you delegated was to keep the noise out of your main thread. But that means the drafting stage is working from a compressed account of what five researchers found, and compression loses things. If the summary said "Granola leads on speed" and dropped the detail that Granola's speed claim only holds for meetings under twenty minutes, your PRD will be built on a fact that's two thirds true.

Four habits fix most of this, and the first one fixes most of the first one.

Write artifacts to files, not to the conversation. This is why stage 1 above tells each researcher to write to docs/research/<company>.md. A file is durable, inspectable, and re-readable. When stage 2 reads five files it is reading what the researchers actually wrote, not a summary of a summary. When something looks wrong three stages later you can open the file and see where the fact went bad. Handoff through the filesystem is dramatically more reliable than handoff through context, and it costs you one clause in the prompt.

Name the artifact in both directions. The stage that produces it should be told exactly what to call it, and the stage that consumes it should be told exactly what to read. Vagueness at a boundary is where a pipeline quietly starts improvising.

Say what to carry forward, not just what to do. "Draft a PRD" leaves the model to decide which of the research findings matter. "Draft a PRD for the largest gap identified in stage 2, and cite the specific competitor weakness it exploits" tells it which thread to keep hold of. Stages are not psychic about your intent any more than the man scraping the second strip is psychic about the first man's standards.

Put the check inside the pipeline. The reviewer stage is not decoration. It's the thing that catches the compressed fact that turned into a false claim. A pipeline with no adversarial stage is a machine for producing confident documents, which isn't the same as producing correct ones.

6.5 When Parallel Wins, and When It Just Burns Money

Everything so far has been about making parallelism work. This section is about the cases where it does not, and it is the section most worth reading twice, because the failure mode is expensive and completely invisible while it is happening.

Parallel execution buys you wall-clock time. It doesn't buy you tokens. Five researchers running at once do not read five companies for the price of one; they read five companies for the price of five, all at the same moment. What you are trading is money for time, and that is often an excellent trade, but you should know that you're making it.

The numbers are worth having in front of you. The AI Builder Club's write-up on fanning out sub-agents measures a parallel test-generation job across six modules dropping from about twelve minutes to about three, and puts the general shape of the trade at three to six times the token cost for a fifty to eighty percent cut in wall-clock time. Eric Cheng, writing up a three hundred file refactor, watched Claude Code spin up five parallel sessions without being asked and found the job finished in fifteen minutes instead of thirty while consuming his plan's usage allowance at twice the rate. His summary is the sentence to remember: the per-file cost doesn't change, you are simply paying for every session at once.

So the trade is good when the time matters and the tasks are genuinely independent. It's bad in three specific situations, and they are worth naming because each one looks superficially like a job for parallelism.

Sequential work dressed up as parallel work. Explore, then plan, then build, then test is a chain where every step needs the previous step's context. Handing those four steps to four sub-agents is worse than doing them in one session, because each agent loses the context the next one needs and you pay four times for the privilege. Parallelism is not a general-purpose speed setting. It only applies where the work actually forks.

Tasks too small to be worth the setup. Spawning a sub-agent costs a few seconds and a few hundred tokens before it does anything useful. For a thirty second job, that overhead is the whole job. Ask yourself whether you would delegate this to a colleague or just do it; the answer transfers.

Work that needs mid-flight coordination. If what researcher A finds should change what researcher B is looking for, sub-agents can't help you, because they can't reach each other while running. Trying to force it produces five agents confidently duplicating each other's work. This is the case that Agent Teams exists for, and it is next.

The rule of thumb that survives all three: fan out on reading, stay serial on deciding. Gathering, surveying, auditing, and reviewing from independent angles all parallelize beautifully. Choosing, drafting, and sequencing don't.

From the field: Claude Code Sub Agents, Burn Out Your Tokens, Eric Cheng

A short practitioner write-up from someone who hit the cost side of this trade without expecting to, on a large refactor where Claude Code parallelized on its own initiative. Worth ten minutes before you run your first wide fan-out, if only so the usage meter does not surprise you the way it surprised him.

6.6 Agent Teams: When the Specialists Talk to Each Other

Everything in this chapter so far has worked around the same wall: sub-agents finish and report, and they never speak to each other. Agent teams take that wall down.

An agent team is a set of full Claude Code sessions rather than a set of delegated tasks. One session is the lead, which is the one you're typing into. The others are teammates, and each is a complete independent session with its own context window, able to message any other teammate by name and to claim work from a task list the whole team shares. The lead spawns them, assigns work, and synthesizes what comes back, but it's no longer the only route between one worker and another.

The difference from the bench you built in Chapter 5 comes down to four things:

DimensionSub-agentsAgent teams
ContextOwn window; result returns to the callerOwn window; fully independent
CommunicationReports back to the main agent onlyTeammates message each other directly
CoordinationThe main agent manages everythingSelf-coordination through messages and a shared task list
Token costLower, results come back summarizedHigher, each teammate is a separate session

Agent teams are experimental at the time of writing and switched off unless you turn them on. You enable them by adding one entry to your settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

After that you ask for a team in plain language, the same way you have asked for everything else in this book:

I am deciding whether to build meeting-notes summarization in-house or
buy it. Spawn three teammates to explore this from different angles: one
on the build case, one on the buy case, and one playing devil's advocate
against whichever looks stronger. Have them challenge each other's
findings, then give me the consensus and where it broke down.

That prompt's doing something the pipeline in 6.3 structurally could not. The three teammates argue. The devil's advocate reads what the other two produced and attacks it, they respond, and what reaches you is a position that has already survived a fight. Anthropic's own documentation leans on exactly this pattern for debugging, spawning several teammates on competing hypotheses and instructing them to try to disprove each other, on the reasoning that a single investigator tends to find one plausible explanation and stop looking.

A handful of practical notes, because this is a feature with edges.

Start with three to five teammates. The documentation is explicit that returns diminish past that, and that three focused teammates routinely beat five scattered ones. Give each one an ownership boundary, because two teammates editing the same file will overwrite each other; split by module, by layer, or by document, never by "help with this." Expect the token bill to scale roughly linearly with the number of teammates, since each is a full session rather than a summarized task. Teammates load your CLAUDE.md and your project skills automatically, which is one more reason Chapter 2 mattered, but they do not inherit the conversation you have been having with the lead, so anything they need has to be in the spawn instruction.

One note specific to how this book works. Teams run in one of two display modes. The split-pane mode, where each teammate gets its own visible pane, needs tmux or iTerm2 and is not supported inside VS Code's integrated terminal. The default in-process mode runs the whole team inside your existing session and works everywhere, and it's the one to use. Your teammates appear in a panel under the prompt, you move between them with the arrow keys, and pressing Enter opens a teammate's transcript so you can read what it is doing or send it a correction directly. That's the entire interface. It's less dramatic than four panes of scrolling text and it loses nothing that matters.

Because the feature is experimental, treat it as an accelerator rather than a foundation. Teams do not survive a session resume cleanly, a teammate cannot spawn teammates of its own, and a session has exactly one team for its lifetime. None of that will bite you on a two-hour research problem. All of it would bite you if you built a weekly ritual on top of it before it settles.

6.7 Context Hygiene: Keeping Sessions Clean

There is a reason this section closes the chapter rather than opening it. Everything you have just learned makes it easier to fill a context window with material you do not need, and a session that has been filled with noise gets measurably worse at the thing you are actually doing.

The mechanism is worth stating plainly, because it's easy to mistake for the model having a bad day. Your main conversation carries everything: your prompts, the files that were read, the tool results, the returned summaries. As that pile grows, the proportion of it that is relevant to your current question shrinks. The model is not getting less capable. It's getting less focused, and the symptom looks like it forgetting a decision you made forty minutes ago.

Sub-agents are the best hygiene tool you have, which is a nice piece of symmetry to end on. The five researchers in 6.3 read a great deal of material and none of it landed in your session; you got five files and five short summaries. That is the whole point of delegation, and it is worth choosing delegation sometimes purely for the cleanliness rather than the speed. The official documentation flags the other side of this too: running many sub-agents that each return long detailed results can consume significant context all by itself, so ask for short returns and put the long version in a file.

Three habits carry the rest.

Clear between unrelated jobs. When you finish the competitor pipeline and move to writing next quarter's OKRs, start a fresh session rather than continuing in the old one. /clear costs you nothing, because everything durable is either in a file or in CLAUDE.md. The instinct to preserve a long session is a habit borrowed from chat tools, and it doesn't serve you here.

Let files be the memory. Anything that matters after this session should exist as a file. Research goes in docs/, decisions go in CLAUDE.md, specs go where specs go. A session is a workspace, not a filing cabinet.

Notice the tell. When Claude Code starts re-asking things it already knows, or contradicting a constraint you set earlier, that's the signal. Don't argue with it and don't repeat yourself more loudly. Save what you need, clear, and come back with a clean thread and a short brief. It takes ninety seconds and it fixes the problem completely.

6.8 Chapter Assignments

Exercise 6.1: Turn one of your sequential habits into a pipeline.

Pick something you currently do in three separate passes, a competitor scan that becomes a positioning note, or interview notes that become themes that become a research summary. Write it as a single staged prompt with the artifacts named and the file paths spelled out. Run it once, then compare what comes out against what you'd have produced by hand. Be honest about which is better. The first pipeline you write is usually worse than your manual version, and the second one usually isn't.

Exercise 6.2: Fan out the widest stage, then break it on purpose.

Take the pipeline from 6.1 and split its widest stage across four or five sub-agents, one per item, each writing to its own file. Time both versions and write the two numbers down, wall-clock and your rough sense of the cost, because the second one is what you'll be asked about. Then run it once more with the file step removed, so the final stage works only from what the earlier stages summarized back. Read the two outputs side by side. That five-minute experiment is what makes 6.4 stick.

Exercise 6.3: Run one agent team and watch it argue.

Enable the setting, then point the build-versus-buy prompt from 6.6 at a decision you're actually facing this quarter. Open at least one teammate's transcript with the arrow keys and Enter, and read how it made its case. Note the one thing the team surfaced that a single session would have settled too early, and note what it cost you. Then write your own fan-out rule, one sentence on when you'll reach for parallel agents and when you won't, into your CLAUDE.md. You'll break the rule eventually, and the note is what will tell you that you did.

6.9 Prompts Worth Saving

The staged pipeline skeleton:

Stage 1: [gathering work], one agent per [item]. Each writes to
docs/[folder]/<item>.md.
Stage 2: read all files and produce [the synthesis].
Stage 3: draft [the artifact] against [the specific finding from stage 2].
Stage 4: use the [reviewer] on that draft and return its findings.

Fan out a survey:

Spawn one research-agent per company for [A, B, C, D, E]. Each researches
only its own: positioning, pricing, the two features they lead with, and
the most common complaint. Each writes to docs/research/<company>.md.

Force a clean handoff:

Read docs/[file].md before you start. Draft against the largest gap named
in it, and cite the specific competitor weakness it exploits.

Spawn an arguing team:

Spawn three teammates to explore [decision] from different angles: one
for [position A], one for [position B], one playing devil's advocate
against whichever looks stronger. Have them challenge each other's
findings, then give me the consensus and where it broke down.

Reset a tired session:

Summarize everything decided in this session into docs/decisions.md, then
tell me what to put in CLAUDE.md so I do not have to re-explain it.

Summary

  • A pipeline describes the whole sequence up front: the stages, what each one produces, and what the next one does with it, all sent as one instruction. Three specialists still do three jobs in order, but you spend your attention once instead of three times.
  • Every pipeline is built from stages, handoffs, and artifacts. The handoff, where one stage's output becomes the next stage's input, is where almost every failing pipeline fails.
  • Claude Code matches each stage to a sub-agent using the description field in that agent's file, so delegation is only as reliable as those labels. Sub-agents can run at the same time, but they cannot talk to each other while working, so anything that has to travel between them goes through your main conversation.
  • The most useful pipeline shape is a wide parallel stage at the front narrowing into a sequential tail. Reading is wide and deciding is narrow, so a fan-out stage costs roughly what its slowest job costs, while drafting and reviewing stay strictly in order.
  • Sub-agents hand back compressed summaries, and compression loses things. Write artifacts to files, name each artifact in both directions, say what to carry forward, and put an adversarial reviewer stage inside the pipeline.
  • Parallelism buys wall-clock time, not tokens: five researchers at once cost five researchers, paid all at the same moment. It's the wrong trade for sequential work dressed up as parallel work, for tasks too small to be worth the setup, and for work that needs coordination mid-flight. Fan out on reading, stay serial on deciding.
  • Agent teams take down the wall between specialists. Teammates are full sessions that message each other and share a task list, so what reaches you is a position that has already survived a fight. They're experimental, switched on through one settings.json entry, and best started at three to five teammates with clear ownership boundaries, with the token bill growing as you add teammates.
  • Teammates load your CLAUDE.md and project skills but not your conversation with the lead, so the spawn instruction must carry everything they need. Use the default in-process mode inside VS Code, and treat teams as an accelerator rather than a foundation until the feature settles.
  • A session filled with noise gets less focused, not less capable. Sub-agents are your best hygiene tool, so ask them for short returns and put the long version in a file. Use /clear between unrelated jobs, let files be the memory, and when Claude Code starts re-asking or contradicting earlier decisions, save what matters, clear, and come back with a short brief.

What's Next

You came into this chapter with a bench of specialists who worked one at a time and you're leaving with a floor that gets scraped by three hands at once. The pipeline is the shape: wide where the work is reading, narrow where the work is judgment, with the artifacts written down at every boundary so nothing has to be remembered. The teams are the shape after that, for the days when the specialists need to argue rather than report.

There's a question this chapter kept deferring. Every agent you've spawned had a model behind it, and every time you've picked one you've picked it on instinct or left the default alone. A researcher reading five web pages, a reviewer tearing apart a spec, and five teammates running at once aren't the same kind of work, and paying the same rate for all of them is how the cost side of this chapter gets away from you. The Models We Reach For at 2am is about that choice: what Opus, Sonnet and Haiku are actually for, what each one costs you, and how to stop reaching for the most expensive one out of nervousness.

More:

Sources used in this chapter: