# 方法论总述

## 一、为什么「先写规格」能防翻车

翻车的代价曲线不是线性的：需求理解错误的返工成本，是写错一行代码的数十倍。
规格（SPEC.md）是需求理解的形式化产物，它的价值有三层：

1. **替 agent 与需求方对齐**：含糊的需求有多种理解，规格强制写成可验证的句子，
   分歧在动手前暴露；
2. **给实现定边界**：规格是「法律文本」，实现以它为唯一依据，规格外的代码按缺陷处理；
3. **给验收定基准**：没有验收标准就没有「完成」的定义，审计无从谈起。

keel 的门禁逻辑：**规格不过审查，禁止进入建造。** 门禁用工具（keel_review）实现
确定性检查，不依赖 agent 自觉。

## 二、五步纪律环

### 1. 锚定（Anchor）——技能 keel-anchor

动手前收敛目标与边界，产出三句话：

- 目标：当……时，系统/产物……（结果可观察、可度量）；
- 不做：至少一条明确不做的项；
- 成功：验收场景的描述，而非实现手段。

门禁：三句话中任何一句无法验证，锚定不算完成。

### 2. 立规（Spec）——技能 keel-spec，工具 keel_spec / keel_review

把三句话展开为规格书五要素：目标、边界（范围内/范围外）、需求（R-xx）、
验收标准（AC-xx）、验证方法。按任务规模选模板：

| 规模 | 判据 | 模板 |
| --- | --- | --- |
| 微任务 | 单文件、单行为、半小时内完成 | spec.minimal |
| 常规任务 | 有明确需求列表与验收标准 | spec |
| 大任务 | 涉及接口、数据、错误路径 | spec.feature |

门禁：keel_review 对规格书零错误；警告逐条有结论（已修改或判为误报并说明理由）。

### 3. 探针（Probe）——技能 keel-probe，工具 keel_spec（模板 assumptions）

把规格正文之外的一切不确定前提登记进 ASSUMPTIONS.md，每条标注：

- 风险 [高]：假设为假会导致方案返工或目标不成立；
- 风险 [中]：假设为假改变实现方式，目标仍可达；
- 风险 [低]：假设为假只影响局部细节。

验证手段按成本从低到高：查权威文档、写 20 行内最小示例、查既有先例、问询并记录、
造数据压边界。结论回填：✅ 已验证 / ❌ 已证伪。

门禁：存在未标记结论的 [高] 假设，禁止进入建造；证伪后规格未同步更新，同样禁止。

### 4. 建造（Build）——技能 keel-build

#### 防过度工程十条守则

1. 最小可行：只实现规格里的行为，规格外的代码按缺陷处理；
2. 禁止投机抽象：接口、类、配置项必须有当前规格的消费者；
3. 一次一种机制：不引入与既有方案并存的第二套机制；
4. 写完即删：重读 diff，删掉不直接服务验收标准的行；
5. 依赖要交押金：新增依赖前在假设登记表记一条假设；
6. 重复先于抽象：两处相似代码先接受重复，第三个使用者再抽象；
7. 防御代码要标价：边界处理必须注释「防御什么」；
8. 不做预优化：性能优化只在验收标准含量化指标时进行；
9. 命名即承诺：标识符使用规格词汇，不发明同义词；
10. 一次提交一个行为：提交粒度对齐需求条目。

#### 范围蔓延护栏

- 规格冻结：进入建造后，规格文本变化只有两个入口——证伪回填、变更单；
- 变更单流程：规格外请求不拒绝、不答应，先填 change-request 模板，批准后改规格再实现；
- 三问自检：是否被现有验收标准覆盖？是完成目标必需还是顺手？能不能记入待办？

### 5. 审计（Audit）——技能 keel-audit，工具 keel_spec（模板 audit）

- 逐条核对验收标准，结果 ✅/❌/跳过（跳过须写理由），证据必填；
- 偏差处置：未通过项修复或走变更单；规格外代码补变更单追认或删除；
- 复盘三问：哪里最接近翻车？哪个规格要素早写能省多少时间？下轮删哪条守则的例外？

门禁：AUDIT.md 零错误、无未处置的 ❌，才允许宣布完成。

## 三、审查规则清单（KEEL-*）

审查引擎按文件名识别对象种类：`SPEC*` → 规格书，`ASSUMPTIONS*` → 假设登记表，
`AUDIT*` → 验收审计，其余报 KEEL-0001。

### 规格书

| 规则 | 严重度 | 检查内容 |
| --- | --- | --- |
| KEEL-0101 | 错误 | 缺少必需小节（目标/验收标准/验证方法） |
| KEEL-0102 | 错误 | 存在未填充占位符 {{...}} |
| KEEL-0103 | 错误 | 「验收标准」为空 |
| KEEL-0106 | 错误 | 「目标」为空 |
| KEEL-0201 | 警告 | 模糊表述词（可能/应该/尽量/优化/改进/等等 等） |
| KEEL-0202 | 警告 | 范围蔓延信号词（顺便/顺手/以后再说/如果时间允许 等） |
| KEEL-0203 | 警告 | 「边界」小节缺失 |
| KEEL-0204 | 警告 | 「范围外」未声明或其后无内容 |
| KEEL-0205 | 警告 | 「需求」为空 |
| KEEL-0207 | 警告 | 同目录无 ASSUMPTIONS*.md（受 requireAssumptions 配置控制） |
| KEEL-0208 | 警告 | 「验证方法」为空 |
| KEEL-0209 | 警告 | 代码围栏未闭合（其后内容不参与检查） |

### 假设登记表

| 规则 | 严重度 | 检查内容 |
| --- | --- | --- |
| KEEL-0301 | 错误 | 登记表为空 |
| KEEL-0302 | 错误 | 条目未标注风险等级 [高]/[中]/[低] |
| KEEL-0303 | 错误 | 高风险条目未标记验证结论 |

### 验收审计

| 规则 | 严重度 | 检查内容 |
| --- | --- | --- |
| KEEL-0401 | 错误 | 审计为空 |
| KEEL-0402 | 警告 | 条目缺少结果标记（✅/❌/通过/未通过/跳过） |
| KEEL-0403 | 错误 | 验收结果存在 ❌ 未通过项（先处置再宣布完成） |

### 通用

| 规则 | 严重度 | 检查内容 |
| --- | --- | --- |
| KEEL-0001 | 错误 | 文件不可读或文件名不是受支持种类 |

审查行为约定：

- 文件头部的 frontmatter 块（---…---）与代码围栏（``` / ~~~）内的内容不参与任何检查；
- 表格数据行要求使用标准 markdown 表格（含 `| --- |` 分隔行）；无分隔行时首行按数据行处理；
- 列位判定：假设登记表以最后一列为结论列（模板列位：编号|假设|风险|验证方法|结论），
  验收审计以第二列为结果列（模板列位：验收标准|结果|证据）；请按模板列位填写；
- 脚手架生成的字段答案不允许为空字符串（留空即视为未作答，用「—」表示不适用）；
- strict 模式下全部警告升级为错误；
- 报告带规则编号、行号与可操作建议；maxFindings 只限制展示规模，
  通过/失败按全部发现判定，截断不会翻转门禁结论；
- 模糊词表与蔓延词表集中在 src/review.ts，可按项目裁剪。

## 四、规模适配

- **一行任务**：仍要 30 秒锚定 + spec.minimal + keel_review。规格短不等于没有规格；
- **中型功能**：spec 模板 + 假设登记 + 变更单护栏；
- **大型功能**：spec.feature 模板 + 接口/数据/错误处理小节 + 探针先行；
- **失败复盘**：把「上次哪里翻车」写成规格的输入，比写检讨书有用。

## 五、常见误区

- 把模板当文书作业：规格的价值在思考过程，不在格式；
- 用审查工具走过场：warning 全部忽略等于没有门禁；
- 规格一次写到位：证伪与变更单本就是流程的一部分，规格允许演进，只禁止悄悄演进；
- 把 keel 当规划工具：keel 只保证「进入规划前规格合格」，任务拆解与排期交给规划技能，
  衔接方式见 [PLANNING_BRIDGE.md](PLANNING_BRIDGE.md)。