Claude Code Subagents: A Practical Guide to Safe Agent Delegation

When Claude Code work gets large, the first thing that breaks is usually not the model. It is the way the work is split. A single conversation that tries to research, write, translate, edit code, run checks, and review ten localized files quickly becomes heavy. The agent rereads the same files, context fills with logs, and the handoff at the end becomes vague.

Subagents are useful because they let you delegate bounded work into a separate context. In this article, delegation does not mean “ask another agent to handle everything.” It means giving a small contract: the goal, allowed files, forbidden files, completion criteria, and the exact shape of the result. That contract is what keeps parallel work from turning into duplicated work.

This guide is based on ClaudeCodeLab article production: writing a Japanese canonical article, localizing it into ten languages, checking prompt templates, and reviewing publication risk. The same patterns apply to code changes, documentation, migrations, and release preparation.

What a subagent is

A subagent is a specialized worker that runs outside the main conversation context. Context is the working memory Claude currently sees: the chat, files it has read, command outputs, instructions, and summaries. If a task will create a lot of search output or log noise, a subagent can do the heavy reading and return only the useful summary.

For official details, check the Claude Code docs for subagents, memory, and slash commands. The important operational points are simple: subagents start with an isolated context, project agents can live in .claude/agents/, and long subagent results still consume the main conversation once returned.

Term	Plain meaning in this guide
subagent	A specialist worker for research, implementation, translation, or review
context	The working memory visible to Claude in the current conversation
disjoint write set	A set of files one worker may edit that does not overlap with another worker
explorer	A read-only research agent that maps the work before editing starts
worker	An editing agent restricted to a specific file set
handoff contract	The task brief that defines scope, constraints, done criteria, and return format

When to delegate

Use subagents when splitting context has real value and the edit boundaries can be made clear. Do not use them just because a task feels important. Small tasks often get slower when delegated because each worker has to rebuild context from scratch.

Task	Delegate?	Why
Localizing one article into ten languages	Yes	Each locale has a separate file and review criteria
Scanning a large codebase for related conventions	Yes	The main thread only needs the map, not every search result
Fixing one typo in one file	No	The coordination cost is larger than the work
Refactoring auth across many modules	Maybe	Start with an explorer, then split by disjoint write sets
Designing an unclear new feature	Not yet	Requirements should be clarified in the main thread first

My practical rule is to delegate only when three things are true: the task produces context-heavy output, each worker can be restricted to explicit files, and the result can be returned as a checklist, table, or short receipt.

The core pattern: explorer, worker, reviewer

For serious work, do not start with several editing agents. Start with an explorer. The explorer reads only, identifies the important files, and proposes write sets. Then workers edit separate file sets. Finally, a reviewer or verification agent checks the result in read-only mode.

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

This sequence prevents the most common failure: three agents all reading and editing the same files because the assignment was too broad.

Use case 1: localized article production

For a ClaudeCodeLab article, the safest workflow is to write the canonical Japanese article first, then localize the full guide. If the canonical article is thin, every translation becomes thin. If the canonical article has examples, pitfalls, templates, and a CTA, the translations can preserve substance while sounding natural in each language.

Role	Allowed files	Job
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	Build the canonical structure, examples, prompts, and CTA
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	Localize naturally without summarizing
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	Localize terms for local readers and preserve technical detail
review-agent	all ten slug files, read-only	Check metadata, mojibake, links, code fences, and publication risk

Here is a copy-paste prompt for a locale worker:

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

Use case 2: verifying article code examples

Article writers and verification agents should not have the same job. The writer explains the concept. The verification agent extracts code fences, checks syntax, validates paths, and reports what can actually be copied.

For example, an article may include a reusable subagent definition:

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

This is not just a snippet for the article. It is a practical shape for .claude/agents/article-reviewer.md. Keep name unique, make description explain when to use the agent, and avoid turning the prompt into a huge policy document. Long-running context practices are covered in the Claude Code context management guide and team memory practices in CLAUDE.md best practices.

Use case 3: code changes with disjoint write sets

Subagents also work well for code when file ownership is explicit. Suppose a blog site needs changes to article cards, OGP image generation, and related-post selection. Those are connected features, but they can be edited separately.

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

The weak version of this prompt is “improve the UI in parallel.” That causes overlap. The strong version names the files each worker may touch and names what each worker must not touch.

Use case 4: read-only review and verification agents

The last agent should often be read-only. A review agent looks for reader value, SEO gaps, vague claims, duplicate content, and missing pitfalls. A verification agent checks metadata, links, commands, code fences, and build risk.

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

This is especially useful for multilingual publishing. The content can read well while one locale has an old date, a broken fence, or a missing CTA. For code-heavy work, combine this with a risk-based review checklist like the Claude Code code review checklist.

Prompt templates for delegation

Use this orchestration prompt before spawning workers:

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

Use this for read-only discovery:

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

Use this for an implementation worker:

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

Failure modes to avoid

The first failure mode is parallelizing before boundaries exist. If three workers are told to “make the article better,” all three will touch the title, intro, examples, and CTA. The output looks busy, but integration gets worse.

The second is returning too much from a subagent. A subagent can protect the main context while it works, but its final response still enters the main thread. Ask for decisions, tables, and receipts, not raw logs.

The third is a weak handoff contract. “Translate naturally” is not enough. Say “do not summarize,” “preserve frontmatter,” “keep pitfalls,” “use local SEO terms,” and “return phrases that need native review.”

The fourth is asking the same agent to implement and validate its own assumptions. Review agents should be skeptical. Tell them to lead with findings, compare the work against the original constraints, and identify publication or production risk.

The fifth is forgetting how agent definitions are loaded. Files under .claude/agents/ may require a fresh session before they are available. For complex reusable agents, a concise filesystem-based definition is easier to maintain than a very long one-off CLI prompt.

Context budget rules

Subagents save context only if you limit what comes back. Put a budget in the prompt:

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

This is the difference between useful delegation and a second wall of text. The article or code may be large; the handoff should stay compact.

Copy-paste reviewer subagent

The safest first subagent is a read-only reviewer. The script below creates .claude/agents/article-reviewer.md; it gives the agent permission to inspect drafts, but not to edit them, so you can add critical review before publication without increasing write risk.

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

Delegation checklist

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

What we saw in practice

In ClaudeCodeLab article work, the biggest improvement did not come from translating faster. It came from separating the canonical draft, locale workers, and read-only review. Earlier workflows sometimes produced one strong language and nine thin variants. With explicit no-summary rules, fixed write sets, and a review receipt, the final review becomes more concrete and less subjective.

If your team is adopting Claude Code, teach subagents as a work-design pattern, not as a magic automation switch. ClaudeCodeLab covers these delegation contracts, review rubrics, and context habits in training and practical product templates for teams that want a repeatable agent workflow.