本讲摘要本讲是 SubAgent 系列的收官篇、做 4 件事全景图回顾8 个常用子代理角色速查、选型决策树从任务特征反推该用哪个、模板库沉淀怎么把团队子代理变成可复用资产、未来演进多模态 / Agent 协议 / MCP 集成。目的是让你看完就能用、用完就能扩、扩完就能传。本讲的三条主线第一、8 个常用子代理角色——按读 / 跑 / 写三类拆、每个角色有明确的工具白名单、触发场景、输出格式速查表让你 30 秒选对子代理。第二、选型决策树——4 步决策任务改不改状态?→ 单读/可执行/可写输出大不大?→ 单子代理 vs 流水线可不可并行?→ 单跑 vs 多跑要不要审批?→ ask 机制、从任务特征反推子代理类型。第三、从个人技巧到团队资产——3 种沉淀方式入 git 共享 / 内部 NPM 包 / GitHub 仓库 3 个长期机制版本管理 / 质量审计 / 使用统计、让子代理从个人一次性脚本变成团队可持续资产。学完本讲、你应该能在 30 秒内为新任务选对子代理、能用决策树向团队成员解释为什么用这个、能用模板库把团队的子代理沉淀成可复用的资产、能规划 SubAgent 在多模态/Agent 协议/MCP 集成上的演进路径。 详细内容SubAgent 系列全景图回顾8 个常用角色速查第 4 讲到第 8 讲用了 5 讲把 SubAgent 讲透——核心概念、3 类单兵实战、多子代理协同。本节用 8 个常用子代理角色做速查回顾、按读 / 跑 / 写三类组织只读类3 个、Read/Grep/Glob 为主、无副作用code-reviewer代码审查——触发用户改完代码后。输出Critical / Warning / Suggestion 三档分级清单。security-auditor安全审计——触发合并 main 前 / 依赖升级后。输出每条带 CVE 编号 / OWASP 分类的漏洞清单。doc-explorer文档侦察——触发用户问这段代码什么意思 / “这个 API 怎么用”。输出定位 5 行上下文。可执行类2 个、Bash 工具配 permission 白名单test-runner跑测试——触发“跑测试” / “verify” / “ci”。输出Passed / Failed / Flaky / Coverage 四字段摘要。diag-runner诊断跑——触发“为什么慢” / “线上报错” / “远程 ssh 排查”。输出瓶颈定位 修复建议。可写类3 个、Edit/Write 配 ask 机制 file_path 白名单pr-drafter(PR 草稿——触发“写个 commit” / “draft PR”。输出.claude/drafts/ 下的 commit-msg.txt 和 pr-description.md、不直接 commit/push。doc-writer文档写——触发“更新文档” / “sync docs”。输出docs/ *.md 文件的更新、绝不碰 src/。test-writer测试写——触发“补测试” / “加 case”。输出tests/ 下的新测试、commit 前必须人 review。8 个角色覆盖了 Claude Code 工程化里 80% 的重复性高、有明确边界、可并行/可串行的任务。每个角色的细节工具白名单 / system prompt / 触发词在前 5 讲里都讲过、本节只给速查、目的是帮你30 秒选对。8 个角色之外、你可能还会遇到自定义子代理——比如 migration-expert本项目数据库迁移专家、legacy-archaeologist读老代码的考古学家、i18n-localizer多语言本地化专家。这些是项目特化的子代理、放在 project-level、模板在实战代码段里给。角色类别工具触发场景输出code-reviewer只读Read/Grep/Glob/Bash改完代码后、commit 前Critical/Warning/Suggestion 清单security-auditor只读Read/Grep/Glob合并 main 前、依赖升级后带 CVE/OWASP 分类的漏洞清单doc-explorer只读Grep/Glob/Read“这段代码什么意思”定位 5 行上下文test-runner可执行Bash白名单/Read/Grep“跑测试” / “verify”Passed/Failed/Flaky/Coveragediag-runner可执行Bash(ssh/psql/curl GET)/Read“为什么慢” / “线上报错”瓶颈定位 修复建议pr-drafter可写Bash/Read/Grep/Edit/Write“写个 commit” / “draft PR”.claude/drafts/ 下的草稿doc-writer可写Read/Grep/Glob/Edit/Write“更新文档” / “sync docs”docs/ *.md 的更新test-writer可写Read/Grep/Glob/Edit/Write/Bash“补测试” / “加 case”tests/ 下的新测试选型决策树从任务特征反推子代理新人最常问的问题“我手头这个任务该用哪个子代理?”——决策树是答案。4 步决策、从任务特征反推到子代理类型第 1 步任务改不改状态?不改状态只读/只跑命令不写 → 进入读 / 跑分支。改状态要写文件 → 进入写分支、且必须配 ask 机制。第 2 步输出大不大?输出大测试报告 / 全项目搜索 → 用单子代理隔离上下文主对话不污染。输出小几句话能说完 → 直接在主对话里做、不用子代理。第 3 步可不可并行?可并行3 个独立探索 → 用并行模式 多子代理。不可并行强依赖、链式 → 用流水线模式、各段一个子代理。第 4 步要不要审批?要改代码 / 改配置 / 推 git) → ask 机制 file_path 白名单。不要只读 / 只跑白名单命令 → 自动放行。4 步决策后、你就能从 8 个常用角色里选 1 个或者决定自定义一个。决策树的可视化版本在实战代码段里、贴在墙上 30 秒做一次选型。子代理模板库沉淀从个人技巧到团队资产子代理的工程价值不止用起来方便、更在传得下去。一个团队 5 个工程师、每个人都自己重写 1 份 code-reviewer——5 份几乎一样但又略有不同、code review 标准不统一、效率浪费。把个人技巧沉淀成团队资产有 3 种方式、各有适用场景方式 1入 git 共享最简单把 .claude/agents/ 整个目录提交到项目的 git 仓库、所有协作者 clone 后自动继承。这是项目特化子代理的天然沉淀方式、门槛低只需要 git add commit)、维护方便PR review 即可。缺点仅限本项目、跨项目需要复制。方式 2内部 NPM 包中等把通用子代理比如 general-code-reviewer / general-explorer封装成 NPM 包、公司内部私有 registry、各项目npm install your-org/claude-agents即可使用。优点跨项目复用、版本管理NPM 自带 semver、可发布审计日志。缺点门槛高需要 registry 账号 维护 README)、小型团队可能 overkill。方式 3:GitHub 仓库开源共享把通用子代理开源到 GitHub类似 awesome-claude-agents / claude-code-best-practice 等社区仓库、社区贡献 团队使用。优点零基础设施负担、社区反馈、跨团队/跨公司复用。缺点维护成本issue / PR / 文档、且公司内部规范不适合开源。3 种方式的选型心法项目内通用 → 入 git公司内通用 → 内部 NPM 包跨公司通用 → 开源 GitHub。子代理文件的 4 要素name / description 触发器 / tools 白名单 / system prompt 三段式在实战代码里给完整模板、新人照着填就行、不用每次都想一遍结构。沉淀方式门槛适用场景版本管理维护成本入 git 共享低git add commit)项目内通用git tag(semver)低PR review 即可内部 NPM 包中需要 registry 账号公司内通用NPM 自带中README changelog)GitHub 仓库高社区维护跨公司通用git tag release高issue/PR/文档跨项目复用user-level vs project-level 的边界第 4 讲讲过 user-level用户级、~ / .claude/agents/和 project-level项目级、./.claude/agents/的区别。本节讲什么放哪、怎么组织。user-level 放什么通用、不依赖项目专有信息的子代理general-code-reviewer任何项目能审查/ general-explorer任何项目能搜/ general-doc-writer任何项目能写文档。这些子代理的 description 里没有项目专有名词、跨项目能用。project-level 放什么项目特化、需要项目知识才能发挥作用的子代理order-domain-expert只有订单项目能懂/ migration-expert本项目迁移规范/ legacy-archaeologist本项目老代码考古。这些子代理的 description 里出现项目专有名词、跨项目用不了但放进项目 git 仓库、新成员 clone 后自动获得、这是项目知识传递的隐藏价值。.claude/agents/ 目录的 3 种组织方式按角色组织.claude/agents/reviewers/(code-reviewer / security-auditor / perf-reviewer).claude/agents/runners/(test-runner / diag-runner / build-runner).claude/agents/writers/(pr-drafter / doc-writer / test-writer)按阶段组织.claude/agents/dev/(dev-time 工具explorer / debugger).claude/agents/ci/(CI 工具test-runner / linter-runner).claude/agents/release/(release 工具pr-drafter / changelog-writer)按技术栈组织.claude/agents/python/(python-linter / python-test-runner / python-doc-generator).claude/agents/react/(react-reviewer / react-test-runner / react-doc-writer)3 种方式各有适用场景团队角色分工明确 → 按角色项目有清晰的 dev/ci/release 阶段 → 按阶段多技术栈项目 → 按技术栈。新手从按角色开始、熟练后再按团队实际情况调整。SubAgent 工程化治理3 个长期机制子代理从个人技巧到团队资产需要 3 个长期机制保障可持续性机制 1子代理版本管理子代理文件进 git、用 git tag 打 semver 版本比如 v1.0.0 / v1.1.0 / v2.0.0。每次子代理的 system prompt 重大变更 → minor version 升工具白名单变更 → major version 升因为有兼容性风险微调只改 description)→ patch version 升。为什么需要团队里有人用了 v1.0.0 的子代理、有人用了 v1.1.0、行为不一致 → 产出不一致。版本管理让哪个项目用的哪个版本清晰可追溯。机制 2子代理质量审计每月跑一次子代理行为对照表在实战代码段里给模板、把每个子代理的实际行为从 Audit 日志提取和预期行为子代理 system prompt 里规定的对照、看是否漂移。比如code-reviewer 原本说输出 Critical/Warning/Suggestion、实际跑出来发现 30% 的报告漏了 Suggestion 段——这就是漂移、要修 system prompt。机制 3子代理使用统计用 Audit 日志统计哪个子代理调用最多?哪个最少?哪个失败率最高?这些数据驱动子代理治理——调用的多 价值高、持续投入优化调用的少 可能没解决真问题、考虑合并或废弃失败率高 子代理设计有问题、要重写。3 个机制叠加、子代理从写完就放着变成持续运营。这是从项目到产品的关键一步。未来演进多模态 / Agent 协议 / MCP 集成SubAgent 在 Anthropic 的路线图上还在快速演化。3 个方向值得关注方向 1多模态子代理当下子代理的工具白名单主要是文本类Read/Grep/Glob/Bash/Edit/Write)、未来会原生支持多模态工具Image / Video / Audio。比如image-explorer读图找 UI 元素/ video-transcriber读视频生成字幕/ audio-summarizer读音频生成摘要。这会大幅扩展看的边界——子代理从看代码变成看一切。方向 2:Agent 协议当下子代理是 Claude Code 内部的私有概念、其他 IDE / 工具比如 Cursor / Cline / Aider有各自的子代理实现、互不兼容。Agent 协议类似 MCP / Agent Protocol是行业标准化的尝试——子代理描述、触发器、工具白名单用统一格式定义、跨工具/跨 IDE 互操作。今天的 .md 文件未来可能变成 .agent.json / .agent.yaml、被任何支持 Agent 协议的工具识别。方向 3:MCP 集成MCP(Model Context Protocol是 Anthropic 推的工具集成协议、让子代理能调用外部工具数据库 / 内部 API / SaaS。当下子代理的 tools 字段是 Claude Code 内置工具、Bash 是万能瑞士军刀但 permission 难配。未来 MCP 集成后、子代理能直接调mcp://database/query而不是Bash: psql -c ...,permission 配在 MCP server 端、更精细。3 个方向都还在演化、但 SubAgent 作为AI 团队协作单元的核心思想会持续——多模态、协议化、集成化是放大这个思想价值的手段。本节的目的不是预测未来、而是让你在设计子代理时考虑演进路径、不锁死在某个工具/某个协议上。️ 实战代码 第 9 讲配套子代理选型决策树可视化 ASCII 图用户任务 | Q1: 任务改不改状态? |-- 不改状态(只读/只跑) --- Q2 | |-- 改状态(要写) ---- 可写类 ask 机制 | Q2: 输出大不大? |-- 大(测试报告/全项目搜索) --- 用子代理隔离上下文 | |-- 小(几句话) ------------ 直接在主对话做 | Q3: 可不可并行? |-- 可并行(3 个独立探索) --- 并行模式 多子代理 | |-- 不可并行(强依赖链) - 流水线模式,各段一子代理 | Q4: 要不要审批? |-- 要(改代码/改配置/推 git) - ask file_path 白名单 | |-- 不要(只读/只跑白名单) - 自动放行 | v 从 8 角色里选 1: 只读 3: code-reviewer / security-auditor / doc-explorer 可执行 2: test-runner / diag-runner 可写 3: pr-drafter / doc-writer / test-writer 第 9 讲配套完整的 8 角色最小可用 .md 模板库# 只读类 # .claude/agents/code-reviewer.md --- name: code-reviewer description: Proactively review code changes for quality and security after I modify code, before commit. tools: Read, Grep, Glob, Bash model: sonnet --- [详细 prompt 见第 5 讲] # .claude/agents/security-auditor.md --- name: security-auditor description: Audit code for security vulnerabilities (SQLi, XSS, SSRF, secrets) before merging to main. tools: Read, Grep, Glob model: opus --- [详细 prompt 见第 5 讲的4 个真实审查场景段] # .claude/agents/doc-explorer.md --- name: doc-explorer description: Find files and code locations when I ask where is X / find all Y. tools: Grep, Glob, Read model: haiku --- [详细 prompt 见第 4 讲的 explorer 模板]# 可执行类 # .claude/agents/test-runner.md --- name: test-runner description: Run tests when I say test it / 跑测试 / verify. tools: Bash, Read, Grep model: haiku --- [详细 prompt 见第 6 讲的完整版,含 permission deny 列表] # .claude/agents/diag-runner.md --- name: diag-runner description: Diagnose slowness / errors / production issues when I say why is it slow / 线上报错. tools: Bash, Read, Grep model: sonnet --- You are a diagnostic runner. SSH to prod, read logs, profile code, report bottlenecks. Allowed: ssh, psql -c SELECT, curl (GET only), top, htop, iostat, vmstat, strace. Forbidden: rm, mv, git push, any write operation.# 可写类(全部配 ask 机制) # .claude/agents/pr-drafter.md --- name: pr-drafter description: Draft commit message and PR description from my staged changes. tools: Bash, Read, Grep, Edit, Write model: sonnet --- [详细 prompt 见第 7 讲的完整版,只写 .claude/drafts/] # .claude/agents/doc-writer.md --- name: doc-writer description: Update README, generate API docs, sync CHANGELOG. tools: Read, Grep, Glob, Edit, Write model: haiku --- [详细 prompt 见第 7 讲的完整版,只写 docs/ *.md] # .claude/agents/test-writer.md --- name: test-writer description: Add tests, fix flaky tests, increase coverage. tools: Read, Grep, Glob, Edit, Write, Bash model: sonnet --- You are a test writer. Add tests to tests/ directory. Run pytest --co to see existing tests. Before any commit, the human MUST review your test code (Git Hook enforces this). Allowed paths: tests/**, conftest.py Forbidden: src/**, migrations/**, config/** 第 9 讲配套.claude/agents/ 目录 3 种组织范例# 方式 1:按角色组织 .claude/agents/ ├── reviewers/ │ ├── code-reviewer.md │ ├── security-auditor.md │ └── perf-reviewer.md ├── runners/ │ ├── test-runner.md │ ├── diag-runner.md │ └── build-runner.md └── writers/ ├── pr-drafter.md ├── doc-writer.md └── test-writer.md # 方式 2:按阶段组织 .claude/agents/ ├── dev/ │ ├── explorer.md │ ├── debugger.md │ └── code-reviewer.md ├── ci/ │ ├── test-runner.md │ ├── linter-runner.md │ └── coverage-runner.md └── release/ ├── pr-drafter.md ├── changelog-writer.md └── version-syncer.md # 方式 3:按技术栈组织 .claude/agents/ ├── python/ │ ├── python-linter.md │ ├── python-test-runner.md │ └── python-doc-generator.md ├── react/ │ ├── react-reviewer.md │ ├── react-test-runner.md │ └── react-doc-writer.md └── infra/ ├── terraform-reviewer.md ├── ansible-runner.md └── k8s-diag.md 第 9 讲配套子代理行为对照表审计用 Audit 日志配置# 子代理行为对照表(每月跑一次审计) # .claude/audits/year-month-subagent-audit.md | 子代理 | 预期行为(system prompt 规定) | 实际行为(从 audit.log 统计) | 漂移? | 修复动作 | |--------|--------------------------|------------------------|-------|---------| | code-reviewer | 输出 3 档:Critical/Warning/Suggestion | 30% 报告漏 Suggestion | ✗ | 强化 system prompt,加必须输出三档 | | security-auditor | 每条带 CVE/OWASP | 5% 报告无分类 | 边缘 | minor:加 default 分类 | | test-runner | 4 字段:Passed/Failed/Flaky/Coverage | 100% 符合 | 无 | - | | pr-drafter | 写 .claude/drafts/ 草稿 | 3% 越权写 src/ | ✗ | major:加 permission deny | | doc-writer | 只写 docs/ *.md | 100% 符合 | 无 | - | | ... | ... | ... | ... | ... | 统计方法: bash # 调用次数 jq -r .tool .claude/audit.log | sort | uniq -c # 失败率 jq -r select(.user_decision deny) | .tool .claude/audit.log | sort | uniq -c# Audit 日志 Hook(从第 7 讲复用,这里给完整版) # .claude/hooks/audit-subagent.sh #!/usr/bin/env bash TOOL_NAME$1 SUBAGENT_NAME$2 FILE_PATH$3 USER_DECISION$4 DIFF_SIZE$5 TIMESTAMP$(date -Iseconds) # 记录所有子代理的工具调用 if [ -n $SUBAGENT_NAME ]; then echo $TIMESTAMP | $SUBAGENT_NAME | $TOOL_NAME | $FILE_PATH | diff_size$DIFF_SIZE | $USER_DECISION \ .claude/audit.log fi exit 0⚠️ 常见坑⚠️ 写了 10 个子代理但没人用模板没沉淀、各自重写最常见的SubAgent 失败模式团队里某个人花 1 周精心写了 5 个子代理、但因为没沉淀没入 git / 没发 NPM / 没人知道、其他人继续自己重写。3 个月后 5 个人的子代理各写一份、标准不统一。修正子代理写完立即入 git(.claude/agents/ 目录,README 写明用法 触发词、团队 stand-up 演示一次。判断标准你团队里是不是每个人都自己写过 code-reviewer?如果是、就是没沉淀。⚠️ 子代理长成野生的没人维护、行为漂移子代理写完当时很完美、3 个月后没人维护。LLM 模型更新了、Claude Code 工具集变了、项目代码风格变了、子代理的行为悄悄漂移——它现在输出的报告和当初定义的不一样。修正每月跑一次子代理行为对照表本节实战代码里给模板、从 Audit 日志提取实际行为、和 system prompt 规定的预期行为对照。漂移 → 修 system prompt行为不再需要 → 合并/废弃。判断标准子代理文件最后修改时间是不是 6 个月前?如果是、该审计了。⚠️ 跨项目复制时硬编码项目名应该用占位符新人最常犯的复用失效错误从 A 项目复制一份子代理到 B 项目、但子代理的 description / system prompt 里硬编码了 A 项目的名字“OrderFlow 订单系统的代码审查员”。结果 B 项目用起来完全不对——子代理不知道自己在 B 项目、还以为是 A 项目。修正子代理模板里用占位符{{PROJECT\_NAME}}/{{LANGUAGE}}/{{FRAMEWORK}}、跨项目复制时批量替换。或者把项目名做成变量、从 CLAUDE.md 里读CLAUDE.md 已经声明了项目名。判断标准子代理的 system prompt 里搜得到具体项目名?如果是、改成占位符。⚠️ 没有 quality gate子代理可以白盒测试、但没有持续监控出问题了才被发现子代理测试通过不代表生产可用。一个 code-reviewer 在测试集上 100% 准确、但生产里 AI 模型更新后它开始漏掉 Suggestion 段、3 个月才被发现。修正配 quality gate——CI 里跑子代理行为对照表每月一次、任何漂移 10% 触发告警。Audit 日志统计失败率、失败率 5% 触发告警。判断标准你的子代理有没有 quality gate自动化的、持续监控的?如果没有、补上——这是从项目到产品的最后一步。 一句话备忘SubAgent 的工程价值不在单个多强、而在团队多齐:8 角色速查 决策树 模板库 3 个长期机制、4 件事把个人技巧变成团队资产、为后续 Skills / Commands / Hooks 章节铺好代理层的地基。