所属阶段：第一阶段「认知建立」（第 1-3 课） 前置条件：无 本课收获：能用自己的话解释五大原则，理解 ECC 在 AI 编程工具生态中的定位
一、本课概述
这是整个课程的第一课。我们不急着安装、不急着写代码，先回答三个最基本的问题：
- ECC 是什么？ — 它在 AI 编程助手生态中扮演什么角色
- ECC 为什么这样设计？ — 五大核心原则的内涵和逻辑
- ECC 的规模有多大？ — 建立对项目体量的感性认识
理解了"为什么"，后面学"怎么做"才不会迷路。
二、ECC 是什么
2.1 一句话定义
Everything Claude Code (ECC) is a production-ready AI coding plugin with specialized agents, skills, commands, and automated hook workflows for software development. — SOUL.md
翻译过来：ECC 是一个面向 AI 编程助手的生产级增强插件，包含专用代理、技能、命令和自动化钩子工作流。
2.2 AI Harness 的概念
要理解 ECC，先理解一个关键词：Harness（工具套件/增强框架）。
┌─────────────────────────────────────────────────┐
│ AI 编程助手 │
│ （Claude Code / Codex / Cursor / Gemini 等） │
│ │
│ 原生能力：读文件、写代码、运行命令、搜索代码 │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ ECC（Harness / 增强框架） │ │
│ │ │ │
│ │ + 47 个专家代理（自动委派任务） │ │
│ │ + 286 个领域技能（沉淀最佳实践） │ │
│ │ + 79 个命令入口（一键触发工作流） │ │
│ │ + 7 种事件钩子（自动化质量保障） │ │
│ │ + 12 种语言规则（编码规范约束） │ │
│ │ │ │
│ └───────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
类比：
- Claude Code 是一台发动机 — 能力强大，但需要调校
- ECC 是一套赛车套件 — 帮你把发动机的性能充分发挥出来
没有 ECC，Claude Code 也能写代码。有了 ECC，Claude Code 会按照最佳实践写代码、自动做安全检查、在适当时机委派给专家代理、持续从会话中学习和改进。
2.3 跨平台支持
ECC 不只服务于 Claude Code，它支持 6 种 AI 编程助手：
| AI 编程助手 | 支持程度 | 说明 |
|---|---|---|
| Claude Code | 完整支持 | 主要目标平台 |
| Codex | 完整支持 | macOS 应用和 CLI |
| Cursor | 适配支持 | 通过 Hook adapter 模式 |
| OpenCode | 插件支持 | Plugin system |
| Gemini | 有限支持 | 通过 GEMINI.md |
| Antigravity | IDE 集成 | — |
这意味着你在 ECC 中学到的知识（Skill、Rule、Agent 的设计思想）是可迁移的 — 不绑定于任何一个具体的 AI 工具。
2.4 项目背景
- 起源：Anthropic x Forum Ventures 黑客马拉松获奖项目
- 演进：经过 10 个月以上的日常高强度使用打磨
- 社区：140K+ GitHub stars、21K+ forks、170+ 贡献者
- 当前版本：v1.10.0（2026 年 4 月）
- 开源协议：MIT
三、五大核心原则
ECC 的一切设计决策都源于 SOUL.md 中定义的五大核心原则。这不是一个随意的列表 — 它们之间有内在的逻辑链。
3.1 原则一：Plan Before Execute（先规划再执行）
Complex changes should be broken into deliberate phases. 复杂变更应该拆解为审慎的阶段。
含义：在动手写代码之前，先想清楚要做什么、分几步做、每步有什么风险。
为什么排在第一位？ 因为这是一切的起点。没有规划，后面的测试、安全、不可变性都是空谈 — 你不知道在测什么、在保护什么。
在 ECC 中的体现：
- 有专门的
plannerAgent 做实施规划 - 有
architectAgent 做系统设计 /plan命令是推荐的第一步操作rules/common/development-workflow.md明确要求"Plan First"
反面教训： 直接开始写代码 → 写到一半发现方向错了 → 推倒重来 → 浪费了大量上下文窗口和 Token
3.2 原则二：Agent-First（代理优先）
Route work to the right specialist as early as possible. 尽早将工作路由给合适的专家。
含义：遇到特定类型的任务（代码审查、安全分析、TDD），不要自己硬做，尽早委派给专业的 Agent。
为什么排在第二位？ 有了规划之后，下一步就是决定"谁来做"。一个通用的 AI 做所有事情，不如让专家代理各司其职。
在 ECC 中的体现：
- 47 个专用 Agent，每个有明确的职责边界
- Agent 按需自动触发（基于
description字段匹配） - 不同 Agent 使用不同模型（Haiku 轻量、Sonnet 主力、Opus 深度）
类比： 医院不是一个全科医生看所有病人。挂号分诊（Plan）→ 转到专科（Agent-First）→ 专科诊断和治疗。
3.3 原则三：Test-Driven（测试驱动）
Write or refresh tests before trusting implementation changes. 在信任实现变更之前，先编写或刷新测试。
含义：代码改完了不等于改对了。唯一的证据是测试通过。
为什么排在第三位？ Agent 完成了工作后，需要验证工作质量。测试是验证的核心手段。
在 ECC 中的体现：
- TDD 严格循环：RED（写测试）→ GREEN（最小实现）→ IMPROVE（重构）
- 80% 最低覆盖率要求
tdd-guideAgent 专门引导 TDD 流程- 验证循环：测试 → Lint → 类型检查 → 安全检查 → 才能提交
TDD 的核心洞察： 先写测试不仅是为了"验证代码"，更是为了明确需求 — 当你写不出测试的时候，说明你还没想清楚要做什么（回到原则一）。
3.4 原则四：Security-First（安全优先）
Validate inputs, protect secrets, and keep safe defaults. 验证输入、保护密钥、保持安全默认。
含义：安全不是事后补的，是设计时就要考虑的。
为什么排在第四位？ 测试验证了功能正确性，但还有一类问题测试未必能覆盖 — 安全漏洞。安全检查是验证环节的重要补充。
在 ECC 中的体现：
security-reviewerAgent 专门做安全审查rules/common/security.md定义了 8 项提交前安全检查清单- AgentShield 工具扫描
.claude/目录的安全漏洞 - AI 代理特有的安全威胁被专门关注（Prompt 注入、MCP 投毒等）
AI 时代的新安全挑战： 传统应用担心 SQL 注入和 XSS。AI 代理额外要担心 Prompt 注入、通过截图/附件/PR 描述植入的恶意指令。ECC 对此有专门的安全指南。
3.5 原则五：Immutability（不可变性）
Prefer explicit state transitions over mutation. 偏好显式状态转换，而非就地修改。
含义：不要直接修改现有数据，而是创建新的数据副本。状态变化要显式、可追踪。
为什么排在最后？ 这是最底层的编程原则。前面四个原则（规划、委派、测试、安全）都依赖一个基础：状态是可控的、可追踪的。如果对象被随意修改，测试结果不可靠，安全审计无法追溯，并行 Agent 会互相踩踏。
在 ECC 中的体现：
rules/common/coding-style.md将不可变性标记为 CRITICAL- 推荐创建新对象而非修改现有对象
- Git 工作流强调每次变更有明确的 commit 记录
在 ECC Rules 中的优先级：
// 伪代码
WRONG: modify(original, field, value) → 就地修改 original
CORRECT: update(original, field, value) → 返回新的副本
3.6 五大原则的内在逻辑链
五个原则不是并列的，它们有一条逻辑链：
Plan Before Execute
│ 想清楚了
▼
Agent-First
│ 分给专家做
▼
Test-Driven
│ 做完要验证
▼
Security-First
│ 验证要包括安全
▼
Immutability
│ 安全的基础是状态可控
▼
（回到开头：可控的状态让下一轮 Plan 更准确）
这是一个闭环。不可变的状态让规划更准确，准确的规划让代理更高效，高效的代理产出需要测试验证，验证需要包括安全维度，安全依赖状态可控。
四、项目规模感知
在深入学习之前，先对 ECC 的体量建立感性认识：
4.1 组件数量
| 组件类型 | 数量 | 作用 |
|---|---|---|
| Agents（代理） | 47 个 | 专业任务执行者 |
| Skills（技能） | 286 个 | 领域知识和工作流 |
| Commands（命令） | 79 个 | 用户交互入口 |
| Hook 事件类型 | 7 种 | 事件驱动自动化 |
| 语言规则集 | 12 种语言 | 编码规范约束 |
| 文档语言 | 7 种 | 国际化支持 |
4.2 技术覆盖
支持的编程语言（规则层面）： TypeScript、Python、Go、Java、Kotlin、Rust、C++、C#、Swift、PHP、Perl、Dart
支持的框架（Skill 层面）： Django、Spring Boot、Laravel、NestJS、React/Next.js、Vue/Nuxt、Flutter、SwiftUI、Ktor 等
4.3 三份官方指南
ECC 提供了三份从入门到进阶的官方指南：
| 指南 | 文件 | 定位 |
|---|---|---|
| Shorthand Guide | the-shortform-guide.md | 安装、基础、理念。入门首选 |
| Longform Guide | the-longform-guide.md | Token 优化、记忆持久化、Eval、并行化 |
| Security Guide | the-security-guide.md | 攻击面、沙箱、消毒、CVE、AgentShield |
本课程的内容基于对这三份指南和仓库所有组件的系统梳理。
五、Agent 编排哲学
SOUL.md 还有一段关于 Agent 编排的重要描述：
ECC is designed so specialists are invoked proactively: planners for implementation strategy, reviewers for code quality, security reviewers for sensitive code, and build resolvers when the toolchain breaks.
翻译：ECC 的设计是主动调用专家 — 不等用户要求，系统自动判断何时需要什么专家：
| 场景 | 自动调用的 Agent |
|---|---|
| 要开始一个新功能 | planner（规划实施策略） |
| 代码写完了 | code-reviewer（代码质量审查） |
| 涉及敏感代码 | security-reviewer（安全审查） |
| 编译/构建失败 | build-error-resolver（修复构建错误） |
| 要写测试 | tdd-guide（引导 TDD 流程） |
| 做架构决策 | architect（系统设计） |
这就是 Agent-First 原则的落地：不是用户手动挑选 Agent，而是系统基于场景自动匹配最合适的专家。
六、本课练习
练习 1：阅读 SOUL.md（5 分钟）
打开 SOUL.md 文件，完整阅读。虽然只有 17 行，但每一行都是设计决策的浓缩。
# 在项目根目录
cat SOUL.md
回答问题：
- Core Identity 部分提到了哪几类组件？
- Agent Orchestration Philosophy 部分的关键词是什么？（提示：proactively）
- Cross-Harness Vision 部分在说什么？
练习 2：浏览 README.md 的 Quick Start（10 分钟）
打开 README.md，只读 Quick Start 部分（不需要执行安装，下节课再做）。
回答问题：
- 安装分几步？
- 为什么 Rules 需要手动安装而不能通过插件自动安装？
- 三份指南分别学什么？
练习 3：用自己的话写出五大原则（15 分钟）
这是本课最重要的练习。
用一段连贯的文字（不是列表），用你自己的话解释五大原则及其内在逻辑。要求：
- 不超过 200 字
- 用你自己的话，不要照抄原文
- 要体现原则之间的逻辑关系（不是简单罗列）
参考格式（不是标准答案，你应该写出不同的版本）：
面对一个复杂任务，ECC 的做法是先规划拆解（Plan Before Execute），然后把每个子任务交给最合适的专家代理去做（Agent-First）。专家做完后，不能直接信任结果，必须通过测试验证（Test-Driven）。验证不仅看功能对不对，还要看安全不安全（Security-First）。而这一切能够可靠运作的基础，是代码的状态是可控的、不会被随意修改的（Immutability）。
练习 4（选做）：思考题
如果你只能保留两个原则（其他三个不再强制），你会保留哪两个？为什么？
提示：没有标准答案。这道题的目的是让你思考哪些原则是其他原则的"前提条件"。
七、本课小结
| 你应该记住的 | 内容 |
|---|---|
| ECC 的定位 | AI 编程助手的增强框架（Harness），不是替代品 |
| 五大原则 | Plan Before Execute → Agent-First → Test-Driven → Security-First → Immutability |
| 原则逻辑 | 它们是一个闭环，不是并列关系 |
| Agent 编排 | 专家被主动调用（proactively），不需要用户手动触发 |
| 跨平台 | 支持 6 种 AI 编程助手，知识可迁移 |
八、下节预告
第 2 课：架构全景 — 六大组件如何协作
下节课我们将深入 ECC 的六大核心组件（Rules、Agents、Skills、Commands、Hooks、Scripts），理解它们各自的职责和协作关系。你将学会画出组件关系图，并能追踪一个命令从用户输入到最终执行的完整链路。
预习建议：提前浏览 CLAUDE.md 和 CONTRIBUTING.md，感受一下不同组件的格式差异。
