Claude Code 子代理实战指南：安全委派并行文章与代码工作

Claude Code 的任务一变大，最先出问题的通常不是模型能力，而是工作拆分方式。一个主对话里同时做调研、写作、翻译、改代码、跑检查、做评审，很快就会变得沉重。Claude 会反复读取同一批文件，日志塞满上下文，最后交接时只剩一句“改好了”，但没人能清楚说明哪些文件为什么被改。

子代理的价值在于把边界清楚的小任务放到独立上下文里执行。这里的“委派”不是把任务随手丢给另一个 AI，而是写清一个小合同：目标、允许编辑的文件、禁止触碰的文件、完成标准、返回格式。合同越清楚，并行工作越不容易变成重复劳动。

这篇指南使用 ClaudeCodeLab 的文章生产流程作为例子：先写日语 canonical 原稿，再本地化到 10 个语言，检查提示词模板，最后做发布前评审。同样的方法也适用于代码修改、文档生成、迁移计划和发布准备。

什么是子代理

子代理是在主对话之外运行的专门工作者。上下文可以理解为 Claude 当前能看到的工作台：聊天记录、读过的文件、命令输出、项目规则和临时总结。大型搜索、日志分析、多语言翻译这类任务会制造大量中间信息，适合交给子代理处理，再只把结论带回主对话。

官方文档可以参考 Claude Code 的 Subagents、Memory 和 Slash commands。实务上要记住三点：子代理有隔离的上下文，项目级代理可以放在 .claude/agents/，子代理返回的长结果仍然会占用主对话上下文。

术语	本文中的直白解释
子代理	负责调研、实现、翻译或评审的专业工作者
上下文	Claude 当前能看到的工作记忆
disjoint write set	不重叠的可编辑文件范围
explorer	只读调研代理，先摸清范围，不直接改文件
worker	只编辑指定文件的执行代理
handoff contract	写清范围、限制、完成标准和返回格式的交接合同

什么时候应该委派

子代理不是越多越好。小改动如果也拆出去，每个代理都要重新读文件，反而更慢。判断标准是：拆开上下文是否有价值，以及编辑范围是否能切得足够清楚。

工作	适合委派吗	原因
一篇文章本地化到 10 个语言	适合	每个语言对应独立文件，评审标准也清楚
扫描代码库找既有写法	适合	主对话只需要地图，不需要所有搜索结果
修改一个错别字	不适合	协调成本高于工作本身
横跨多个模块的认证重构	先调研再决定	需要 explorer 先确认影响范围
需求还不明确的新功能	暂不适合	应先在主对话中确认需求

我的实用标准是：任务会产生大量中间信息、每个 worker 可以限制在明确文件内、最终结果能用清单或表格返回。这三点同时满足，才值得委派。

核心模式：explorer、worker、reviewer

不要一开始就启动多个编辑代理。先让 explorer 只读调研，找到相关文件、现有约定、潜在风险，并建议如何分配不重叠的编辑范围。然后 worker 才开始改文件。最后 reviewer 或 verification agent 以只读方式检查结果。

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"]

这个顺序能避免最常见的失败：多个代理因为任务描述太宽泛，同时读取和编辑同一批文件。

用例 1：多语言文章生产

以 ClaudeCodeLab 的文章为例，安全流程是先写好日语 canonical 原稿，再完整本地化。canonical 是基准稿。如果基准稿只有概念列表，10 个语言都会变成薄内容；如果基准稿包含实例、踩坑、模板和 CTA，翻译才有足够信息可以自然本地化。

角色	允许编辑的文件	工作
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	构建基准结构、实例、提示词和 CTA
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	自然本地化，不允许压缩成摘要
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	调整术语，让本地读者容易理解
review-agent	10 个 slug 文件，只读	检查 frontmatter、乱码、链接、代码块和发布风险

可直接复制给翻译代理的提示词：

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

用例 2：让验证代理检查文章里的代码示例

文章作者和验证代理不应该做同一件事。作者负责解释概念，verification agent 负责抽取代码块、检查语法、确认路径是否合理，并说明哪些内容能直接复制使用。

---
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.

这段示例可以放在 .claude/agents/article-reviewer.md。name 要唯一，description 要写清楚什么时候调用它。不要把系统提示写成很长的制度文件；长期规则更适合放进 CLAUDE.md 或团队清单。相关做法可以继续看上下文管理指南和CLAUDE.md 最佳实践。

用例 3：用不重叠编辑范围切代码任务

代码工作也可以这样拆。假设博客站点同时要改文章卡片、OGP 图片生成和相关文章逻辑，这些功能相关，但文件可以分开。

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.

弱提示词是“并行改善 UI”。强提示词会说清楚谁能改什么、不能改什么、最终要返回什么证据。

用例 4：只读 reviewer 和 verification agent

最后一个代理经常应该是只读的。reviewer 看读者价值、SEO 缺口、重复内容、缺失的失败例；verification agent 看 metadata、链接、命令、代码块和构建风险。

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.

多语言发布时，这一步非常实用。正文可能读起来不错，但某个语言忘了更新日期，某个代码块没闭合，某个 CTA 丢失。代码工作可以配合代码评审清单一起使用。

可复制的委派模板

主对话先贴这个 orchestration prompt：

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 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 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

失败模式与避免方法

第一种失败是还没有边界就并行。三个 worker 都收到“把文章写好一点”，他们会同时改标题、导入、例子和 CTA，最后合并成本比写作成本更高。

第二种失败是返回太多内容。子代理工作时能保护主上下文，但最终结果一旦回到主对话，也会占上下文。要求返回决策、表格、证据和风险，不要返回整段日志。

第三种失败是 handoff contract 太弱。“自然翻译”不够，要写“禁止摘要”“保留 frontmatter”“保留失败例”“使用本地 SEO 词”“列出需要母语者复核的表达”。

第四种失败是让实现者验证自己的假设。reviewer 应该带着怀疑阅读，先列问题，再给结论。

第五种失败是忘记 agent 定义的加载方式。.claude/agents/ 下的文件可能需要新会话才能稳定可用。复杂的复用代理，最好写成简洁的文件定义，而不是每次粘贴超长 CLI 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.

正文和代码可以很长，但交接应该短。把“产物”和“交接说明”混在一起，主对话很快会被正文、翻译备注和验证日志塞满。

可复制的只读评审子代理

最安全的第一步，是先建立只读评审代理。下面的脚本会创建 .claude/agents/article-reviewer.md。它只能阅读草稿并指出风险，不能直接修改文件，因此适合放在发布前做最后一轮质量检查。

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

委派检查清单

# 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.

实际尝试后的结果

在 ClaudeCodeLab 的文章改善中，提升最大的一点不是“翻译更快”，而是把 canonical 原稿、语言 worker 和只读 reviewer 分开。以前很容易出现一个语言内容很厚、其他语言只是摘要的情况。现在先固定基准稿，再要求各语言禁止摘要、保留 CTA、返回检查证据，发布前评审会具体很多。

如果团队正在导入 Claude Code，建议把子代理当作“工作设计方法”来教，而不是神奇的自动化按钮。ClaudeCodeLab 的培训和产品模板会把委派合同、评审标准和上下文管理整理成团队可复用的流程。