ECC安装与配置：把 Claude Code 装进一个能稳定发挥的 Harness

一、从一次"差口气"说起

老陈做了五年前端，最近接了个全栈私活：Python 后端加 React 前端，登录、注册、JWT、邮箱验证，外加一个管理后台。

听起来不大。干起来才发现处处别扭。

本地跑得挺顺的代码，一推到线上就报错。pip install 装出来的版本和 lock 文件对不上，celery worker 启动报 ImportError，邮件发送的 SMTP 凭据在 .env.example 里少了一行。前端那边更糟：登录页的 UI 调了三版，老陈总觉得差点味道------按钮圆角、字体、留白，单独看都没问题，搁一起就散。

他试过 GitHub Copilot，提示贴脸但不会动项目。试过 Cursor，能改但分不清当前项目的命名规范。试过把项目丢给网页版 Claude，让它看 README 后写代码------写是写了，第二次开窗口又得把背景从头讲一遍。

每次提 PR，老陈都在跟同一组问题搏斗：环境对不上、UI 没标准、跨会话丢上下文、命名风格飘。

问题不在他不会写。在他和 AI 助手之间，缺一套能稳定发挥的"运行环境"。

二、问题不在模型，在 Harness

这个词是跟 affaan 的推文学的：harness。原意是马具，引申到 AI 语境，就是"套在 agent 外面的那一整套基础设施"------skill、agent、hook、rule、memory、tool surface、verification loop。

模型再强，套在一团乱的 harness 上，跑出来的效果也飘。

老陈后来回想，撞上的每一类问题，几乎都能映射到 harness 的某个组件：

效果不好的场景	harness 哪块没做对
本地和线上依赖对不上	rules 缺项目级规范，hooks 缺 pre-commit 锁版本
UI 调三版还是差口气	skill 缺 design system / frontend-patterns
跨会话总是从头讲背景	缺 SessionStart/Stop 钩子、缺 memory 落盘
命名风格飘忽不定	rules 缺语言级编码规范
改完一个文件，另一个文件莫名坏掉	缺 verification loop、缺 e2e-testing
不同 AI 助手效果差异巨大	没统一的 MCP 配置、没统一的工具 surface

每一行都是工程问题，不是 prompt 问题。

三、ECC 是什么：Claude Code 的 Harness 框架

ECC 全称 Everything Claude Code。GitHub 仓库 affaan-m/everything-claude-code，目前 14 万 star、21k fork、170 多个贡献者。作者 affaanmustafa，Anthropic x Forum Ventures 黑客松的获胜者------他用 Claude Code 配合这套配置做了 zenith.chat，2025 年 9 月拿的奖。

官方 README 开头那句话很关键：

来自 Anthropic 黑客马拉松获胜者的完整 Claude Code 配置集合。

不止是配置文件，而是一整套完整系统：技能体系、本能行为、记忆优化、持续学习、安全扫描，以及研究优先的开发模式。

它的定位很清晰：ECC 不是 Claude Code 的替代品，也不是某个 IDE 插件。它是 Claude Code（以及 Codex、Cursor、OpenCode、Gemini）的 harness 框架------把"如何让 agent 在你的项目里稳定发挥"这件事，开箱即用地做成了一套可复用资产。

仓库里大致这些东西：

63 个 sub-agent（planner、architect、code-reviewer、python-reviewer、go-build-resolver......）
251 个 skill（按语言和领域分门别类）
79 个 slash command（含 multi-* 系列）
一套 hooks（PreToolUse、PostToolUse、Stop、SessionStart、PreCompact......）
12 个语言目录的 rules（common、typescript、python、golang、swift、php......）
跨平台 Node.js 脚本（Windows / macOS / Linux 都跑得动）

配套还有两个指南：Shorthand Guide 讲基础搭建，Longform Guide 讲 token 经济、内存持久化、验证循环、并行化策略。基础先读 Shorthand，进了门再看 Longform。

把 ECC 装上，相当于给 Claude Code 套上 affaan 那匹跑赢黑客松的马具。

四、ECC 怎么把那些"差口气"的场景一个个对号入座

老陈装了 ECC 之后，把自己的痛点挨个对了一遍官方文档，发现每一项都有现成方案。

环境对不上 → rules/common/coding-style.md 强制把依赖锁文件、pre-commit 配置写进项目规范；scripts/hooks/pre-compact.js 之类的钩子会在写文件前检查 lock 状态；deployment-patterns skill 给的就是 Docker + 健康检查 + 回滚的标准做法。

UI 差口气 → frontend-patterns 和 react-patterns 两个 skill 内置了 design system 接入流程；frontend-slides、liquid-glass-design 等 skill 让 UI 风格有据可依；frontend-a11y 把无障碍硬指标也带上了。

跨会话丢上下文 → SessionStart、PreCompact、Stop 三个钩子形成闭环：会话开始自动从 ~/.claude/sessions/YYYY-MM-DD-topic.tmp 加载上次的状态；上下文快撑爆时 PreCompact 把关键信息落盘；会话结束 Stop 钩子把今日决策、踩过的坑、未完成项写到当日 session 文件。continuous-learning skill 在 Stop 钩子里顺手把"这次调试的非平凡发现"提炼成可复用 skill，下回直接加载。

命名风格飘 → rules/typescript、rules/python 等语言目录里就是各语言的强制编码规范------命名、错误处理、不可变性、文件组织，全是明文写的。Claude Code 在你的项目里跑，自动加载这套规范。

改一处坏一处 → verification-loop、eval-harness 两个 skill 把"checkpoint-based eval"和"continuous eval"两种验证模式都内置了；e2e-testing skill 配套 Playwright 模式；tdd-workflow 让 agent 写代码前先写测试。

不同 AI 助手效果差异 → ECC 兼容 Claude Code、Codex、Cursor、OpenCode、Gemini 一堆 harness。这意味着同一套配置，换模型不换规则，效果相对稳定。

安全问题 → 配套工具 AgentShield（npx ecc-agentshield scan）扫 CLAUDE.md、settings.json、MCP 配置、hooks、agent 定义，5 大类：密钥检测（14 种模式）、权限审计、钩子注入分析、MCP 服务风险评估、agent 配置审查。返回 A-F 等级，CI 退出码 2 直接挂门禁。

把官方文档翻完，老陈那张"问题---harness 组件"对照表每一行都有了对应。

五、安装：分两条路

5.1 推荐方式：作为插件

bash 复制代码

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

装完即可使用 63 个 agent、251 个 skill、79 个 command。命名空间是 ecc:，所以命令长这样：

bash 复制代码

/ecc:plan "添加用户认证"
/ecc:code-review

5.2 ⚠️ rules 不会自动装

这是新手最容易栽的坑。Claude Code 插件系统不支持通过插件分发 rules，是上游限制。所以装完插件后，要再手动复制 rules 目录：

bash 复制代码

git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code

mkdir -p ~/.claude/rules
cp -R rules/common ~/.claude/rules/
cp -R rules/typescript ~/.claude/rules/   # 选你用的语言

Windows 下用 PowerShell：

powershell 复制代码

New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules" | Out-Null
Copy-Item -Recurse rules/common "$HOME/.claude/rules/"
Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"

不要同时跑 ./install.sh --profile full 或 npx ecc-install --profile full。插件已经会自动加载 ECC 的 skills、commands 和 hooks；再执行完整安装会把同一批内容再次复制到用户目录，导致技能重复、运行时行为重复。

5.3 multi-* 命令还要再装一层

/multi-plan、/multi-execute、/multi-backend、/multi-frontend、/multi-workflow 这几个 multi-* 命令需要额外运行时：

bash 复制代码

npx ccg-workflow

它会装两个关键组件：~/.claude/bin/codeagent-wrapper 和 ~/.claude/.ccg/prompts/*。没装的话，这几个 multi-* 命令直接报缺组件。

5.4 装好第一件事：跑 AgentShield

bash 复制代码

npx ecc-agentshield scan

扫一遍当前项目配置，密钥、权限、钩子注入、MCP 风险，一次性出报告。CI 挂门禁就用这条命令。

六、配置原则：装上不算完，得按需精简

ECC 装完默认是"开箱即用"------所有 skill、所有 agent、所有 MCP 都注册着。这对个人玩具项目挺爽，对生产项目就是性能灾难。

README WARNING 里那句话说得很直白：

不要一次启用所有 MCP。如果启用了太多工具，你的 200k 上下文窗口可能会缩小到 70k。

6.1 三个硬指标

全局配置 20-30 个 MCP
单项目启用 <10 个
活动工具 <80 个

6.2 老陈的精简顺序

先砍 MCP。Playwright 和 Chrome DevTools 都暴露了 click、screenshot、navigate、type，功能高度重叠。Python 后端 + React 前端，浏览器测试主要靠 Playwright，于是关掉 Chrome DevTools。

接着是行业 skill。healthcare-、defi- 、homelab-、wireguard- 、marketing-、recsys-------这些是通用 Agent OS 的"行业模板"，不是 coding runtime。一个都不留。

最后是 agent。保留 6 个就够：planner、architect、code-reviewer、python-reviewer、typescript-reviewer、performance-optimizer。删掉 swift-reviewer、rust-reviewer、cpp-reviewer、go-reviewer 这些用不上的语言审查 agent；删掉 chief-of-staff、silent-failure-hunter、conversation-analyzer 这些实验型 agent。

6.3 包管理器和钩子严格度

bash 复制代码

export CLAUDE_PACKAGE_MANAGER=pnpm                    # 强制用 pnpm
export ECC_HOOK_PROFILE=standard                      # strict | standard | off
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder"    # 临时闭嘴

ECC 自动检测顺序：环境变量 → .claude/package-manager.json → package.json 的 packageManager 字段 → 锁文件 → 全局配置。

精简完之后，老陈那个项目跑起来才顺了手。

七、跨平台：Windows 也能照着敲

ECC 整套 hooks 和脚本都用 Node.js 重写过了，Windows / macOS / Linux 三端都跑得动。Windows 下唯一要注意的是路径写法：

Unix：~/.claude/rules/
Windows：$HOME/.claude/rules/

~/.claude/ 在 Windows 里实际指向 C:\Users\<用户名>\.claude\，PowerShell 不会自动展开 ~，用 $HOME 更稳。

八、装好之后

老陈的项目跑了两周，再回头看那个用户系统：

依赖问题没了。rules 把 lock 文件和 pre-commit 写成了项目硬规范，agent 改代码自动遵循。
UI 不用反复调了。frontend-patterns skill 让 Claude Code 写组件前先调 design system，三版变一版。
跨会话不再丢上下文。SessionStart 钩子把昨天的 session 文件喂回去，模型接得上。
命名风格统一了。rules/typescript 一上，组件命名、文件命名、错误处理全按规范来。
改一处不再坏别处。verification-loop 跑起来，每改一个文件自动跑测试。

老陈跟同事讲起这事，说了句不太上台面的话：

"以前觉得 AI 写代码不行，折腾一圈才明白，是我那马具太破。"

ECC 不让模型变强。它把模型周围那一圈乱糟糟的配置，收编成了能复用、能迭代、能团队共享的 harness 基础设施。