Back to Details

spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-Driven Development

规范驱动开发

A comprehensive methodology for systematic software feature development that ensures quality, maintainability, and successful delivery through structured planning.
这是一套用于系统化软件功能开发的综合方法论，通过结构化规划确保质量、可维护性和交付成功。

When to Use This Skill

何时使用该方法

Ideal scenarios:
  • Complex features with multiple components, integrations, or user interactions
  • High-stakes projects where rework costs are significant
  • Team collaboration requiring shared understanding
  • AI-assisted development where clear structure improves output quality
  • Knowledge preservation for future maintainers
Less suitable:
  • Simple bug fixes with obvious solutions
  • Experimental prototypes for rapid iteration
  • Time-critical hotfixes requiring immediate action
  • Well-established patterns with minimal ambiguity
理想场景：
  • 包含多个组件、集成或用户交互的复杂功能
  • 返工成本高昂的高风险项目
  • 需要达成共识的团队协作场景
  • 清晰结构可提升输出质量的AI辅助开发
  • 为未来维护人员留存知识
不太适合的场景：
  • 解决方案明确的简单Bug修复
  • 需快速迭代的实验性原型
  • 需立即处理的时间紧迫的热修复
  • 歧义极小的成熟模式

The Three-Phase Workflow

三阶段工作流

Phase 1: Requirements Gathering

阶段1：需求收集

Purpose: Transform vague feature ideas into clear, testable requirements
Process:
  1. Capture user stories expressing value and purpose
  2. Define acceptance criteria using EARS format (Easy Approach to Requirements Syntax)
  3. Identify edge cases and constraints
  4. Validate completeness and feasibility
EARS Format Patterns:
WHEN [event] THEN [system] SHALL [response]
IF [precondition] THEN [system] SHALL [response]
WHEN [event] AND [condition] THEN [system] SHALL [response]
Example:
markdown
**User Story:** As a new user, I want to create an account, so that I can access personalized features.

**Acceptance Criteria:**
1. WHEN user provides valid email and password THEN system SHALL create new account
2. WHEN user provides existing email THEN system SHALL display "email already registered" error
3. WHEN user provides password shorter than 8 characters THEN system SHALL display "password too short" error
4. WHEN account creation succeeds THEN system SHALL send confirmation email
目标： 将模糊的功能构想转化为清晰、可测试的需求
流程：
  1. 捕获表达价值与目标的用户故事
  2. 使用EARS格式（需求语法简易方法）定义验收标准
  3. 识别边缘情况与约束条件
  4. 验证完整性与可行性
EARS格式模板：
WHEN [event] THEN [system] SHALL [response]
IF [precondition] THEN [system] SHALL [response]
WHEN [event] AND [condition] THEN [system] SHALL [response]
示例：
markdown
**用户故事：** 作为新用户，我想要创建一个账户，以便访问个性化功能。

**验收标准：**
1. WHEN 用户提供有效的邮箱和密码 THEN 系统 SHALL 创建新账户
2. WHEN 用户提供已注册的邮箱 THEN 系统 SHALL 显示“邮箱已注册”错误
3. WHEN 用户提供的密码短于8个字符 THEN 系统 SHALL 显示“密码过短”错误
4. WHEN 账户创建成功 THEN 系统 SHALL 发送确认邮件

Phase 2: Design Documentation

阶段2：设计文档编写

Purpose: Create a comprehensive technical plan for implementation
Process:
  1. Research technical approaches and constraints
  2. Define system architecture and component interactions
  3. Specify data models and interfaces
  4. Plan error handling and testing strategies
Design Document Structure:
markdown
undefined
目标： 制定全面的技术实现方案
流程：
  1. 调研技术方案与约束条件
  2. 定义系统架构与组件交互
  3. 明确数据模型与接口
  4. 规划错误处理与测试策略
设计文档结构：
markdown
undefined

Overview

概述

[High-level summary of approach]
[方案的高层总结]

Architecture

架构

[System components and their relationships]
[系统组件及其关系]

Components and Interfaces

组件与接口

[Detailed component descriptions]
[详细的组件说明]

Data Models

数据模型

[Data structures and validation rules]
[数据结构与验证规则]

Error Handling

错误处理

[Error scenarios and response strategies]
[错误场景与响应策略]

Testing Strategy

测试策略

[Testing approach for different layers]

**Decision Documentation:**
```markdown
[针对不同层级的测试方法]

**决策文档：**
```markdown

Decision: [Title]

决策：[标题]

Context: [Situation requiring decision] Options Considered:
  1. [Option 1] - Pros: [benefits] / Cons: [drawbacks]
  2. [Option 2] - Pros: [benefits] / Cons: [drawbacks] Decision: [Chosen option] Rationale: [Why this was selected]
undefined
背景： [需要做出决策的场景] 备选方案：
  1. [方案1] - 优势：[益处] / 劣势：[不足]
  2. [方案2] - 优势：[益处] / 劣势：[不足] 决策： [选定方案] 理由： [选择该方案的原因]
undefined

Phase 3: Task Planning

阶段3：任务规划

Purpose: Break design into actionable, sequential implementation steps
Process:
  1. Convert design elements into specific coding tasks
  2. Sequence tasks to enable incremental progress
  3. Define clear objectives and completion criteria
  4. Reference requirements for traceability
Task Structure:
markdown
- [ ] 1. [Epic/Major Component]
- [ ] 1.1 [Specific implementation task]
  - [Implementation details]
  - [Files/components to create]
  - _Requirements: [Requirement references]_
Task Sequencing Strategies:
  • Foundation-First: Core interfaces before dependent components
  • Feature-Slice: End-to-end vertical slices for early validation
  • Risk-First: Tackle uncertain areas early
  • Hybrid: Combine approaches based on project needs
目标： 将设计拆解为可执行的、按顺序排列的实现步骤
流程：
  1. 将设计元素转化为具体的编码任务
  2. 对任务排序以支持增量式进展
  3. 明确目标与完成标准
  4. 关联需求以确保可追溯性
任务结构：
markdown
- [ ] 1. [史诗/主要组件]
- [ ] 1.1 [具体实现任务]
  - [实现细节]
  - [需创建的文件/组件]
  - _需求：[需求引用]_
任务排序策略：
  • 基础优先： 先开发核心接口，再开发依赖组件
  • 功能切片： 端到端的垂直切片，以便早期验证
  • 风险优先： 尽早处理不确定的部分
  • 混合模式： 根据项目需求组合多种策略

Quality Checklists

质量检查清单

Requirements Checklist

需求检查清单

  • All user roles identified and addressed
  • Normal, edge, and error cases covered
  • Requirements are testable and measurable
  • No conflicting requirements
  • EARS format used consistently
  • 已识别并覆盖所有用户角色
  • 已覆盖正常、边缘与错误场景
  • 需求可测试、可衡量
  • 无冲突需求
  • 一致使用EARS格式

Design Checklist

设计检查清单

  • All requirements addressed in design
  • Component responsibilities well-defined
  • Interfaces between components specified
  • Error handling covers expected failures
  • Security considerations addressed
  • 所有需求均在设计中得到体现
  • 组件职责定义清晰
  • 已明确组件间的接口
  • 错误处理覆盖预期故障
  • 已考虑安全因素

Tasks Checklist

任务检查清单

  • All design components have implementation tasks
  • Tasks ordered to respect dependencies
  • Each task produces testable code
  • Requirements references included
  • Scope is appropriate (2-4 hours each)
  • 所有设计组件均有对应的实现任务
  • 任务排序遵循依赖关系
  • 每个任务均可产出可测试的代码
  • 包含需求引用
  • 范围合适（每个任务2-4小时）

Integration with AI Workflows

与AI工作流的集成

For Claude Code / AI Assistants:
  1. Start with context: Provide project background, constraints, and goals
  2. Work in phases: Complete requirements before design, design before tasks
  3. Iterate: Refine outputs through conversation rather than single requests
  4. Validate: Ask AI to review outputs against checklists
  5. Trace: Maintain links between requirements, design, and tasks
Example prompt for starting a spec:
I'm working on [project context]. We need to add [feature description].

Context:
- Technology: [stack]
- Users: [target audience]
- Constraints: [key limitations]

Please help me develop requirements using the EARS format, starting with user stories and acceptance criteria.
针对Claude Code / AI助手：
  1. 从上下文开始： 提供项目背景、约束条件与目标
  2. 分阶段推进： 完成需求后再进行设计，完成设计后再规划任务
  3. 迭代优化： 通过对话完善输出，而非单次请求
  4. 验证： 让AI对照检查清单评审输出
  5. 追溯： 保持需求、设计与任务之间的关联
启动规范编写的示例提示词：
我正在开发[项目背景]。我们需要添加[功能描述]。

背景：
- 技术栈：[技术栈]
- 用户：[目标受众]
- 约束条件：[关键限制]

请帮助我使用EARS格式开发需求，从用户故事和验收标准开始。

Common Pitfalls to Avoid

需避免的常见陷阱

  1. Skipping phases: Each phase builds on the previous; shortcuts create problems
  2. Vague requirements: "System should be fast" vs specific, measurable criteria
  3. Implementation details in requirements: Focus on what, not how
  4. Over-engineering design: Solve current requirements, not hypothetical future ones
  5. Monolithic tasks: Break down into 2-4 hour increments
  6. Missing error cases: Always consider what happens when things go wrong
  1. 跳过阶段： 每个阶段都建立在前一阶段的基础上，走捷径会引发问题
  2. 模糊需求： 避免“系统应快速运行”这类表述，要使用具体、可衡量的标准
  3. 在需求中包含实现细节： 聚焦于“做什么”，而非“怎么做”
  4. 过度设计： 解决当前需求即可，不要针对假设的未来需求设计
  5. 单体任务： 拆解为2-4小时的小任务
  6. 遗漏错误场景： 始终要考虑出错时的情况

Next Steps

后续步骤

After completing a spec:
  1. Begin implementation following task sequence
  2. Track progress by marking tasks complete
  3. Update spec if implementation reveals gaps
  4. Validate completed work against requirements
  5. Document learnings for future specs
完成规范后：
  1. 按照任务顺序开始实现
  2. 通过标记任务完成来跟踪进度
  3. 若实现过程中发现漏洞，更新规范
  4. 根据需求验证已完成的工作
  5. 记录经验教训，为未来的规范编写提供参考