AgentSkillsCN

spec

以需求、设计、任务三阶段进行规格驱动开发，把模糊功能想法转化为可实现、可验证的规范与计划；适用于复杂功能、多组件集成、高风险项目、团队协作、AI 辅助开发与知识沉淀；不适用于简单 bug 修复、快速实验原型、紧急热修复或成熟模式下不确定性很低的改动。

中文原作
SKILL.md
--- frontmatter
name: spec
description: 以需求、设计、任务三阶段进行规格驱动开发，把模糊功能想法转化为可实现、可验证的规范与计划；适用于复杂功能、多组件集成、高风险项目、团队协作、AI 辅助开发与知识沉淀；不适用于简单 bug 修复、快速实验原型、紧急热修复或成熟模式下不确定性很低的改动。

规格驱动开发（Spec-Driven Development）

概览

使用该方法进行系统化的软件功能开发，以减少歧义、提升质量与可维护性，并通过结构化规划提高交付成功率。

元信息

  • •名称: spec-driven-development
  • •描述: 使用需求、设计、任务三阶段的系统化方法，把模糊功能想法转为清晰、可实现的解决方案，以减少歧义、提升质量并促进 AI 协作。
  • •许可证: MIT
  • •兼容性: Claude Code、Cursor、VS Code、Windsurf
  • •元数据:
    • •类别: methodology
    • •复杂度: intermediate
    • •作者: Kiro Team
    • •版本: 1.0.0

三阶段工作流

阶段 1：需求收集

目的: 将模糊的功能想法转化为清晰、可测试的需求。

流程:

  1. •编写能够表达价值与目的的用户故事
  2. •使用 EARS 格式定义验收标准
  3. •识别边界情况与约束
  4. •验证完整性与可行性

EARS 格式模式:

code
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 发送确认邮件

阶段 2：设计文档

目的: 形成全面的技术实现计划。

流程:

  1. •调研技术方案与约束
  2. •定义系统架构与组件交互
  3. •明确数据模型与接口
  4. •规划错误处理与测试策略

设计文档结构:

markdown
## 概览
[高层方案摘要]

## 架构
[系统组件与关系]

## 组件与接口
[组件的详细说明]

## 数据模型
[数据结构与校验规则]

## 错误处理
[错误场景与响应策略]

## 测试策略
[不同层级的测试方式]

决策记录:

markdown
### 决策: [标题]
**背景:** [需要决策的情境]
**候选方案:**
1. [方案 1] - 优点: [收益] / 缺点: [不足]
2. [方案 2] - 优点: [收益] / 缺点: [不足]
**决策:** [选择的方案]
**理由:** [选择原因]

阶段 3：任务规划

目的: 将设计拆解为可执行、可顺序推进的实现步骤。

流程:

  1. •把设计元素转化为具体编码任务
  2. •按依赖关系排序以支持增量交付
  3. •为每个任务定义清晰目标与完成标准
  4. •关联需求以便追溯

任务结构:

markdown
- [ ] 1. [史诗/主要组件]
- [ ] 1.1 [具体实现任务]
  - [实现细节]
  - [要创建的文件/组件]
  - _需求: [需求引用]_

任务排序策略:

  • •基础优先: 先做核心接口与基础设施，再做依赖组件
  • •功能切片: 以端到端纵向切片验证主流程
  • •风险优先: 优先处理不确定或高风险部分
  • •混合: 根据项目特点组合使用

质量检查清单

需求清单

  • • 识别并覆盖所有用户角色
  • • 覆盖正常、边界与错误场景
  • • 需求可测试、可衡量
  • • 无冲突或相互矛盾的需求
  • • EARS 格式使用一致

设计清单

  • • 设计覆盖全部需求
  • • 组件职责清晰
  • • 组件间接口明确
  • • 错误处理覆盖预期失败场景
  • • 纳入安全考虑

任务清单

  • • 设计中的每个组件都有实现任务
  • • 任务顺序符合依赖关系
  • • 每个任务产生可测试代码
  • • 任务包含需求引用
  • • 单个任务规模适中（2-4 小时）

与 AI 工作流集成

面向 Claude Code / AI 助手:

  1. •先提供背景、约束与目标
  2. •依次完成需求、设计、任务三个阶段
  3. •通过对话迭代完善输出
  4. •使用清单进行自检与复核
  5. •维持需求、设计与任务之间的可追溯性

用于启动规格的示例提示:

code
我正在做 [项目背景]，需要新增 [功能描述]。

上下文:
- 技术栈: [stack]
- 用户: [目标人群]
- 约束: [关键限制]

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

常见陷阱

  1. •跳过阶段：每个阶段都依赖前一步，跳过会导致返工
  2. •需求含糊：比如“系统要快”而非可衡量指标
  3. •把实现细节写进需求：需求关注“做什么”，不是“怎么做”
  4. •过度设计：只解决当前需求，避免为假设场景过度建设
  5. •任务过大：拆分到 2-4 小时的实现粒度
  6. •忽略错误场景：始终考虑失败与异常路径

后续步骤

  1. •按任务顺序开始实现
  2. •随进度勾选已完成任务
  3. •实现过程中发现缺口就更新规格
  4. •完成后对照需求进行验收
  5. •记录经验以便后续规格复用