Claude Code教程 -07- 多 Agent 协同开发完全指南Hooks × Subagents × Skills从心智模型到可落地配置的一份完整参考。覆盖概念辨析、加载机制、以及一条贯穿「需求分析 → 方案设计 → 开发 → 测试 → 代码审查 → 文档编写 → 发布」全流程的实战案例所有配置文件均可直接复制到项目里使用。文章目录Claude Code教程 -07- 多 Agent 协同开发完全指南Hooks × Subagents × Skills[toc]目录一、心智模型七种指导方式与三大扩展机制三者是什么、放在哪、谁来决定要不要执行一句话记忆法为什么这个区分很重要底层机制加载时机、上下文流动、Hook 事件详解会话生命周期里三者分别什么时候进入上下文Hook 事件详解实战常用的一批架构设计原则三个判断问题 常见反模式遇到一个新需求先问自己三个问题常见反模式实战案例给项目搭一条完整的功能开发流水线核心约束Subagent 之间怎么传话目录结构总览逐个拆解七个阶段的具体配置与实现阶段一需求分析 — requirements-analyst.md阶段二方案设计 — solution-architect.md阶段三开发实现 — 主线程为主developer.md 为辅阶段四测试验证 — test-engineer.md阶段五代码审查 — code-reviewer.md阶段六文档更新 — doc-writer.md阶段七发布检查 — release-manager.md编排层把七个阶段串成一条 Skill配套 Hooks贯穿全流程的护栏端到端演示完整走一遍真实场景进阶技巧与排查方法给 Subagent 配专属 HookSkill Hook 组合做强制流程兜底用 Plugin 打包整套体系分享给团队流水线卡住了怎么排查模型分配策略快速上手 Checklist目录心智模型七种指导方式与三大扩展机制底层机制加载时机、上下文流动、Hook 事件详解架构设计原则三个判断问题 常见反模式实战案例给项目搭一条完整的功能开发流水线需求→发布逐个拆解七个阶段的具体配置与实现编排层把七个阶段串成一条 Skill端到端演示完整走一遍真实场景进阶技巧与排查方法快速上手 Checklist一、心智模型七种指导方式与三大扩展机制Claude Code 提供七种指导 Claude 行为的方式CLAUDE.md、Rules、Skills、Subagents、Hooks、Output Styles、追加系统提示词。日常协同开发里用得最多、也最容易混淆的是Skills、Subagents、Hooks这三个本指南聚焦这三者。三者是什么、放在哪、谁来决定要不要执行维度Skills技能Subagents子代理Hooks钩子本质一份该怎么做的操作手册一个有独立系统提示词的专职助手绑定到生命周期事件的 shell 命令 / HTTP 请求 / 提示词存放位置.claude/skills/name/SKILL.md.claude/agents/name.md.claude/settings.json或~/.claude/settings.json触发方式Claude 判断任务匹配概率性或/skill-name显式调用Claude 判断任务匹配或agent-name显式调用或被 Skill/其他流程调用事件发生就必然执行无需 Claude决定执行位置主对话的上下文窗口里你能实时看到每一步全新的、独立的上下文窗口只把最终摘要带回主对话主对话之外由 Claude Code 宿主程序直接执行确定性概率性——Claude 有可能判断这次不需要用概率性——是否调用取决于任务匹配确定性——exit code 2就是硬拦截100% 生效典型用途可复用的固定流程发布检查、PR 审查模板、周报生成大范围检索、跑测试看日志、深度调研——会产生大量你不需要逐字看的中间输出的任务安全护栏拦截危险命令、自动化收尾自动格式化、强制跑测试一句话记忆法Skill 你希望 Agent知道怎么做的事这个仓库里怎么加一个接口、怎么走发布流程Hook 你希望无论 Agent 怎么想都必须发生的事危险命令必须被拦截、改完文件必须跑一次 lintSubagent 你希望委托出去、不污染主对话的事大范围代码检索、完整测试日志分析为什么这个区分很重要确定性 vs 概率性是整个心智模型里最关键的一条分界线。CLAUDE.md 和 Skills 本质上都是自然语言指令Claude 大概率会遵守但在长会话、上下文被压缩、或者读到的文件里混入了误导性内容prompt injection时指令是有可能被打折扣执行的。Hooks 不一样它是代码不是叮嘱。PreToolUse钩子返回exit code 2这次工具调用就是被物理拒绝了不存在Claude 这次判断觉得可以就绕过去的情况。结论任何真正意义上的安全红线不许删库、不许强推主分支、不许读取密钥文件只能用 Hook 实现写在 CLAUDE.md 里当一句强调是不够的。底层机制加载时机、上下文流动、Hook 事件详解会话生命周期里三者分别什么时候进入上下文会话启动session start ├─ CLAUDE.md根目录 → 全文加载常驻整个会话直到结束 ├─ 所有 Skills 的 name description → 只加载名字 一句话简介几十 token 级别 ├─ 所有 Subagents 的 name description tools → 同上轻量级 └─ Hooks 配置 → 不进入模型上下文宿主程序自己记着独立于对话之外 ────────────── 会话进行中 ────────────── 触发某个 Skill你打了 /xxx或 Claude 判断当前任务匹配它的 description → 这时候 SKILL.md 的完整正文才第一次加载进主对话上下文 → 之后的执行仍然发生在主对话里你能实时看到 Claude 在按这份手册一步步做 → 上下文成本只有被触发的 Skill 才会加载全文没被用到的 Skill 全程只占几十 token 触发某个 SubagentClaude 通过内置的 Task 工具调用 → 开一个全新的上下文窗口这个 subagent 的 markdown 正文变成它的系统提示词 → 它在自己独立的沙盒里读文件、写文件、跑命令、思考——这个过程完全不写入主对话 → 结束后只把它任务完成后的最终回复传回主对话中间的搜索过程、报错重试、 冗长日志统统留在它自己的上下文里随着这次调用结束而丢弃 → 上下文成本主对话只多了几行调用了 xxx 子代理 → 收到结论xxx 每次工具调用 / 文件写入 / 会话开始结束等生命周期节点 → 对应的 Hook 100% 被触发作为独立进程运行不占用模型的推理成本 → 如果是可拦截类型的钩子如 PreToolUse且判断需要拦截 Claude 在上下文里只会看到操作被拒绝你的错误信息 它自己没有办法绕过只能根据这条反馈调整下一步一句话总结协作关系Skill 负责流程编排Subagent 负责重活累活隔离出去干Hook 负责任何情况下都不能违反的红线。Hook 事件详解实战常用的一批Hook 可以绑定在很多生命周期节点上下面是日常协同开发里最常用、最值得配置的几个事件触发时机能否阻断典型用途UserPromptSubmit你提交一条消息Claude 还没开始处理之前能在 prompt 送入模型前做检查或注入额外上下文PreToolUse任意工具Bash、Edit、Write…即将执行之前能exit code 2硬拦截安全护栏的核心拦截危险命令、校验参数合法性PermissionRequestClaude 请求某项操作权限时能自动批准/拒绝特定类型的权限请求减少人工确认PostToolUse工具执行完成之后不能阻断已经执行完了自动格式化、记录日志、触发下游动作PostToolUseFailure工具执行失败之后不能阻断记录失败原因做告警或重试逻辑SubagentStart某个子代理刚被启动不能阻断记录流水线跑到哪一步了做审计SubagentStop某个子代理运行结束能可要求继续记录该阶段完成情况做审计日志StopClaude主对话认为任务已完成准备结束这一回合能可强制继续收尾前的强制校验比如必须先跑一遍测试PreCompact上下文即将被压缩之前不适用提前备份完整对话记录防止关键信息在压缩中丢失SessionStart/SessionEnd会话开始 / 结束不适用加载项目特定上下文 / 做收尾清理NotificationClaude 发出通知如等待权限确认时不适用转发到桌面通知、Slack 等外部渠道注册位置可以写在settings.json项目级或用户级、组织的 managed policy settings 里也可以直接写进某个 Skill 或 Subagent 的 YAML frontmatter 里做局部生效的钩子。Hook 类型除了最常用的command跑一段 shell 脚本还支持http调用一个 HTTP 端点、mcp_tool调用一个 MCP 工具、prompt让 Claude 用一段提示词自己判断、agent调用一个专门的子代理来做判断——本指南里的例子全部用command类型是最简单直接、最不容易出偏差的一种。退出码含义command类型exit 0正常不做任何拦截exit 2硬拦截把 stderr 里的内容作为拒绝理由反馈给 Claude其他非零码通常视为脚本本身出错会被记录但不一定拦截——具体行为请以你所用版本的官方文档为准重要的护栏建议只用0和2两种避免歧义架构设计原则三个判断问题 常见反模式遇到一个新需求先问自己三个问题这件事必须 100% 发生、不允许 Claude 有任何看情况的空间吗→ 是写成HookPreToolUse拦截 /PostToolUse自动化 /Stop收尾检查这件事的执行过程会产生大量你不需要在主对话里逐字看到的中间输出吗大范围搜索、跑测试、读日志、调研文档 → 是写成Subagent只要求它回传一句话摘要这是一个你希望可复用、按固定步骤走、但每次细节略有不同的流程吗发布检查、PR 审查、生成周报、需求分析 → 是写成Skill用精准的description让 Claude 知道什么时候该用它常见反模式把红线写进 CLAUDE.md 当一句强调短会话里可能有效长会话、上下文压缩、或文件内容包含误导信息时容易失守。真正的红线只能靠 Hook Permission 配置保证。开发阶段教条式地上 Subagent需要反复讨论、调整方向的核心开发工作丢进隔离的子代理反而降低了可控性——你看不到中间过程没法随时插手。只有方案已经钉死、纯执行的范式化任务才适合隔离。在 Subagent 里嵌套调用别的 Subagent 做复杂编排技术上可能可行但出问题极难排查主对话完全看不到子代理内部又调了谁。编排权应该收在主线程用 Skill 承载每一步之间你都能插手。description写得太模糊Skill 和 Subagent 能否被正确自动触发高度依赖description字段写得够不够具体。检查代码质量这种描述容易被忽略或误触发在完成一段修改后主动调用检查代码质量、安全性和可维护性这种带了触发时机和范围的描述效果好得多。一份 Skill 塞下所有阶段把需求分析到发布的所有逻辑写进一个巨大的 SKILL.md会导致上下文一次性加载过多、单个阶段出错难定位。按阶段拆分成独立的 SubagentSkill 只负责编排顺序和关键节点确认是更清晰的架构。实战案例给项目搭一条完整的功能开发流水线目标效果在 Claude Code 里输入/feature自动跑完整个软件开发周期——需求分析 → 方案设计 → 开发实现 → 测试验证 → 代码审查 → 文档更新 → 发布检查七个阶段里需求分析、方案设计、测试验证、代码审查、文档更新、发布检查这六步适合做成独立 Subagent会产生大量你不需要逐字看的中间过程或者是范式化的固定流程开发实现默认放在主线程里做需要随时讨论调整只有范式化程度高的模块才委托给专门的 developer 子代理。全程有一层跨阶段共享的 Hook 护栏危险命令拦截、自动格式化以及一个feature-pipelineSkill 负责编排顺序、在关键节点等待你确认。核心约束Subagent 之间怎么传话Subagent 相互之间、以及与之前的对话历史之间没有共享上下文——每一个都是全新开始。所以协作靠两层机制主线程编排Skillfeature-pipelineSkill 常驻主对话依次调用每个 agent判断上一步做完了该叫下一个了并且在关键决策点停下来等你确认。文件系统作为交接介质每个阶段的产出必须落地成文件需求文档、设计文档、测试报告、审查意见下一个阶段的 agent 通过Read工具去读上一阶段的文件而不是依赖记得上一步说过什么。目录结构总览myproject/ ├── .claude/ │ ├── settings.json # 全局 Hooks跨全流程共享的护栏 │ ├── skills/ │ │ └── feature-pipeline/ │ │ └── SKILL.md # 编排七个阶段 │ └── agents/ │ ├── requirements-analyst.md # 阶段1需求分析 │ ├── solution-architect.md # 阶段2方案设计 │ ├── developer.md # 阶段3开发可选范式化任务用 │ ├── test-engineer.md # 阶段4测试验证 │ ├── code-reviewer.md # 阶段5代码审查 │ ├── doc-writer.md # 阶段6文档更新 │ └── release-manager.md # 阶段7发布检查 ├── docs/ │ ├── requirements/ # 阶段1产出 │ ├── design/ # 阶段2产出 │ ├── test-reports/ # 阶段4产出 │ ├── .pipeline-log/ # Hook 自动写入的审计日志 │ └── CHANGELOG.md └── scripts/ └── hooks/ ├── block-dangerous.sh # 拦截危险命令 ├── post-edit-format.sh # 自动格式化 └── log-stage.sh # 记录阶段完成情况逐个拆解七个阶段的具体配置与实现阶段一需求分析 —requirements-analyst.md--- name: requirements-analyst description: 需求分析专家。把用户模糊的功能诉求转化为结构化需求文档主动识别遗漏的边界条件。用于新功能开发的第一步。 tools: Read, Write, Grep, Glob model: sonnet --- 你是需求分析师。收到一个功能诉求后 1. 先用 Grep/Glob 扫一遍现有代码库了解相关模块的现状避免提出与现状脱节的需求 2. 输出结构化需求文档包含 - 背景与目标这个功能解决什么问题 - 用户故事作为 X我希望 Y以便 Z - 功能范围明确「做什么」和「不做什么」 - 边界条件与异常场景这一项最容易被漏重点检查 - 验收标准清单形式可勾选 3. 把文档写入 docs/requirements/feature-slug.md 4. 最后用一段话总结本次需求有哪些地方是你做了假设、需要用户确认的 不要在这一步写任何实现代码或做技术选型只谈要做什么不谈怎么做。设计要点tools只给了Read, Write, Grep, Glob不给Bash或Edit——这一阶段不应该有能力修改任何现有代码权限最小化本身就是一种隐性护栏。阶段二方案设计 —solution-architect.md--- name: solution-architect description: 技术方案设计专家。读取需求文档产出技术设计方案包括架构选型、接口设计、数据模型和风险点。用于需求确认后、开发开始前。 tools: Read, Write, Grep, Glob, Bash model: opus --- 你是方案设计师。收到需求文档路径后 1. 完整阅读该需求文档 2. 用 Grep/Glob 分析现有代码的架构模式、已用的库、代码风格方案要尽量复用现有模式不要凭空引入新的技术栈 3. 输出技术设计文档包含 - 整体方案一段话说清楚思路 - 涉及的模块/文件清单新增哪些、修改哪些 - 接口设计API 签名、数据结构用代码块给出 - 数据模型变更如涉及数据库给出 schema 变化 - 技术选型及理由如果有多个可选方案列出取舍 - 风险点与需要用户确认的开放问题 4. 写入 docs/design/feature-slug.md 如果需求文档中有你判断会导致技术方案显著复杂化的部分明确指出并给出替代建议而不是硬着头皮设计。设计要点model特意设成opus——方案设计是全流程里最需要深度权衡判断力的一步值得用更强的模型相比之下跑测试、格式化这类纯执行型环节用sonnet甚至更轻量的模型就够按阶段分配模型是控制 token 成本的现实做法。阶段三开发实现 — 主线程为主developer.md为辅开发这一步刻意不强制做成 Subagent大部分时候应该在主线程直接做因为你需要频繁介入、调整方向、随时看到代码变化。完全丢给隔离环境反而降低了可控性。但有一种场景适合委托范式化、重复性强、方案已经足够明确的模块比如按设计文档批量生成 CRUD 接口、按同一模式加多个类似的表单校验——这种照图纸砌砖的活丢给隔离环境跑不占用主线程的来回确认。--- name: developer description: 按技术设计文档实现代码。仅用于方案已经明确、实现路径清晰的模块开发不用于需要反复讨论设计的复杂功能。 tools: Read, Write, Edit, Bash, Grep, Glob model: sonnet --- 你是一名遵循设计文档实现代码的工程师。收到设计文档路径后 1. 完整阅读设计文档严格按文档里的接口签名和数据结构实现不要自行改动设计 2. 如果设计文档存在歧义或明显缺漏**停止实现并列出问题**不要自己猜一个方案填上去 3. 编码遵循项目现有的代码风格先读几个同目录下的现有文件确认风格 4. 实现完成后运行现有的 lint 命令自查一遍 5. 最后列出本次改动涉及的文件清单附一句话说明每个文件改了什么阶段四测试验证 —test-engineer.md--- name: test-engineer description: 测试执行与分析专家。为新功能编写测试用例并运行完整测试套件隔离处理冗长的测试输出。 tools: Read, Write, Bash model: sonnet --- 你负责测试。收到设计文档和改动文件清单后 1. 参照设计文档里的「验收标准」为改动的模块编写单元测试如项目已有测试框架遵循现有风格 2. 执行完整测试套件 3. 将结果写入 docs/test-reports/feature-slug.md - 全部通过写明覆盖了哪些用例 - 有失败定位失败用例总结失败原因和你认为的根因不要贴完整堆栈 并明确这是「测试用例本身有问题」还是「被测代码有 bug」 4. 只在主对话回复一句话摘要详细内容留在报告文件里设计要点这一步的价值就在于隔离噪音——完整跑一次测试套件动辄几百行输出堆进主对话只会让后续判断质量因为上下文变脏而下降。丢给 Subagent脏东西留在它自己的沙盒上下文里回到主线的只有一句话结论。阶段五代码审查 —code-reviewer.md--- name: code-reviewer description: 代码变更审查专家。对照设计文档检查实现是否符合方案、有无安全和质量问题。用于开发和测试完成后、合并代码前。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是资深代码审查员。收到设计文档路径后 1. 用 git diff 查看本次全部改动 2. 对照设计文档逐项检查实现是否覆盖了设计里的所有接口、数据模型是否一致、 是否有设计文档没提到但实际引入的额外改动需要说明原因 3. 独立检查代码质量边界条件、安全隐患硬编码密钥、未校验输入、SQL 拼接等、 命名和风格是否符合项目现有习惯 4. 不修改任何文件只输出审查结论 5. 用「✅ 可以合并 / ⚠️ 建议修改后合并 / ❌ 阻断合并」给结论附具体理由列表设计要点tools里没有Write或Edit——审查者不应该有能力顺手改一下这个约束用工具权限而不是靠自觉更可靠。阶段六文档更新 —doc-writer.md--- name: doc-writer description: 技术文档撰写专家。审查通过后更新用户文档、API 文档和变更日志。 tools: Read, Write, Edit, Bash model: sonnet --- 你负责文档同步。收到需求文档、设计文档和 code-reviewer 的审查结论后 1. 如果涉及对外 API 变化更新对应的 API 文档保持现有文档的格式和风格 2. 如果涉及用户可见的行为变化更新 README 或用户指南里的相关章节 3. 读取 git log 中本次功能相关的提交在 CHANGELOG.md 顶部按 feat / fix / docs 分类新增一条记录 4. 文档中避免复制粘贴设计文档的内部实现细节——只写用户/使用者需要知道的部分阶段七发布检查 —release-manager.md--- name: release-manager description: 发布前最终检查专家。确认代码审查通过、测试通过、文档已更新准备发布所需的版本信息但不执行任何实际的推送或打 tag 操作。 tools: Read, Bash model: sonnet --- 你负责发布前的最终检查。收到本次功能的全部产出文件后 1. 确认 code-reviewer 的结论是「✅ 可以合并」否则立即终止并说明原因 2. 确认 test-engineer 报告里测试全部通过否则立即终止并说明原因 3. 确认 CHANGELOG.md 已经包含本次改动 4. 检查当前分支状态、待提交文件列表确认没有遗漏或误提交的文件比如临时文件、.env 5. 生成一份发布摘要包含本次改动概述、涉及文件数、CHANGELOG 条目预览 6. 只生成摘要**绝不自行执行 git tag、git push 等操作**——这些交由主线程在用户确认后执行设计要点即使是发布检查也刻意不给 Bash 里的写权限动作留口子——这个 agent 的tools只给Read, Bash用于只读的git status、git log检查真正的推送动作留在主线程执行且必须用户明确确认这是高风险动作交还人工决策权的具体体现。编排层把七个阶段串成一条 Skill.claude/skills/feature-pipeline/SKILL.md--- name: feature-pipeline description: 完整功能开发流水线从需求分析到发布检查。当用户提出一个新功能需求、说开发一个XX功能或输入 /feature 时使用。 --- # 功能开发全流程 严格按顺序执行每个阶段结束后把该阶段产出摘要展示给用户。以下节点**必须等待用户明确确认后才能继续**其余阶段可以连续推进 1. **需求分析**调用 requirements-analyst 子代理生成 docs/requirements/feature.md → 展示需求文档摘要**等待用户确认需求范围无误** 2. **方案设计**调用 solution-architect 子代理读取需求文档生成 docs/design/feature.md → 展示技术方案摘要尤其是技术选型和风险点**等待用户确认方案** 3. **开发实现** - 如果设计文档标注的实现路径清晰、范式化程度高调用 developer 子代理 - 否则在当前主对话中直接根据设计文档编码方便随时跟用户讨论调整 4. **测试验证**调用 test-engineer 子代理运行测试并生成 docs/test-reports/feature.md 如果测试失败停止流程把失败摘要反馈给用户等待修复后重新测试 5. **代码审查**调用 code-reviewer 子代理对照设计文档审查改动 如果结论是「❌ 阻断合并」停止流程并反馈审查意见等待修复后重新审查 6. **文档更新**调用 doc-writer 子代理更新用户文档和 CHANGELOG 7. **发布检查**调用 release-manager 子代理确认前六步全部就绪生成发布摘要 → 展示发布摘要**询问是否确认打 tag 并推送。未经用户明确确认不要执行 git tag 或 git push**配套 Hooks贯穿全流程的护栏护栏是跨全部七个阶段共享的写在项目级settings.json里对主线程和所有子代理同时生效不需要每个 agent 各写一份。.claude/settings.json{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:bash scripts/hooks/block-dangerous.sh}]}],PostToolUse:[{matcher:Edit|Write,hooks:[{type:command,command:bash scripts/hooks/post-edit-format.sh}]}],SubagentStop:[{hooks:[{type:command,command:bash scripts/hooks/log-stage.sh}]}]}}scripts/hooks/block-dangerous.shPreToolUse读 stdin 里的 JSON 判断命令内容硬拦截高危操作#!/usr/bin/env bash# Claude Code 会把工具调用信息以 JSON 形式通过 stdin 传给这个脚本INPUT$(cat)CMD$(echo$INPUT|grep-ocommand\s*:\s*[^]*|head-1)ifecho$CMD|grep-Eqrm -rf|push --force.*main|push -f.*main;thenecho 检测到高危命令已拦截。如确需执行请人工在终端里手动运行。2exit2# exit code 2 硬拦截Claude Code 直接拒绝这次工具调用fiexit0scripts/hooks/post-edit-format.shPostToolUse改完文件自动格式化不阻断流程#!/usr/bin/env bashnpx prettier--write./dev/null21npx eslint.--fix/dev/null21exit0scripts/hooks/log-stage.shSubagentStop每个阶段结束时留一条审计记录方便事后追溯流水线跑到哪一步#!/usr/bin/env bash# Claude Code 会把这次 subagent 运行的信息以 JSON 通过 stdin 传入# 具体字段以当前版本官方 hooks 文档为准这里做保守处理原样落盘事后再解析mkdir-pdocs/.pipeline-logcatdocs/.pipeline-log/stages.jsonlechodocs/.pipeline-log/stages.jsonlexit0三个脚本记得加执行权限chmod x scripts/hooks/*.sh。端到端演示完整走一遍真实场景你/feature 给用户系统加一个忘记密码的邮件找回功能 [requirements-analyst 子代理运行中... 生成 docs/requirements/forgot-password.md] Claude需求文档已生成要点验证邮箱存在性但不暴露账号信息、 重置链接 15 分钟过期、限流每小时最多请求 3 次。 需要你确认链接过期时间是否要做成可配置项 你不用写死 15 分钟就行 [solution-architect 子代理运行中... 生成 docs/design/forgot-password.md] Claude方案已生成新增 POST /auth/forgot-password 和 POST /auth/reset-password 两个接口复用现有的邮件发送服务 reset token 用现有的 Redis 实例存TTL 900 秒。 风险点现有邮件服务没有限流机制需要新加。是否按此方案继续 你可以 [主线程开始编码因为涉及邮件服务改造路径不算完全范式化未走 developer 子代理] ...编码过程中PostToolUse 钩子每次改完文件都自动跑一遍 prettier / eslint... [test-engineer 子代理运行中... 生成 docs/test-reports/forgot-password.md] Claude✅ 12 个测试全部通过覆盖了正常流程、token 过期、限流触发三种场景 [code-reviewer 子代理运行中...] Claude⚠️ 建议修改后合并——reset token 生成用的是 Math.random() 建议换成 crypto.randomBytes其余没有问题 你改一下 [主线程修复该问题PostToolUse 钩子再次自动格式化] [code-reviewer 子代理再次运行...] Claude✅ 可以合并 [doc-writer 子代理运行中... 更新 API 文档和 CHANGELOG.md] Claude文档已更新 [release-manager 子代理运行中...] Claude发布检查通过审查✅、测试✅、CHANGELOG已更新、无遗漏文件。 改动清单4 个新增文件、2 个修改文件。是否确认打 tag 并推送 你确认全程你只在两个真正需要判断力的节点需求范围、技术方案被打断中间跑测试、跑审查、跑发布检查产生的大量输出都被隔离在各自的子代理上下文里主对话始终干净可读。若中途某个高危命令被触发比如某次调试中不小心让 Claude 想执行git push --forceblock-dangerous.sh会在它真正执行前就拦下不管这个命令是主线程发起还是某个子代理内部发起的——Hook 的护栏对整个会话层面生效不因为在子代理里就失效。进阶技巧与排查方法给 Subagent 配专属 HookSubagent 的 YAML frontmatter 里也能写hooks:字段实现只有这个子代理的某类调用才做额外校验。比如一个只读数据库的子代理可以专门加一条PreToolUse校验 SQL 必须是SELECT--- name: db-reader description: 执行只读数据库查询 tools: Bash hooks: PreToolUse: - matcher: Bash hooks: - type: command command: ./scripts/validate-readonly-query.sh ---Skill Hook 组合做强制流程兜底如果发现 Claude 有时会偷懒跳过Skill 里写的某一步比如没经过完整审查就想合并可以在关键节点加一个Stop或PreToolUse钩子做兜底校验即使 Skill 正文已经写了要检查也用代码再校验一遍——双保险。用 Plugin 打包整套体系分享给团队这套settings.jsonskills/agents/全部可以打包成一个 Plugin团队其他人一键安装就获得同样的七阶段流水线和护栏不需要每人手动配一遍。Plugin 里的 Skill 会自动带命名空间如/myteam:feature-pipeline避免和别人本地的同名 Skill 冲突。流水线卡住了怎么排查先看docs/.pipeline-log/stages.jsonl——SubagentStop钩子记录了每个阶段实际跑没跑、跑了几次如果某个阶段迟迟没被自动触发大概率是对应 Subagent 的description写得不够具体Claude 判断这个任务不匹配——把触发时机和范围写得更明确如果 Hook 没有生效检查脚本是否有执行权限chmod x、matcher的工具名是否拼写正确、settings.json的 JSON 格式是否有效如果某个子代理反复给出你不认可的结论去改它.md正文里的检查标准而不是每次都手动否决——让下一次调用就按新标准来模型分配策略不是所有阶段都需要最强的模型阶段建议模型档位理由方案设计更强如 opus需要深度权衡取舍判断力要求最高代码审查中等如 sonnet需要理解代码语义但任务边界清晰需求分析、文档编写中等如 sonnet结构化整理为主测试执行、格式化类 Hook轻量或不需要模型纯执行型Hook 甚至完全不需要调用模型快速上手 Checklist在新项目里从零搭建这套体系按这个顺序做mkdir -p .claude/skills .claude/agents docs/requirements docs/design docs/test-reports scripts/hooks先只配一个最简单的护栏 Hook比如拦截rm -rf验证PreToolUse确实生效——这是成本最低、见效最快的一步写第一个 Subagent建议从code-reviewer开始价值直接、风险最低用code-reviewer显式调用测试它是否按预期工作确认单个 Subagent 工作正常后再逐个补齐其余阶段的 Subagent最后写编排 Skill把各阶段串起来先只串两三个阶段跑通再逐步扩展到完整七阶段每加一个新的 Subagent 或 Skill都用一次真实的小任务实际跑一遍确认description能被正确触发而不是只检查语法对不对稳定后再考虑打包成 Plugin 分享给团队这套体系不需要一次搭完——从一条护栏 Hook 开始逐步替换掉重复劳动是比一次性铺开整套七阶段更稳妥的落地路径。