everything-claude-code/docs/project-overview.zh-CN.md

# Everything Claude Code 项目分析

## 项目定位

这个仓库本质上不是一个“业务应用”，而是一套给 AI 编码代理使用的“工程化运行时 + 能力分发包”。它把提示词、子代理定义、技能库、命令库、hooks、规则、安装器、状态管理、测试与跨平台适配整合在一起，目标是把 Claude Code、Codex、Cursor、OpenCode 这类 agent harness 调教成更稳定、更可控、更像资深工程师的工作流系统。

从仓库里的实际内容看，它当前是一个成熟的产品化分发仓库，而不是零散配置集合：有 `25` 个 agents、`57` 个 commands、`108` 个 skills、完整的 hook runtime、选择性安装 manifest、CLI、SQLite 状态查询命令，以及测试与校验链。核心说明在 [README.md](../README.md)、[package.json](../package.json)、[AGENTS.md](../AGENTS.md)。

## 它到底在做什么

它做的事可以概括成 5 层：

### 1. 规则层

把团队/个人想让 AI 始终遵守的工程规范固化下来，比如 TDD、80% 覆盖率、安全检查、immutability、Git 工作流、性能与上下文管理。这部分在 `rules/` 下面，按 `common + language packs` 组织。

### 2. 能力层

把不同任务拆成可复用能力单元。

- `agents/` 是“角色型子代理”，例如 planner、architect、security-reviewer、code-reviewer、build-error-resolver。
- `skills/` 是“方法论/领域知识包”，例如 TDD、verification-loop、frontend-patterns、market-research、deep-research、security-review、frontend-slides、x-api 等。

### 3. 交互层

把常用工作流做成斜杠命令。比如 `/plan`、`/tdd`、`/code-review`、`/verify`、`/quality-gate`、`/loop-start`、`/model-route`、`/sessions`、`/harness-audit`。这部分在 `commands/`。

### 4. 自动化运行时

通过 hooks 在会话开始、编辑文件、运行命令、会话结束等时机自动触发行为，例如：

- 加载上下文
- 保存 session
- 建议 compact
- 格式化代码
- TypeScript 检查
- `console.log` 检查
- 质量门禁
- 成本跟踪
- 从会话中提取可学习模式

配置在 `hooks/hooks.json`，实现主要在 `scripts/hooks/`。

### 5. 安装与适配层

它不是只服务 Claude Code，而是做了多平台适配：

- `.claude-plugin/` 面向 Claude Code 插件
- `.codex/` 面向 Codex
- `.cursor/` 面向 Cursor
- `.opencode/` 面向 OpenCode

安装不是硬编码复制，而是 manifest 驱动的 profile/module/component 选择性安装，见：

- `manifests/install-profiles.json`
- `manifests/install-components.json`
- `manifests/install-modules.json`

## 主要功能

按功能看，这个项目覆盖面非常广：

- `工程开发工作流`
  规划、TDD、代码评审、构建修复、E2E、覆盖率、重构清理、文档更新、质量门禁。
- `多语言支持`
  TypeScript、Python、Go、Java、Kotlin、Rust、Perl、PHP、Swift、C++ 等都有规则或技能包。
- `安全能力`
  安全 reviewer、security-review skill、安全扫描、输入校验、secret 管理、提交前检查。
- `上下文与记忆管理`
  SessionStart/Stop hooks、pre-compact、strategic compact、持续学习、instinct import/export/evolve。
- `多代理编排`
  worktree/tmux orchestration、multi-plan、multi-execute、loop-start、loop-status、PM2 工作流。
- `研究与内容能力`
  deep-research、market-research、article-writing、investor-materials、investor-outreach、crosspost、x-api。
- `媒体与文档能力`
  frontend-slides、fal-ai-media、video-editing、visa-doc-translate、document-processing 类技能。
- `运行状态与诊断`
  `ecc` CLI 支持 `install/plan/list-installed/doctor/repair/status/sessions/session-inspect/uninstall`。

## 这个仓库的实际架构

你可以把它理解成下面这条链路：

用户请求  
→ 命令或 AGENTS 指令触发  
→ 选择合适 agent / skill / rule  
→ hooks 在关键时机做自动检查与状态保存  
→ scripts 负责真正执行安装、审计、诊断、状态查询  
→ 不同平台目录把同一套能力映射到 Claude / Codex / Cursor / OpenCode

这也是为什么它看起来像“文档很多”，但其实不是文档仓库。Markdown 只是配置载体，真正的产品能力来自：

- 结构化规则
- 可组合技能
- 自动化 hooks
- 安装与运行时脚本
- 测试和校验链

## 最值得注意的几个特点

- 它强调“agent-first”，不是单 agent 直接硬做，而是主动委派给 planner、reviewer、security-reviewer 等角色。
- 它强调“research-first”和“verification-first”，不是只生成代码，还要求验证、评审、学习、沉淀。
- 它已经从 Claude Code 配置包，演化成“AI agent harness performance system”。
- 它支持“按需安装”，不是所有用户都要装全量能力。
- 它把“经验”产品化了：把作者长期使用中总结的流程，固化成规则、命令、hook 和技能。

## 适合什么人用

最适合这几类人：

- 想把 Claude Code / Codex / Cursor 调成稳定工程助手的个人开发者
- 想给团队统一 AI 编码规范和工作流的技术负责人
- 需要多语言、多框架、多工具链支持的工程团队
- 想做 AI agent orchestration、持续学习、自动质量门禁的人

## 一句话总结

这个项目是在做一套“给 AI 编码代理装上的工程操作系统”。它不是帮你开发某个业务功能，而是帮你把 AI 开发这件事本身标准化、自动化、可复用、可审计。

## AI 代码正确性保障与自动化测试

这个项目保证“AI 生成代码正确”的方式，不是靠某一个单点机制，而是靠一整套分层校验体系。核心思路是：先用规则约束 AI 的行为，再用 hooks 做即时检查，再用命令触发系统性验证，最后用测试和覆盖率把这些机制本身也测住。

先说结论：它并不能“数学上保证” AI 代码一定正确，但它把常见错误尽量前移、自动化、制度化了。也就是说，它主要保证的是“高概率正确 + 尽早暴露问题 + 可重复验证”，而不是一次生成就绝对无误。

### 一、它如何保证 AI 代码更靠谱

#### 1. 规则约束

仓库把 TDD 设成默认工作方式，明确要求先写测试，再写实现，再验证覆盖率，最低 80%。这不是建议，而是写进规则和 skill 的硬约束。也就是说，AI 理想状态下不是“先瞎写代码再补测试”，而是按 RED → GREEN → REFACTOR 的节奏工作。

#### 2. 任务分工

它鼓励把任务分给专门 agent，比如：

- `tdd-guide` 负责测试优先
- `code-reviewer` 负责改完后的质量检查
- `security-reviewer` 负责敏感逻辑
- `build-error-resolver` 负责构建和类型问题

这能降低一个 agent 同时负责“写代码、判断自己对不对、审查自己”的自我偏差。

#### 3. Hooks 即时纠偏

只要 AI 编辑文件，hooks 就会在后台做一些轻量但高频的自动检查，尽量在错误扩散前拦住。

#### 4. 人工触发的深度验证

比如 `/verify`、`/quality-gate`、`/test-coverage`、`/eval`，这些命令要求 AI 在关键节点主动跑构建、类型检查、lint、测试、覆盖率、安全扫描、差异审查。

#### 5. 项目自身也被测试

这个仓库不只是要求别人测试，它自己的 hook、安装器、manifest、命令和适配逻辑都有自动化测试和 CI 校验。

### 二、具体自动化机制有哪些

#### 1. TDD 机制

TDD 是第一道“正确性”防线。它要求：

- 先写测试
- 先运行并确认测试失败
- 再写最小实现让测试通过
- 再重构
- 最后检查覆盖率是否达到 80%+

它强调三类测试都需要：

- 单元测试：函数、组件、工具方法
- 集成测试：API、数据库、服务交互
- E2E 测试：关键用户路径

这意味着它不是只关心“代码能跑”，而是要求对行为、边界条件、错误路径都建立测试样例。

#### 2. 编辑后的自动 hook 检查

这是最接近“实时守门员”的部分。

- `post-edit-format`
  文件编辑后自动格式化 JS/TS，支持 Biome 或 Prettier。
- `post-edit-typecheck`
  编辑 `.ts/.tsx` 后自动找最近的 `tsconfig.json`，跑 `tsc --noEmit`，并尽量只过滤出和当前文件相关的错误。
- `quality-gate`
  编辑后跑轻量质量门禁。对不同语言用不同工具：
  - JS/TS/JSON/MD 走 Biome 或 Prettier
  - Go 走 `gofmt`
  - Python 走 `ruff format`
- `check-console-log`
  每次响应结束时检查已修改的 JS/TS 文件里是否残留 `console.log`。

这一层解决的是“写完马上出问题”的场景，比如格式错、类型错、调试语句没删掉。

#### 3. 系统化验证命令

最核心的是 `/verify`。它要求按顺序做：

1. Build Check
2. Type Check
3. Lint Check
4. Test Suite
5. Security / Secrets / `console.log` 审计
6. Git diff 审查

这里的关键点不是“有这些命令”，而是顺序。比如 build 都不过，就不应该继续往下假装验证通过。

另外还有两个辅助命令：

- `/quality-gate`
  按路径或项目范围手动执行质量管线，适合在 hook 之外主动检查。
- `/test-coverage`
  专门做覆盖率分析，找出低于 80% 的文件，并按缺口补测试。

这说明它不把“测试通过”当成终点，还要求你看覆盖率盲区。

#### 4. Eval 机制

这是更偏 AI 工程的方法，不只是传统代码测试。

它引入几类概念：

- `Capability eval`
  AI 是否具备某个新能力
- `Regression eval`
  新改动是否破坏旧行为
- `pass@1 / pass@3 / pass^3`
  用来评估 AI 在多次尝试中的稳定性

这和普通单元测试不同。普通测试是“代码对不对”，eval 更像“AI 工作流整体是否稳定地产出对的结果”。

#### 5. 会话级持续学习与回放

这不是直接验证代码是否正确，但它能减少 AI 因“失忆”导致的错误重复。

- `session-start`
  会话开始时加载上次 session 摘要、已学习技能、项目类型等上下文。
- `session-end`
  每次 Stop 时从 transcript 中提取用户请求、用过的工具、修改过的文件，写入 session 文件。
- `evaluate-session`
  会话结束时判断这次对话里有没有可抽取的稳定模式，供后续沉淀成 skill。

这层对“正确性”的贡献是减少上下文断裂、避免同类错误反复出现。

### 三、这个仓库自己做了哪些自动化测试

这部分很关键。因为如果这些 hooks、命令、安装器本身不可靠，那整套“保障正确性”的系统就是空的。

当前仓库有 50+ 个测试文件，覆盖范围很广，测试类别大致分为：

- `hooks 测试`
  覆盖 quality-gate、evaluate-session、auto-tmux-dev、hook flags 等行为。
- `安装与配置测试`
  覆盖 install-plan、install-apply、manifest、install-state 等逻辑。
- `CLI 和脚本测试`
  覆盖 `ecc`、`harness-audit`、`doctor`、`repair`、`session-inspect` 等命令。
- `底层库测试`
  覆盖 formatter 解析、包管理器检测、项目类型识别、状态存储等基础能力。
- `集成级测试`
  验证 hooks 和整体链路在组合情况下是否按预期工作。

### 四、除了业务测试，还有“结构正确性”校验

这个项目还有一类很实用的自动化：不是测业务逻辑，而是测仓库里的“配置资产”有没有坏掉。也就是 agents、commands、skills、rules、hooks 这些内容是否仍然有效。

`npm test` 里会先跑一串 validator，再跑测试，包括：

- `validate-agents.js`
  检查 agent Markdown 是否有 frontmatter、必需字段、合法模型值。
- `validate-commands.js`
  检查命令文档非空，以及引用的 command / agent / skill 是否存在。
- `validate-rules.js`
  检查所有 rule 文件是否非空可读。
- `validate-skills.js`
  检查每个技能目录是否有 `SKILL.md`。
- `validate-hooks.js`
  检查 `hooks/hooks.json` 的 schema、事件名、matcher、hook 类型和字段是否合法。

这类测试很重要，因为 ECC 本身大量依赖 Markdown 和 JSON 配置文件。少一个字段、拼错一个 agent 名称，普通代码单测未必能及时发现，但 validator 能直接拦住。

### 五、覆盖率是怎么要求的

它明确要求 80%+ 覆盖率，这既出现在规则里，也出现在 npm 脚本里。

`package.json` 中的 `coverage` 脚本使用 `c8`，并设置了硬阈值：

- lines 80
- functions 80
- branches 80
- statements 80

也就是说，不是“跑个 coverage 看看”，而是没到门槛就失败。

### 六、它能保证“用户项目里的代码正确”到什么程度

这里要区分两件事：

#### 1. ECC 仓库自身

它自己的 hooks、命令、安装器、适配层，是有自动化测试和覆盖率门槛的。

#### 2. 用户正在开发的业务项目

ECC 并不会天然知道你的业务逻辑是否正确。它做的是提供一套强制工作流，让 AI 去：

- 先写测试
- 跑构建、类型、lint、测试
- 看 coverage
- 做 diff review
- 做安全检查
- 必要时做 eval

所以它对用户项目的保障，本质上是“把正确性验证流程自动化和制度化”，而不是“替代业务测试”。

换句话说，它更像质量系统，而不是万能判题器。

### 七、这套体系的优点和边界

优点很明确：

- 错误暴露得更早，尤其是格式、类型、调试残留这种低级问题
- AI 不容易跳过测试和验证步骤
- 支持回归验证，不只是“这次能跑”
- 对复杂 agent 工作流有 eval 思维，不只盯着代码编译通过
- 这个系统本身也被测试，不是空口宣言

但边界也很明确：

- 它不能自动理解你的业务需求是否“真正满足用户意图”
- 没有业务测试数据时，它无法凭空证明正确性
- 某些 hook 是“提醒/警告型”，不是强阻断
- 很多质量检查依赖目标项目本身配置了 `build`、`lint`、`test`、`tsc`、formatter 等工具链

### 一句话总结

这个项目保证 AI 代码“更正确”的核心，不是靠单次生成更聪明，而是靠“测试优先 + 编辑后即时检查 + 提交前系统验证 + 覆盖率门槛 + eval + 仓库自身被充分测试”的组合拳。

## 自动化测试与验证方法总表

下表汇总了这个项目中主要的自动化测试与验证方法。这里的“测试”不仅包括传统单元测试，也包括构建检查、类型检查、质量门禁、配置校验、回归评估等自动化验证手段，因为 ECC 的目标本来就不是只测代码函数，而是保障整套 AI 工程流程的正确性。

| 什么测试 | 测试的方法 | 为什么要做这个测试 | 能解决什么问题 |
|---|---|---|---|
| 单元测试 | 对单个函数、工具方法、组件逻辑编写独立测试，用最小输入输出断言行为 | 最小粒度验证功能正确性，是发现逻辑错误最快的手段 | 解决函数实现错误、边界条件遗漏、重构后回归问题 |
| 集成测试 | 测 API、数据库、服务交互、模块间协作，验证请求到响应或服务到服务的完整链路 | 很多错误不在单个函数，而在模块之间的拼接处 | 解决接口联调失败、数据库交互错误、服务调用顺序问题 |
| E2E 测试 | 用 Playwright 等浏览器自动化测试关键用户流程 | 最终用户看到的是完整流程，不是单个函数 | 解决页面流程跑不通、按钮可点但业务不成功、前后端联通失败 |
| TDD 红绿重构测试 | 先写失败测试，再写最小实现让其通过，最后重构并保持测试为绿 | 强制 AI 先定义正确行为，再写实现，降低拍脑袋写代码的概率 | 解决“先写代码后补测试”导致的伪验证、需求理解偏差 |
| Build Check | 执行项目构建命令，先确认能完整 build | 如果项目连构建都过不了，其他验证意义很小 | 解决打包失败、缺依赖、构建配置错误、语法级阻断问题 |
| Type Check | 执行 `tsc --noEmit`、`pyright` 等类型检查 | AI 很容易写出语法正确但类型不一致的代码 | 解决类型不匹配、参数传错、返回值不符合约定的问题 |
| Lint Check | 执行 ESLint、Ruff 等静态检查 | 代码不仅要能跑，还要符合项目约定和最佳实践 | 解决潜在坏味道、危险写法、风格不一致、简单逻辑疏漏 |
| 覆盖率检查 | 用 `c8`、Vitest/Jest 覆盖率、pytest-cov 等统计并设置 80% 门槛 | 测试通过不等于测得充分，需要知道哪些代码根本没被触达 | 解决测试盲区、分支未覆盖、表面通过但风险仍高的问题 |
| `/verify` 全量验证 | 按固定顺序执行 build、types、lint、tests、安全检查、diff review | 需要一个统一、可复用的“提交前体检流程” | 解决只做局部检查、漏掉关键验证步骤的问题 |
| `/quality-gate` 质量门禁 | 对文件或项目范围手动执行格式、lint、类型等质量检查 | hook 是自动触发的，但需要人工随时重跑统一质量管线 | 解决改动较多时遗漏局部错误、需要集中复查的问题 |
| `/test-coverage` 覆盖率补强 | 分析低覆盖文件，定位缺失测试并补齐 | 覆盖率不足时，仅看总体数字不够，需要知道缺口在哪 | 解决“知道不够测，但不知道该补哪”的问题 |
| `/eval` 能力/回归评估 | 定义 capability eval 和 regression eval，并记录 pass@k | AI 工程中很多问题不是普通单测能完全表达的 | 解决 prompt/agent 变化后的能力退化、稳定性不足问题 |
| Capability Eval | 为一个新能力定义成功标准并自动检查是否达成 | AI 需要被验证“会不会做这件事”，而不只是“代码能不能跑” | 解决新增能力不可度量、结果模糊、是否达标难判断的问题 |
| Regression Eval | 为已有能力定义基线，更新后重新验证 | 新功能上线最常见的风险是破坏旧功能 | 解决历史行为被破坏、升级后退化、版本回归问题 |
| pass@k / pass^k 评估 | 多次尝试统计成功率和稳定性 | AI 输出存在波动，单次成功不能说明真正可靠 | 解决“偶尔成功但不稳定”的假可靠问题 |
| 编辑后自动格式化 | `post-edit-format` 在文件编辑后自动运行 Biome/Prettier | 很多低级问题不该等到人工发现 | 解决格式漂移、代码风格不统一、格式导致的 review 噪音 |
| 编辑后自动类型检查 | `post-edit-typecheck` 在编辑 TS 文件后自动执行局部类型检查 | 越早看到类型错误，修复成本越低 | 解决刚编辑完就引入的类型错误，避免后续扩散 |
| 编辑后自动质量门禁 | `quality-gate` 按文件类型执行 Biome/Prettier/gofmt/ruff | 需要低延迟的自动化守门，尽快把错误暴露给 AI | 解决语言级格式/质量问题，减少提交前集中爆炸 |
| `console.log` 审计 | Stop hook 自动扫描修改文件中的调试输出 | AI 和人类一样，都会忘删临时调试代码 | 解决调试日志残留、噪音输出、生产代码不干净的问题 |
| 安全扫描 | 搜索 secrets、危险模式，必要时配合安全 skill / reviewer | AI 生成代码时常会忽视 secrets、输入验证等安全问题 | 解决密钥泄漏、明显安全疏漏、调试信息暴露问题 |
| Git diff 审查 | 自动查看变更文件和 diff 范围 | 仅看最终代码不够，需要知道到底改了什么 | 解决误改文件、无关改动混入、遗漏清理的问题 |
| Session Start / End 验证链 | 会话开始加载上下文，会话结束提取摘要、记录变更和工具使用 | AI 的错误很多来自上下文断裂，而不是实现能力本身 | 解决跨会话失忆、重复犯错、接手历史任务时上下文缺失 |
| 持续学习评估 | `evaluate-session` 根据会话长度和内容判断是否可提炼模式 | 好的解决方案应沉淀成可复用能力，而不是每次重学 | 解决经验无法积累、同类问题重复探索的问题 |
| Hook 配置校验 | `validate-hooks.js` 校验 `hooks.json` schema、事件、字段、hook 类型 | hook 是自动化核心，配置一坏，整套机制就失效 | 解决 hook 配置拼写错误、事件名错误、字段不合法的问题 |
| Agent 配置校验 | `validate-agents.js` 校验 agent frontmatter、必填字段、模型合法性 | agent 定义是编排基础，损坏后会直接影响 AI 工作流 | 解决 agent 元数据缺失、配置非法、引用失败的问题 |
| Command 文档校验 | `validate-commands.js` 检查命令文档非空，且引用的 command/agent/skill 存在 | 命令是用户入口，文档失真会导致执行流程错误 | 解决命令引用失效、文档和真实能力脱节的问题 |
| Skill 结构校验 | `validate-skills.js` 校验每个技能目录都存在 `SKILL.md` | skill 是核心知识单元，结构必须稳定 | 解决 skill 缺失、目录不完整、安装后不可用的问题 |
| Rule 文件校验 | `validate-rules.js` 检查规则文件是否可读且非空 | 规则是 AI 行为约束基础，空文件等于失效 | 解决规则丢失、空规则、安装后行为退化的问题 |
| 安装器测试 | 测 `install-plan`、`install-apply`、manifest、install-state 等逻辑 | 安装层错误会让整个系统装不对、装不全、装错位置 | 解决 selective install 失效、路径错误、状态记录异常 |
| CLI 测试 | 测 `ecc`、`doctor`、`repair`、`harness-audit`、`sessions` 等脚本 | CLI 是用户直接操作系统的入口，必须可靠 | 解决命令行参数解析错误、输出不符合预期、功能失效 |
| Hook 脚本测试 | 对 `quality-gate`、`evaluate-session`、`auto-tmux-dev` 等脚本做独立测试 | hook 运行频率高，任何错误都会被快速放大 | 解决 hook 误报、漏报、跨平台行为不一致的问题 |
| 集成级 hook 测试 | 将多个 hook 或相关脚本组合起来验证完整链路 | 单个模块正确，不代表组合后仍然正确 | 解决组合行为异常、事件触发顺序错误、整体链路不通的问题 |
| 状态存储测试 | 测 session aliases、state store、install state 等持久化逻辑 | ECC 很依赖状态记录来支持连续工作 | 解决状态写坏、会话恢复失败、安装状态漂移的问题 |
| 工具解析测试 | 测 formatter 检测、包管理器检测、项目类型识别等基础能力 | 自动化链路依赖环境探测，探测错了后续全错 | 解决检测错误导致执行了错误工具、走错工作流的问题 |
| Harness 审计 | `harness-audit` 检查仓库在工具覆盖、上下文效率、质量门禁等维度是否达标 | 需要从系统层面评估一个 AI harness 是否“配齐了” | 解决功能缺失、能力不完整、质量体系不闭环的问题 |

### 如何理解这张表

这张表里的方法可以分成四组：

- `开发前与开发中`
  TDD、单元测试、集成测试、E2E、编辑后 hooks。
- `提交前与交付前`
  `/verify`、`/quality-gate`、覆盖率、安全扫描、diff review。
- `AI 工程专项`
  `/eval`、Capability Eval、Regression Eval、pass@k、持续学习。
- `ECC 自身质量`
  validators、hook tests、CLI tests、install tests、state/store tests、harness audit。

也就是说，这个项目不是只在“代码写完以后”才测，而是把测试和验证铺在了整个 AI 开发生命周期里。