Parent-Child Agent Design in Claude Code

Claude Code can keep system design and final judgment in a parent agent while moving exploration, implementation, and review into separate contexts. This tutorial builds a repository-ready configuration in which a capable, high-effort parent delegates to children sized to the difficulty of each task.

The parent owns decisions; children own bounded work

The parent agent is the main Claude Code session that talks with the user and decides requirements, constraints, decomposition, and acceptance. A subagent receives one task from the parent, investigates or implements it in a separate context, and returns a summary. Claude Code can define each child’s system instructions, model, effort, tools, and permissions.[1]

What this page covers

• Separate decisions that remain with the parent from execution delegated to subagents
• Explain the roles of .claude/agents/ and .claude/skills/
• Create agent definitions for exploration, implementation, and review
• Select models, effort, tools, and worktrees based on task risk
• Choose between standard subagents and Agent Teams

Do not turn “the parent is always the strongest and every child is always the lightest” into a fixed rule. Keep ambiguous judgments with the parent, then lower the model and effort as the child’s task becomes simpler. Cutting capability needed for implementation or security review creates rework and can increase total cost.

flowchart LR
    U["User"] --> P["Parent: requirements, decomposition, acceptance"]
    P --> E["explorer: read-only research"]
    P --> W["implementer: bounded implementation"]
    P --> R["reviewer: diff verification"]
    E --> P
    W --> P
    R --> P

Separate policy, roles, and procedures in the directory

Repository configuration should separate session-wide policy context, child-agent roles, and procedures loaded only when needed. Claude Code reads project subagents from .claude/agents/ and project Skills from .claude/skills/<name>/SKILL.md.[1][2]

project/
├── CLAUDE.md
├── .claude/
│   ├── agents/
│   │   ├── explorer.md
│   │   ├── implementer.md
│   │   └── reviewer.md
│   └── skills/
│       └── feature-delivery/
│           ├── SKILL.md
│           ├── references/
│           │   └── handoff-schema.md
│           └── scripts/
│               └── verify-changed-files.sh
└── src/

• CLAUDE.md: facts needed throughout a session, such as protected areas, required commands, and language policy
• .claude/agents/: each child’s role, model, effort, tools, permissions, and completion-report format
• .claude/skills/: reusable procedures whose full instructions load only when their description matches a request
• references/: detailed specifications that do not need to remain in the Skill’s main body
• scripts/: deterministic verification or transformation steps better implemented as programs than repeated by an LLM

The Skill body remains in context after invocation, so keep its entry point short and link only the references required for the task.[2] Put model roles in agent definitions and place workflow order and completion criteria in a Skill. The same procedure can then be reused by different agents.

Define a lightweight, read-only explorer

Exploration often generates large search results, making it especially useful to separate from the parent’s context. Create .claude/agents/explorer.md, omit editing tools, and constrain the response to a summary with file references.

---
name: explorer
description: Explore code before a change. Use to locate impact, execution paths, and existing tests. Never modify files.
tools: Read, Grep, Glob
model: haiku
effort: low
permissionMode: plan
maxTurns: 12
---

Trace the target execution path from its entry point.

Return:
1. Relevant files and their roles
2. The propagation path of the proposed change
3. Existing tests and missing checks
4. Unknowns

Do not expand a speculative solution. Cite the supporting files.

model: haiku with effort: low is an example for fast, bounded, read-only investigation. Raise it to sonnet or medium when the search space is very large, dependencies are complex, or output quality is insufficient. Claude Code accepts a model alias or full model ID in model, and compatible models support effort values from low through max.[1]

Isolate the implementer’s change in a worktree

An implementation worker needs editing permission, but concurrent edits in the parent’s working directory create conflicts. Setting isolation: worktree in .claude/agents/implementer.md gives the agent a temporary Git worktree.[1]

---
name: implementer
description: Implement one bounded feature from an approved plan and run its targeted validation. Return without implementation if a design decision remains open.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
effort: medium
permissionMode: acceptEdits
isolation: worktree
maxTurns: 24
skills:
  - feature-delivery
---

Implement only the target and completion criteria provided by the parent.
Do not perform unrelated refactoring.

At completion, return changed files, validation performed, and unresolved issues.

Implementation generally needs more judgment than exploration. This example therefore separates a light explorer from a balanced implementation agent. Move only simple transformations proven safe to Haiku; keep specification-dependent changes on Sonnet or a more capable model.

Give the reviewer higher effort without editing rights

Review is not a request to rewrite the code. Its job is to find missed problems and return evidence for the parent’s decision. In .claude/agents/reviewer.md, remove editing tools and fix the review dimensions and severity format.

---
name: reviewer
description: Review an implementation for correctness, security, regressions, and missing tests. Never modify files.
tools: Read, Grep, Glob, Bash
model: sonnet
effort: high
permissionMode: plan
maxTurns: 18
---

Inspect only the changed diff and its relevant execution path.
Return concrete defects in severity order, with supporting files and reproduction conditions.
Do not edit files or include unsupported concerns or preference-only comments.

The same Sonnet model can use medium for implementation and high for complex verification. Adjusting effort as well as the model name concentrates reasoning on difficult review work.

Put decomposition, handoff, and stopping rules in a Skill

.claude/skills/feature-delivery/SKILL.md tells the parent what must be settled before starting a child and what must return before the next phase. A Skill is a reusable procedure loaded when the request matches its description. Opening the file lets the team inspect inputs, workflow, and completion criteria.[2]

---
name: feature-delivery
description: Use when adding a bounded feature to an existing repository with separate exploration, implementation, and review.
---

## Input gate

- Behavior to change
- Behavior that must not change
- Completion criteria
- Authorized validation

Return to the parent and do not implement when any item is missing.

## Workflow

1. Delegate impact analysis to explorer.
2. The parent fixes the plan and file ownership from the findings.
3. Send only independent changes to implementer.
4. Receive the implementer's validation result.
5. Delegate a diff review to reviewer.
6. The parent accepts or rejects findings and synthesizes the final result.

## Completion

- Each completion criterion maps to a validation result
- Unresolved issues are explicit
- No file was edited concurrently by multiple agents

To provide a subagent with a Skill at startup, list the Skill name in the agent definition’s skills field. Claude Code loads that Skill body into the child at startup.[1] Loading every Skill would enlarge the child’s initial context, so include only what that role needs.

Tell the parent how to decompose and integrate

After adding the configuration, request the workflow from the parent like this:

Act as the parent with Opus and high effort.
First settle requirements, non-goals, and completion criteria.
Do not delegate implementation while any design decision remains open.

1. Use explorer to map the impact
2. Send only independent changes to implementer
3. Use reviewer to inspect the diff after implementation
4. Have the parent integrate results and report unknowns and validation

Do not let multiple agents edit the same file concurrently.

Select the parent’s model and effort for the session, while child settings remain fixed in agent definitions. A child does not automatically receive the parent’s full conversation history, so each delegation must include the goal, scope, non-goals, expected output, and completion criteria.[1]

Use Agent Teams only when children must coordinate

Agent Teams provides a team lead, multiple teammates, a shared task list, and mailbox messaging.[3] It is a better fit than standard subagents for investigations that exchange intermediate findings, debugging that tests competing hypotheses, or frontend and backend owners that must negotiate a contract.

Create an Agent Team with architect, frontend, and backend teammates.
The architect must settle the API contract and completion criteria.
The frontend and backend teammates must own separate files.
Broadcast contract changes through the mailbox, and have the team lead inspect the diff before integration.

Agent Teams is experimental and disabled by default. Each teammate also has an independent context, so token usage rises with the team size.[3] Avoiding Teams when only a final result must return is the first cost control.

Measure total tokens, parent context, and rework separately

A subagent can preserve the parent’s context without reducing the total tokens consumed by the whole system. Each child independently runs a model and tools, so greater concurrency raises total use. Anthropic’s Research case study also reports that multi-agent systems use more tokens than standard chat.[4]

Evaluate three measures separately:

Scroll horizontally→

Measure	What to inspect	Improvement
Total tokens	Sum consumed by the parent and every subagent	Reduce agent count, turn limits, and duplicate investigation
Parent context	Amount of intermediate output returned to the parent	Return evidence-backed summaries instead of raw logs
Rework	Work repeated after poor decomposition or an undersized model	Define input gates, completion criteria, and model or effort escalation rules

This table scrolls horizontally. Keyboard users can focus the table and use the left and right arrow keys.

Only reduce capability while maintaining task success. Add escalation rules to the Skill, such as moving an insufficient explorer from haiku/low to sonnet/medium, or raising reviewer effort when findings are superficial.

Verify roles, permissions, and conflicts

The minimum parent-child configuration is ready when every check passes.

• Only the parent owns requirements, decomposition, and final acceptance

• Each agent’s description identifies both invocation conditions and exclusions

• explorer and reviewer have no unnecessary editing rights

• implementer receives one bounded scope and one set of completion criteria

• Concurrent implementation is separated by file or worktree

• The Skill defines missing-input, failure, escalation, and stopping rules

• The parent can accept or reject work from the subagent summary alone

References

1. Anthropic, Create custom subagents
2. Anthropic, Extend Claude with skills
3. Anthropic, Orchestrate teams of Claude Code sessions
4. Anthropic, How we built our multi-agent research system, 2025-06-13

For details of the latest releases and updates, refer to the official websites and documentation.

Related links

• Comparing Orchestration in Claude, ChatGPT, and Codex
• Parent-Child Agent Design in Codex
• State Management and Handoffs