Lesson 3: Writing Prompts for Delegation
Learning goals:
- Write a self-contained delegation prompt that doesn't rely on the subagent seeing the conversation between you and the orchestrator
- Spell out the task's scope, boundaries, and which sources to use inside the delegation prompt itself
- Explain the "one problem domain, one agent" principle and what breaking it costs you
Prerequisites: Finish Lesson 2 and understand the orchestrator-subagent architecture and context isolation | Previous: Lesson 2 << | Next: Lesson 4 >>
Recap: Anything the Subagent Can't See, You Have to Write In for It
Lesson 2 covered one mechanism that matters here: "Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read. Claude composes a delegation message that summarizes the task, and the subagent works from there."1 This lesson makes that concrete. It means all the background you talked through with the user at the orchestrator level, the tradeoffs you settled in earlier rounds, the offhand constraint the user tossed in — the subagent knows none of it. The only thing the subagent knows is whatever words you wrote into this one delegation task.
This isn't a gentle reminder, it's a hard constraint: the quality ceiling of the delegation prompt sets the quality ceiling of what the subagent produces. Anything the prompt doesn't spell out, the subagent will either guess at, skip, or invent an assumption for and keep going. Guess right and you got lucky. Guess wrong and that whole subtask is basically wasted.
Self-Contained: The Prompt Has to Say the Whole Thing on Its Own
Self-contained: after reading a delegation prompt, the subagent needs no extra background to work out accurately what it should do. There's a simple test for whether a prompt is self-contained. Pull it out on its own, strip away all the context between you and the orchestrator, and read it cold. If you still have to guess to fill in the task details, the prompt fails the test.
Take the Lesson 1 example of researching pricing across three cloud providers. If the orchestrator hands the subagent a task that says only "look up AWS pricing," that one line carries enough information for the orchestrator itself — because the orchestrator's context still holds the background of "why we're looking this up," "who we'll compare it against afterward," and "what dimensions we're comparing on." But the subagent can't see any of that. What it receives is one lonely line, "look up AWS pricing," and it's left to guess: pricing for which product categories? Just current prices, or the changes over the past year? What should the deliverable look like once it's found? Every guess is a bet that can go wrong.
Spell Out Scope and Constraints: What to Do, What Not to Do, Which Sources to Use
The official guidance lists what a solid subagent task description should contain: "Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries. Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information."2
Break that list open. "Objective" and "output format" are easy to grasp. The two that get skipped are the last pair — source guidance and task boundaries. Source guidance tells the subagent where to look for the answer: the official pricing page, a third-party price-comparison site, or both with the official page taking precedence. Task boundaries tell the subagent this run only covers this slice, don't reach beyond it: only current prices, no historical price changes; only the main product lines, don't list out every obscure service. Miss those two and the subagent tends to drift one of two ways. It either misses information you actually wanted, or it fetches far more than you wanted and burns tool calls and tokens you could have saved.
Rewritten as a self-contained task description with clear scope, the cloud-provider research looks roughly like this:
Pulled out on its own, this description lets the subagent judge accurately "what to look up, how far to take it, what to deliver" without knowing anything the orchestrator discussed internally.
The Counterexample: Vague Instructions Leave Subagents to Improvise
What actually goes wrong when you don't spell out scope and boundaries — the official team gave a real example from practice: "We started by allowing the lead agent to give simple, short instructions like 'research the semiconductor shortage,' but found these instructions often were vague enough that subagents misinterpreted the task or performed the exact same searches as other agents."2
"research the semiconductor shortage" reads like it hands over a task, but it pins down nothing — over what time range? Focused on the supply side, the demand side, or policy impact? Delivered in what form? Three subagents handed the same vague instruction will very likely all search toward "the causes of the semiconductor shortage," the angle that comes to mind first, and the result is three heavily overlapping bodies of research, while the angles that actually needed coverage (say, the impact on downstream industries, or how different countries responded) go untouched. This is the root, at the prompt level, of the "duplicated work" problem from Lesson 2 — it's not that the subagents won't listen, it's that the task description itself never drew the boundaries.
One Problem Domain, One Agent
Beyond writing a single prompt clearly, how multiple subagents split the work also follows a principle you can distill from official practice — the official team never named it, this naming is ours: one problem domain, one agent — each subagent should own only one class of clearly bounded problem, rather than having a single subagent juggle several unrelated things at once.
The official system has a direct example: they set up a dedicated CitationAgent, "a CitationAgent, which processes the documents and research report to identify specific locations for citations. This ensures all claims are properly attributed to their sources."2 Finding where citations go is a completely different kind of work from "researching some company's pricing strategy" — the former is checking and locating, the latter is searching and judging. Hand both to the same subagent and it has to switch back and forth between two entirely different modes of thinking, and its task description grows long and tangled from trying to serve two objectives, easy to shortchange one for the other. Split into two focused subagents, each one's task description stays simple and clearly bounded — which echoes the yardstick from Lesson 1: if it can be split into independent subtasks, it's worth splitting.
Recap
- The subagent can't see the orchestrator's conversation history,1 which means a delegation prompt has to be self-contained: readable on its own, apart from any conversational background, and still enough for the subagent to judge accurately what it should do.
- A solid task description has to contain an objective, an output format, source guidance, and clear task boundaries; without these, subagents duplicate work, leave gaps, or fail to find necessary information.2
- The official real-world counterexample proves that vague instructions like "research the semiconductor shortage" lead subagents to misinterpret the task or run the exact same searches as other subagents2 — scope and boundaries aren't optional, they're the key to avoiding duplicated work.
- One problem domain, one agent (this lesson's distillation of official practice): each subagent should own only one class of clearly bounded problem, like setting up a dedicated CitationAgent to handle citation locations, splitting work of different natures across different subagents2 so each task description stays simple and focused.
- To judge whether a delegation prompt is good enough, the test is simple: pull it out on its own and read it once, and see whether the subagent has to guess to fill in the task details.
>> Lesson 4: Collaboration Patterns: Pipeline, Review, Voting