Claude Code Subagents Workflow: A Production Guide

The claude code subagents workflow is the pattern that separates toy demos from production-grade engineering automation. A subagent is a Claude instance spawned by a coordinator to handle a bounded slice of a larger task, isolated from the parent's context, and returning a structured result. Get the decomposition right and you compress multi-hour engineering tasks into minutes. Get it wrong and you accumulate context bloat, branch collisions, and silent attribution loss. This guide covers the mechanics, the decision rules, and the guardrails that actually hold under load.

What is a subagent in Claude Code, and when should you spawn one?

A subagent is a fresh Claude Code session launched by a coordinator agent to execute a narrowly scoped task. It starts with an empty context window, receives only what the coordinator explicitly passes, and returns a structured result. The coordinator never shares its full conversation history with the subagent; that isolation is the point.

The spawn decision comes down to three criteria:

1. Independence -- the subtask does not depend on in-flight results from a sibling subtask.
2. Scope clarity -- the subtask has a clear input contract and a verifiable output.
3. Context cost -- keeping the work in the parent thread would dilute attention across unrelated tokens.

When all three hold, spawn. When the subtask is tightly coupled to the parent's evolving state, stay single-threaded. The Agentic Architecture & Orchestration domain of the CCAR-F exam (weighted at 27%) tests exactly this judgment call, making it the highest-stakes domain on the paper.

How does the coordinator decide which subagents to spawn?

The coordinator's job is decomposition, dispatch, and synthesis. It does not execute tasks itself; it routes them. A well-designed coordinator follows a hub-and-spoke architecture: one central orchestrator, N specialist subagents, no peer-to-peer chatter between subagents.

The decision logic looks like this:

Coordinator dynamic subagent selection is a model-driven decision: the coordinator inspects the task, classifies it, and selects the appropriate specialist. This is distinct from pre-configured routing, where the pipeline is fixed at design time. For most production engineering workflows, a hybrid works best: fixed routing for well-understood task types, dynamic selection for novel or ambiguous requests.

Parallel vs sequential spawning

For parallel spawning across engineers on the same repository, the safest guard is to assign each subagent a disjoint file set before spawning. Overlapping write targets are the primary cause of branch collisions in team settings.

How should you structure CLAUDE.md to keep subagents on-task?

CLAUDE.md is the primary mechanism for encoding repo-specific rules that every Claude Code session inherits. Without it, subagents default to general coding conventions that may conflict with your codebase's standards.

A production-grade CLAUDE.md for a subagents workflow has three layers:

1. Scope constraints -- explicit file and directory boundaries the agent is permitted to modify.
2. Style and convention rules -- formatting, naming, import order, test requirements.
3. Verification requirements -- what the agent must confirm before returning a result (tests pass, linter clean, diff is minimal).

# CLAUDE.md

## Scope
- Modify only files under `src/` and `tests/`.
- Do not reformat files outside the direct change scope.
- Do not alter `package-lock.json` or `yarn.lock` unless explicitly instructed.

## Conventions
- TypeScript strict mode; no `any` types.
- All new functions require a JSDoc comment.
- Test files mirror source paths under `tests/`.

## Verification
- Run `npm test` before returning. If tests fail, diagnose and fix before reporting.
- Report the diff size (lines added / removed) in your structured output.
- If a change would affect more than 50 lines outside the target file, pause and ask.

The three-level configuration hierarchy means that a root-level CLAUDE.md sets defaults, directory-level files narrow scope, and user-level settings handle personal preferences. Subagents inherit the hierarchy from the directory they are launched in, so placing task-specific CLAUDE.md files in subdirectories is a clean way to scope subagent behaviour without polluting the root config.

Per the version control implications of this hierarchy, the root and directory-level files should be committed to the repository. User-level files should not. This distinction matters for teams: committed files enforce shared standards; uncommitted files allow individual customisation without drift.

What verification loop should you trust for agentic coding outputs?

The weakest verification loop is "the model says it's done." The strongest is a deterministic external signal: tests pass, the linter exits zero, the diff is within scope. The CCAR-F exam consistently rewards deterministic solutions over probabilistic ones when stakes are high -- a principle that applies directly to verification design.

A practical three-stage loop:

Stage 1: Structural check
  - Does the output match the expected schema or interface?
  - Is the diff scoped to the declared target files?

Stage 2: Functional check
  - Do unit tests pass?
  - Do integration tests pass for affected paths?

Stage 3: Semantic check (human or LLM-as-judge)
  - Does the change accomplish the stated goal?
  - Are there unintended side effects?

Stage 3 is the only probabilistic stage. For high-stakes changes (security patches, data migrations, public API modifications), route Stage 3 to a human via a structured handoff. For routine changes, an independent review subagent can handle it -- but note the self-review limitation: a subagent reviewing its own output is not independent. Spawn a separate instance with only the diff and the acceptance criteria.

How do you orchestrate Claude Code with MCP servers without bloating context?

MCP servers extend what subagents can do: read from databases, call external APIs, write to filesystems, trigger CI pipelines. The risk is tool overload -- a subagent with 40 tools available spends attention on tool selection rather than task execution.

The solution is scoped tool distribution: each subagent receives only the tools relevant to its declared scope. A subagent tasked with reading test results needs the CI log tool, not the database write tool.

Practical MCP scoping for a subagents workflow:

Environment variable expansion in MCP config lets you parameterise tool access at launch time, which is the cleanest way to scope credentials per subagent without hardcoding secrets into CLAUDE.md.

For context management, the rule is: pass summaries, not transcripts. When a subagent completes and the coordinator needs its output, extract the structured result and discard the subagent's conversation history. Summary injection for fresh sessions is the pattern: compress prior work into a dense fact block, inject it into the next session's system prompt, and start with a clean context window.

What production workflows actually benefit from subagents?

Not every engineering task warrants a subagents workflow. The overhead of decomposition, dispatch, and synthesis is real. Here are the task types where the pattern pays off, and where it does not.

For the refactor and audit cases, the per-file and cross-file pass pattern is the standard approach: a first pass handles per-file changes in parallel, a second cross-file pass handles consistency (import paths, shared types, naming). The two passes must be sequential with respect to each other, but within each pass the subagents run in parallel.

Plan-then-build as the default entry point

For any task above a certain complexity threshold, the coordinator should enter plan mode before spawning subagents. Plan mode produces a structured decomposition that the coordinator can inspect, the user can approve, and the subagents can execute against. Skipping plan mode is the most common cause of narrow decomposition failure: the coordinator spawns subagents for a subtask that was never the right unit of work.

How do you keep parallel Claude Code sessions from colliding?

Branch collisions happen when two subagents write to the same file concurrently. The fix is not coordination between subagents (that reintroduces coupling) but pre-assignment of disjoint write scopes by the coordinator before any subagent is spawned.

A coordinator prompt that enforces this:

You are coordinating a refactor of the authentication module.

Before spawning any subagents, produce a JSON manifest that assigns each
subagent a disjoint set of files. No file may appear in more than one
subagent's assignment. Format:

{
  "subagents": [
    { "id": "sa-1", "files": ["src/auth/login.ts", "tests/auth/login.test.ts"] },
    { "id": "sa-2", "files": ["src/auth/session.ts", "tests/auth/session.test.ts"] }
  ]
}

Do not spawn any subagent until the manifest is complete and verified.

This is a prerequisite gate design: the manifest is a gate that must pass before execution begins. If the manifest reveals that two required changes share a file, the coordinator collapses them into a single sequential subagent rather than risking a collision.

For teams running multiple engineers with Claude Code sessions simultaneously, the same principle applies at the branch level: each engineer's Claude Code session should operate on a dedicated branch. Merging is a human-gated step, not an automated one.

What does a minimal end-to-end subagents workflow look like in code?

Below is a simplified coordinator prompt that implements the full pattern: decompose, gate, spawn, verify, synthesise.

COORDINATOR_SYSTEM = """
You are a coordinator agent for engineering tasks.

Workflow:
1. Receive the task description.
2. Produce a JSON decomposition: list of subtasks, each with id, scope (files),
   goal (one sentence), and acceptance_criteria (list of strings).
3. Confirm the decomposition has no overlapping file scopes.
4. For each subtask, produce a subagent prompt that includes:
   - The subtask goal
   - The exact files in scope
   - The acceptance criteria
   - The verification command to run
5. After all subagents complete, collect their structured results.
6. Verify each result against its acceptance criteria.
7. If any result fails, re-route that subtask (do not silently suppress failures).
8. Produce a final synthesis report.

Never execute file changes yourself. Delegate all execution to subagents.
"""

SUBAGENT_SYSTEM = """
You are an execution agent. You receive a single bounded task.

Rules:
- Modify only the files listed in your scope.
- Run the verification command before reporting completion.
- Return a JSON result: { "subtask_id": str, "status": "pass"|"fail",
  "diff_lines_added": int, "diff_lines_removed": int,
  "verification_output": str, "notes": str }
- If verification fails, diagnose and retry once. If it fails again, set
  status to "fail" and explain in notes. Do not fabricate a passing result.
"""

The structured result format is critical. A coordinator that receives free-text from subagents cannot reliably synthesise or verify. JSON with explicit status fields is the minimum viable contract.

How does the CCAR-F exam test subagents workflow knowledge?

Domain 1 (Agentic Architecture & Orchestration) carries 27% of the CCAR-F exam weight, making it the single largest domain. The exam draws 4 scenarios at random from a bank of 6 per sitting, so every candidate will face at least one multi-agent scenario.

The exam consistently tests three judgment calls in the subagents context:

1. When to spawn vs stay single-threaded -- scenarios present a task and ask which architecture is appropriate. The answer turns on independence, scope clarity, and context cost.
2. How to handle subagent failure -- scenarios present a failed subagent result and ask how the coordinator should respond. The correct answer is almost always root-cause diagnosis and targeted re-routing, not silent suppression or full restart.
3. How to enforce constraints -- scenarios ask whether a guardrail should be implemented via prompt instruction or programmatic hook. The rule: when the constraint is high-stakes and must not be bypassed, use a programmatic hook. When it is advisory, a prompt instruction is proportionate.

Our concept library at /concepts covers 174 atomic concepts mapped to all five CCAR-F domains and 30 task statements. The agentic architecture concepts are the densest cluster, reflecting the domain's exam weight.