Spec 编程工作流文档
Spec 编程是一种以 规格驱动开发 的工程方法论：在动手写代码之前，先把"做什么"写清楚，再把"怎么做"想明白，最后才动手实现。AI 辅助下的 Spec 编程将每个阶段都变成人机协作的结构化产出。
总体流程
PRD → UI 设计 → 技术方案 → 开发 → 测试 → 上线
每个阶段都有明确的输入、产出物、验收标准，上一阶段的产出是下一阶段的输入。
阶段一：PRD（产品需求文档）
目标
将模糊的业务诉求转化为清晰、可验证的需求规格。
输入
- 业务目标 / 用户痛点
- 相关背景资料（竞品分析、数据报告等）
推荐 AI 工具
| 工具 | 用途 |
|---|
| ChatGPT / Claude | 用户故事梳理、PRD 草稿生成、需求完整性检查 |
| Notion AI | 在 Notion 中直接生成和整理 PRD 文档 |
| Gemini | 结合 Google Workspace，快速整理调研资料 |
| Perplexity | 竞品调研、行业背景快速检索 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
自定义 /prd | /prd [功能名] | 将 PRD 提示词模板注册为 slash command，一键生成标准 PRD 草稿 |
自定义 /ac | /ac [功能描述] | 自动生成验收标准（Acceptance Criteria）列表 |
自定义 /review-prd | /review-prd | 读取当前 PRD.md，检查完整性（缺失异常流、边界条件、Out of Scope） |
如何注册自定义 Skill：在项目根目录创建 .claude/commands/prd.md，写入提示词，即可通过 /prd 调用。
与 AI 协作方式
- 描述业务背景，让 AI 帮你梳理核心用户故事
- AI 生成 PRD 草稿，人工审查并补充边界条件
- AI 检查需求完整性（是否有遗漏的异常流、权限场景）
产出物：PRD.md
## 功能名称
## 背景与目标
## 用户角色
## 核心用户故事
- As [角色], I want [功能], so that [价值]
## 功能需求（正常流 + 异常流）
## 非功能需求（性能、安全、兼容性）
## 数据需求
## 验收标准（AC）
## 不在范围内（Out of Scope）
## 开放问题（Open Questions）
验收标准
阶段二：UI 设计
目标
将文字需求转化为可交互的视觉规格，消除理解歧义。
输入
推荐 AI 工具
| 工具 | 用途 |
|---|
| v0 (Vercel) | 输入文字描述，直接生成 React UI 组件和页面 |
| Galileo AI | 自然语言生成高保真 UI 设计稿 |
| Uizard | 草图/截图转 UI 原型，支持 AI 生成线框图 |
| Figma AI / Magician | Figma 内的 AI 插件，生成图标、文案、变体 |
| Claude / ChatGPT | 生成页面清单、组件树、交互说明文字 |
| Midjourney / DALL-E | 生成 UI 风格参考图、插画、配图 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
自定义 /ui-inventory | /ui-inventory | 读取 PRD.md，自动输出页面清单、组件清单、状态列表（loading/empty/error） |
自定义 /design-review | /design-review | 对照 PRD 检查 UI 设计稿是否遗漏状态或交互场景 |
自定义 /design-token | /design-token | 根据设计描述生成标准 Design Token 定义（颜色、字体、间距） |
与 AI 协作方式
- 提供 PRD，让 AI 生成页面清单和信息架构
- AI 输出低保真线框图描述 / Markdown 表格形式的组件清单
- 人工在设计工具（Figma / Pencil）中实现，AI 辅助生成样式规范
- AI 检查设计是否覆盖了 PRD 中所有状态（loading、empty、error）
产出物
| 产出物 | 说明 |
|---|
| 页面清单 | 所有页面/弹窗/底部栏的列表 |
| 组件规范 | 颜色、字体、间距、圆角等 Design Token |
| 交互说明 | 每个操作对应的状态流转 |
| 标注文档 | 供开发使用的精确尺寸标注 |
验收标准
阶段三：技术方案设计
目标
在写代码之前，确定架构、接口、数据模型、关键算法，让团队对实现路径达成共识。
输入
- 已评审的 PRD.md
- UI 设计稿 / 标注文档
推荐 AI 工具
| 工具 | 用途 |
|---|
| Claude | 架构设计讨论、数据模型设计、API 接口设计、任务拆解 |
| ChatGPT | 技术选型对比、方案权衡分析 |
| GitHub Copilot Chat | 结合代码库上下文的技术方案讨论 |
| Mermaid + AI | 用 AI 生成 Mermaid 语法的架构图、流程图、ER图 |
| Eraser.io | AI 生成系统架构图、时序图 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
自定义 /tech-design | /tech-design | 读取 PRD.md，输出完整技术方案草稿（数据模型、API 设计、任务拆解） |
自定义 /task-breakdown | /task-breakdown | 将技术方案拆解为带依赖关系的开发子任务列表 |
自定义 /api-design | /api-design [资源名] | 为指定资源生成 RESTful API 接口定义（含请求/响应示例和错误码） |
自定义 /security-review | /security-review | 对技术方案进行安全检查，列出潜在漏洞和应对措施 |
与 AI 协作方式
- 描述需求，让 AI 列出候选技术方案及其权衡
- AI 生成数据模型草稿（数据库表结构 / 数据类）
- AI 生成 API 接口设计（RESTful / GraphQL）
- 人工确认方案，AI 检查潜在的性能和安全问题
- AI 将方案拆解为可并行的开发子任务
产出物：TECH_DESIGN.md
## 技术选型与理由
## 系统架构图（文字描述 / ASCII 图）
## 数据模型
- 实体定义
- 字段说明
- 关系图
## API 设计
- 接口列表
- 请求/响应结构
- 错误码规范
## 关键流程
- 核心业务流程图
- 状态机
## 安全考量
## 性能考量
## 任务拆解（Task Breakdown）
- 任务列表（可并行 / 串行标注）
- 依赖关系
## 技术风险与应对
验收标准
阶段四：开发
目标
按技术方案实现功能，保持代码可读、可测试、可维护。
输入
- TECH_DESIGN.md 中的任务列表
- API 接口文档
- UI 设计稿
推荐 AI 工具
| 工具 | 用途 |
|---|
| Claude Code | 在终端中直接操作代码库，理解上下文后生成/修改代码 |
| GitHub Copilot | IDE 内代码补全、函数实现、注释生成 |
| Cursor | AI 原生 IDE，支持多文件上下文编辑和 Chat |
| Windsurf | AI 驱动的 IDE，支持 Cascade 多步骤自动完成任务 |
| Codeium | 免费的 AI 代码补全，支持多种 IDE |
| Tabnine | 本地部署的 AI 代码补全，适合隐私要求高的场景 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
内置 /commit | /commit | 自动分析 staged 变更，生成符合 Conventional Commits 规范的提交信息 |
内置 simplify | /simplify | Review 已修改的代码，检查复用性、代码质量和效率，自动修复问题 |
内置 claude-api | /claude-api | 帮助使用 Claude API / Anthropic SDK 构建 AI 功能 |
自定义 /impl | /impl [任务描述] | 读取任务上下文（PRD + 接口文档），按规范实现功能代码 |
自定义 /review | /review | 对当前 diff 做代码 Review，检查逻辑、安全、性能问题 |
/commit 和 /simplify 是 Claude Code 内置 Skill，可直接使用，无需配置。
与 AI 协作方式（逐任务循环）
1. 给 AI 提供当前任务描述 + 相关上下文文件
2. AI 生成代码实现草稿
3. 人工 Review：检查逻辑正确性、安全问题、编码风格
4. AI 根据 Review 意见修改
5. 人工确认，提交代码
开发规范
## 提交规范
- feat: 新功能
- fix: Bug 修复
- refactor: 重构（不改变行为）
- test: 测试相关
- docs: 文档更新
## 代码 Review 检查项
- [ ] 逻辑与需求一致
- [ ] 无明显性能问题（N+1 查询、不必要的重复计算）
- [ ] 无安全漏洞（SQL注入、XSS、未授权访问）
- [ ] 错误处理完整
- [ ] 关键逻辑有注释
产出物
- 通过 Code Review 的 PR / MR
- 与 API 文档保持同步的接口实现
- 单元测试（覆盖核心业务逻辑）
验收标准
阶段五：测试
目标
系统性地验证实现与需求的一致性，发现并修复缺陷。
输入
- PRD.md 中的验收标准（AC）
- 已完成开发的功能分支
推荐 AI 工具
| 工具 | 用途 |
|---|
| Claude / ChatGPT | 根据 AC 生成测试用例矩阵、分析失败原因 |
| GitHub Copilot | 在 IDE 中自动生成单元测试代码 |
| Cursor | 根据实现代码自动生成对应测试文件 |
| Applitools | AI 驱动的视觉回归测试，自动比对 UI 差异 |
| Testim | AI 辅助录制和维护 E2E 自动化测试 |
| Mabl | AI 自动修复因 UI 变更而失效的测试脚本 |
| Katalon | AI 辅助生成和执行跨平台 UI 测试 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
自定义 /gen-tests | /gen-tests [文件路径] | 读取实现代码，自动生成对应的单元测试，覆盖正常流和边界值 |
自定义 /test-matrix | /test-matrix | 读取 PRD 验收标准，生成完整的测试用例矩阵 |
自定义 /bug-report | /bug-report | 交互式生成标准化 Bug 报告（引导填写复现步骤、预期/实际行为） |
内置 loop | /loop 30m /run-tests | 每 30 分钟自动执行测试并汇报结果，适合 CI 等待期监控 |
与 AI 协作方式
- 提供 PRD，让 AI 生成测试用例矩阵
- AI 辅助生成自动化测试脚本（UI 自动化 / 接口测试）
- 测试执行后，AI 辅助分析失败原因
- AI 生成 Bug 报告模板，标准化缺陷描述
测试分层
| 层级 | 类型 | 工具（Android/KMP） | 覆盖目标 |
|---|
| L1 | 单元测试 | JUnit5 / kotlin.test | 业务逻辑、算法 |
| L2 | 集成测试 | Ktor Test / MockK | API 集成、数据层 |
| L3 | UI 测试 | Espresso / Compose UI Test | 核心用户流程 |
| L4 | 端到端测试 | 手动 / Maestro | Happy Path + 关键异常流 |
测试用例结构
## 测试用例：[功能名称]
### 前置条件
### 测试步骤
### 预期结果
### 实际结果
### 状态：Pass / Fail / Blocked
Bug 报告结构
## Bug 标题
## 严重级别：P0 / P1 / P2 / P3
## 复现步骤
## 预期行为
## 实际行为
## 环境信息（设备、OS版本、App版本）
## 截图/录屏
产出物
- 测试用例文档
- 测试执行报告
- Bug 列表（已关闭 / 遗留说明）
验收标准
阶段六：上线
目标
安全、可回滚地将功能发布到生产环境，并监控上线后的质量。
输入
推荐 AI 工具
| 工具 | 用途 |
|---|
| Claude / ChatGPT | 生成上线 Checklist、撰写 Release Notes、分析告警日志 |
| Datadog AI | 智能告警归因、异常检测、日志摘要 |
| Sentry AI | 自动分析崩溃堆栈，关联代码变更，推断根因 |
| New Relic AI | 自然语言查询监控数据，AI 辅助根因分析 |
| PagerDuty AIOps | 告警降噪、智能事件关联、自动升级策略 |
| Grafana Assistant | 自然语言生成监控看板查询语句 |
推荐 Claude Code Skill
| Skill / 命令 | 使用方式 | 说明 |
|---|
自定义 /release-notes | /release-notes | 分析 git log 中本次发布的所有提交，自动生成结构化 Release Notes |
自定义 /deploy-checklist | /deploy-checklist | 根据本次变更内容（diff / PR 描述）生成定制化上线 Checklist |
自定义 /incident | /incident [告警内容] | 粘贴监控告警或崩溃日志，AI 辅助分析根因并给出排查建议 |
内置 update-config | /update-config | 配置 Claude Code 自动化钩子，如"上线后自动执行健康检查脚本" |
内置 loop | /loop 10m /check-deploy | 上线期间定时轮询部署状态或监控指标，自动汇报 |
与 AI 协作方式
- AI 生成上线 Checklist（根据本次变更内容定制）
- AI 辅助撰写发布说明（Release Notes）
- 上线后，AI 辅助分析监控告警和日志
上线 Checklist
## 上线前
- [ ] 所有测试用例通过
- [ ] P0/P1 Bug 已修复
- [ ] 数据库迁移脚本已准备并测试
- [ ] 配置项 / 环境变量已更新到生产环境
- [ ] 回滚方案已明确（回滚步骤、耗时评估）
- [ ] 灰度/特性开关已配置（如需要）
- [ ] 相关文档已更新（API 文档、运维手册）
- [ ] 通知相关干系人（产品、客服、运营）
## 上线中
- [ ] 按灰度策略逐步放量
- [ ] 实时监控关键指标（崩溃率、错误率、核心业务指标）
- [ ] 值班人员就位
## 上线后（24-72小时）
- [ ] 崩溃率、ANR 率未超过基线
- [ ] 核心业务转化指标正常
- [ ] 用户反馈渠道无异常集中投诉
- [ ] 监控告警无持续触发
发布说明模板
## v1.x.x 发布说明
### 新功能
- [功能名] 简要描述
### 问题修复
- [Bug描述] 修复说明
### 已知问题
- [遗留说明]
### 升级注意事项
- [迁移步骤（如有）]
产出物
- 发布包（APK / AAB / 服务端镜像）
- 上线执行记录
- 上线后监控报告（24h 快报）
验收标准
阶段间传递规范
PRD.md ──→ UI 设计稿 + 组件规范
──→ TECH_DESIGN.md（API 设计 + 任务拆解）
──→ 代码 PR + 单元测试
──→ 测试报告 + Bug 列表
──→ 上线记录 + 监控报告
黄金原则：下一阶段不开始，除非当前阶段的验收标准已满足。
自定义 Claude Code Skill 创建指南
文档中标注"自定义"的 Skill 均需要在项目中手动创建，方法如下：
目录结构
项目根目录/
└── .claude/
└── commands/
├── prd.md
├── ac.md
├── tech-design.md
├── task-breakdown.md
├── impl.md
├── review.md
├── gen-tests.md
├── test-matrix.md
├── release-notes.md
└── deploy-checklist.md
示例：创建 /prd Skill
新建 .claude/commands/prd.md，内容如下：
你是一个经验丰富的产品经理。基于用户提供的功能描述，生成一份完整的 PRD 文档，包含：
1. 背景与目标
2. 用户角色
3. 核心用户故事（As / I want / So that 格式）
4. 功能需求（正常流 + 异常流）
5. 非功能需求
6. 验收标准（AC）
7. Out of Scope
8. Open Questions
功能描述：$ARGUMENTS
内置 Skill 一览
| Skill | 命令 | 无需配置 |
|---|
| commit | /commit | 直接使用 |
| simplify | /simplify | 直接使用 |
| loop | /loop [间隔] [命令] | 直接使用 |
| update-config | /update-config | 直接使用 |
| claude-api | /claude-api | 直接使用 |
AI 协作通用提示词模板
PRD 阶段
我要做一个 [功能名]，背景是 [业务背景]，目标用户是 [用户角色]。
请帮我：
1. 梳理核心用户故事
2. 列出功能需求（正常流 + 异常流）
3. 指出可能遗漏的边界场景
4. 生成验收标准（AC）
技术方案阶段
基于以下 PRD，帮我设计技术方案：
[粘贴 PRD 内容]
请输出：
1. 数据模型设计
2. API 接口设计
3. 关键流程说明
4. 任务拆解（标注依赖关系）
5. 潜在风险
开发阶段
当前任务：[任务描述]
相关上下文：[粘贴相关文件或接口定义]
请实现该功能，要求：
- 遵循 [项目编码规范]
- 包含错误处理
- 关键逻辑加注释
测试阶段
基于以下 AC，生成测试用例矩阵：
[粘贴验收标准]
要求覆盖：正常流、异常流、边界值、权限场景
本文档基于 Spec 编程方法论，适用于 AI 辅助软件开发场景。
