核验范围：本文阅读的是 affaan-m/ECC 的 v2.0.0 标签，重点核对 README.md、.claude-plugin/plugin.json、hooks/README.md、skills/continuous-learning-v2/SKILL.md 和 the-shortform-guide.md。文中用 Claude Code 讲机制，因为 ECC 在这个 harness 上的资料最完整。Cursor、OpenCode、Codex 等环境的安装位置、可用事件、自动加载方式都不同，不能把本文的配置原样复制过去。本文没有对 ECC 做独立的能力评测。

很多人第一次看 ECC，会先被目录数量吓到。它同时出现 Rules、Skills、Hooks、Agents、Commands、MCP、memory、instincts，看起来像把所有 Agent 领域的名词都装进了一个仓库。于是常见的两种反应是：要么觉得它无所不能，直接全量安装；要么觉得只是很长的提示词合集，索性不看。

这两种理解都不太准确。ECC 更像一套给编码 Agent 加工作规程的组件库。它不负责把一个能力普通的模型变成资深工程师，也不能替你判断需求是否正确。它做的事情是把容易遗漏的约束、重复的流程、工具调用前后的检查，以及跨会话保存的信息，放到相对合适的位置。

读完后，你应该能回答下面这些具体问题：

• 用户说 “给登录接口加限流并补测试” 时，哪一类组件会先起作用？
• 为什么 Rule 不等于强制执行，Hook 又为什么不等于模型一定会改对代码？
• 一百多个 Skills 会不会每次都塞进上下文？
• 持续学习到底记录了什么，是否会把项目习惯带到别的仓库？
• 第一次安装应该开哪些功能，怎样确认它真的在运行？

如果你还没有用过 Claude Code 或同类工具，也不用急着安装。先建立一个判断框架，比先复制一段安装命令更有用。

阅读前先统一几个词

这篇文章会反复出现几个词。它们在不同产品里名字可能不同，但意思接近。

Context 是这篇里最重要的概念。模型不会自动知道你的项目约定，它只会根据当前能看到的内容做判断。ECC 的许多设计都在处理同一个问题：哪些信息应该一直可见，哪些信息只在需要时加载，哪些操作应该在模型执行前后由程序检查。

先给出全貌：一次任务是怎样穿过 ECC 的

假设你在一个 TypeScript 项目里提出需求：

给 POST /api/login 增加 IP 限流。沿用现有错误格式，补单元测试，并确认不会把 token 打到日志里。

一条理想的任务路径大致如下。这里的箭头是理解用的流程，不代表每一个 ECC 安装都会按这个顺序自动调度。

  flowchart TD
  U[用户提出需求] --> C[Harness 组装当前上下文]
  C --> R[Rules 提供项目约束]
  C --> S[按任务读取相关 Skill]
  S --> T[Agent 读取代码并规划工具调用]
  T --> P[PreToolUse Hook 检查或提醒]
  P -->|允许| X[执行 Read Edit Bash 等工具]
  P -->|阻断| F[返回原因，调整方案]
  X --> Q[PostToolUse Hook 格式化或快速检查]
  Q --> V[运行测试并复核 diff]
  V --> M[可选：记录会话观察]
  

把它翻成白话：Rule 告诉 Agent “项目一向怎么做”；Skill 告诉它 “这类任务通常怎样做”；Agent 决定读哪些文件、调用什么工具；Hook 在特定工具调用前后运行确定性的脚本；测试和代码审查负责判断最终改动是否真的满足需求。持续学习则是另一条可选支路，它尝试从多次会话中提炼习惯。

这里已经能看出边界：如果没有测试覆盖限流逻辑，Skill 写得再好也不能替你证明功能正确；如果 Hook 只是在终端输出警告，Agent 仍可能忽略警告；如果模型把 “不要记录 token” 理解错了，最终仍要靠测试、审查和最小权限把风险压下来。

ECC 是什么，不是什么

ECC 把自己定位为 “agent harness operating system”。这是一句产品定位，并不是行业标准术语。对使用者来说，更准确的说法是：它为多个 Agent 运行环境提供一组可选择安装的工作流定义、规则、自动化 Hooks 和辅助配置。

以 v2.0.0 标签的仓库目录计，Claude Code 一侧公开列出 64 个 agents、261 个 skills 和 84 个 legacy command shims。发布说明 与 目录结构 都能交叉核对这些数量。数字只说明覆盖面，不说明某一个 Skill 的质量，也不意味着你应该同时启用它们。

ECC 不是下面这些东西：

• 不是模型训练。安装后不会改变基础模型的知识、推理能力或上下文窗口。
• 不是 CI。它可以在本地 Hook 中触发检查，但不能代替远端 CI、分支保护和人工代码审查。
• 不是安全边界。一个会提醒危险 Bash 命令的 Hook，不能代替 sandbox、凭据隔离和最小权限。
• 不是项目文档的替身。项目里真实的架构、运行方式和业务规则仍应写在项目文档与代码中。
• 功能越多，不代表 Agent 越聪明。它们会叠加上下文、延迟、权限和排错成本。

把这些预期放低，反而更容易从 ECC 获得价值。它最适合减少那些你已经知道应该做、却常在赶工时漏掉的动作，例如改完 TypeScript 后跑一次类型检查，提交前查看 diff，或者在测试缺失时先提醒自己停下来。

五类组件：职责、触发方式和常见误解

为了读源码方便，本文把 ECC 的主要内容归成五类。MCP 和 memory 会单独讨论，因为它们既不是单纯的提示规则，也不是普通 Hook。

Rules：把长期约束写成可被加载的说明

Rule 适合放相对稳定、跨任务重复使用的约定。例如：

1
2
3
4
5

## API 约定

- 失败响应统一为 `{ code, message, requestId }`。
- 新增接口必须在 `tests/api/` 增加覆盖。
- 不得将 authorization、cookie、token 写入日志。

它的优点是简单。你不必在每一次提问中重复项目风格，Agent 也能在开始工作时有一份基线。ECC 的 rules 目录还按 common、TypeScript、Python 等语言组织，适合选择与你项目有关的部分。

Rule 的弱点同样直接：它是一段给模型看的文字。模型可能没有加载到它，可能看到了却理解不完整，也可能在复杂任务里没有遵守。因此，不能把 “禁止提交密钥” 只写成 Rule 就认为密钥不会提交。高风险规则至少还应由 pre-commit、密钥扫描、CI 或仓库权限来兜底。

一个实用的判断方法是：如果违反后只会让代码风格不一致，先写 Rule；如果违反后会造成数据泄露、线上事故或不可逆修改，就不要只靠 Rule。

Skills：可按需取用的工作流包

Skill 可以理解为针对某类问题的操作手册。一个 Skill 往往有 SKILL.md，也可能带脚本、检查清单、示例、codemap 或相关资料。以 TDD 类工作流为例，内容可能要求先观察现有测试、写一个会失败的测试、实现最小代码、再运行验证。

它和 Rule 的差别在于粒度。Rule 更像长期有效的 “不要做什么” 和 “默认怎么做”；Skill 更像 “现在要做 X，这里有一套适合 X 的步骤”。技能可以由 slash command 触发，也可以被 Agent 按任务判断后读取。后者不是数学上的必然事件，模型是否挑中合适的 Skill 取决于 harness 的加载策略、Skill 描述和当时的上下文。

这也解释了为什么 “261 个 Skills 会不会把上下文挤爆” 这个问题不能只看目录数。文件存在磁盘上，和它是否进入本轮上下文，是两回事。好的使用方式是让少量高频、边界明确的 Skill 可发现，在任务相关时再读详情。把所有技能全文常驻注入，通常只会让模型更难抓住当前任务。

对初学者，我建议先挑两个就够：一个测试工作流，一个代码审查或验证工作流。连续使用一周后再回答两个问题：它是否让你少漏步骤？它是否让 Agent 的输出变得更可验证？如果答案都是否，先改 Skill 的描述或停用它，不要急着增加更多目录。

Agents：把角色和权限拆开，但别神化 “多 Agent”

ECC 的 agent 文件描述不同专项角色，例如规划、代码审查、构建修复或安全复核。主 Agent 可以把一段任务交给子 Agent，并拿回结果继续决策。这样做的价值是给不同任务准备不同的关注点，也能把长任务拆成较小的上下文块。

不过，子 Agent 不是第二个独立的真相来源。它看到的文件、能调用的工具、继承的指令、产生的费用和失败方式，都由宿主环境决定。两个 Agent 读取了同一份错误需求，很可能给出两份风格不同但同样错误的答案。更稳妥的分工是让它们做可复核的工作：一个找相关文件，一个提出测试清单，一个独立检查 diff。最终修改仍应由有明确权限的执行者落地。

当任务只是改一个文案、修一个明显的拼写错误或跑一次单测时，调度子 Agent 往往比直接处理更慢。只有任务能自然拆开，并且每个子任务都有明确输入、输出和验收方式时，多 Agent 才值得引入。

Hooks：唯一真正挂在事件上的组件

Hook 是外部脚本。它不等待模型 “想起来要执行”，而是由 harness 在事件发生时运行。以 ECC 的 Claude Code Hook 文档为例，典型顺序是：Agent 选择工具，PreToolUse 运行，工具执行，PostToolUse 运行。Hooks 文档 还列出了 Stop、SessionStart、SessionEnd 与 PreCompact 等生命周期事件。

  sequenceDiagram
  participant U as 用户
  participant A as Agent
  participant H as PreToolUse Hook
  participant T as 工具
  participant P as PostToolUse Hook
  U->>A: 修改登录限流并补测试
  A->>H: 准备调用 Edit 或 Bash
  alt Hook 允许
    H->>T: 继续执行
    T-->>P: 返回工具结果
    P-->>A: 格式化、类型检查或警告
  else Hook 阻断
    H-->>A: 返回阻断原因
  end
  

在 Claude Code 的这套约定中，PreToolUse 以退出码 2 可以阻断工具调用；向 stderr 输出内容则可以作为非阻断提醒。PostToolUse 已经发生在工具执行之后，它可以分析结果、格式化文件或提示问题，但不能撤回刚才那次工具调用。这个时间差非常重要。

例如，”禁止在非 tmux 环境启动长时间开发服务” 适合 PreToolUse，因为必须在命令运行前拦住；”编辑 .ts 文件后运行 tsc --noEmit“ 适合 PostToolUse，因为它依赖编辑结果；”发现类型错误后自动撤销编辑” 则不是可靠设计，因为它需要处理文件状态、并发编辑和误删风险。

ECC 为 Claude Code 给出了开发服务器阻断、提交前质量检查、编辑后格式化、TypeScript 检查、会话摘要等 Hook 示例。它还提供 minimal、standard、strict 三种 Hook profile，以及 ECC_DISABLED_HOOKS 等运行时开关。运行时控制说明 是首次安装前值得读的页面。

Hook 的代价也要算进去。每次 Edit 后自动跑类型检查，在小项目里很舒服，在大型 monorepo 里可能让每一次修改都变慢。每个 Hook 都应能回答四个问题：匹配什么事件？读取什么输入？写入什么地方？失败时会阻断、警告还是静默失败？答不上来时，先不要启用。

Legacy commands：入口，不是能力本体

ECC 仍保留 commands/ 目录和不少 slash command。官方短指南明确把它们称为向 Skills 迁移过程中的兼容入口，长期可复用的逻辑应该在底层 Skill 中。短指南的 Skills and Commands 一节 说得很清楚。

这对读仓库很有帮助：当你看到 /tdd、/code-review 或类似名字时，不要只读 command 文件。顺着它找到实际引用的 Skill，才知道它要求什么、读取哪些文件、会不会执行脚本。否则很容易把 84 个兼容入口误读成 84 个完全不同的系统。

MCP 不属于上面五类，却常常是风险和上下文的来源

MCP 把数据库、浏览器、GitHub、部署平台等外部能力描述成 Agent 可调用的工具。它能减少手动复制信息，但也把更多工具名称、参数说明、授权范围和潜在副作用放进 Agent 的工作环境。

可以把 MCP 想成你给新人开的系统账号。问题不是 “能不能连上”，而是：它是否只读？能访问哪些项目？能否删除、发送、部署或付款？调用前是否需要人类确认？密钥放在哪里？这些问题与 Skill 是否写得优雅没有直接关系。

上下文成本同样现实。ECC 的 README 建议关闭不用的 MCP，并把活跃 MCP 控制在 10 个以内、工具控制在 80 个以内；它还指出工具描述会消耗模型上下文。README 的上下文排错说明 给出的数字是项目维护者的经验建议，不应当作所有模型和所有项目的固定阈值。

我会把 MCP 分成三档管理：

这张表不是 ECC 专有的规则，却是使用任何 Agent 工具时都该建立的边界。

上下文管理：大目录不等于大提示词，但仍要设预算

一个常见误区是 “把所有资料给模型，它就一定做得更好”。模型的上下文不是无限免费的工作记忆。无关内容会增加费用和延迟，也会让重要约束被埋在长文本里。工具越多，模型还越容易在选择工具时犹豫。

ECC 在 Claude Code 的 Hook 运行时提供两个与 SessionStart 相关的开关：ECC_SESSION_START_MAX_CHARS 用来限制附加上下文，文档默认值为 8000 字符；ECC_SESSION_START_CONTEXT=off 可以关闭这部分附加上下文。它们只调节这一段生命周期注入，并不等于清空模型的全部历史，更不等于在其他 harness 上也有同名变量。

可以按下面的顺序排查 “Agent 最近变笨了” 这类模糊问题：

1. 先看当前是否启用了不需要的 MCP 和工具，而不是先怀疑模型版本。
2. 检查 SessionStart 是否加载了过长、过时或互相冲突的项目摘要。
3. 让每个 Skill 的触发条件更具体。例如把 “帮助写代码” 改成 “新增 TypeScript API 路由时，先定位同类路由与测试”。
4. 移除重复安装。ECC 的 README 特别提醒，不要把插件安装和全量手动安装叠在一起，否则 Hooks 和资源可能重复加载。Quick Start 有这条说明。
5. 用一个小任务复现，并记录加载了哪些规则、调用了哪些工具、耗时和测试结果。没有可观察的样本，调参很容易变成猜测。

这也是为什么我不建议初学者一上来就开完整 profile。你需要先建立 “这一项功能带来了什么效果” 的因果感，而不是在一堆自动化里猜是谁改了文件、谁让命令变慢、谁把上下文占满。

连续学习 v2：它学习的不是模型参数，而是本地的行为模式

ECC 的 continuous-learning-v2 把一条可复用的小习惯叫作 instinct。它不会魔法般地 “记住整个项目”，也不会训练基础模型。一个 instinct 由触发条件、动作、置信度、领域、证据和作用域组成。例如：

1
2
3
4
5
6
7
8
9
10
11

---
id: prefer-result-errors
trigger: "为这个仓库新增错误处理时"
confidence: 0.7
domain: "code-style"
scope: project
---

## Action

优先返回 Result 类型，不抛出业务异常。

“在这个仓库优先用 Result” 是项目习惯。”写入用户输入前先校验” 更可能是跨项目习惯。把这两类东西混在一起，持续学习就会污染不同项目。v2.1 因此引入项目级 instinct：框架写法、目录结构、代码风格默认留在项目范围；出现于两个以上项目且平均置信度不低于 0.8 的同名模式，才是全局提升候选。continuous-learning-v2 的升级条件 写明了这一规则。

它的流程可以拆成五步：

  flowchart LR
  A[会话提示与工具活动] --> B[PreToolUse 和 PostToolUse 记录观察]
  B --> C[按 Git remote 或仓库路径归类项目]
  C --> D[后台 observer 提取候选 instinct]
  D --> E[项目级或全局 instinct]
  E --> F[人工检查后 evolve 或 promote]
  

第一步已经包含一个隐私事实：官方 Skill 的流程图把 prompts、tool calls、outcomes 写入 observations.jsonl。这些原始观察默认留在本机。官方同时说明导出只能导出 instinct 模式，不能导出原始 observations，也声称不会把实际代码或对话内容共享出去。数据目录和隐私说明 值得逐行阅读。”不会共享” 不等于 “本地没有敏感数据”。如果你的提示、命令行参数或工具输出可能含客户信息、路径、密钥或个人数据，就应把本地观察文件也视为需要保护的数据。

项目识别也有细节。v2.1 会优先使用 CLAUDE_PROJECT_DIR，然后尝试 Git remote URL，再回退到仓库根路径。它为项目计算一个 12 字符的标识，相关元数据记录在 homunculus 数据目录。默认目录优先级是 CLV2_HOMUNCULUS_DIR、$XDG_DATA_HOME/ecc-homunculus、$HOME/.local/share/ecc-homunculus。因此同一远程仓库在不同机器上可以归到同一项目，但没有 remote 的目录回退是机器相关的。

默认不开 observer，不等于不需要检查 Hook

continuous-learning-v2/config.json 中的 observer.enabled 默认是 false，run_interval_minutes 默认是 5，min_observations_to_analyze 默认是 20。也就是说，自动分析并生成 instinct 的后台 observer 默认并没有打开。Hook 是否已经注册、是否在收集观察，以及你使用的安装方式是否重复注册，是另一组需要核实的状态。

尤其要避免重复配置。官方文档指出，作为插件安装时，Claude Code 会加载插件的 hooks/hooks.json；如果你又把同一个 observe.sh 的 PreToolUse/PostToolUse 配置手动抄进 ~/.claude/settings.json，就可能双重执行，还会碰到 ${CLAUDE_PLUGIN_ROOT} 的解析问题。Quick Start 的安装说明 已经给出这个警告。

我的建议是把持续学习分成三个阶段，而不是直接开启自动提升：

1. 先只读取文档和本地目录结构，确认团队是否允许保存 observations。
2. 开启观察后，先检查一段时间产生的候选。删除错误模式，尤其警惕 “某次临时修复” 被当成长期规范。
3. 只有模式在项目内稳定出现，并且你能说清它为何成立时，再考虑 /evolve。从项目级提升到全局前，先用 dry-run 和人工复核。

置信度也不能当作统计学上的真实概率。文档用 0.3、0.5、0.7、0.9 表示从暂定到近乎确定的行为等级。这是项目内部的启发式分数，不能解读为 “有 70% 的数学正确率”。它的用途是排序和决定是否建议应用，而不是替代审查。

一次从零开始的最小实践

下面是一条比 “全量安装然后祈祷” 更安全的上手路线。建议在一个可随时丢弃的练习仓库完成，不要直接拿生产仓库试验。

第一步：先选目标，而不是先选功能

给自己一个可验收的小目标，例如：

修改一个已有 TypeScript 函数，并为边界输入补一条会失败后再通过的测试。

目标越具体，越容易判断 ECC 是否有帮助。不要用 “让 Agent 写得更好” 作为第一个目标，它无法测量。

第二步：只安装最小表面

ECC 的 README 提供插件路径和手动安装路径，并明确提醒两者选一个，不要叠加。若你想先看 Rules、Agents、Commands 与核心 Skill，而不让 Hooks 全局运行，文档给出的 Claude 目标最小 profile 是：

1

./install.sh --profile minimal --target claude

它刻意排除了 hooks-runtime。如果你后来需要 core profile 但暂时不要 baseline Hooks，文档还给出 --without baseline:hooks 的方式。安装命令、系统前提和目标平台会随版本变化，所以应从 v2.0.0 的 Quick Start 复制，而不是从不带版本号的博客转载中复制。

安装完成后不要马上接入 MCP，也不要开持续学习。先确认你只得到自己预期的文件和行为。若你本来只想使用一个测试 Skill，却发现每次编辑都开始跑类型检查，说明 Hooks 或旧配置已经参与进来，需要停下排查。

第三步：拿一个任务走完整闭环

在练习仓库让 Agent 完成任务时，主动要求它按以下顺序工作：

1. 先读取目标函数、相邻测试和项目约定，说明准备改什么。
2. 写或调整一个能表达需求的测试。没有测试框架时，先说明验证替代方案。
3. 做最小实现，不顺手重构无关文件。
4. 运行与改动有关的测试、类型检查或 lint。
5. 查看 git diff，检查是否有无关格式化、调试日志、敏感信息和测试遗漏。

这五步有一部分可以由 Skill 或 Hook 提醒，但最终的验收仍在你手里。特别是 git diff，它是理解 Agent 实际做了什么的最低成本方法。初学阶段不要只看聊天窗口里 “已经完成” 的自然语言总结。

第四步：再打开一个 Hook，观察副作用

如果最小组合稳定，再单独启用一个有明确收益的 Hook。例如编辑 TypeScript 后的类型检查，或提交前的秘密扫描提醒。一次只开一个，并记录三件事：

• 它在什么事件发生时运行；
• 它消耗多少时间，失败信息是否容易理解；
• 它是提醒还是阻断，关闭开关在哪里。

第一次不要选择会自动修改很多文件的 Hook。自动格式化看似安全，但仓库的 formatter 配置、换行规则和生成文件都可能让 diff 膨胀。先在一个小分支观察，再决定是否常开。

第五步：用清单而不是感觉验收

完成一周左右的小任务后，检查下面这张表。只要有一项答不清，就先维持当前规模。

这比 “装了多少功能” 更能反映你是否真的掌握了 Agent 工程工具。

常见失败方式，以及该从哪里查起

现象一：同一个提醒出现两次

先检查是否把插件安装和手动安装叠加了，或者把插件内部 Hook 又复制进用户级设置。重复 Hook 会带来双重检查、重复日志和难以解释的性能损耗。不要先改脚本内容，先列清安装路径和实际加载的配置。

现象二：Agent 明明读了 Rule，还是违反约定

这不是罕见例外，而是提示型约束的正常局限。先把 Rule 改得更具体，提供正确与错误的项目内例子；再为高风险条目添加可以执行的检查；最后把验收写进测试或 CI。不要用 “再写十条 Rule” 代替可执行验证。

现象三：每次编辑都很慢

查看编辑后 Hook 是否启动了全量测试、全仓类型检查或网络调用。把昂贵检查放到提交、PR 或明确的质量门，而不是每次 Edit。ECC 的 Hook profile 和禁用列表正是用来做这种分层的，具体名称要以你安装的版本为准。

现象四：持续学习学到了错误习惯

把它当作数据质量问题，不是模型 “变笨了”。删除或降低错误 instinct，找出产生它的那几次 observation，确认是否把一次应急修复、个人偏好或不同项目的规则错误归纳成长期模式。项目级隔离能减少污染，不能自动判断一条习惯是否值得保留。

现象五：MCP 接上后回答反而变差，或者权限让人不安

先禁用不相关 MCP，确认工具数量和描述是否挤占上下文；再审计每个服务器的认证、读写范围和确认机制。对生产系统采用只读账号、独立服务账号或人工审批。能调用工具不代表应该授权调用。

我会怎样评价 ECC

ECC 的价值在于把 Agent 工程里容易纠缠的几种机制分开：长期约定放在 Rules，专项步骤放在 Skills，事件驱动检查放在 Hooks，复杂任务可以交给受限角色，跨会话模式则单独保存和审查。这样每一层都能独立配置、独立验证、独立关闭。

它的风险也来自同一个特点。组件多意味着组合更多。一个全量配置可能同时有过长的启动上下文、重复的 Hooks、权限过大的 MCP、质量不佳的 Skill，以及未经审查的学习数据。不了解每一层的边界时，使用者往往只能感觉到 “Agent 很随机”。

因此，我不建议把 ECC 当成第一次接触 AI 编程时的默认全家桶。它更适合作为一套可拆的材料：先拿走一个测试 Skill、一条项目 Rule、一个可关闭的 Hook，观察它们对真实任务的影响。等你可以解释一条 Edit 为什么被拦截、一个 Skill 为什么会被读到、一个 instinct 从哪里来，再扩大范围。

小结

ECC 不是替你写代码的超级插件，而是一套帮助 Agent 按规程工作的组件库。

• Rules 是长期文字约束，不能替代执行型安全控制。
• Skills 是按需读取的工作流，不应因为数量多就全部常驻上下文。
• Hooks 与工具事件绑定。在 Claude Code 中，PreToolUse 可以阻断，PostToolUse 只能在事后检查或提醒。
• Agents 适合可拆分、可复核的专项任务，不会自动带来正确性。
• MCP 需要按上下文成本和权限风险管理。
• 持续学习保存的是本地观察中提炼出的模式，不是模型训练；项目级隔离、人工检查和数据保护都不能省。

第一次使用时，从一个练习任务、两个 Skills、零或一个 Hook 开始。只要你能把加载、执行、验证、数据位置和关闭方法说清楚，下一层自动化才值得加上去。

参考资料

• ECC v2.0.0 官方仓库
• v2.0.0 README 与 Quick Start
• Claude Code Hooks 文档
• continuous-learning-v2 Skill
• The Shortform Guide