[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”ECC 值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

一句话：ECC 是一个 AI 编程 Agent 的 harness 性能优化系统，为 Claude Code、Cursor、Codex、OpenCode 等工具提供 skills、hooks、rules、安全扫描和持续学习能力。

为什么需要它

裸用 Claude Code 时，你需要自己写 CLAUDE.md、配置 hooks、摸索最佳实践。ECC 把 10+ 个月的实战经验打包成一套即插即用的系统：63 个 Agent、251 个 Skills、79 个命令、34 条 Rules、20+ 个 Hook 脚本。没有它，你需要从零构建这些配置；有了它，一条命令就能获得生产级的 Agent 工作流。

核心优势

• 跨工具统一：一套配置同时适配 Claude Code、Cursor、Codex CLI、OpenCode、GitHub Copilot 等 7+ 工具，不用每换一个工具就重写规则
• 规模庞大：251 个 Skills 覆盖 TypeScript、Python、Go、Swift、Java、Perl 等 12+ 语言生态，Django、NestJS、Spring Boot、Laravel 等框架都有专用模式
• 安全扫描（AgentShield）：内置 1282 个测试、98% 覆盖率、102 条静态分析规则，可检测 CLAUDE.md 注入、MCP 风险、hook 注入等 5 类安全问题
• 持续学习系统：通过 /skill-create 从 git 历史提取项目专属 Skills，通过 instinct 系统积累经验
• Hook 自动化：PreToolUse/PostToolUse/Stop 等 8 类 hook 事件，自动格式化、TypeScript 检查、session 持久化等开箱即用

性能表现

官方无公开 benchmark 数据。ECC 的”性能”主要体现在：

[!note] 注意 ECC 的”性能优化”指的是优化 Agent 的工作流程质量（减少返工、提升代码规范性），而非运行时性能。

快速上手

安装（Claude Code 插件方式，推荐）

# 1. 添加 ECC 为 marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# 2. 安装插件
/plugin install ecc@ecc

# 3. 验证安装
/plugin list ecc@ecc

安装后即可使用 63 个 Agent、251 个 Skills、79 个命令。

手动安装（备选）

# 克隆仓库
git clone https://github.com/affaan-m/ECC.git
cd ECC

# 复制配置到你的项目
cp -r .claude/ /你的项目/.claude/
cp CLAUDE.md /你的项目/CLAUDE.md
cp -r skills/ /你的项目/skills/
cp -r hooks/ /你的项目/hooks/
cp -r rules/ /你的项目/rules/

MCP 配置

# 插件安装不会自动启用 MCP，需要手动配置
# 复制 MCP 定义到项目级 .mcp.json
cp mcp-configs/mcp-servers.json /你的项目/.mcp.json

# 如果你已有同名 MCP，用环境变量排除
export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"

[!warning] 替换 API Key mcp-servers.json 中的 YOUR_*_HERE 占位符必须替换为你的真实 API Key。

配置要点

1. Hook 配置：hooks/hooks.json 由 Claude Code v2.1+ 自动加载，不要在 plugin.json 中重复声明，否则会报 Duplicate hooks file 错误
2. Hook 运行时控制：ECC_HOOK_PROFILE=minimal|standard|strict 控制 hook 严格程度；ECC_DISABLED_HOOKS=... 禁用特定 hook
3. 规则分层：rules/common/ 是通用规则，rules/typescript/ rules/python/ 等是语言专用规则
4. AgentShield 安全扫描：npx ecc-agentshield scan 快速扫描，--opus 启用三阶段对抗分析

适用场景

适合：

• 使用 Claude Code / Cursor / Codex 做日常开发，想快速获得生产级 Agent 工作流
• 团队想统一 AI 编码规范和安全标准
• 需要跨语言（TS/Python/Go/Swift/Java）的统一开发体验
• 想从 git 历史自动提取项目专属 Skills

不适合：

• 只用 GitHub Copilot（Copilot 没有 hook 系统和 subagent API，ECC 的自动化能力大部分不可用）
• 对 CLAUDE.md 有严格自定义需求（ECC 会覆盖你的配置，需要仔细合并）
• 轻量使用场景（ECC 体量很大，小项目可能用不上 251 个 Skills）

已知坑 & 注意事项

[!warning] Duplicate hooks file 错误 最常见的问题。Claude Code v2.1+ 自动加载插件的 hooks/hooks.json，如果你在 plugin.json 中显式声明 hooks 路径，会触发重复检测错误。不要加 "hooks" 字段。参见 #29、#52、#103。

[!warning] GateGuard restate-retry 循环 长会话中 GateGuard 的 fact-force restate-retry 循环可能放大模型的重复陷阱（#2142）。目前 Open 状态。

[!warning] Codex 插件路径不稳定 repo marketplace 使用 ./，本地插件发现有限制（#2128）。

• 配置覆盖风险：ECC 的 CLAUDE.md 会替换你项目原有的配置，安装前务必备份
• MCP 不自动启用：插件安装不会自动配置 MCP 服务器，需要手动操作
• Windows 兼容：Claude 配置目录是 %USERPROFILE%\.claude，不是 ~/claude

竞品对比

选择建议：如果你想要一套完整的 Claude Code 增强系统（skills + hooks + rules + 安全），选 ECC。如果你只需要某个单一能力（记忆、压缩、远程调用），用对应的轻量工具更合适。ECC 和 claude-mem/Headroom 可以共存，但需要注意 CLAUDE.md 的合并。

生态 & 社区

• 维护状态：2000+ commits，v2.0.0-rc.1（2026 年 4 月），活跃开发中
• 文档质量：好——README 极其详尽，有中文翻译，有 examples/ 目录提供真实项目配置示例
• 周边生态：AgentShield（安全扫描）、NanoClaw（模型路由）、ecc-dashboard（GUI 仪表盘）、skill-creator GitHub App
• 社区活跃度：207K stars、31.8K forks、170+ contributors，Issues 响应快

引入评估

结论：推荐 — ECC 是目前最全面的 AI 编程 Agent harness 优化系统，特别适合 Claude Code 深度用户。体量大但模块化，可以选择性启用。注意备份现有配置再安装。

推荐引入版本：v2.0.0-rc.1（最新，含 Dashboard GUI 和 Operator 工作流）

相关链接

前置知识：Claude Code · MCP 竞品：../记忆与持久化/claude-mem · ../记忆与持久化/Headroom · RTK 使用场景：AI Agent · 开发工具 底层概念：Claude Code · MCP 项目落地：[[ ]] 对比笔记：../对比与选型/ECC vs Headroom vs RTK vs claude-mem 对比

• 官方仓库
• 官网
• AgentShield
• npm: ecc-universal
• npm: ecc-agentshield

个人备注

{留白，供后续补充实际使用心得}