Openspec 规范驱动开发工作流-需求文档篇

背景

使用 openspec 工作流进行开发，投喂的需求文档要如何规范编写？

工作流简介

OpenSpec 的 propose 阶段会读取需求描述，自动生成三个核心产物：

AI 会基于需求文档 + 项目上下文（config.yaml 中定义的技术栈、架构约定、AGENTS.md）来生成这些产物。需求文档的质量直接决定了产物质量。

产品需求文档的建议

1. 明确的内容

2. 可选明确的内容（可以大幅提升 AI 产物质量）

3. 格式建议

复制代码

# 【产品名】功能名称

> 来源：[文档链接]
> 日期：YYYY/MM/DD

## 背景
为什么做？解决什么问题？

## 目标
1. 目标 1
2. 目标 2

## 非目标（有则填）
- 不涉及 xxx
- 不修改 xxx

## 触发条件
### 场景 A：xxx
- 触发路径描述
### 场景 B：xxx
- 触发路径描述

## 行为规则
- 用户操作 A → 系统行为 A
- 用户操作 B → 系统行为 B
- 异常情况：刷新/关闭 → 行为描述

## 疲劳度 / 频率控制（可选）
- 关闭后 N 天再弹
- 接受/拒绝后永不再弹
- 在线参数控制说明

## UI / 展示内容（有设计稿则不用写，无则必写）
- 位置、尺寸、样式要求
- 文案内容（标题、描述、按钮文案）
- 动画要求

## 可配置项
- 在线参数名 & 类型 & 默认值
- 配置规则说明

## 回退方案
- 如何不发版快速下线

## 投放时间（可选）
持续 N 天

4. 常见问题 & 反模式

总结

核心原则：需求文档越结构化、越场景化，OpenSpec 生成的 proposal/design/tasks/spec 质量越高。

最关键的三点：

触发条件要穷举 --- 每个触发路径单独列出
行为规则用"当...则..."格式 --- AI 会直接转为 spec 场景
写清非目标和边界 --- 防止 AI 过度实现或遗漏异常处理