方法论总述

August 16, 2026 · View on GitHub

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

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

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

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

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

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

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

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

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

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

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

审查引擎按文件名识别对象种类：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-0001	错误	文件不可读或文件名不是受支持种类

审查行为约定：

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