所属阶段：第二阶段「组件精讲」（第 4-15 课） 前置条件：第 3 课 本课收获：掌握 10 个通用规则文件的内容，理解分层继承模型
一、本课概述
Rules 是 ECC 六大组件中最"安静"的一个 --- 它不执行任何操作，但所有操作都受它约束。本课我们将：
- 理解分层继承模型 --- Rules 如何从通用到语言到项目逐层覆盖
- 逐个讲解 10 个通用规则 --- 每个文件的核心要求和关键清单
- 建立规则全景视图 --- 用表格总结所有规则的要点
Rules 是 ECC 的"宪法"。理解了 Rules，才能理解 Agent 为什么这样做、Skill 为什么这样写。
二、分层继承模型
2.1 三层结构
ECC 的 Rules 采用三层继承架构：
bash
优先级（从低到高）：
第一层：rules/common/ ← 通用默认值（适用所有语言）
│
│ 语言规则继承并覆盖
▼
第二层：rules/<language>/ ← 语言特定规则（如 golang/、typescript/）
│
│ 项目规则继承并覆盖
▼
第三层：.claude/rules/ ← 项目级规则（最高优先级）2.2 覆盖规则
当层级之间产生冲突时，更具体的层级优先（类似 CSS 的 specificity）：
| 冲突场景 | 生效的规则 | 原因 |
|---|---|---|
| common 说"不可变"，golang 说"指针接收器可变" | golang 的 | 语言 > 通用 |
| common 说"80% 覆盖率"，项目说"90% 覆盖率" | 项目的 | 项目 > 语言 > 通用 |
| common 说"函数 < 50 行"，语言未提及 | common 的 | 无覆盖则继承 |
2.3 安装注意事项
安装语言规则时，不能用 /* 扁平化复制：
bash
# 错误！同名文件会互相覆盖
cp rules/common/* ~/.claude/rules/
cp rules/golang/* ~/.claude/rules/ # coding-style.md 会覆盖 common 的！
# 正确！保持目录结构
cp -r rules/common ~/.claude/rules/common
cp -r rules/golang ~/.claude/rules/golang这是因为 common/ 和语言目录下有同名文件（如 coding-style.md），扁平化复制会导致语言文件覆盖通用文件，而不是形成继承关系。
三、十大通用规则逐个讲解
rules/common/ 目录下有 10 个规则文件。以下逐个解析。
3.1 coding-style.md --- 编码风格
这是最核心的规则文件，定义了代码质量的底线要求。
核心要求：
| 要求 | 级别 | 内容 |
|---|---|---|
| 不可变性 | CRITICAL | 创建新对象，永远不修改现有对象 |
| 文件大小 | 强烈建议 | 200-400 行典型，800 行为上限 |
| 函数大小 | 强烈建议 | 不超过 50 行 |
| 嵌套深度 | 建议 | 不超过 4 层 |
| 错误处理 | 必须 | 每一层都显式处理错误，不能静默吞掉 |
| 输入验证 | 必须 | 在系统边界验证所有外部输入 |
不可变性示例（伪代码）：
scss
// 错误：就地修改
modify(original, field, value) → 改变了 original 本身
// 正确：返回新副本
update(original, field, value) → 返回新对象，original 不变代码质量清单（每次提交前检查）：
- 代码可读性好，命名清晰
- 函数小于 50 行
- 文件小于 800 行
- 嵌套不超过 4 层
- 错误处理完善
- 无硬编码值（用常量或配置）
- 使用不可变模式
设计哲学 ：MANY SMALL FILES > FEW LARGE FILES。高内聚、低耦合。按功能/领域组织文件，而不是按类型。
3.2 testing.md --- 测试要求
核心要求：最低 80% 测试覆盖率。
三种必需的测试类型：
| 类型 | 测试目标 | 必需程度 |
|---|---|---|
| 单元测试 | 独立函数、工具、组件 | 必需 |
| 集成测试 | API 端点、数据库操作 | 必需 |
| E2E 测试 | 关键用户流程 | 必需 |
TDD 强制流程（六步法）：
markdown
1. Write --- 先写测试
2. Fail --- 运行测试，确认失败（RED）
3. Implement --- 写最小实现
4. Pass --- 运行测试，确认通过（GREEN）
5. Refactor --- 重构改善（IMPROVE）
6. Verify --- 验证覆盖率 >= 80%测试命名规范：使用 AAA 模式（Arrange-Act-Assert）：
javascript
// 命名格式：should_<预期行为>_when_<条件>
test("should return error when input is empty", () => {
// Arrange: 准备测试数据
// Act: 执行被测函数
// Assert: 验证结果
});测试失败排查：
- 使用
tdd-guideAgent - 检查测试隔离性
- 验证 Mock 是否正确
- 修复实现，不要修复测试（除非测试本身有错）
3.3 security.md --- 安全准则
8 项提交前安全检查清单：
- 无硬编码密钥（API key、密码、Token）
- 所有用户输入已验证
- SQL 注入防护（参数化查询）
- XSS 防护（HTML 已消毒）
- CSRF 保护已启用
- 身份验证/授权已验证
- 所有端点有速率限制
- 错误消息不泄露敏感数据
密钥管理三原则：
- 永远不在源码中硬编码密钥
- 总是使用环境变量或密钥管理器
- 在应用启动时验证必需密钥存在
安全响应协议（发现安全问题时）：
markdown
1. STOP --- 立即停止当前工作
2. security-reviewer --- 调用安全审查 Agent
3. 修复 CRITICAL 问题
4. 轮换任何可能已暴露的密钥
5. 全库排查类似问题3.4 git-workflow.md --- Git 工作流
Conventional Commits 格式：
xml
<type>: <description>
<optional body>类型列表：
| 类型 | 用途 | 示例 |
|---|---|---|
| feat | 新功能 | feat: add user registration |
| fix | 修复 | fix: handle null input in parser |
| refactor | 重构 | refactor: extract auth middleware |
| docs | 文档 | docs: update API reference |
| test | 测试 | test: add integration tests for auth |
| chore | 杂务 | chore: update dependencies |
| perf | 性能 | perf: cache database queries |
| ci | CI/CD | ci: add coverage reporting |
PR 流程：
- 分析完整提交历史（不只是最新 commit）
- 使用
git diff [base-branch]...HEAD查看所有变更 - 撰写全面的 PR 摘要
- 包含测试计划和 TODO
- 新分支用
-u标志推送
3.5 performance.md --- 性能优化
模型选择策略：
| 模型 | 能力定位 | 成本 | 适用场景 |
|---|---|---|---|
| Haiku 4.5 | Sonnet 的 90% 能力 | Sonnet 的 1/3 | 轻量 Agent、高频调用、Worker Agent |
| Sonnet 4.6 | 最佳编码模型 | 中等 | 主力开发、复杂编码、流程编排 |
| Opus 4.5 | 最深推理 | 最高 | 架构决策、复杂推理、深度分析 |
上下文窗口管理：
避免在上下文的最后 20% 执行以下任务：
- 大规模重构
- 跨多文件的功能实现
- 复杂交互的调试
低上下文敏感度的任务（可以在后期执行）：
- 单文件编辑
- 独立工具创建
- 文档更新
- 简单 Bug 修复
Extended Thinking：
- 默认启用，保留最多 31,999 Token 用于内部推理
- 快捷键：Option+T（macOS）/ Alt+T（Windows/Linux）
- 复杂任务建议开启 Plan Mode 配合使用
3.6 patterns.md --- 设计模式
Skeleton Projects 模式：
实现新功能时的推荐流程：
- 搜索经过实战验证的 Skeleton 项目
- 用并行 Agent 评估选项（安全、可扩展性、相关性、实现规划）
- 克隆最佳匹配作为基础
- 在已验证的结构中迭代开发
Repository Pattern：
sql
定义标准操作接口：findAll, findById, create, update, delete
│
▼
具体实现处理存储细节（数据库、API、文件等）
│
▼
业务逻辑依赖抽象接口，不依赖存储机制好处：轻松切换数据源，简化测试（可用 Mock 替换）。
API 响应格式：
统一的响应信封格式：
- 成功/状态指示符
- 数据载荷（错误时为 null）
- 错误消息字段（成功时为 null）
- 分页响应的元数据（total, page, limit）
3.7 agents.md --- Agent 编排
Agent 即时调用规则（无需用户提示）：
| 场景 | 自动调用的 Agent |
|---|---|
| 复杂功能请求 | planner |
| 代码写完/修改完 | code-reviewer |
| Bug 修复或新功能 | tdd-guide |
| 架构决策 | architect |
并行执行原则：
独立的操作必须并行执行，不能串行：
markdown
# 正确：三个独立分析并行执行
同时启动：
1. Agent 1: 安全分析 auth 模块
2. Agent 2: 性能审查 cache 系统
3. Agent 3: 类型检查 utilities
# 错误：不必要的串行
先 Agent 1，再 Agent 2，再 Agent 3多视角分析： 对复杂问题使用 Split Role 子代理：事实审查者、高级工程师、安全专家、一致性审查者、冗余检查者。
3.8 hooks.md --- Hook 系统
三种 Hook 类型：
| 类型 | 触发时机 | 用途 |
|---|---|---|
| PreToolUse | 工具执行前 | 验证参数、修改参数 |
| PostToolUse | 工具执行后 | 自动格式化、检查 |
| Stop | 会话结束时 | 最终验证 |
自动接受权限（allowedTools）：
- 对可信的、定义明确的计划启用
- 对探索性工作禁用
- 永远不要使用
dangerously-skip-permissions标志 - 通过
~/.claude.json中的allowedTools配置
TodoWrite 最佳实践： 用 TodoWrite 工具追踪多步任务进度。Todo 列表能暴露：乱序步骤、遗漏项、多余项、粒度错误、需求误解。
3.9 development-workflow.md --- 开发工作流
这是最完整的工作流定义，串联了多个规则：
markdown
1. Plan First（规划）
└─ 使用 planner Agent 创建实施计划
└─ 识别依赖和风险
└─ 拆解为阶段
2. TDD Approach（测试驱动）
└─ 使用 tdd-guide Agent
└─ RED → GREEN → IMPROVE
└─ 验证 80%+ 覆盖率
3. Code Review（代码审查）
└─ 使用 code-reviewer Agent
└─ 修复 CRITICAL 和 HIGH 问题
└─ 尽量修复 MEDIUM 问题
4. Commit & Push（提交推送）
└─ 详细的 Commit Message
└─ 遵循 Conventional Commits 格式注意这个流程如何呼应五大原则：Plan → Agent-First → Test-Driven → Security → Immutability（通过 Git 的不可变提交记录体现）。
3.10 code-review.md --- 代码审查
定义了代码审查的标准和流程：
审查流程：
- 收集上下文（git diff）
- 理解变更范围
- 阅读周围代码（不孤立审查变更）
- 应用审查清单
- 报告发现（按严重级别）
严重级别：
| 级别 | 必须修复？ | 示例 |
|---|---|---|
| CRITICAL | 是 | 安全漏洞、数据丢失风险 |
| HIGH | 是 | 逻辑错误、缺少错误处理 |
| MEDIUM | 建议 | 性能问题、代码重复 |
| LOW | 可选 | 命名改进、注释完善 |
四、规则间的交叉引用
10 个规则文件不是孤立的，它们之间有明确的引用关系：
markdown
development-workflow.md
├── 引用 → git-workflow.md（提交格式）
├── 引用 → testing.md（TDD 要求）
└── 引用 → agents.md（Agent 调用时机）
coding-style.md
└── 被引用于 → security.md（输入验证）
→ testing.md（代码质量影响测试）
performance.md
└── 引用 → agents.md（模型选择影响 Agent 配置）development-workflow.md 是串联所有规则的"主线"，理解它就理解了规则体系的全貌。
五、本课练习
练习 1：阅读全部 10 个文件（30 分钟）
逐个打开 rules/common/ 下的 10 个文件，完整阅读。
bash
ls rules/common/
# 按顺序阅读每个文件练习 2：用表格总结（15 分钟）
填写以下表格（可在纸上或文档中）：
| 文件 | 一句话总结 | 最关键的一条规则 | 关联的 Agent |
|---|---|---|---|
| coding-style.md | |||
| testing.md | |||
| security.md | |||
| git-workflow.md | |||
| performance.md | |||
| patterns.md | |||
| agents.md | |||
| hooks.md | |||
| development-workflow.md | |||
| code-review.md |
练习 3：识别覆盖点（10 分钟）
思考以下场景，哪条规则会被语言特定规则覆盖：
- Go 语言中使用指针接收器修改 struct --- 这与 coding-style.md 的哪条规则冲突？
- Rust 的所有权系统 --- 这与不可变性原则是什么关系？
- Python 的 PEP 8 --- 这会覆盖 coding-style.md 的哪些格式规范？
练习 4（选做）：画规则关系图
在纸上画出 10 个规则文件之间的引用关系图。哪个文件被引用最多？哪个文件引用了最多其他文件？
六、本课小结
| 你应该记住的 | 内容 |
|---|---|
| 分层继承 | common → language → project，越具体优先级越高 |
| 不可变性级别 | CRITICAL --- 这是 coding-style 中优先级最高的规则 |
| 覆盖率要求 | 最低 80%，TDD 六步法强制执行 |
| 安全检查 | 8 项提交前清单，安全响应协议五步法 |
| 模型选择 | Haiku（轻量）、Sonnet（主力）、Opus（深度推理） |
| 开发工作流 | Plan → TDD → Review → Commit，串联了多个规则 |
| 安装陷阱 | 不能扁平化复制 rules 目录，必须保持层级结构 |
七、下节预告
第 5 课：Rules（下）--- 语言特定规则与实战
下节课我们将从通用规则进入语言特定规则。你将看到 Go、TypeScript、Python 等语言如何继承和覆盖通用规则，学会为新语言草拟规则文件。
预习建议 ：打开 rules/golang/coding-style.md，与 rules/common/coding-style.md 对比阅读，找出 3 个不同之处。