所属阶段：第一阶段「认知建立」（第 1-3 课） 前置条件：第 1 课 本课收获：能画出六大组件关系图，能说清每个组件的职责边界
一、本课概述
上节课我们理解了 ECC 的五大设计原则和项目定位。这节课，我们进入 ECC 的"内部结构"，回答三个问题：
- 六大组件各是什么？ --- 每个组件的本质、职责、数量
- 它们如何协作？ --- 一个用户请求从输入到完成，经过了哪些组件
- 三组关键区分 --- 容易混淆的概念如何分清
学完这节课，你应该能在白板上画出组件关系图，并能追踪任意一条命令的完整执行链路。
二、六大组件对比表
ECC 由六类核心组件构成。下表是全景对比：
| 维度 | Rules | Agents | Skills | Commands | Hooks | Scripts |
|---|---|---|---|---|---|---|
| 本质 | 约束条件 | 专家执行者 | 知识单元 | 用户入口 | 事件触发器 | 底层工具 |
| 类比 | 交通法规 | 专科医生 | 教科书 | 挂号窗口 | 自动报警器 | 医疗器械 |
| 数量 | 10 通用 + 12 语言 | 47 个 | 286 个 | 79 个 | 7 种事件类型 | 28+ 脚本 |
| 给谁用 | Claude 遵守 | Claude 委派 | Claude 查阅 | 用户调用 | 系统自动触发 | Hook/Agent 调用 |
| 文件格式 | Markdown | YAML frontmatter + MD | Markdown（结构化） | YAML frontmatter + MD | JSON 配置 | JavaScript (.js) |
| 所在目录 | rules/ |
agents/ |
skills/ |
commands/ |
.claude/settings.json |
scripts/ |
2.1 Rules --- 约束条件
Rules 是 Claude 必须遵守的编码规范和行为准则。它们不"做"事情，而是"限制"事情怎么做。
bash
rules/
├── common/ # 10 个通用规则（所有语言适用）
│ ├── coding-style.md
│ ├── testing.md
│ ├── security.md
│ └── ...
├── golang/ # 语言特定规则（覆盖通用规则）
├── typescript/
├── python/
└── ...（12 种语言）关键特征 ：分层继承。common/ 定义通用默认值，语言目录覆盖不适用的部分。项目级 .claude/rules/ 优先级最高。
2.2 Agents --- 专家执行者
Agent 是具有特定专业能力的子代理。每个 Agent 有明确的职责边界、可用工具集和推荐模型。
yaml
# agents/code-reviewer.md 的 frontmatter
---
name: code-reviewer
description: Expert code review specialist...
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---47 个 Agent 覆盖了从规划（planner）、审查（code-reviewer）、安全（security-reviewer）到构建修复（build-error-resolver）的完整开发生命周期。
2.3 Skills --- 知识单元
Skill 是沉淀下来的领域知识和工作流定义。它不执行任务，而是提供"怎么做"的参考。
一个典型的 Skill 有三个标准段落：
- When to Use --- 什么场景下查阅这个 Skill
- How It Works --- 具体的步骤和规范
- Examples --- 代码示例和最佳实践
286 个 Skill 覆盖了从语言最佳实践到框架模式到测试策略的方方面面。
2.4 Commands --- 用户入口
Command 是用户通过 /xxx 形式调用的快捷入口。它本身通常很轻量，职责是将用户意图路由到对应的 Skill 或 Agent。
yaml
# commands/tdd.md
---
description: Legacy slash-entry shim for the tdd-workflow skill.
---
# 实际工作委派给 tdd-workflow skill很多 Command 是 shim（垫片）--- 它只是一个入口，真正的逻辑在 Skill 中。
2.5 Hooks --- 事件触发器
Hook 是在特定事件发生时自动触发的处理器。ECC 支持 7 种 Hook 事件：
| Hook 类型 | 触发时机 | 典型用途 |
|---|---|---|
| PreToolUse | 工具执行前 | 参数校验、权限检查 |
| PostToolUse | 工具执行后 | 自动格式化、lint 检查 |
| Stop | 会话结束时 | 最终验证、总结 |
| Notification | 异步通知 | 长任务完成提醒 |
| SessionStart | 会话开始时 | 环境初始化 |
| SessionEnd | 会话结束时 | 状态持久化 |
| SubagentStop | 子代理结束时 | 子代理结果处理 |
Hook 在 .claude/settings.json 中以 JSON 声明配置，实际执行逻辑由 Scripts 提供。
2.6 Scripts --- 底层工具
Scripts 是 Node.js 编写的实用工具脚本，为 Hook、安装、诊断等提供底层实现。
csharp
scripts/
├── hooks/ # Hook 的实际执行脚本
│ └── run-with-flags.js # Hook 统一调度器
├── lib/ # 共享工具库
├── install-plan.js # 安装规划
├── install-apply.js # 安装执行
├── doctor.js # 环境诊断
└── ...Scripts 是唯一的"纯代码"组件 --- 其他五类都是声明式的 Markdown 或 JSON。
三、协作模型
六大组件不是孤立存在的，它们形成一条清晰的协作链路。
3.1 核心协作流程
yaml
用户
│
│ 输入 /tdd "实现用户登录"
▼
Command（入口路由）
│
│ /tdd 命令识别意图，委派给 tdd-workflow skill
▼
Skill（知识提供）
│
│ tdd-workflow 提供 TDD 六步法：RED→GREEN→IMPROVE
▼
Agent（专家执行）
│
│ tdd-guide agent 按照 skill 中的知识执行：
│ 写测试→运行→实现→运行→重构
│ （全程遵循 Rules 的约束）
▼
Rules（约束检查）
│
│ coding-style: 不可变性、命名规范
│ testing: 80% 覆盖率
│ security: 无硬编码密钥
▼
Hooks（自动介入）
│
│ PostToolUse: 每次写文件后自动格式化
│ Stop: 会话结束前验证覆盖率
▼
Scripts（底层执行）
run-with-flags.js 调度 Hook 脚本
格式化、lint、覆盖率工具实际运行3.2 协作原则
- Command 不包含业务逻辑 --- 它只是路由，真正的知识在 Skill 中
- Agent 遵循 Rules，参考 Skills --- Agent 是执行者，但受 Rules 约束、以 Skills 为指导
- Hook 透明介入 --- 用户不需要手动触发 Hook，它们在恰当的时机自动运行
- Scripts 不直接面对用户 --- 它们是被 Hook 和其他组件调用的底层工具
3.3 追踪示例：/tdd 命令的完整链路
让我们完整追踪一次 /tdd "实现用户注册" 的执行过程：
| 步骤 | 组件 | 具体动作 |
|---|---|---|
| 1 | Command (commands/tdd.md) |
识别为 TDD 请求，路由到 tdd-workflow skill |
| 2 | Skill (skills/tdd-workflow/) |
提供 TDD 流程定义：先写测试、再实现、再重构 |
| 3 | Agent (agents/tdd-guide.md) |
使用 Read/Write/Edit/Bash/Grep 工具执行 TDD |
| 4 | Rules (rules/common/testing.md) |
约束：覆盖率必须 >= 80%，使用 AAA 模式 |
| 5 | Rules (rules/common/coding-style.md) |
约束：不可变性、函数 < 50 行 |
| 6 | Hook (PostToolUse) | 每次 Edit/Write 后自动运行格式化 |
| 7 | Script (scripts/hooks/...) |
实际执行格式化和 lint 命令 |
| 8 | Hook (Stop) | 会话结束前验证测试全部通过 |
四、三组关键区分
初学者最容易混淆的三组概念：
4.1 Skill vs Agent --- 知识 vs 执行者
| 维度 | Skill | Agent |
|---|---|---|
| 本质 | 知识（What & How） | 执行者（Who） |
| 类比 | 教科书 | 专科医生 |
| 能否执行任务 | 不能，只提供参考 | 能，有 tools 列表 |
| 有 tools 字段吗 | 没有 | 有（Read, Write, Bash 等） |
| 有 model 字段吗 | 没有 | 有（haiku/sonnet/opus） |
| 数量 | 286 个 | 47 个 |
一句话区分：Skill 告诉你"怎么做心脏手术"，Agent 是"能做心脏手术的外科医生"。
4.2 Command vs Skill --- 入口垫片 vs 持久知识单元
| 维度 | Command | Skill |
|---|---|---|
| 本质 | 用户交互入口 | 持久化知识 |
| 触发方式 | 用户输入 /xxx |
被 Command 或 Agent 引用 |
| 内容复杂度 | 通常很短（shim） | 通常很详细 |
| 是否可独立使用 | 是（用户直接调用） | 是（Agent 可直接引用） |
一句话区分：Command 是"挂号窗口"，Skill 是"诊疗手册"。很多 Command 的全部工作就是说"请翻到诊疗手册第 X 页"。
实例：commands/tdd.md 只有几行，核心内容是 Apply the tdd-workflow skill。真正的 TDD 流程定义在 skills/tdd-workflow/ 中。
4.3 Hook vs Script --- 声明 vs 实现
| 维度 | Hook | Script |
|---|---|---|
| 本质 | 声明式配置 | 命令式实现 |
| 格式 | JSON（在 settings.json 中） | JavaScript（.js 文件） |
| 定义了什么 | "什么时候触发"、"匹配什么条件" | "具体做什么" |
| 可以独立运行吗 | 不能 | 可以 |
一句话区分：Hook 是"闹钟设置"（几点响、响什么铃声），Script 是"闹钟的电路板"（让铃声实际响起来的机制）。
五、目录结构与文件规范
5.1 项目根目录结构
bash
everything-claude-code/
├── agents/ # 47 个 Agent（Markdown + YAML frontmatter）
├── skills/ # 286 个 Skill（结构化 Markdown）
├── commands/ # 79 个 Command（Markdown + YAML frontmatter）
├── rules/ # 分层规则体系
│ ├── common/ # 10 个通用规则
│ ├── golang/ # 5 个 Go 规则
│ ├── typescript/ # 语言规则...
│ └── ...
├── scripts/ # Node.js 工具脚本
│ ├── hooks/ # Hook 执行脚本
│ └── lib/ # 共享库
├── hooks/ # Hook 声明配置
├── tests/ # 测试套件
├── CLAUDE.md # 项目指令文件
├── SOUL.md # 核心理念
└── CONTRIBUTING.md # 贡献指南5.2 文件命名规范
所有文件一律使用 小写字母 + 连字符（kebab-case）：
bash
# 正确
code-reviewer.md
tdd-guide.md
build-error-resolver.md
# 错误
CodeReviewer.md
tdd_guide.md
BuildErrorResolver.md5.3 Agent 文件格式
yaml
---
name: agent-name # 简短语义化名称
description: 描述文本 # 精确触发描述（Agent的"简历"）
tools: ["Read", "Grep"] # 最小权限工具集
model: sonnet # haiku/sonnet/opus
---
# Agent 正文（Markdown）
角色定义、工作流程、输出格式...5.4 Skill 文件格式
markdown
# Skill Name
## When to Use
描述使用场景...
## How It Works
步骤和规范...
## Examples
代码示例和最佳实践...5.5 Command 文件格式
yaml
---
description: 命令的简短描述
---
# Command Name
委派逻辑或直接说明...六、深入阅读指引
要全面理解组件协作关系，建议阅读以下文件：
| 文件 | 内容 | 阅读目的 |
|---|---|---|
CLAUDE.md |
项目架构概述 | 了解整体结构和关键命令 |
CONTRIBUTING.md |
贡献指南 | 了解每种组件的格式规范 |
SOUL.md |
核心理念 | 回顾设计原则如何映射到组件 |
AGENTS.md |
Agent 目录 | 快速浏览 47 个 Agent |
COMMANDS-QUICK-REF.md |
命令速查 | 快速浏览 79 个命令 |
七、本课练习
练习 1：追踪 /plan 命令的完整链路（15 分钟）
模仿本课中 /tdd 的追踪方式，追踪 /plan "重构用户模块" 的执行链路：
- 打开
commands/plan.md，看它委派给了哪个 Skill - 找到对应的 Skill 文件，看它定义了什么流程
- 找到
agents/planner.md，看它的 tools 和 model - 思考：哪些 Rules 会在这个过程中起约束作用？
练习 2：手绘组件关系图（10 分钟）
在纸上或白板上画出六大组件的关系图，要求：
- 标出每个组件的名称和数量
- 用箭头表示调用/引用关系
- 标注 Hook 在哪些环节自动介入
- 标注用户的交互入口在哪里
练习 3：对比三组概念（10 分钟）
打开以下文件，实际感受三组概念的差异：
- 对比
commands/tdd.md（Command）和skills/tdd-workflow/（Skill）--- 注意内容量的差异 - 对比
agents/tdd-guide.md（Agent）和同一个 Skill --- 注意 Agent 有 tools/model 而 Skill 没有 - 打开
.claude/settings.json看 Hook 声明，再打开scripts/hooks/看实际脚本
练习 4（选做）：思考题
如果让你新增一个"数据库迁移"的工作流，你会：
- 创建哪些组件？（Command？Skill？Agent？）
- 它们之间如何协作？
- 需要什么 Hook 来保障质量？
八、本课小结
| 你应该记住的 | 内容 |
|---|---|
| 六大组件 | Rules（约束）、Agents（执行）、Skills（知识）、Commands（入口）、Hooks（触发）、Scripts（底层） |
| 协作链路 | 用户 → Command → Skill → Agent →（遵循 Rules），Hooks 自动介入，Scripts 提供底层 |
| Skill vs Agent | 知识 vs 执行者 |
| Command vs Skill | 入口垫片 vs 持久知识 |
| Hook vs Script | 声明 vs 实现 |
| 文件命名 | 一律小写加连字符（kebab-case） |
九、下节预告
第 3 课：上手体验 --- 安装与目录漫游
下节课我们将动手安装 ECC，浏览每个核心目录，打开文件感受格式差异。你将运行测试来验证环境，并对 ECC 的 400+ 个文件建立感性认识。
预习建议：确保你的机器上已安装 Node.js >= 18 和 Claude Code CLI。