specification-first

规格优先

概述

先编写规格说明，再进行实现。规格说明是唯一可信来源。代码应根据规格说明生成，而不是反过来。

核心原则： 行为规格说明定义系统做什么。代码实现如何做到。没有规格说明，就只能靠猜测。

没有例外。没有变通。没有捷径。

首要指令

NO IMPLEMENTATION WITHOUT A SPECIFICATION FIRST

如果你还没有编写一份定义输入、输出、边界情况和验收标准的规格说明，就无权编写代码。这不是可选项，也不是小题大做。这能避免 AI 生成代码失败的首要原因：构建了错误的东西。

适用场景

以下情况必须使用：

• 开发新功能或模块
• 创建 API 端点
• 构建数据管道
• 构建任何具有明确输入和输出的系统
• 用户说“帮我构建 X”或“创建 Y”

例外情况（请与人工确认）：

• 配置变更
• 行为明确的单行缺陷修复
• 文档更新

入门流程

BEFORE writing any implementation code:

1. IDENTIFY: What are the inputs?
2. DEFINE: What are the expected outputs?
3. CONSTRAIN: What are the boundaries and limitations?
4. EDGE: What happens at the edges? (empty, null, maximum, concurrent)
5. ACCEPT: What criteria demonstrate correctness?
6. WRITE: Produce the specification document
7. APPROVE: Obtain user confirmation
8. ONLY THEN: Implement

Omit any step = building the wrong thing

规格说明文档模板

# [Feature Name] Specification

## Purpose
[Single sentence: what this does and why it exists]

## Inputs
| Input | Type | Required | Constraints | Default |
|-------|------|----------|-------------|---------|
| [name] | [type] | [yes/no] | [validation rules] | [default] |

## Outputs
| Scenario | Output | Shape |
|----------|--------|-------|
| Success | [what is returned] | [type/structure] |
| Invalid input | [error response] | [error shape] |
| Not found | [404 response] | [error shape] |

## Behavior

### Standard Path
1. [Step-by-step behavior for normal usage]
2. [Include state mutations, side effects]

### Edge Cases
| Case | Input | Expected Behavior |
|------|-------|-------------------|
| Empty input | "" | Return validation error |
| Maximum length | 10000 chars | Truncate to 5000 |
| Concurrent access | 2 simultaneous requests | Serialize second request |
| [case] | [input] | [behavior] |

## Acceptance Criteria
- [ ] [Criterion 1 - testable, specific]
- [ ] [Criterion 2 - testable, specific]
- [ ] [Criterion 3 - testable, specific]

## Explicitly Excluded (YAGNI)
- [Feature intentionally omitted]
- [Optimization intentionally deferred]

与测试优先开发的关系

digraph spec_test_flow {
    rankdir=LR;
    spec [label="Author Spec\n(this skill)", shape=box style=filled fillcolor=lightyellow];
    test [label="Write Failing Test\nfrom Spec Criteria", shape=box style=filled fillcolor="#ffcccc"];
    code [label="Write Minimal Code\nto Pass Test", shape=box style=filled fillcolor="#ccffcc"];
    verify [label="Verify Against\nSpec Criteria", shape=box style=filled fillcolor="#ccccff"];

    spec -> test [label="acceptance criteria\nbecome test cases"];
    test -> code [label="test-first cycle"];
    code -> verify [label="all criteria satisfied?"];
    verify -> spec [label="no - revise spec\nor implementation"];
}

规格说明 -> 测试 -> 代码 -> 对照规格说明验证

规格说明中的验收标准直接对应测试用例。每项标准至少生成一个测试。如果无法根据某项标准推导出测试，该标准就过于含糊——请完善规格说明。

规格说明详略级别

级别	适用场景	范围
最简	简单功能，行为显而易见	目的 + 输入 + 输出 + 3 项验收标准
标准	大多数功能	上述完整模板
详尽	复杂系统、公共 API、多租户系统	完整模板 + 时序图 + 状态机 + 错误分类

根据复杂度调整规格说明的详略。实用函数只需最简规格说明。身份验证系统则需要详尽规格说明。

认知陷阱

自我辩解	事实
“它太简单了，不值得写规格说明”	简单功能也隐藏着边界情况。编写规格说明只需 2 分钟。
“我会在编码时弄清楚”	你会构建出错误的东西，然后返工三次。
“用户已经描述了他们的需求”	用户描述的是目标，而不是行为。规格说明可以弥合这一差距。
“测试优先就够了；我不需要规格说明”	测试优先告诉你要验证什么。规格说明告诉你要构建什么。两者缺一不可。
“规格说明会拖慢我的进度”	规格说明能避免构建错误的东西。从任何可衡量的角度看，这都会更快。
“我会在事后补写规格说明”	实现完成后编写的规格说明，只会为已构建的内容找理由，而不是描述原本应该构建的内容。
“AI 理解我的意图”	AI 会生成看似合理、但可能偏离意图的代码。规格说明可以消除歧义。

防护措施

禁止的操作：

• 在规格说明获批前开始实现
• 编写测试时不参考规格说明中的标准
• 变更行为时不更新规格说明
• 未对照验收标准进行验证就交付
• 推迟处理边界情况（“之后再处理”）
• 实现完成后才编写规格说明

必须采取的行动：

• 编写代码前取得规格说明批准
• 将验收标准与测试用例逐项一一对应
• 需求变化时更新规格说明
• 宣布完成前验证所有标准均已通过
• 明确列出排除的功能（即不构建的内容）

集成

工作流顺序：

• godmode:intent-discovery -> 生成设计
• godmode:specification-first -> 根据设计生成规范
• godmode:task-planning -> 根据规范生成实施计划
• godmode:test-first -> 根据规范标准生成测试
• godmode:completion-gate -> 根据规范标准进行验证

必需的配套技能： 实施时调用 godmode:test-first