spec-writing

规格编写

概述

规格定义软件应该做什么，绝不规定如何实现。这项技能运用待办工作（JTBD）方法，将需求拆分为范围适当、可测试的规格文件，以驱动自主实现。每份规格都会生成不含实现细节的「假设／当／则」验收标准。

这是一项严格的技能。 必须严格遵循每个阶段、关卡和格式规则。

首要规则

[HARD-GATE:SPEC] 规格中绝不能包含实现细节。

禁止内容	允许内容
代码块或代码片段	行为描述
变量名或函数签名	可观察的结果
技术选型（「使用 React」「使用 PostgreSQL」）	能力要求（「在浏览器中渲染」「持久化数据」）
算法建议（「使用 K 均值聚类」）	成功标准（「提取 5-10 种主要颜色」）
架构模式（「使用 MVC」）	面向用户的行为
库引用（「使用 Zod 进行验证」）	验证要求（「拒绝格式错误的输入」）

原因： 不含实现细节的规格能够保留灵活性。实现 Agent 可以根据代码库、技术和约束选择最佳方案，也可以更改方案而无需更新规格。

阶段 1：待办工作（JTBD）

使用以下格式识别用户或系统要完成的工作：

When [situation], I want to [motivation], so I can [expected outcome].

示例：

• 「当我上传图片时，我想提取其中的调色板，这样就能在设计中使用这些颜色。」
• 「当我收到 API 请求时，我想验证其载荷，这样就能在处理前拒绝格式错误的数据。」

通过探索性问题收集待办工作：

1. 用户／参与者是谁？
2. 什么情况会触发这一需求？
3. 他们想要什么结果？
4. 如果他们无法完成这项工作，会发生什么？

完成 JTBD 识别后停止——将所有待办工作提交给用户确认，然后再拆分主题。

阶段 2：关注主题

将每项待办工作拆分为独立主题。应用**「一句话中不含‘和’」测试：**

测试	结果	操作
「这份规格涵盖颜色提取。」	通过	单个主题——一个规格文件
「这份规格涵盖颜色提取和调色板渲染。」	未通过	两个主题——拆分为两个规格文件
「这份规格涵盖用户身份验证和会话管理。」	未通过	拆分为两份规格
「这份规格涵盖注册表单的输入验证。」	通过	单个主题——一个规格文件

每个主题对应一个规格文件。

完成主题拆分后停止——先确认规格文件列表，再开始编写。

阶段 3：编写规格文件

文件命名约定： <int>-<descriptive-name>.md

specs/
├── 01-color-extraction.md
├── 02-palette-rendering.md
├── 03-export-formats.md
└── 04-color-accessibility.md

规格文件模板

# [Topic Name]

## Job to Be Done
When [situation], I want to [motivation], so I can [expected outcome].

## Acceptance Criteria

### [Criterion 1 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]
- And [additional observable outcome]

### [Criterion 2 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]

## Edge Cases
- [Describe boundary condition and expected behavior]
- [Describe error condition and expected behavior]

## Data Contracts
- Input: [Describe shape, constraints, valid ranges]
- Output: [Describe shape, guarantees, invariants]

## Non-Functional Requirements
- Performance: [measurable target, e.g., "responds within 200ms for 95th percentile"]
- Accessibility: [specific standard, e.g., "WCAG 2.1 AA"]
- Security: [specific requirement, e.g., "input sanitized against XSS"]

验收标准质量规则

规则	良好示例	不佳示例
可观察的行为结果	「从任意图片中提取 5-10 种主要颜色」	「使用 k=8 的 K 均值聚类」
可测试	「颜色数据在不同会话间保持不变」	「存储在 PostgreSQL JSONB 列中」
明确且可衡量	「调色板在 500ms 内发生变化」	「使用 WebSocket 实现实时更新」
独立（自成一体）	「图片加载后渲染调色板」	「使用 React useEffect 钩子实现」
不含实现细节	「无法从存储的数据中还原密码」	「使用 12 轮加盐的 bcrypt」

完成规格编写后停止——进入阶段 4 前先执行审查清单。

规格审查清单

#	检查项	通过标准
1	不包含实现细节	不含代码、函数名或技术选型
2	通过「不含 And 的一句话」测试	每份规格恰好涵盖一个主题
3	所有标准均采用 Given/When/Then 格式	不含自由形式的标准描述
4	所有标准均可测试	每项标准都能通过测试验证
5	记录边缘情况	每份规格至少记录 2 项
6	定义数据契约	指定输入和输出的形状
7	命名一致	采用 <int>-<descriptive-name>.md 格式

第 4 阶段：组织故事地图

将规格整理成故事地图，用于发布规划：

CAPABILITY 1    CAPABILITY 2    CAPABILITY 3    CAPABILITY 4
─────────────   ─────────────   ─────────────   ─────────────
basic upload    auto-extract    manual arrange  export PNG
bulk upload     palette gen     templates       export SVG
drag-drop       color names     grid layout     share link
                accessibility   animation       collaborate

• 横向行 = 候选版本
• 顶行 = 最小可行版本
• 每一行都逐步增加各方面的能力

SLC 发布标准

针对每个横向切片，评估：

标准	问题	要求
简单	能否以狭窄的范围快速发布？	以周计，而非以月计
令人喜爱	人们真的愿意使用吗？	令人愉悦，而不只是可用
完整	能否完整完成一项工作？	端到端，而非半成品

[HARD-GATE] 发布必须满足全部三项标准。「简单但不完整」的版本不可发布。「完整但不令人喜爱」的版本不可发布。

完成故事地图后停止——在最终确定发布切片前，先征求用户确认。

第 5 阶段：规格审查模式

审查现有规格（而非编写新规格）时：

1. 阅读 specs/ 中的所有规格文件
2. 根据首要规则检查每份规格（不含代码和实现细节）
3. 验证是否通过「不含 And 的一句话」测试
4. 确保命名规范一致
5. 验证所有验收标准是否采用 Given/When/Then 格式
6. 标记违规项，并在可能时自动修复

对于大型规格集，可通过 Agent 工具（使用 subagent_type="Explore"）部署最多 100 个并行子代理，每个规格文件对应一个子代理。

反模式／常见错误

错误	错误原因	应采取的做法
在规格中包含代码片段	限定实现方式	描述行为，而非机制
指定技术（「使用 Redis」）	无法采用更好的替代方案	描述能力（「缓存结果」）
用「and」组合多个主题	规格范围过广，难以实现和测试	拆分为单独的规格文件
验收标准含糊（「运行良好」）	无法据此编写测试	指定可衡量的具体结果
缺少边缘情况	边界条件会出现缺陷	每份规格至少记录 2 项边缘情况
跳过数据契约	输入／输出含糊不清	始终定义形状和约束
编写代码后才写规格	规格是在为代码辩护，而非引导实现	规格必须先于实现
验收标准描述 UI 布局	属于实现细节	描述用户可以完成什么

防止自我合理化的约束

• [HARD-GATE] 不得包含任何实现细节——不得包含代码、技术名称或架构
• [HARD-GATE] 不得跳过「不含 And 的一句话」测试——拆分每个复合主题
• [HARD-GATE] 不得接受不符合 Given/When/Then 格式的验收标准
• [HARD-GATE] 最终确定规格前，不得跳过审查清单
• 不得跳过边缘情况——每份规格至少需要 2 项
• 不得跳过数据契约——每份规格都需要定义输入／输出的形状
• 不得在实现后编写规格——规格引导代码，而非反过来

集成点

技能	关系
autonomous-loop	规划模式会读取规格，以识别实现缺口
acceptance-testing	测试直接根据规格中的验收标准生成
reverse-engineering-specs	根据现有代码生成规格（棕地项目）
prd-generation	PRD 提供高层需求；规格对其进行详细说明
planning	计划会引用规格中的验收标准来定义任务
test-driven-development	红阶段会编写符合规格验收标准的测试
writing-skills	可使用此方法论来编写技能

具体示例：完整规格文件

# Image Color Extraction

## Job to Be Done
When I upload an image to the design tool, I want to automatically extract
its dominant colors, so I can use those colors in my design palette.

## Acceptance Criteria

### Dominant Color Extraction
- Given an uploaded image in PNG, JPG, or WebP format
- When the extraction process completes
- Then 5-10 dominant colors are returned as hex values
- And colors are ordered by prominence (most dominant first)

### Transparent Image Handling
- Given an uploaded image with transparent regions
- When the extraction process completes
- Then transparent regions are excluded from color analysis
- And at least 3 dominant colors are still returned

### Processing Feedback
- Given an image upload has started
- When extraction is in progress
- Then the user sees a progress indicator
- And extraction completes within 3 seconds for images up to 10MB

## Edge Cases
- Single-color image: returns 1 color (not an error)
- Very large image (>50MB): returns an error with size limit message
- Corrupted image file: returns an error with clear message, no crash
- Animated GIF: extracts colors from the first frame only

## Data Contracts
- Input: Image file (PNG, JPG, WebP), max 50MB
- Output: Array of 1-10 hex color strings, ordered by prominence
- Error output: Error object with code and human-readable message

## Non-Functional Requirements
- Performance: <3s for images up to 10MB, <10s for images up to 50MB
- Accessibility: Color values include WCAG contrast ratio against white/black

验证关卡

在声称规格已完成之前：

1. 验证基本规则——任何规格中都不得包含实现细节
2. 验证每项规格都通过“无需使用‘和’即可用一句话概括”测试
3. 验证所有验收标准都采用 Given/When/Then 格式
4. 验证每项规格都包含边缘情况和数据契约
5. 验证故事地图至少包含一个完整的 SLC 发布切片
6. 验证用户已确认规格集

技能类型

刚性——不得偏离无实现细节规则、JTBD 结构、Given/When/Then 格式和审核清单，也不得跳过或调整任何要素。