第 2 课：架构全景 — 六大组件如何协作

王小酱
5 阅读9分钟

所属阶段：第一阶段「认知建立」（第 1-3 课） 前置条件：第 1 课 本课收获：能画出六大组件关系图，能说清每个组件的职责边界

一、本课概述

上节课我们理解了 ECC 的五大设计原则和项目定位。这节课，我们进入 ECC 的"内部结构"，回答三个问题：

  1. 六大组件各是什么？ — 每个组件的本质、职责、数量
  2. 它们如何协作？ — 一个用户请求从输入到完成，经过了哪些组件
  3. 三组关键区分 — 容易混淆的概念如何分清

学完这节课，你应该能在白板上画出组件关系图，并能追踪任意一条命令的完整执行链路。

二、六大组件对比表

ECC 由六类核心组件构成。下表是全景对比：

维度RulesAgentsSkillsCommandsHooksScripts
本质约束条件专家执行者知识单元用户入口事件触发器底层工具
类比交通法规专科医生教科书挂号窗口自动报警器医疗器械
数量10 通用 + 12 语言47 个286 个79 个7 种事件类型28+ 脚本
给谁用Claude 遵守Claude 委派Claude 查阅用户调用系统自动触发Hook/Agent 调用
文件格式MarkdownYAML frontmatter + MDMarkdown（结构化）YAML frontmatter + MDJSON 配置JavaScript (.js)
所在目录rules/agents/skills/commands/.claude/settings.jsonscripts/

2.1 Rules — 约束条件

Rules 是 Claude 必须遵守的编码规范和行为准则。它们不"做"事情，而是"限制"事情怎么做。

rules/
├── common/          # 10 个通用规则（所有语言适用）
│   ├── coding-style.md
│   ├── testing.md
│   ├── security.md
│   └── ...
├── golang/          # 语言特定规则（覆盖通用规则）
├── typescript/
├── python/
└── ...（12 种语言）

关键特征：分层继承。common/ 定义通用默认值，语言目录覆盖不适用的部分。项目级 .claude/rules/ 优先级最高。

2.2 Agents — 专家执行者

Agent 是具有特定专业能力的子代理。每个 Agent 有明确的职责边界、可用工具集和推荐模型。

# 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。

# 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、安装、诊断等提供底层实现。

scripts/
├── hooks/           # Hook 的实际执行脚本
│   └── run-with-flags.js   # Hook 统一调度器
├── lib/             # 共享工具库
├── install-plan.js  # 安装规划
├── install-apply.js # 安装执行
├── doctor.js        # 环境诊断
└── ...

Scripts 是唯一的"纯代码"组件 — 其他五类都是声明式的 Markdown 或 JSON。

三、协作模型

六大组件不是孤立存在的，它们形成一条清晰的协作链路。

3.1 核心协作流程

用户
 │
 │  输入 /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 协作原则

  1. Command 不包含业务逻辑 — 它只是路由，真正的知识在 Skill 中
  2. Agent 遵循 Rules，参考 Skills — Agent 是执行者，但受 Rules 约束、以 Skills 为指导
  3. Hook 透明介入 — 用户不需要手动触发 Hook，它们在恰当的时机自动运行
  4. Scripts 不直接面对用户 — 它们是被 Hook 和其他组件调用的底层工具

3.3 追踪示例：/tdd 命令的完整链路

让我们完整追踪一次 /tdd "实现用户注册" 的执行过程：

步骤组件具体动作
1Command (commands/tdd.md)识别为 TDD 请求，路由到 tdd-workflow skill
2Skill (skills/tdd-workflow/)提供 TDD 流程定义：先写测试、再实现、再重构
3Agent (agents/tdd-guide.md)使用 Read/Write/Edit/Bash/Grep 工具执行 TDD
4Rules (rules/common/testing.md)约束：覆盖率必须 >= 80%，使用 AAA 模式
5Rules (rules/common/coding-style.md)约束：不可变性、函数 < 50 行
6Hook (PostToolUse)每次 Edit/Write 后自动运行格式化
7Script (scripts/hooks/...)实际执行格式化和 lint 命令
8Hook (Stop)会话结束前验证测试全部通过

四、三组关键区分

初学者最容易混淆的三组概念：

4.1 Skill vs Agent — 知识 vs 执行者

维度SkillAgent
本质知识（What & How）执行者（Who）
类比教科书专科医生
能否执行任务不能，只提供参考能，有 tools 列表
有 tools 字段吗没有有（Read, Write, Bash 等）
有 model 字段吗没有有（haiku/sonnet/opus）
数量286 个47 个

一句话区分：Skill 告诉你"怎么做心脏手术"，Agent 是"能做心脏手术的外科医生"。

4.2 Command vs Skill — 入口垫片 vs 持久知识单元

维度CommandSkill
本质用户交互入口持久化知识
触发方式用户输入 /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 实现

维度HookScript
本质声明式配置命令式实现
格式JSON（在 settings.json 中）JavaScript（.js 文件）
定义了什么"什么时候触发"、"匹配什么条件""具体做什么"
可以独立运行吗不能可以

一句话区分：Hook 是"闹钟设置"（几点响、响什么铃声），Script 是"闹钟的电路板"（让铃声实际响起来的机制）。

五、目录结构与文件规范

5.1 项目根目录结构

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）：

# 正确
code-reviewer.md
tdd-guide.md
build-error-resolver.md

# 错误
CodeReviewer.md
tdd_guide.md
BuildErrorResolver.md

5.3 Agent 文件格式

---
name: agent-name           # 简短语义化名称
description: 描述文本       # 精确触发描述（Agent的"简历"）
tools: ["Read", "Grep"]    # 最小权限工具集
model: sonnet               # haiku/sonnet/opus
---

# Agent 正文（Markdown）
角色定义、工作流程、输出格式...

5.4 Skill 文件格式

# Skill Name

## When to Use
描述使用场景...

## How It Works
步骤和规范...

## Examples
代码示例和最佳实践...

5.5 Command 文件格式

---
description: 命令的简短描述
---

# Command Name
委派逻辑或直接说明...

六、深入阅读指引

要全面理解组件协作关系，建议阅读以下文件：

文件内容阅读目的
CLAUDE.md项目架构概述了解整体结构和关键命令
CONTRIBUTING.md贡献指南了解每种组件的格式规范
SOUL.md核心理念回顾设计原则如何映射到组件
AGENTS.mdAgent 目录快速浏览 47 个 Agent
COMMANDS-QUICK-REF.md命令速查快速浏览 79 个命令

七、本课练习

练习 1：追踪 /plan 命令的完整链路（15 分钟）

模仿本课中 /tdd 的追踪方式，追踪 /plan "重构用户模块" 的执行链路：

  1. 打开 commands/plan.md，看它委派给了哪个 Skill
  2. 找到对应的 Skill 文件，看它定义了什么流程
  3. 找到 agents/planner.md，看它的 tools 和 model
  4. 思考：哪些 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。

avatar
文章
阅读
粉丝