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 质量越高。
最关键的三点：

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

产品设计agent-skills（AI辅助产品设计）