spec-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Specification Writing

规范编写

Overview

概述

Specifications define WHAT the software should do, never HOW. This skill applies the Jobs to Be Done (JTBD) methodology to break requirements into properly scoped, testable specification files that drive autonomous implementation. Every spec produces Given/When/Then acceptance criteria free of implementation details.

This is a RIGID skill. Every phase, gate, and format rule must be followed exactly.

规范定义软件应当做什么，绝不定义如何实现。本技能应用待办任务（JTBD）方法论将需求拆解为范围合理、可测试的规范文件，支撑自主研发。每份规范都会产出不含实现细节的Given/When/Then格式验收标准。

这是一项严格型技能，每个阶段、门槛和格式规则都必须严格遵守。

The Cardinal Rule

核心规则

[HARD-GATE:SPEC] Specifications must NEVER contain implementation details.

Forbidden	Allowed
Code blocks or snippets	Behavioral descriptions
Variable names or function signatures	Observable outcomes
Technology choices ("use React", "use PostgreSQL")	Capability requirements ("renders in browser", "persists data")
Algorithm suggestions ("use K-means clustering")	Success criteria ("extracts 5-10 dominant colors")
Architecture patterns ("use MVC")	User-facing behaviors
Library references ("use Zod for validation")	Validation requirements ("rejects malformed input")

Why: Implementation-free specs preserve flexibility. The implementing agent can choose the best approach for the codebase, technology, and constraints — and change course without spec updates.

[硬性门槛:SPEC] 规范中绝对不能包含实现细节。

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

原因： 不含实现细节的规范保留了灵活性，实现侧的Agent可以根据代码库、技术栈和约束选择最优方案，也可以在不需要更新规范的前提下调整实现路径。

Phase 1: Jobs to Be Done (JTBD)

阶段1：待办任务（JTBD）梳理

Identify the user's or system's jobs using this format:

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

Examples:

"When I upload an image, I want to extract its color palette, so I can use those colors in my design."
"When I receive an API request, I want to validate the payload, so I can reject malformed data before processing."

Gather jobs through discovery questions:

Who is the user/actor?
What situation triggers this need?
What outcome do they want?
What happens if they cannot accomplish this?

STOP after JTBD identification — present all jobs to the user for confirmation before breaking into topics.

使用以下格式识别用户或系统的待办任务：

When [场景], I want to [动机], so I can [预期结果].

示例：

"When I upload an image, I want to extract its color palette, so I can use those colors in my design."
"When I receive an API request, I want to validate the payload, so I can reject malformed data before processing."

通过调研问题收集待办任务：

谁是用户/执行者？
什么场景触发了这个需求？
他们想要什么结果？
如果他们无法完成这个任务会发生什么？

JTBD识别完成后即可暂停——拆分为主题前先将所有待办任务提交给用户确认。

Phase 2: Topics of Concern

阶段2：关注主题拆分

Break each job into discrete topics. Apply the "One Sentence Without 'And'" test:

Test	Result	Action
"This spec covers color extraction."	PASS	Single topic — one spec file
"This spec covers color extraction and palette rendering."	FAIL	Two topics — split into two spec files
"This spec covers user authentication and session management."	FAIL	Split into two specs
"This spec covers input validation for the registration form."	PASS	Single topic — one spec file

Each topic becomes one specification file.

STOP after topic breakdown — confirm the list of spec files before writing them.

将每个待办任务拆分为独立主题，适用**"不含'和'的单句"测试：**

测试内容	结果	操作
"This spec covers color extraction."	通过	单一主题——对应一份规范文件
"This spec covers color extraction and palette rendering."	不通过	两个主题——拆分为两份规范文件
"This spec covers user authentication and session management."	不通过	拆分为两份规范
"This spec covers input validation for the registration form."	通过	单一主题——对应一份规范文件

每个主题对应一份规范文件。

主题拆分完成后即可暂停——编写规范前先确认规范文件清单。

Phase 3: Write Specification Files

阶段3：编写规范文件

File naming convention:

<int>-<descriptive-name>.md

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

文件命名规则：

<数字>-<描述性名称>.md

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

Specification File Template

规范文件模板

markdown

undefined

markdown

undefined

[Topic Name]

[主题名称]

Job to Be Done

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

When [场景], I want to [动机], so I can [预期结果].

Acceptance Criteria

[Criterion 1 Name]

[标准1名称]

Given [precondition]
When [action]
Then [observable outcome]
And [additional observable outcome]

Given [前置条件]
When [操作]
Then [可观测结果]
And [额外可观测结果]

[Criterion 2 Name]

[标准2名称]

Given [precondition]
When [action]
Then [observable outcome]

Given [前置条件]
When [操作]
Then [可观测结果]

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]

Input: [描述结构、约束、有效范围]
Output: [描述结构、保障、不变量]

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"]

undefined

Performance: [可量化指标，例如 "95分位响应时间在200ms以内"]
Accessibility: [具体标准，例如 "WCAG 2.1 AA"]
Security: [具体要求，例如 "输入经过XSS sanitize处理"]

undefined

Acceptance Criteria Quality Rules

验收标准质量规则

Rule	Good Example	Bad Example
Observable behavioral outcome	"Extracts 5-10 dominant colors from any image"	"Use K-means clustering with k=8"
Testable	"Color data persists across sessions"	"Store in PostgreSQL JSONB column"
Specific and measurable	"Palette changes appear within 500ms"	"Use WebSocket for real-time updates"
Independent (stands alone)	"Palette renders when image loads"	"Implement with React useEffect hook"
Implementation-free	"Passwords cannot be recovered from stored data"	"Use bcrypt with 12 salt rounds"

STOP after writing specs — run the audit checklist before proceeding to Phase 4.

规则	正面示例	反面示例
可观测的行为结果	"从任意图片中提取5-10个主色"	"使用k=8的K-means聚类"
可测试	"颜色数据跨会话持久化"	"存储在PostgreSQL JSONB列中"
具体可量化	"调色板变更在500ms内生效"	"使用WebSocket实现实时更新"
独立（可单独成立）	"图片加载完成后渲染调色板"	"使用React useEffect钩子实现"
无实现细节	"无法从存储数据中恢复密码"	"使用12次盐轮的bcrypt加密"

规范编写完成后即可暂停——进入阶段4前先运行审核 checklist。

Spec Audit Checklist

规范审核 Checklist

#	Check	Pass Criteria
1	No implementation details	Zero code, function names, or tech choices
2	One Sentence Without 'And' test	Each spec covers exactly one topic
3	All criteria are Given/When/Then	No free-form prose criteria
4	All criteria are testable	Each can be verified by a test
5	Edge cases documented	At least 2 per spec
6	Data contracts defined	Input and output shapes specified
7	Consistent naming	`<int>-<descriptive-name>.md` format

#	检查项	通过标准
1	无实现细节	无代码、函数名、技术选型内容
2	通过"不含'和'的单句"测试	每份规范仅覆盖一个主题
3	所有标准都是Given/When/Then格式	无自由格式的验收标准
4	所有标准都可测试	每条标准都可以通过测试验证
5	边界case已记录	每份规范至少包含2个边界case
6	数据契约已定义	明确了输入和输出结构
7	命名统一	符合 `<数字>-<描述性名称>.md` 格式

Phase 4: Story Map Organization

阶段4：故事地图梳理

Organize specs into a story map for release planning:

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

Horizontal rows = candidate releases
Top row = minimum viable release
Each row adds capabilities across the board

将规范整理为故事地图用于发布规划：

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 Release Criteria

SLC发布标准

For each horizontal slice, evaluate:

Criterion	Question	Standard
Simple	Can it ship fast with narrow scope?	Weeks, not months
Lovable	Will people actually want to use it?	Delightful, not just functional
Complete	Does it fully accomplish a job?	End-to-end, not half-done

[HARD-GATE] A release must satisfy ALL three. "Simple but incomplete" is not shippable. "Complete but not lovable" is not shippable.

STOP after story map — get user confirmation on release slicing before finalizing.

针对每个横向切片，评估以下维度：

标准	问题	要求
简单	能否在小范围下快速发布？	以周为单位交付，而非月
易用	用户会不会真的想用？	体验愉悦，而非仅能用
完整	是否能完整完成一个任务？	端到端可用，而非半完成

[硬性门槛] 一个发布版本必须同时满足以上三个条件。"简单但不完整"不能发布，"完整但不好用"也不能发布。

故事地图完成后即可暂停——最终确认前先获得用户对发布切片的确认。

Phase 5: Specs Audit Mode

阶段5：规范审核模式

When auditing existing specs (rather than writing new ones):

Read all spec files in
```
specs/
```
Check each against the Cardinal Rule (no code, no implementation details)
Verify "One Sentence Without 'And'" test
Ensure consistent naming convention
Verify Given/When/Then format for all acceptance criteria
Flag violations and auto-fix where possible

Deploy up to 100 parallel subagents via the

Agent

tool (with

subagent_type="Explore"

) — one per spec file — for large spec sets.

审核已有规范（而非编写新规范）时：

读取
```
specs/
```
目录下的所有规范文件
对照核心规则检查每一份规范（无代码、无实现细节）
验证是否通过"不含'和'的单句"测试
确保命名规则统一
验证所有验收标准都是Given/When/Then格式
标记违规项，尽可能自动修复

针对大规模规范集，可以通过

Agent

工具（

subagent_type="Explore"

）最多启动100个并行子Agent，每个子Agent处理一份规范文件。

Anti-Patterns / Common Mistakes

反模式/常见错误

Mistake	Why It Is Wrong	What To Do Instead
Including code snippets in specs	Locks implementation approach	Describe behavior, not mechanism
Naming technologies ("use Redis")	Prevents better alternatives	Describe capability ("caches results")
Combining topics with "and"	Spec too broad, hard to implement/test	Split into separate spec files
Vague acceptance criteria ("works well")	Cannot write a test for it	Specific measurable outcome
Missing edge cases	Bugs in boundary conditions	Document at least 2 edge cases per spec
Skipping data contracts	Input/output ambiguity	Always define shapes and constraints
Writing specs after code	Specs justify code instead of driving it	Specs come BEFORE implementation
Acceptance criteria that describe UI layout	Implementation detail	Describe what the user can accomplish

错误	错误原因	正确做法
在规范中包含代码片段	锁死了实现方案	描述行为，而非实现机制
指定技术（"使用Redis"）	排除了更优的替代方案	描述能力（"缓存结果"）
用"和"合并多个主题	规范太宽泛，难以实现/测试	拆分为独立的规范文件
模糊的验收标准（"运行良好"）	无法对应编写测试	给出具体可量化的结果
缺失边界case	边界条件下容易出Bug	每份规范至少记录2个边界case
缺失数据契约	输入输出存在歧义	始终定义结构和约束
代码写完后再补规范	规范变成了代码的 justification，而非指导	规范在实现前编写
验收标准描述UI布局	属于实现细节	描述用户可以完成的目标

Anti-Rationalization Guards

反合理化约束

[HARD-GATE] Do NOT include ANY implementation details — no code, no tech names, no architecture
[HARD-GATE] Do NOT skip the "One Sentence Without 'And'" test — split every compound topic
[HARD-GATE] Do NOT accept acceptance criteria that are not in Given/When/Then format
[HARD-GATE] Do NOT skip the audit checklist before finalizing specs
Do NOT skip edge cases — every spec needs at least 2
Do NOT skip data contracts — every spec needs input/output shapes
Do NOT write specs after implementation — specs drive code, not the reverse

[硬性门槛] 不得包含任何实现细节——无代码、无技术名称、无架构设计
[硬性门槛] 不得跳过"不含'和'的单句"测试——拆分所有复合主题
[硬性门槛] 不得接受非Given/When/Then格式的验收标准
[硬性门槛] 规范最终确认前不得跳过审核checklist
不得跳过边界case——每份规范至少需要2个
不得跳过数据契约——每份规范都需要明确输入输出结构
不得在实现完成后编写规范——规范指导代码，而非反过来

Integration Points

集成点

Skill	Relationship
`autonomous-loop`	Planning mode reads specs to identify implementation gaps
`acceptance-testing`	Tests are derived directly from spec acceptance criteria
`reverse-engineering-specs`	Generates specs from existing code (brownfield)
`prd-generation`	PRD provides high-level requirements; specs detail them
`planning`	Plans reference spec acceptance criteria for task definition
`test-driven-development`	Red phase writes tests matching spec acceptance criteria
`writing-skills`	Skills can be specified using this methodology

技能	关联关系
`autonomous-loop`	规划模式读取规范识别实现缺口
`acceptance-testing`	测试直接从规范的验收标准衍生而来
`reverse-engineering-specs`	从已有代码生成规范（ brownfield 场景）
`prd-generation`	PRD提供高层需求，规范细化需求
`planning`	规划参考规范验收标准定义任务
`test-driven-development`	红阶段编写匹配规范验收标准的测试
`writing-skills`	可以用这套方法论定义技能规范

Concrete Example: Complete Spec File

具体示例：完整规范文件

markdown

undefined

markdown

undefined

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)

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

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

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

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

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

undefined

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

undefined

Verification Gate

验证门槛

Before claiming specs are complete:

VERIFY the Cardinal Rule — zero implementation details in any spec
VERIFY every spec passes the "One Sentence Without 'And'" test
VERIFY all acceptance criteria use Given/When/Then format
VERIFY every spec has edge cases and data contracts
VERIFY the story map has at least one complete SLC release slice
VERIFY the user has confirmed the spec set

宣称规范完成前：

验证核心规则——所有规范都没有实现细节
验证每份规范都通过"不含'和'的单句"测试
验证所有验收标准都使用Given/When/Then格式
验证每份规范都有边界case和数据契约
验证故事地图至少包含一个完整的SLC发布切片
验证用户已经确认规范集

Skill Type

技能类型

Rigid — The no-implementation-details rule, JTBD structure, Given/When/Then format, and audit checklist must be followed exactly. No elements may be skipped or adapted.

严格型——无实现细节规则、JTBD结构、Given/When/Then格式和审核checklist都必须严格遵守，不得跳过或调整任何环节。