乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > ECC 源码架构解析:别把配置大全当能力本身

ECC 源码架构解析:别把配置大全当能力本身

当前时间： 2026-08-12 05:00:11 分类：办公文件 评论(0)
ECC 源码架构解析:别把配置大全当能力本身

ECC 最容易被看轻，因为它的外表很像一个配置仓库。

我更在意的是另一件事：它把团队工作方式拆成了不同 AI Coding 工具都能加载的部件，skill、rule、command、hook、MCP、插件 manifest，各归各位。

这件事听起来不性感，但很接近 AI Coding 进团队后的真实问题：模型已经够强了，团队经验怎么进模型的工作现场？

先别把它当配置仓库

看 ECC 这种仓库，第一反应很容易是：

这不就是一大堆 Claude Code / Codex / Cursor / OpenCode 配置吗？

如果只看文件数量，这个判断也不算离谱。

仓库里能看到 .claude、.codex、.cursor、.opencode、.kiro、.github、.agents 等多套目录，还能看到 skills、rules、commands、hooks、MCP 配置、GitHub prompt、团队配置和企业控制文件。

只停在“配置大全”这个判断，后面的架构就看不到了。

ECC 更像是在回答一个更难的问题：

怎么把一套工程团队的方法论，迁移到不同 AI Coding Harness 里？

这里的 Harness 可以理解成 AI Coding 工具的运行壳：Claude Code、Codex、Cursor、OpenCode、Gemini CLI、Kiro 等。模型负责生成和推理，Harness 负责加载指令、暴露工具、执行命令、触发 hook、管理上下文和权限。

ECC 的源码形态说明了一件事：

AI Coding 的能力不是只从模型参数里长出来的。它还来自宿主加载了什么规则、暴露了什么工具、在哪些事件上拦截、用什么流程逼 Agent 验证。

我按这个问题往下读源码。

一套能力包，拆成六层

ECC 的入口很多，能串起来的主要是六层：

插件层：.claude-plugin / .codex-plugin技能层：.agents/skills / .claude/skills规则层：.claude/rules / .cursor/rules / .codex/AGENTS.md命令层：.claude/commands / .github/promptsHook 层：.cursor/hooks/*工具层：.mcp.json / .codex/config.toml / ecc-tools.json

看起来散，其实职责并不一样。

插件层回答“怎么被宿主发现和安装”。

技能层回答“什么时候该触发哪套工作流”。

规则层回答“在这个仓库里什么能做，什么不能做”。

命令层回答“某类任务应该怎么启动”。

Hook 层回答“在 prompt 提交、文件编辑、shell 执行前后怎么拦一下”。

工具层回答“Agent 能调用哪些外部能力”。

如果用普通工程系统类比，ECC 不是一个业务服务，更像一个跨 IDE / CLI 的“团队工程制度发布包”。

它把团队规范拆成文件，然后投递到不同 Harness 能识别的位置。

普通 prompt pack 到这里就结束了。ECC 还多了一层分发、适配和运行时约束。

把它放进一次真实 session 里看，会更清楚：

安装阶段：manifest 把 skills / commands / MCP 注册给宿主启动阶段：AGENTS.md、rules、默认配置进入上下文任务阶段：用户用 command 或自然语言启动某类工作流执行阶段：skill 约束步骤，MCP 提供外部能力事件阶段：hook 在 prompt、tool、edit、stop 等节点插入检查收尾阶段：verification / review / compact 把结果和证据整理出来

这条链路里，模型只占中间一段。前面有加载，旁边有工具，后面有验证。

ECC 这类仓库和“收藏一堆 prompt”的差别也在这里：prompt 是一次输入，能力包是运行时环境。一个只影响模型下一段话，另一个影响 Agent 从看到需求到收尾验证的整条路径。

插件层：让能力包先被宿主识别

先看两个 manifest。

.codex-plugin/plugin.json 里声明了：

{  "name": "ecc",  "version": "2.0.0-rc.1",  "skills": "./skills/",  "mcpServers": "./.mcp.json",  "interface": {    "displayName": "ECC",    "category": "Coding",    "capabilities": ["Interactive", "Read", "Write"]  }}

.claude-plugin/plugin.json 则把 Claude Code 能识别的入口列出来：

{  "name": "ecc",  "version": "2.0.0-rc.1",  "skills": ["./skills/"],  "commands": ["./commands/"]}

这两个文件的意义不在字段本身，而在抽象边界：

插件 manifest 只声明能力入口，不直接规定每一步怎么做。具体行为规则在 skills、commands、hooks、rules、MCP 里。

也就是说，插件层是发现机制，不是能力本体。

很多人装插件时会问“这个插件是不是能让模型更聪明”。更准确的问法应该是：

这个插件把哪些能力入口注册进了 Harness？这些入口会在什么时机进入模型上下文？哪些入口会变成可执行工具？哪些入口只是可读规则？

ECC 的 manifest 给了一个最小答案：Codex 侧暴露 skills 和 MCP，Claude 侧暴露 skills 和 commands。

不同宿主能接住的能力不同，所以同一套方法论必须做适配。

技能层：把“该怎么做”拆成可触发工作流

.agents/skills/ 下面有很多 SKILL.md，比如：

tdd-workflowverification-loopsecurity-reviewstrategic-compactapi-designbackend-patternsfrontend-patternseval-harnessdeep-researchdocumentation-lookup

这些文件不是普通说明文。

它们的典型结构是：

---name: verification-loopdescription: "A comprehensive verification system for Claude Code sessions."---

然后正文规定什么时候触发、怎么执行、输出什么格式。

比如 verification-loop 不是泛泛地说“写完要测试”，而是把验证拆成构建、类型检查、lint、测试、安全扫描、diff review 六段，并要求输出固定报告。

这类 skill 的作用是把模糊要求变成可执行流程：

“注意质量”  ↓build / typecheck / lint / test / security / diff  ↓结构化 verification report

这才是 Agent 可执行的东西。

模型并不缺“知道要测试”的常识。缺的是在上下文复杂、用户催促、任务很长的时候，还能坚持走完整流程。

Skill 的价值就在这里：

把经验压成触发条件和执行步骤，让 Harness 在合适时机把它喂给模型。

规则层：不是让模型自由发挥，而是给它仓库边界

ECC 还有一层容易被忽视：rules。

例如 .claude/rules/everything-claude-code-guardrails.md 里有 prompt defense、commit workflow、architecture、code style、detected workflows 等内容。

里面有一句提示很值得保留：

Generated by ECC Tools from repository history. Review before treating it as a hard policy file.

这句话很工程化。

它承认规则可以从仓库历史生成，但不能盲信。也就是说，ECC 并不是把生成结果伪装成绝对真理，而是把它变成可审查的规则文件。

团队落地 AI Coding，绕不开这一步：

不要只把规范写在人的脑子里。也不要只靠模型“理解项目风格”。把规范落成文件，让 Agent 每次都能读到。

这里可以用一个退款 Agent 的例子来理解。

如果项目里有这样的隐含规则：

退款金额不能由前端传入值直接决定。必须以后端订单明细、支付流水、优惠券抵扣重新计算。

你把它写成 prompt，可能某次有效。

你把它写进仓库规则，并让 Harness 在相关文件读取或编辑时注入，才更接近工程控制。

规则层管的就是这些不该靠临场发挥的边界。

Hook 层：把“事后提醒”改成“事件拦截”

ECC 里 .cursor/hooks/ 很值得看。

例如 before-submit-prompt.js 会读取用户提交的 prompt，检查里面是否像是带了 OpenAI key、GitHub token、AWS key、Slack token、private key。如果匹配到，就在提交前打印警告。

伪代码大概是：

const prompt = input.prompt || input.content || input.message || "";const secretPatterns = [  /sk-[a-zA-Z0-9]{20,}/,  /ghp_[a-zA-Z0-9]{36,}/,  /AKIA[A-Z0-9]{16}/,  /xox[bpsa]-[a-zA-Z0-9-]+/,  /-----BEGIN (RSA |EC )?PRIVATE KEY-----/];for (const pattern of secretPatterns) {  if (pattern.test(prompt)) {    console.error("[ECC] WARNING: Potential secret detected in prompt!");  }}

这段代码不复杂，但能看出 hook 的作用：

不要等模型生成完再提醒。在事件发生前后插入检查点。

在 AI Coding 里，很多风险不是“模型不知道”，而是“没有人在那个时机拦”。

比如：

  • • 提交 prompt 前检查是否泄露密钥；
  • • 执行 shell 前检查危险命令；
  • • 读文件后注入附近规则；
  • • 编辑文件后跑格式化或安全检查；
  • • session 结束时保存摘要；
  • • compact 前把重要状态写到 memory。

Hook 把 AI Coding 从“聊天”变成“事件驱动系统”。

没有 hook，很多约束只能写在 prompt 里。

有 hook，约束就可以挂到真实操作点上。

命令层：把高频任务变成入口，而不是每次重新讲需求

ECC 还有 .claude/commands/ 和 .github/prompts/。

例如：

.claude/commands/database-migration.md.claude/commands/feature-development.md.claude/commands/add-language-rules.md.github/prompts/tdd.prompt.md.github/prompts/security-review.prompt.md

这些文件的作用不是让用户少打几个字那么简单。

它们把高频任务的启动方式标准化了。

“做一个数据库迁移”不是一句话能讲清的。它通常涉及 schema、migration、回滚、数据兼容、测试、发布顺序。如果每次都靠用户临时描述，Agent 的执行路径一定会漂。

命令层把这类任务变成固定入口：

/database-migration  ↓读取迁移工作流  ↓按固定顺序检查 schema / migration / types / tests  ↓输出可审查结果

这和公司里沉淀 runbook 是同一件事。

只是读 runbook 的人，变成了 Agent。

工具层：MCP 不是越多越好，默认边界更要紧

ECC 的 Codex 指南里有一段对 MCP 的说明：

Treat the project-local .codex/config.toml as the default Codex baseline.

它还强调配置合并策略：

Add-only by defaultExisting servers are never modified or removedDrift warningsUser config is always preserved

这比“我给你配了 7 个 MCP”更重要。

MCP 工具一多，真实问题不是“能不能调用”，而是：

谁来管理这些配置？新增工具会不会覆盖用户已有配置？凭证放哪里？远程工具默认是不是只读？高风险操作要不要用户确认？

ECC 的 .codex/AGENTS.md 里还写了外部动作边界：networked tools 默认按只读处理；posting、publishing、pushing、merging、opening paid jobs、changing third-party resources、modifying credentials 需要明确用户批准。

有工程价值的是这层边界感。

不是“接了很多工具”。

而是“工具接进来以后，谁负责权限和边界”。

这里还有一个更底层的判断：跨宿主能力不是等价的。

ECC README 里明确写到，Codex 还没有 Claude-style hook execution parity。也就是说，Claude Code 里可以靠 hook 做运行时拦截的东西，到 Codex 侧就要退回到 AGENTS.md、model_instructions_file、sandbox / approval 设置和 MCP 配置上。

这不是一个小差异。

如果一个团队把“安全检查”全部设计成 hook，那它迁移到 Codex 以后就会丢一部分执行力。反过来，如果你把所有约束都写成长期指令，Claude Code 里又会浪费 hook 能提供的事件拦截能力。

所以 ECC 的跨宿主适配，本质上不是文件路径映射，而是能力降级：

Claude Code：plugin manifest + skills + commands + hooks + MCPCodex：AGENTS.md + skills + MCP + sandbox/approval + agent rolesCursor / OpenCode：rules / hooks / MCP 能力各有差异

这也是为什么 .claude/ecc-tools.json 里会记录 selectedComponents、selectedPackages、dependencyGraph、resolutionOrder、managedFiles。它不是只在复制文件，而是在保存一次“能力选择和投递计划”。

工程上最怕的是假装所有宿主一样。ECC 的价值，恰好在它把这些不一样暴露了出来。

ECC 的运行模型：把团队经验编译成 Harness 能加载的文件

把这些层串起来，ECC 的运行模型大概是：

团队经验 / 仓库历史 / 工作流  ↓生成或维护 skills、rules、commands、hooks、MCP 配置  ↓按 Claude / Codex / Cursor / OpenCode 等宿主格式投递  ↓Harness 在 session、prompt、tool、edit、command 等时机加载  ↓模型在更强约束下执行 AI Coding 任务

所以 ECC 的价值不在“文件够多”。

文件多只是表象。

架构点在这里：

同一套工程制度，要能被多个 Agent Harness 消费。

这件事做不好，就会变成到处复制粘贴规则。

做得好，团队规范就能像依赖一样升级、裁剪、审查。

这里还有一个容易忽略的工程点：ECC 把“生成”和“运行”分开了。

规则可以从仓库历史生成，MCP 可以按 profile 安装，skills 可以按宿主投递。但这些生成出来的文件，最终还是落到 .claude、.codex、.cursor、.opencode 这类宿主目录里，由 Harness 在运行时读取。

这就避免了一种常见坏味道：所有东西都塞进一个超级 prompt。超级 prompt 读起来很完整，运行时却很难知道哪句话在什么时候生效，也很难禁用其中一段。拆成文件以后，至少可以做到：

规则可以审查技能可以按任务触发命令可以单独维护MCP 可以按权限裁剪hook 可以挂到具体事件

从团队治理角度看，这比“写一份万能提示词”更像工程资产。

一个具体例子：退款逻辑怎么进入 Agent

假设你们在做一个订单退款系统，真实约束是：

退款金额必须由后端重新计算；优惠券、余额、支付渠道、部分退款都要进入计算；高金额退款需要审批；退款接口必须幂等；每次退款状态变化要写审计日志。

如果只靠用户在聊天框里写：

帮我实现退款，注意安全。

Agent 很容易只写 happy path。

按 ECC 的思路，这些约束会被拆到不同层：

rules：退款金额、审批、审计、幂等规则skills：api-design、security-review、verification-loopcommands：feature-development 或 database-migrationhooks：编辑后跑测试、提交前查密钥MCP：查订单文档、查接口规范、跑测试、查日志

当 Agent 修改 refund-service 文件时，规则层告诉它业务边界。

当它准备提交时，verification skill 逼它跑验证。

当它调用外部工具时，MCP 权限边界决定它能查什么、能不能写。

当 prompt 里出现敏感 token，hook 在提交前拦一下。

这不是“更会写代码”。

这是把 Agent 放进一个有制度的工程环境。

别急着全量照抄

这类仓库最容易出两个问题。

第一个是上下文污染。

skills、rules、commands、hooks、MCP 都有用，但不是每一条都应该在每次任务里出现。无关规则太多，模型会被噪声拖慢，甚至把不相关约束误用到当前任务。

所以好的能力包必须能裁剪。

ECC 的 ecc-tools.json 里能看到 profile、selectedComponents、selectedPackages、dependencyGraph、managedFiles 这类字段，说明它不是简单全量复制，而是在做 install plan。

第二个是规则陈旧。

仓库演进后，生成规则可能过期。比如测试框架换了、包管理器换了、目录结构变了，旧规则继续注入，Agent 反而会稳定地做错事。

所以规则层一定要有审查和再生成机制。

所以 Generated by ECC Tools from repository history. Review before treating it as a hard policy file. 这句话值得保留。

团队该怎么抄

如果你想借鉴 ECC，我建议别从“复制所有配置”开始。

先问五个问题：

1. 哪些规则必须每次进入上下文？2. 哪些能力只在特定任务触发？3. 哪些风险应该用 hook 拦，而不是写进 prompt？4. 哪些工具默认只读，哪些需要确认？5. 规则变更以后，怎么测试和回滚？

一个团队需要的 AI Coding 能力包，通常不必一开始做得很大。

最小可用版本可以只有：

AGENTS.md：项目边界和工作方式skills：验证、代码审查、安全审查rules：语言规范、业务边界、危险操作hooks：密钥扫描、危险命令、编辑后检查MCP：文档检索、代码搜索、测试执行

先把这几层跑通，再扩 agents、commands、memory、parallel workflow。

不要反过来。

否则配置越多，Agent 越像背着一车过期 SOP 的实习生。

为什么这类仓库会火

AI Coding 工具正在从“聊天框”变成“工程系统”。

早期大家关心模型会不会写代码。

现在该问的是：

它有没有流程？有没有边界？有没有上下文？有没有验证？有没有权限？有没有团队规范？

ECC 的源码恰好把这些问题摊在了文件系统里。

它不是一个可以无脑复制的答案。

它更像一个信号：AI Coding 的下一段竞争，不只是“谁的模型更会写代码”，而是谁能把团队的工程纪律变成 Agent Harness 能加载、能触发、能验证的能力层。

资料来源

  • • affaan-m/everything-claude-code / ECC，源码快照：edebcc89efa09dc2705748151d98286ff3bb6023，2026-06-08。
  • • README.md：项目定位、跨 Harness 支持、版本说明。
  • • .codex-plugin/plugin.json、.claude-plugin/plugin.json：Codex / Claude Code 插件入口。
  • • .codex/AGENTS.md：Codex 侧 skills、MCP、外部动作边界。
  • • .agents/skills/*/SKILL.md：TDD、verification、security、context compact 等技能定义。
  • • .claude/rules/everything-claude-code-guardrails.md：仓库规则与 prompt defense 基线。
  • • .cursor/hooks/before-submit-prompt.js：prompt 提交前密钥模式检查。
  • • .claude/ecc-tools.json：install profile、dependency graph、managed files。