第 3 课：上手体验 — 安装与目录漫游

所属阶段：第一阶段「认知建立」（第 1-3 课） 前置条件：第 2 课 本课收获：完成安装，浏览过每个核心目录，对文件格式有感性认识

---

一、本课概述

前两课我们理解了设计理念和架构全景。这节课终于要动手了：

1. 安装 ECC — 三种安装方式，选择最适合你的
2. 认识 Profile — 按需安装，不必全装
3. 目录漫游 — 每个目录打开几个文件，感受真实的格式
4. 运行测试 — 验证环境是否就绪

学完这节课，你应该有一个可用的 ECC 环境，并且对 400+ 个文件的组织方式有直观感受。

---

二、安装前准备

2.1 环境要求

依赖	最低版本	检查命令
Node.js	>= 18	node --version
Claude Code CLI	最新	claude --version
Git	任意	git --version

2.2 获取代码

# 方式一：克隆仓库
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code

# 方式二：如果要贡献代码，先 fork
gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code

---

三、三种安装方式

ECC 提供三种安装方式，适合不同场景：

3.1 Plugin Marketplace（推荐新手）

最简单的安装方式，通过 Claude Code 的插件系统一键安装：

# 在 Claude Code 中执行
/plugin install ecc@ecc

优点：零配置，自动管理依赖 缺点：可能不是最新版

3.2 Shell 脚本安装（推荐开发者）

直接在仓库中运行安装脚本，可以选择安装 Profile：

# 完整安装（所有组件）
./install.sh --profile full

# 只安装核心组件
./install.sh --profile core

# 安装特定语言规则
./install.sh typescript
./install.sh python golang

# 同时安装多种语言
./install.sh typescript python

优点：灵活可控，可选 Profile 缺点：需要手动维护

3.3 npx 安装（一行命令）

通过 npx 运行安装器，适合快速上手：

# 安装并指定语言
npx ecc-install typescript

# 安装完整版
npx ecc-install --profile full

优点：不需要克隆仓库 缺点：依赖 npm registry

3.4 安装方式对比

维度	Plugin	Shell 脚本	npx
难度	最低	中等	低
灵活性	低	最高	中等
需要克隆仓库	否	是	否
Profile 支持	有限	完整	完整
推荐场景	快速体验	日常开发	CI/CD

---

四、安装 Profile

ECC 不需要一次性安装全部组件。Profile 机制让你按需选择：

4.1 五种 Profile

Profile	包含内容	适合谁
core	基础 Rules + 核心 Agents（planner, code-reviewer, tdd-guide）+ 常用 Commands	极简主义者
developer	core + 语言 Reviewers + Build Resolvers + 开发相关 Skills	日常开发
security	core + security-reviewer + 安全 Skills + 安全 Hooks	安全敏感项目
research	core + architect + 分析类 Agents + 研究 Skills	技术调研
full	全部 47 Agents + 286 Skills + 79 Commands + 所有 Hooks	完整体验

4.2 建议

• 学习阶段：使用 full Profile，这样你可以探索所有组件
• 生产项目：从 developer 开始，按需添加
• 安全审计：security Profile 是最小必要集

# 本课程推荐：完整安装以便学习
./install.sh --profile full

---

五、目录漫游

安装完成后，让我们逐个目录浏览，感受文件格式的差异。

5.1 agents/ — 专家代理

# 随机打开几个 Agent 文件
cat agents/planner.md
cat agents/code-reviewer.md
cat agents/security-reviewer.md

观察要点：

• 每个文件都以 YAML frontmatter 开头（--- 包围）
• frontmatter 中有 name、description、tools、model 四个字段
• 正文是 Markdown 格式的角色定义和工作流

对比三个 Agent 的 frontmatter：

Agent	tools	model
planner	Read, Grep, Glob	opus
code-reviewer	Read, Grep, Glob, Bash	sonnet
security-reviewer	Read, Write, Edit, Bash, Grep, Glob	sonnet

注意：planner 只需要读取能力（做规划不需要写文件），而 security-reviewer 需要完整的读写能力（可能需要修复安全问题）。

5.2 skills/ — 领域知识

# 浏览 skills 目录结构
ls skills/
# 随机打开一个 Skill
cat skills/tdd-workflow/SKILL.md

观察要点：

• Skill 通常在子目录中，包含 SKILL.md 主文件
• 结构化段落：When to Use → How It Works → Examples
• 没有 YAML frontmatter 中的 tools 和 model（Skill 不执行，只提供知识）

5.3 commands/ — 用户入口

cat commands/tdd.md
cat commands/plan.md
cat commands/code-review.md

观察要点：

• frontmatter 只有 description 字段（比 Agent 简单得多）
• 很多 Command 标注为 "Legacy shim"，内容只是委派到 Skill
• Command 文件通常很短（10-30 行）

5.4 rules/ — 编码规则

# 通用规则
cat rules/common/coding-style.md
cat rules/common/security.md

# 语言特定规则
cat rules/golang/coding-style.md

观察要点：

• 通用规则是纯 Markdown，没有 frontmatter
• 语言规则以 > This file extends common/xxx.md 开头
• 语言规则可能有 paths: frontmatter 指定适用的文件路径

# rules/golang/coding-style.md 的 frontmatter
---
paths:
  - "**/*.go"
  - "**/go.mod"
---

这个 paths 字段告诉 Claude：只在处理 .go 文件时应用这些规则。

5.5 scripts/ — 底层工具

ls scripts/
ls scripts/hooks/
ls scripts/lib/

观察要点：

• 全部是 .js 文件（CommonJS 格式）
• hooks/ 目录下有 Hook 的实际执行脚本
• lib/ 目录下有共享工具函数
• 这是唯一不用 Markdown 的组件目录

5.6 格式差异总结

目录	frontmatter	正文格式	典型长度
agents/	name, description, tools, model	Markdown（角色+流程）	50-200 行
skills/	name, description（可选）	Markdown（When/How/Examples）	100-400 行
commands/	description	Markdown（极简委派）	10-30 行
rules/	paths（语言规则可选）	Markdown（规范+清单）	30-100 行
scripts/	无	JavaScript	50-200 行

---

六、运行测试验证环境

安装完成后，运行测试套件验证一切正常：

# 运行全部测试
node tests/run-all.js

6.1 测试结构

tests/
├── run-all.js           # 测试入口（运行所有测试）
├── lib/
│   ├── utils.test.js    # 工具函数测试
│   └── package-manager.test.js  # 包管理器检测测试
└── hooks/
    └── hooks.test.js    # Hook 集成测试

6.2 预期输出

正常情况下，所有测试应该通过：

Running tests...
  utils.test.js ............ PASS
  package-manager.test.js .. PASS
  hooks.test.js ............ PASS

All tests passed!

如果有测试失败，检查：

1. Node.js 版本是否 >= 18
2. 依赖是否安装完整（npm install）
3. 文件权限是否正确

---

七、关键参考文件

ECC 提供了几个重要的参考文件，在后续学习中会反复用到：

文件	内容	用途
AGENTS.md	47 个 Agent 的完整列表和简介	快速查找 Agent
COMMANDS-QUICK-REF.md	79 个命令的速查表	快速查找命令
examples/	使用示例	学习最佳实践
docs/SKILL-DEVELOPMENT-GUIDE.md	Skill 开发指南	创建新 Skill
the-shortform-guide.md	入门简明指南	快速上手参考
the-longform-guide.md	进阶详细指南	深入学习参考
the-security-guide.md	安全指南	安全最佳实践

---

八、本课练习

练习 1：完成安装（10 分钟）

选择一种安装方式完成安装。推荐使用 Shell 脚本的 full Profile：

./install.sh --profile full

验证安装成功：

• ~/.claude/agents/ 目录下有 Agent 文件
• ~/.claude/skills/ 目录下有 Skill 文件
• ~/.claude/commands/ 目录下有 Command 文件

练习 2：运行测试（5 分钟）

node tests/run-all.js

确认所有测试通过。如果失败，按照提示排查问题。

练习 3：目录漫游（20 分钟）

按照本课第五节的指引，逐个目录浏览文件。对每个目录：

1. 随机打开 2-3 个文件
2. 注意 frontmatter 的差异
3. 感受正文格式的不同
4. 记录你觉得有趣或困惑的地方

建议记录格式：

文件	我注意到的	我的疑问
agents/planner.md	model 是 opus，不是 sonnet	为什么规划需要最强模型？
commands/tdd.md	只有 10 行，全是委派	为什么不直接去掉 Command？
...	...	...

练习 4（选做）：统计组件数量

运行以下命令，验证你对项目规模的认知：

echo "Agents:" && ls agents/*.md | wc -l
echo "Skills:" && ls skills/ | wc -l
echo "Commands:" && ls commands/*.md | wc -l
echo "Rules (common):" && ls rules/common/*.md | wc -l
echo "Language dirs:" && ls -d rules/*/ | grep -v common | wc -l

---

九、本课小结

你应该记住的	内容
三种安装方式	Plugin marketplace、Shell 脚本、npx
五种 Profile	core / developer / security / research / full
Agent frontmatter	name, description, tools, model
Skill 结构	When to Use / How It Works / Examples
Command 特点	极简，通常是到 Skill 的 shim
语言规则特点	paths: frontmatter + extends 引用
测试命令	node tests/run-all.js

---

十、下节预告

第 4 课：Rules（上）— 通用规则体系

下节课我们将深入 rules/common/ 目录，逐个讲解 10 个通用规则文件。你将理解分层继承模型，掌握不可变性、TDD、安全检查等核心规范的具体内容。

预习建议：提前阅读 rules/common/coding-style.md 和 rules/common/testing.md，尝试总结其中的关键要求。