开源 Agent 套件 ECC 的边界：它替你解决什么，又明确不管什么
本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。
装一套 harness 增强件，换来的从来不是模型变聪明，而是把你原本每次都要重新叮嘱一遍的工程流程，变成不依赖你记性的默认行为——这件事有价值，但它的收益上限和代价，都比宣传语里窄。 ECC 是这类东西里做得比较彻底的一个：MIT 许可，仓库地址 https://github.com/affaan-m/ECC ，agents 目录 67 个 agent、skills 目录 281 个技能、commands 目录 94 个命令，外加 hooks、rules、记忆与安全扫描。规模大到值得单独讨论边界，也大到踩坑的方式跟小工具完全不同。
站内已经有几篇讲通用方法论的：Agent 框架横向对比讲怎么比框架，多 Agent 框架选型讲多角色协作该选什么，规格驱动开发 SDD讲先写规格再写码这条路子。这篇不重复那些，它只干一件事：拿一个你现在就能 clone 下来逐行核对的具体项目，看这些方法论落到文件系统里长什么样、代价是什么。
一、它到底装了什么东西进你的机器
先说定位。README 里那句自我描述很直白：agent 本来就会写代码，ECC 给它加的是一套协同的工程系统和工具箱。仓库里把这条链写成了一行：
plan -> test -> implement -> review -> verify -> remember -> improve
后面跟着一句更能说明设计取向的话：Optimize the context window. Persist everything else. 优化上下文窗口，其余的一律落盘持久化。这句话基本能解释仓库里所有目录的存在理由。
它区分了五种载体，各自解决不同的问题，这个区分本身就是这套东西最值得抄的部分：
- rules 是常驻上下文的标准，所以要按语言和项目挑着装；
- skills 是按需加载的工作流，任务用到才进上下文；
- agents 是有独立上下文和工具权限的执行体，用来把规划、实现、复审隔开；
- hooks 是由 harness 事件触发的脚本，跑在模型上下文之外；
- instincts 是从真实会话里提取出来、带置信度的模式，相关时才被召回。
其中「规则还是技能」这条最常被搞混，docs/capability-surface-selection.md 干脆把它写成了一份可执行的判定顺序：先问「这件事是不是每次路径或事件匹配就该发生、不需要模型判断」，是就用 rule；否则问「是不是只在任务需要时才该加载的工作流」，是就用 skill；再往下才是 MCP、本地 CLI 脚本、以及在 skill 里直接调外部 API。它还写了成本偏置：两个方案都可行时，优先选运行时更小、token 开销更低、外部活动部件更少的那个；不确定就从小的开始，等结构化服务端边界确实划算了再升级到 MCP。
这份文档对你的意义不在于 ECC 怎么组织自己，而在于你写自己的 prompt 资产时会遇到同一个问题：一条约束到底该塞进常驻规则、写成可调用的技能，还是做成一个脚本。判定顺序照抄就能用。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| agents | 有独立上下文与工具权限的角色，规划、复审、构建修复、安全、各语言 review | agents/ | 调用 planner、code-reviewer、build-error-resolver 这类角色时 |
| skills | 按需加载的工作流与领域手册，TDD、安全审查、检索、评测等 | skills/ | 触发 tdd-workflow、eval-harness、strategic-compact 等技能时 |
| commands | 迁移期保留的斜杠入口，主力面已经转向技能 | commands/，退役的在 legacy-command-shims/ | 用 /ecc:plan、/code-review、/build-fix 时 |
| rules | 常驻加载的语言与通用标准 | rules/common、rules/typescript 等 | 每一次会话都在吃你的上下文 |
| hooks | 事件触发的脚本，跑在模型之外做确定性检查 | hooks/hooks.json、scripts/hooks/ | 编辑文件、执行命令、会话起止时自动触发 |
| 记忆保管库 | 跨 harness 的本地 Markdown 记忆与交接 | skills/unified-memory/SKILL.md，数据在 .ecc/memory/ 与 ~/.ecc/memory/ | 想让 Codex 接着 Claude Code 的活干时 |
| 安全扫描 | 把 agent 配置本身当攻击面来扫 | skills/security-scan/ | 跑 /security-scan 或独立的扫描包时 |
二、它确实替你解决的那几件事
第一件是计划不再只存在于聊天记录里。 计划被写成可编辑的产物，之后才进入实现。仓库近期还给它加了个叫 Plan Canvas 的东西：agent 写完计划在本地回环浏览器里打开，你点到哪块就在哪块挂编号批注，从侧栏聊，最后按「批准」或「要求修改」，这个结论直接落到计划流程的确认闸门上。它的实现是一个说 JSON 的普通 CLI（ecc-plan-canvas），不绑具体 harness 和模型。实际收益是审计划的成本从「把意见重新打一遍字」降到「指着说」——计划评审之所以经常被跳过，很大程度就是复述成本太高。
第二件是 TDD 从一句叮嘱变成带证据的闸门。 README 里那张对照表把话说得很清楚：没有系统时，「请用 TDD」是一条模型可能忘掉的指令；有了流程之后，它变成 RED → GREEN → REFACTOR 的分段流程，每一段都要留下证据。最终交付物不只是代码，而是一串痕迹：计划、失败的测试、通过的测试、复审发现、以及最后的构建/lint/类型/测试验证。
第三件是换个上下文复审。 写代码的那个上下文去审自己写的代码，天然看不见自己的盲区。ECC 的做法是把复审交给独立上下文的 agent，/code-review 就是这条路径的入口。这不是什么新思想，但它被固定成了默认动作而不是你临时想起来的动作。
第四件是会话结束后剩下点东西。 记忆不等于存一整份长得吓人的对话记录，而是蒸馏成摘要、instincts 和可复用的技能。ECC_MAX_INJECTED_INSTINCTS 和 ECC_INSTINCT_CONFIDENCE_THRESHOLD 两个环境变量控制会话开始时注入多少条、置信度门槛多高——这两个键的存在本身就说明作者清楚这条路径会反噬上下文。关于记忆分层的通用思路，可以对照会话上下文预算怎么算那篇。
跨 harness 的记忆保管库是当前在推的方向：项目和团队记忆放在 .ecc/memory/，用户记忆放在 ~/.ecc/memory/，格式是本地可读的 Markdown，可以从一个 harness 写交接、在另一个 harness 里检索。文档在这里的措辞很克制，值得原样记住：记忆是未经审核的上下文，不是可执行策略；重要结论要回到权威来源核实，被接受的知识应该晋升进受治理的项目文档，而不是靠改记忆的信任级别来解决。
三、边界与代价：它明确不管的部分
它不改变模型能力。 流程能让一次糟糕的实现更早暴露，不能让模型突然会写它本来不会写的东西。TDD 闸门保证的是「有失败测试再有实现」，不保证测试本身测对了地方。
它不承担正确性责任。 记忆库那段话已经写了：召回的内容是未审核上下文，agent 不得当成指令或策略执行，重要主张要另行核实。这条同样适用于 instincts——从你过去会话里提取出来的模式，只代表你过去那么干过，不代表那么干是对的。
hook 层不是所有 harness 都有。 仓库自己列了限制：Codex 目前没有 Claude 式的 hook 执行对等，那边的约束靠 AGENTS.md、可选的指令文件覆盖和沙箱/审批设置来做；GitHub Copilot 既没有 hook 系统也没有子代理接口，ECC 在那边只剩指令和 prompt 层。也就是说，「确定性检查跑在模型之外」这个卖点，换个 harness 就可能只剩一半。想清楚 hook 到底能管什么，可以先看 Claude Code hooks 机制。
rules 是要付常驻成本的。 文档反复强调只装 rules/common 加你真正在用的那一个语言包。这不是客气话：常驻规则每次会话都在占位置。同理，README 里对 MCP 的建议是压住同时启用的服务器与工具数量，并且提供了 /context-budget 让你回头砍掉不需要的规则。
它会往你的机器里写文件、挂钩子、连外部服务，这是实打实的代价。 安装会在 harness 配置目录里落一批文件，hook 会在你编辑文件和执行命令时被触发并运行 shell，MCP 服务端可能持有凭据。仓库自己在安全章节里把这三样都定性成「可执行配置」。它给的对冲手段是：只从官方渠道装（GitHub 仓库、官方 npm 包、官方 GitHub App、插件标识 ecc@ecc、项目站点），第三方转载不在维护范围；卸载只删自己安装状态里记录过的文件，不认领你 harness 目录下的其他东西；以及提供 node scripts/ecc.js list-installed、doctor、repair、uninstall --dry-run 这一组先看后动的命令。
默认连接器被刻意压到很少。 README 写明只带一个默认连接器 chrome-devtools，其余都是包着 CLI/REST 的技能或需要显式选择的目录项；一次专门的审计把此前预置的那批默认连接器全退掉了，规则和退役依据记在 docs/MCP-CONNECTOR-POLICY.md。这是一个明确的取舍：开箱能力少一点，换攻击面和上下文占用小一点。
还有一部分功能压根不在基础安装里。 比如 multi-* 那组命令不在基础插件和规则安装的覆盖范围内，要另外初始化一个外部运行时才能跑起来。装完发现某个命令不工作，先确认它是不是本来就需要额外依赖。
四、套件越大，越容易出的是这三类问题
规模本身会制造问题，而且是特定的三类。ECC 自己的 docs/ARCHITECTURE-IMPROVEMENTS.md 就是一份坦率的自查，值得任何维护 prompt 资产库的人读一遍。
第一类是一致性漂移。 那份文档开篇第一条就是计数不同步：说明文件里写的 agent/技能/命令数量和仓库里实际数量对不上，README 和其他文档之间也各说各的。它给的建议是把计数从文件系统派生出来，或者维护单一清单文件让脚本和文档都读它，并且把这条的影响判为高——因为它直接影响第一印象和贡献者的信任。同一份文档里还列了另外几处同类问题：测试入口用的是硬编码文件列表，新写的测试文件不改入口就永远不会被执行；schemas/hooks.schema.json 定义了 hook 配置形状，但校验脚本没有用它，于是校验逻辑和 schema 会各自漂移；面向 Codex 和 Cursor 的技能子集是主目录的子集，主目录增删了不同步就会脱节；多语种文档在英文源演进后会悄悄过期。
这几条的共同结构是一样的：真相有多个副本，而副本之间没有强制对齐的机制。你自己攒的规则库、技能库、命令库一旦超过几十个文件，就会遇到同一件事。可执行的对策也就那么两条——要么让派生物自动生成，要么让 CI 在不一致时直接失败。
第二类是安装路径叠加。 这是这套东西最容易踩、后果最难查的坑。README 反复写：每个 harness 只选一条安装路径。插件装法和完整手动安装叠在一起，会造成技能、命令、hook 或配置重复。hook 重复执行尤其阴间——它不报错，只是每件事做两遍。相关的还有一条具体的历史教训：不要在插件清单 .claude-plugin/plugin.json 里显式声明 hooks 字段，因为宿主会按约定自动加载插件的 hooks/hooks.json，显式声明会触发重复检测报错；这个问题在仓库里来回修过好几轮，最后是加了回归测试来防止被重新引入。
第三类是上下文被自己的资产吃掉。 一套 281 个技能、94 个命令、几十份规则的东西，如果全部常驻，光是描述就能把窗口占掉一大截。ECC 的应对是把「加载时机」当成一等设计维度：技能按需加载，规则选择性安装，hook 跑在模型之外，会话起始注入的上下文有独立的环境变量可以调小甚至关掉（ECC_SESSION_START_MAX_CHARS 与 ECC_SESSION_START_CONTEXT），hook 本身还有 ECC_HOOK_PROFILE 和 ECC_DISABLED_HOOKS 两个运行时开关，不用改 hook 文件就能降严格度或临时停掉某几个。
顺带说一个有据可查的设计取向：docs/ECC-2.0-GA-ROADMAP.md 描述后续控制面时，执行顺序刻意是「先只读、后变更、晋升要过闸」——只读面稳定之后才加变更面，变更面要求显式能力门、不可变审计回执、试运行预览，失败时向关闭方向失败；技能从候选区进入正式面，必须有记录在案的评测结果、人工批准和可回滚路径。文档还专门写了一句：每个编号项是独立的实施车道，不要把只读面和变更面合并。你不一定认同这种节奏，但把「谁能改东西、凭什么改」写死在流程里，跟上来就给 agent 开写权限是两条路。
五、上手与避坑清单
一、装之前先决定「只装一条路径」，并把这个决定写下来。 会踩是因为你今天用插件装完，过两周看到文档里另一条命令顺手又跑了一遍，中间隔着的时间足够你忘掉。避法：在项目 README 或个人笔记里记一行「本机 Claude Code 用插件装，Codex 用同步脚本」，怀疑重复时先跑 node scripts/ecc.js list-installed 看安装状态，再跑 doctor 和 repair，不要直接重装。
二、rules 只装 common 加一个语言包。 会踩是因为语言包列表看着都有用，全拷贝的动作成本几乎为零，代价却要到几周后上下文吃紧时才显现，而且那时候你已经不记得是它造成的。避法：把规则当成常驻预算来算账，装完隔一周用 /context-budget 回看一次，砍掉没触发过的。
三、拷贝规则时拷整个语言目录，不要拷目录里的文件。 会踩是因为习惯性地 cp rules/typescript/*.md。文档明确说明要整目录拷，这样相对引用才不会断、文件名才不会撞。避法：命令里用 -R 带目录名，别带通配符。
四、别把仓库里的原始 hook 配置直接塞进 harness 的设置文件。 会踩是因为它看起来就是一份现成的 JSON。但那份文件是面向插件和仓库的，里面的命令路径需要安装器重写才是对的；插件装法下宿主本来就会自动加载它，再复制一份就会重复触发。避法：用安装器的 hook 运行时模块装，让它把路径解析好。
五、装完先跑一次安全扫描，把 agent 配置当代码审。 会踩是因为你默认「配置文件不是代码」。但 hook 会执行 shell、MCP 配置里可能有密钥、项目说明文件会进模型上下文——这三样都是可执行面。避法：/security-scan 跑一遍，尤其在你从任何非官方渠道拿到过配置片段之后。
六、别把记忆当结论用。 会踩是因为检索出来的 Markdown 读着很像事实。但文档给它的定位是未经审核的上下文，配套的体检命令也只报告问题、不替你删改记忆内容，可选的记忆 MCP 面上刻意不提供复审、晋升、覆写这几类工具——换句话说，把记忆升格成结论这一步，系统压根没打算替你做。避法：记忆里出现的关键判断，回到代码或权威文档核实一遍；确认无误的，晋升进正式项目文档，而不是留在记忆里反复被召回。
七、装完发现某个命令不动，先查它是不是需要额外运行时。 会踩是因为命令确实出现在命令列表里，但基础安装并不覆盖它的外部依赖。避法：翻一下该命令在文档里的说明段落，看有没有单独的初始化步骤。
最后
这套东西的价值，在于它把「每次都要重新说一遍的工程要求」变成了不依赖你记性的默认行为，并且把加载时机、权限边界、卸载路径都当成一等问题处理。它的边界也同样清楚：不提升模型能力、不担保正确性、hook 那套确定性检查换个 harness 就打折、常驻规则和默认连接器都要你自己付上下文的账。
如果你要评估它，建议的读法是：先读 docs/capability-surface-selection.md，因为那份判定顺序你不用装 ECC 也能立刻用在自己的规则库上；再读 docs/ARCHITECTURE-IMPROVEMENTS.md，它会告诉你这类资产库长大之后会烂在哪；最后才回到 README 的安装章节，挑一条路径装下去。
一份三条的自检：你能说清自己装的是哪一条路径吗？你能列出当前常驻加载的规则有哪些吗？你能在不看文档的情况下把它干净卸掉吗？三个都答不上来，就先别装。
本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。