Subagent prompts: why every fork needs its own brief

Give every forked agent its own brief, not a copy of the parent's. A subagent prompt is the short contract a child agent carries: its goal, the paths it may touch, the paths it must not, the command that proves its work, and the person who owns the merge. When you reuse the parent prompt for every child, you copy the parent's ambiguity down the whole tree, and the children apply it to files the parent never thought about. In Cursor, Anysphere's AI code editor, that gap usually surfaces in the review queue, which is the worst place to find it.

We watched this happen on a live workshop call. A parent agent reported success while one of its children had quietly edited paths the parent never owned. The summary read clean. The diff did not. Nobody had signed the change, so nobody caught it until review.

Write a brief each child can be held to

Start with five lines. A subagent prompt does not need to be long to be useful, it needs to be specific. Goal, allowed paths, forbidden paths, verification command, merge owner. If a child cannot name its own scope, it should not be running yet.

The reason this matters is that delegation rarely breaks at the model. It breaks at the handoff, where parent intent and child scope drift apart and no artifact records who owned what. A separate brief forces that disagreement into the open before the diff lands, when it is cheap to fix.

Here is a brief you can paste into a child's first message and adapt:

Goal: add rate-limit headers to the public API responses.
Allowed paths: src/api/**, tests/api/**
Forbidden paths: src/auth/**, infra/**, any MCP connector
Verify: pnpm test -- tests/api && pnpm lint src/api
Merge owner: @priya

Make children return receipts, not summaries

A child should report what it did, not how it felt about the work. The receipt is three things: the paths it touched, the commands it ran, and the tests that prove existing behavior still holds. Prose is not a receipt. A parent that green-lights a summary is approving work nobody inspected.

This is where chained agents leak. Each link returns a tidy paragraph that omits the child-owned paths underneath it, and the parent confidently merges a diff it cannot fully see. The fix is boring and it works: every child returns its receipt in a fixed shape, and the parent checks that shape against the actual change.

Stop review-queue theater with a decision stub

Green CI is not a reason. Reviewers keep asking "why this approach?" and finding no written answer anywhere, so the review becomes a vibe check that optimizes for checks passing. Force three lines into the pull request template and the debate moves to something real:

• Constraints considered
• Alternatives rejected, and why
• Verification proof (the command and its output)

Now a reviewer compares the stub to the diff instead of reconstructing intent from chat history. Replay becomes a debugging tool, not a review requirement.

Card every connector before a child can fire it

A connector wired up in a hurry tends to reach data nobody put on the diagram, and a forked child can trigger it without the parent noticing. Give each MCP server one markdown card: allowed actions, forbidden actions, owner, rollback. Operators should know what "off" looks like before any child touches it. The OWASP and NIST guidance below is a good sanity check for which actions belong on the forbidden line.

A single rules file can hold the delegation boundary for whatever tool you run:

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

The handoff is healthy when a stranger can answer four questions from the pull request alone:

If your repo cannot state its boundaries plainly, the children will guess, and guessing scales badly. Keep the human strategist above the automated worker. Our agentic coding training walks teams through turning each of these into a rule, a receipt, and a checklist.

Common questions

Why do subagent prompts need to be separate from the parent prompt? Because a shared prompt carries the parent's ambiguity into every child, and the children apply it to paths the parent never considered. A separate brief pins the goal, allowed paths, forbidden paths, verification command, and merge owner, so disagreement surfaces before the diff lands rather than in the review queue.

What should a subagent return when it finishes? A receipt: the paths it touched, the commands it ran, and the tests proving existing behavior still holds. Summaries are not receipts. A parent that accepts prose instead of artifacts is approving work nobody inspected, which is how mystery diffs reach review and get merged before anyone notices the missing scope.

How do we review parallel forks without replaying every chat? Check briefs against diffs. Each fork carries a five-line scope ledger, each pull request carries a decision stub with constraints and rejected alternatives, and reviewers compare those artifacts to the change itself. Replay then becomes a way to debug a surprise, not a requirement for every review.

Does this slow the team down? A little, at the front, and it saves more at the back. Writing five lines of scope and a three-line stub costs a minute per fork. Catching an out-of-bounds child before merge, instead of after a production incident, saves an afternoon. The cost lands where it is cheap and the savings land where mistakes are expensive.

Where to start

Pick the next forked run on your board and give one child a written brief, a receipt, and a decision stub before it executes. See agentic coding governance for the wider playbook once the pattern sticks.

Further reading

• Claude Code docs: getting started
• OpenAI Developers: Codex quickstart
• OWASP Top 10 for Large Language Model Applications
• NIST AI Risk Management Framework
• Google Search Central: helpful, people-first content
• Google Search Central: generative AI content guidance
• OpenAI Skills repository