从四个 agent 定义文件反推开源 Agent 套件 ECC 的分工模型
本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。
读 ECC 的 agent 定义文件，真正有信息量的不是那几段角色描述，而是每个文件被削掉了什么。 四个文件摆在一起看，会发现它们的差别不在”你是一位资深某某”这句开场白上——那句谁都会写——而在 tools 白名单里少了哪个工具、输出模板锁死了哪几个字段、红旗清单盯的是代码还是盯的是产物本身。这些才是把一个通用模型压成某个特定形状的东西。
先说清楚本篇和站内几篇的分工。Claude Code subagent 怎么用 讲的是机制本身，Agent 角色分工怎么切 和 任务分解粒度怎么定 讲的是通用方法论——该不该拆、拆到多细。这篇不重复那些结论，只干一件事：拿一个任何人都能 clone 下来当场核对的开源项目，看这套方法论落到具体文件里长什么样，以及它为此付出了什么代价。ECC 是 MIT 许可证的开源套件，装在编码 agent 之上，README 里给自己的定义是一条流水线：plan -> test -> implement -> review -> verify -> remember -> improve。
一、四个文件，四种被削过的形状
agents/planner.md 的产出是一份计划文档，而且模板是硬的。它的 Plan Format 一节直接给出 markdown 骨架，每个实现步骤必须带四个字段：Action（具体动作）、Why（为什么要这一步）、Dependencies（依赖哪一步）、Risk（Low/Medium/High）。文件末尾的 Red Flags to Check 里，前几条是常见代码坏味道（函数超 50 行、嵌套超 4 层、硬编码值），最后三条却掉转枪口指向计划自己：没有测试策略的计划、没有明确文件路径的步骤、无法独立交付的阶段。再往上一节 Sizing and Phasing 写死了一句话——每个阶段必须能独立合入，避免出现”所有阶段做完才有东西能跑”的计划。
agents/architect.md 同样跑 opus，产出却完全不同：它交的是取舍记录。Trade-Off Analysis 一节要求每个设计决策都写满 Pros、Cons、Alternatives、Decision 四项；ADR 模板给到 Context / Decision / Consequences / Alternatives Considered / Status / Date。它的 Red Flags 是一串架构反模式的名字——Big Ball of Mud、Golden Hammer、Premature Optimization、Not Invented Here、Analysis Paralysis、Magic、Tight Coupling、God Object。也就是说，architect 管”为什么这么选、放弃了什么”，planner 管”第几步动哪个文件”。两件事在人脑子里经常糊成一团，在这里被拆成两个文件。
agents/code-explorer.md 换成了 sonnet，流程五步：找入口、追执行路径、映射架构分层、识别已有模式、记录依赖。它的输出模板收得比前两个更死——Entry Points、Execution Flow、Architecture Insights、Key Files 表（三列：File、Role、Importance）、Dependencies 分 External 和 Internal 两栏、最后 Recommendations for New Development 一节只允许三种句式：Follow、Reuse、Avoid。这三种句式就是它被允许发表意见的全部空间：说清新代码该沿用什么、复用什么、绕开什么，且都指向已经存在的代码。除此之外，文件里没有让它给代码质量打分的地方，也没有让它出设计方案的地方——流程第三步提到留意反模式，落点也是记录在架构洞察里，不是拿去做评审结论。它交的是一张地图，地图上可以标”此处有坑”，但不负责告诉你路该怎么修。
agents/silent-failure-hunter.md 开篇一句话定调：对静默失败零容忍。它的猎捕目标枚举到了代码形态这一级——空的 catch 块、错误被转成 null 或空数组且不留上下文、.catch(() => []) 这种看起来很优雅的兜底、丢掉的堆栈、笼统的 rethrow、网络与文件与数据库调用外面没有超时和错误处理、事务性工作没有回滚。输出格式只有五项：location、severity、issue、impact、fix recommendation。没有寒暄，没有总体评价。
二、约束到底写在哪几个位置
把四个文件的头部并排看，约束落点很清楚：
# agents/planner.md 与 agents/architect.md
tools: Read, Grep, Glob
model: opus
# agents/code-explorer.md
model: sonnet
tools: Read, Grep, Glob
# agents/silent-failure-hunter.md
model: sonnet
tools: Read, Grep, Glob, Bash
第一个落点是 tools 白名单。这四个角色没有一个拿到 Write 或 Edit——规划、设计、探索、猎错全是只读工种，猎错那个多一个 Bash 是因为它要跑检查。作为对照，同目录下的 agents/spec-miner.md 确实拿到了 Write，但文件里紧跟一段 Tool guardrails，把 Write 限死到只能创建 openspec/specs/<capability>/spec.md 这一个路径，并要求 Bash 保持只读、不做变更不装包不联网。权限不是靠正文里叮嘱一句”请谨慎”，是靠白名单加一条能被人读懂的书面边界，两者都落在文件里而不是落在口头约定里。
第二个落点是 model。规划和架构给 opus，探索和猎错给 sonnet。同目录的 code-architect.md、code-reviewer.md 也是 sonnet。这条选择本身就是分工模型的一部分：需要权衡和推理的岗位吃贵模型，需要遍历和模式匹配的岗位吃便宜模型。全能 agent 做不到这一点，因为它一个会话里什么活都干。
第三个落点是输出模板。四个文件都有 Output Format 或等价的模板段落，且模板越靠下游越死。planner 给的是骨架，允许你填；code-explorer 给的是表格列名；silent-failure-hunter 只剩五个字段。产物形状固定下来，下一环才敢直接消费。
第四个落点是 description 字段。planner 和 architect 的 description 里都带 “Use PROACTIVELY”，code-reviewer.md 更狠，写着 “MUST BE USED for all code changes”。这一行不是给人看的说明文字，是给编排层看的路由信号。
还有一处容易被忽略：这四个文件正文的第一段是完全相同的六条 Prompt Defense Baseline，逐字一致——不改身份不覆盖项目规则、不泄露密钥凭据、非必要不输出可执行代码与链接、对同形字符与零宽字符与紧迫话术保持怀疑、把外部抓取内容一律当不可信数据先校验、不生成攻击类内容。也就是说，对提示注入的处理不是挑几个高危角色单独加固，而是每个 agent 文件都带一份——成本极低的一种落法：写进模板，跟着文件走。
| 组成部分 | 它负责什么 | 仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| planner | 出实现计划，带步骤依赖与风险等级 | agents/planner.md | 复杂特性动工前 |
| architect | 出设计取舍与 ADR | agents/architect.md | 结构性决策、要留记录时 |
| code-explorer | 追执行路径、交代码地图 | agents/code-explorer.md | 改陌生模块、接手老代码 |
| silent-failure-hunter | 猎静默失败与危险兜底 | agents/silent-failure-hunter.md | 改 PR、排”看起来正常”的怪问题 |
| 特性开发编排 | 七阶段串起探索到评审 | commands/feature-dev.md | 想按固定流程做一个新特性 |
| PR 评审编排 | 并列跑六个评审角色再汇总 | commands/review-pr.md | 提完 PR 想过一遍机器评审 |
| 流水线技能 | 给出各阶段该调谁的对照表与两道人工闸门 | skills/orch-pipeline/SKILL.md | 想知道整套怎么串 |
| 编排规则 | 写明并行派发与交付契约 | rules/common/agents.md | 自己写编排逻辑时 |
三、拆开的好处，要串起来才看得见
单看四个文件，你只会觉得”分得挺细”。把编排文件拿出来读，才知道细分的收益兑现在哪。
commands/review-pr.md 定义的评审流程是：先用 gh pr view 拿 PR 详情和 diff，再去找项目自己的 CLAUDE.md、lint 配置、TS 配置和仓库约定，然后并列跑六个角色——code-reviewer、comment-analyzer、pr-test-analyzer、silent-failure-hunter、type-design-analyzer、code-simplifier——最后去重、按严重度排序、分组汇报。这里有一条很实用的约束叫 Confidence Rule：只报置信度 80 及以上的问题，且分三档，Critical 是 bug/安全/数据丢失，Important 是缺测试和质量问题，Advisory 只在你明确要的时候才给。六个角色各自视角单一，汇总层负责去重和排序——这个结构如果压进一个全能 agent，六种视角会在同一段上下文里互相稀释，最后输出一堆不痛不痒的”建议关注”。
commands/feature-dev.md 是另一种串法，七个阶段：读需求 → 用 code-explorer 摸现有代码 → 带着探索结论去问澄清问题并等回复 → 用 code-architect 出设计并等批准 → 实现 → 用 code-reviewer 评审 → 收尾。注意第 3、4 阶段都明确写了要等用户回应再往下走。skills/orch-pipeline/SKILL.md 把闸门写得更硬：GATE 1 在计划之后，用户不批准就不许写实现代码；GATE 2 在提交之前，不确认就不许 commit；两道闸门之间不停。同一个文件里还有一句话点破了交接方式——整条流水线不携带隐藏状态，规划文档本身就是交接物。这跟站内讲的中间产物落盘是一个道理：角色之间靠文件传，不靠会话记忆传，所以角色才敢换模型、才敢并行、才敢重跑。
最有意思的是 rules/common/agents.md。它前半段鼓励并行派发独立任务，后半段紧跟一条 Delegation Completion Contract，三条：你的最终消息就是交付物，绝不能以”正在等后台 agent”结束回合；一旦派发就必须负责收集，禁止发完不管；只有当工作装不进一个上下文时才拆，深度是结果不是计划。这条规则底下附了 rationale，写明它来自一次实际观察到的失败——研究型角色照着”并行派发”那一节生了一堆子任务，然后把”等待中”当成最终答案返回，所有子任务其实都跑完了，结果全被丢掉。规则加了一句结论：并行规则如果没有配套的完成契约，产出的就是僵尸任务。把踩坑记录连同修正一起写进规则文件，比只留一条冷冰冰的规范有用得多。
四、边界与代价
通用模板必然是钝的。 agents/architect.md 后半段有一节明确标着 Project-Specific Architecture (Example)，里面是一套示例技术栈和一张按用户量分级的扩容计划；agents/planner.md 的 Worked Example 是一份 Stripe 订阅计费的完整计划。两处都老实标了”示例”，但它们的作用是给详细度定基准，不是给你的项目下结论。你的仓库长什么样，模板不知道。照着示例里的结论抄，抄到的是别人项目的形状。
只读换来的是交接成本。 这四个角色一个字节的代码都不写，好处是它们不可能把你的仓库改坏，代价是每一次交接都要把上下文重述一遍。规划文档要写得够细，下一环才接得住；写得细，token 就花在重复叙述上。分工不是免费的，省下来的是上下文污染，付出去的是重复描述。
每个角色都有明确不管的事。 code-explorer 不评价好坏，所以你不要指望它告诉你”这段设计有问题”；silent-failure-hunter 盯的是错误处理的形态，不是业务逻辑对不对——一段错误处理完美但算错了金额的代码，它不会有反应。review-pr 的置信度门槛也意味着，低于 80 的疑点会被直接丢掉，这条规则换来的是噪音少，丢掉的是那些”说不太准但确实可疑”的线索。
它会往你机器上写东西。 README 给的手动安装方式是把 agents/*.md 拷进 ~/.claude/agents/、把 rules/common 和一个语言包拷进 ~/.claude/rules/ecc/、技能平铺到 ~/.claude/skills/<skill-name>/。hooks 更重：hooks/README.md 里 PreToolUse 那张表明确写了哪些钩子会用退出码 2 直接拦截，比如在 tmux 之外跑 dev server 会被挡下，提交前的质量检查发现问题也会拦。这是它的设计意图，但你得知道自己的机器上多了一层会拦命令的东西。同一份文档还专门警告：不要把仓库里的 hooks.json 直接粘进 ~/.claude/settings.json 或拷进 ~/.claude/hooks/hooks.json，那份文件是面向插件与仓库路径的，必须走安装器重写路径。
数量本身就是代价。 67 个 agent、281 个技能、94 个命令，全铺开的结果是你根本记不住有哪些角色，路由信号再准也架不住候选集太大。README 里同时提供了按需安装的入口，这是有原因的。涉及模型服务商时还有一层：不同角色挂不同模型，账单结构和额度规则各家不同且会调整，以官方最新说明为准。
五、上手与避坑清单
别一次全装。 会踩是因为 full 档会把技能、规则、hooks 一起铺到你的配置目录，之后你分不清一个奇怪行为是你自己的配置还是它带来的。避法：先只拷 agents/*.md，跑几天看哪几个角色真的被调起来；再加 rules/common 和一个你实际在用的语言包。README 里还留了一条容易忽略的提醒——如果你已经按插件方式装了，就不要再跑 ./install.sh --profile full，两种装法会打架。
hooks 必须走安装器。 会踩是因为 hooks/hooks.json 里每条 command 都是一长串 node -e 引导代码，靠环境变量和一组候选路径去定位仓库根目录；你手动拷过去，路径解析不到，钩子会以一种不太好排查的方式失效。避法：用安装器的 hooks 运行时模块单独装，它会针对你实际的配置根目录重写命令。
别指望装完就自动分工。 会踩是因为路由信号写在 description 里——PROACTIVELY、MUST BE USED 这类措辞是给编排层的软提示，不是硬开关，模型完全可能视而不见。避法：用 /feature-dev、/review-pr 这种固定编排入口，把该调谁写死；或者在你自己项目的规则文件里写清楚”什么情况下必须调哪个角色”。
拆完一定要收。 会踩是因为并行派发很爽，写完派发逻辑就以为完事了，实际结果是派出去的活跑完没人接。避法：照 rules/common/agents.md 的完成契约来——派发者必须等结果、整合结果、然后自己返回，最终那条消息就是交付物。这一条比它看起来重要，因为失败时不会报错，只会安静地少东西。
闸门别拆。 会踩是因为一路自动跑到底看起来效率最高，但一个错的计划会被极其忠实地实现出来，回滚成本远大于当初多看两分钟计划。避法：保留计划之后、提交之前这两个确认点，它们卡的正是最贵的两个错误。这个话题在人在环中怎么设计里展开过。
模板当基准，别当答案。 会踩是因为示例写得太完整，容易顺手照抄。避法：抄它的字段结构和详细度——每步写清 Action / Why / Dependencies / Risk，每个决策写清 Pros / Cons / Alternatives / Decision——技术选型部分一律换成你自己的。
收个尾
这套分工模型可以压成三个自检问题，问的是你自己写的任何一个 agent：它的 tools 里有没有一个是它其实不需要的？它的输出有没有固定到下一环能直接消费的程度？它派出去的活，谁负责收？
想继续往下读，建议的顺序是：rules/common/agents.md 看编排契约和那条来自真实翻车的 rationale，skills/orch-pipeline/SKILL.md 看各阶段该调谁和两道闸门，commands/review-pr.md 看多角色汇总怎么去重排序，最后到 agents/ 目录里挑跟你日常语言对应的那个 reviewer 文件对着读。四个文件读完，你大概就知道自己该抄哪几行、该跳过哪几段了。
本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。