Back to Details

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.
ForbiddenAllowed
Code blocks or snippetsBehavioral descriptions
Variable names or function signaturesObservable 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:
  1. Who is the user/actor?
  2. What situation triggers this need?
  3. What outcome do they want?
  4. 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."
通过调研问题收集待办任务：
  1. 谁是用户/执行者？
  2. 什么场景触发了这个需求？
  3. 他们想要什么结果？
  4. 如果他们无法完成这个任务会发生什么？
JTBD识别完成后即可暂停——拆分为主题前先将所有待办任务提交给用户确认。

Phase 2: Topics of Concern

阶段2：关注主题拆分

Break each job into discrete topics. Apply the "One Sentence Without 'And'" test:
TestResultAction
"This spec covers color extraction."PASSSingle topic — one spec file
"This spec covers color extraction and palette rendering."FAILTwo topics — split into two spec files
"This spec covers user authentication and session management."FAILSplit into two specs
"This spec covers input validation for the registration form."PASSSingle 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

Job to Be Done

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

Acceptance Criteria

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

Edge Cases

  • [Describe boundary condition and expected behavior]
  • [Describe error condition and expected behavior]
  • [描述边界条件和预期行为]
  • [描述错误条件和预期行为]

Data Contracts

Data Contracts

  • Input: [Describe shape, constraints, valid ranges]
  • Output: [Describe shape, guarantees, invariants]
  • Input: [描述结构、约束、有效范围]
  • Output: [描述结构、保障、不变量]

Non-Functional Requirements

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

验收标准质量规则

RuleGood ExampleBad 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

#CheckPass Criteria
1No implementation detailsZero code, function names, or tech choices
2One Sentence Without 'And' testEach spec covers exactly one topic
3All criteria are Given/When/ThenNo free-form prose criteria
4All criteria are testableEach can be verified by a test
5Edge cases documentedAt least 2 per spec
6Data contracts definedInput and output shapes specified
7Consistent 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:
CriterionQuestionStandard
SimpleCan it ship fast with narrow scope?Weeks, not months
LovableWill people actually want to use it?Delightful, not just functional
CompleteDoes 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):
  1. Read all spec files in 
    specs/
  2. Check each against the Cardinal Rule (no code, no implementation details)
  3. Verify "One Sentence Without 'And'" test
  4. Ensure consistent naming convention
  5. Verify Given/When/Then format for all acceptance criteria
  6. 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.
审核已有规范（而非编写新规范）时：
  1. 读取
    specs/
    目录下的所有规范文件
  2. 对照核心规则检查每一份规范（无代码、无实现细节）
  3. 验证是否通过"不含'和'的单句"测试
  4. 确保命名规则统一
  5. 验证所有验收标准都是Given/When/Then格式
  6. 标记违规项，尽可能自动修复
针对大规模规范集，可以通过
Agent
工具（
subagent_type="Explore"
）最多启动100个并行子Agent，每个子Agent处理一份规范文件。

Anti-Patterns / Common Mistakes

反模式/常见错误

MistakeWhy It Is WrongWhat To Do Instead
Including code snippets in specsLocks implementation approachDescribe behavior, not mechanism
Naming technologies ("use Redis")Prevents better alternativesDescribe capability ("caches results")
Combining topics with "and"Spec too broad, hard to implement/testSplit into separate spec files
Vague acceptance criteria ("works well")Cannot write a test for itSpecific measurable outcome
Missing edge casesBugs in boundary conditionsDocument at least 2 edge cases per spec
Skipping data contractsInput/output ambiguityAlways define shapes and constraints
Writing specs after codeSpecs justify code instead of driving itSpecs come BEFORE implementation
Acceptance criteria that describe UI layoutImplementation detailDescribe 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

集成点

SkillRelationship
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

Image Color Extraction

Job to Be Done

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.
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

Acceptance Criteria

Dominant Color Extraction

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

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

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

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

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

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:
  1. VERIFY the Cardinal Rule — zero implementation details in any spec
  2. VERIFY every spec passes the "One Sentence Without 'And'" test
  3. VERIFY all acceptance criteria use Given/When/Then format
  4. VERIFY every spec has edge cases and data contracts
  5. VERIFY the story map has at least one complete SLC release slice
  6. VERIFY the user has confirmed the spec set
宣称规范完成前：
  1. 验证核心规则——所有规范都没有实现细节
  2. 验证每份规范都通过"不含'和'的单句"测试
  3. 验证所有验收标准都使用Given/When/Then格式
  4. 验证每份规范都有边界case和数据契约
  5. 验证故事地图至少包含一个完整的SLC发布切片
  6. 验证用户已经确认规范集

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都必须严格遵守，不得跳过或调整任何环节。