很多人第一次接触 OpenSpec会误以为它适合“需求已经很清楚”的项目。其实恰恰相反它最有价值的场景之一就是你只有一个模糊目标却还不知道系统到底该怎么做。这时候OpenSpec 不是要求你一开始就写出完美 spec而是帮你把“模糊问题”一步步压缩成“可验证行为”。先理解一个误区很多项目失败不是因为没人写需求而是因为一开始就把“想法”当成了“需求”又把“需求”当成了“实现方案”。比如一句话“做一个审批系统。”这其实什么都没说清楚。谁发起谁审批驳回后怎么办通知谁异常怎么处理全都还是空白。OpenSpec 的作用不是替你凭空补完这些细节而是给你一个结构让你有地方承认“不确定”并把这些不确定逐步消化掉。OpenSpec 在这个场景里的角色如果一句话概括proposal 用来承认你现在知道什么、不知道什么。spec 用来定义系统必须如何表现。design 用来解释准备如何实现。tasks 用来把事情拆成可以执行的步骤。所以OpenSpec 不是一份文档而是一套“从模糊到清晰”的工作流。最常见的问题当一个需求刚出现时很多人会卡在这里业务目标模糊。用户场景不完整。异常情况没想过。规则边界不明确。技术方案也没谱。这时如果直接让 AI 写代码结果往往是“看起来能跑但和真正要的东西不一致”。因为 AI 最擅长补全而你最怕的恰恰是它在你没定义清楚时替你做了错误补全。所以第一原则不是“赶紧实现”而是“先把错误自由度压下去”。Skill 1先写问题不急着写答案当你还不清楚怎么做时第一步不要写 spec先写一个最小 proposal。你可以用下面这个模板## Why 我们要解决什么问题 ## Goal 这一期最小目标是什么 ## In Scope 这次明确要做什么 ## Out of Scope 这次明确不做什么 ## Open Questions 还有哪些关键问题没想清楚比如你收到一个需求“做一个请假审批能力。”不要马上进入实现先写## Why 员工请假目前靠线下沟通流程不可追踪统计困难。 ## Goal 实现最小可用的线上请假审批流程。 ## In Scope 员工提交请假申请 主管审批 审批结果通知员工。 ## Out of Scope 暂不支持转签、加签、抄送、销假。 ## Open Questions 超过几天是否需要二级审批 驳回后是否允许修改重提 通知方式是站内信还是邮件这一步非常关键因为它把“没想清楚”从脑子里拿到了文档里。一旦未知被列出来需求就开始变得可讨论。Skill 2不要问“需求够不够细”要问“能不能验证”很多人写需求时会问“这够不够细”其实更有用的问题是“别人能不能根据这段话判断系统是否做对了”这就是 OpenSpec 的核心转折点从描述想法转向描述行为。比如不好系统支持请假审批。这个说法太空。你根本无法据此判断系统做得对不对。更好### Requirement: Submit Leave Request 系统 SHALL 允许员工提交请假申请。 #### Scenario: 提交成功 - WHEN 员工填写请假日期和原因并提交 - THEN 系统创建一条请假记录 - AND 状态为 PENDING_APPROVAL为什么这个更好因为它已经可以验收了。你可以看结果、测状态、验证流程。所以需求细化的本质不是“写得更长”而是“写得更可验证”。Skill 3用场景把细节逼出来如果你不知道还缺什么不要发呆直接写场景。最少先写三类场景成功场景。失败场景。边界场景。继续用请假审批举例。成功场景#### Scenario: 提交成功 - WHEN 员工填写完整信息并提交 - THEN 系统创建请假单 - AND 状态为 PENDING_MANAGER_APPROVAL失败场景#### Scenario: 缺少原因 - WHEN 员工未填写请假原因就提交 - THEN 系统拒绝提交 - AND 提示原因不能为空边界场景#### Scenario: 超过三天 - WHEN 员工提交超过 3 天的请假 - THEN 系统在主管同意后进入二级审批你会发现一旦你开始写场景需求细节会自动浮现出来原因是否必填3 天是自然日还是工作日谁是二级审批人二级审批通过后状态是什么驳回时是否必须填写理由也就是说细节很多时候不是“凭空想出来”的而是“在写场景时暴露出来”的。Skill 4区分 spec 和 design这是很多人用 OpenSpec 时最容易混乱的地方。spec 管什么spec 管的是系统行为。业务规则。权限约束。状态变化。验收条件。例如超过 3 天需要二级审批。驳回时必须填写原因。审批完成后通知申请人。这些都应写进 spec。design 管什么design 管的是状态机怎么设计。用几张表。审批链怎么查。通知通过什么机制发送。如何做幂等与补偿。例如使用 leave_requests 和 approval_records 两张表。审批流由状态机驱动。通知走异步消息队列。主管关系从组织架构服务实时查询。这些更适合写到 design。一句话区分spec系统应该怎么表现。design系统准备怎么实现。当你不清楚需求时先别急着做 design。因为你连“应该怎么表现”都没定技术方案很容易提前跑偏。Skill 5复杂需求不要写成一个大块很多需求之所以越写越乱是因为试图用一份大文档把所有问题一次说完。OpenSpec 更好的方法是拆分。还是请假系统可以拆成这些 RequirementSubmit Leave RequestManager ApprovalDepartment ApprovalRejection HandlingNotification每个 Requirement 下再写自己的 Scenario。这样你不会面对一坨“审批系统需求说明”而是在处理一组可管理的行为单元。这对 AI 也非常重要。因为 AI 对局部、明确、结构化的约束响应得更稳定对大段模糊描述的理解则更容易漂移。Skill 6允许“带问号的规范”存在很多人卡住是因为总觉得“没想清楚就不能写”。其实恰恰应该反过来因为没想清楚所以更要写。你可以在 proposal 或 design 里显式保留未决项## Open Questions - 请假时长计算按自然日还是工作日 - 驳回后是否允许修改原单重提 - 二级审批是否需要按部门配置这不是不专业而是专业。因为你把风险和认知空洞前置暴露了而不是把它们留给后续实现阶段爆炸。Skill 7从“需求描述”升级到“验收语言”如果你想让 OpenSpec 真正落地最关键的一步是不要只写“系统要支持什么”而要写“做到什么算完成”。比如普通写法支持消息通知。更好的写法### Requirement: Approval Notification 系统 SHALL 在审批结束后通知申请人。 #### Scenario: 审批通过通知 - WHEN 请假单状态变为 APPROVED - THEN 系统向申请人发送审批通过通知 #### Scenario: 审批驳回通知 - WHEN 请假单状态变为 REJECTED - THEN 系统向申请人发送驳回通知 - AND 通知中包含驳回原因这种写法的价值在于产品能看懂。开发能实现。测试能验收。AI 不容易自由发挥。这就是 OpenSpec 真正的协作价值。一个可直接套用的实操流程当你拿到一个模糊需求时可以直接按下面这套走。第一步写最小 proposal目标是把模糊问题装进结构里不追求完整只追求边界清晰。模板## Why ## Goal ## In Scope ## Out of Scope ## Open Questions第二步列核心动作问自己用户和系统之间最核心的动作有哪些例如请假审批提交申请审批申请驳回申请通知结果每个动作先单独成一个 Requirement。第三步每个动作写 3 个场景至少写正常成功。常见失败。一个边界情况。这是最容易逼出需求细节的步骤。第四步把实现细节移到 design一旦你开始写数据库结构服务边界状态机消息机制重试与补偿说明你进入 design 了不要再混在 spec 里。第五步拆任务把已经明确的内容拆成 tasks- [ ] 建请假单表 - [ ] 新增提交申请接口 - [ ] 增加主管审批接口 - [ ] 增加驳回原因校验 - [ ] 实现审批完成通知 - [ ] 编写接口测试这样需求才真正开始可执行。一个最小完整示例下面给你一个非常小的完整例子。proposal.md## Why 员工请假流程目前依赖线下沟通无法追踪审批状态。 ## Goal 上线最小可用的请假审批功能。 ## In Scope 员工提交请假 主管审批 结果通知。 ## Out of Scope 不支持转签、加签、抄送。 ## Open Questions 超过几天需要二审 驳回后是否允许修改后重提spec.md### Requirement: Submit Leave Request 系统 SHALL 支持员工提交请假申请。 #### Scenario: 提交成功 - WHEN 员工填写请假日期和原因并提交 - THEN 系统创建请假单 - AND 状态为 PENDING_MANAGER_APPROVAL #### Scenario: 缺少原因 - WHEN 员工未填写原因提交 - THEN 系统拒绝提交 - AND 返回错误提示 ### Requirement: Manager Approval 系统 SHALL 支持直属主管审批请假申请。 #### Scenario: 审批通过 - WHEN 主管批准申请 - THEN 系统将状态更新为 APPROVED #### Scenario: 审批驳回 - WHEN 主管驳回申请 - THEN 系统将状态更新为 REJECTED - AND 记录驳回原因design.md## Data Model leave_requests approval_records ## Decisions 审批状态使用状态机管理。 通知采用异步发送。 驳回原因字段为必填。tasks.md- [ ] 创建请假单表 - [ ] 创建审批记录表 - [ ] 开发提交申请接口 - [ ] 开发主管审批接口 - [ ] 增加驳回原因校验 - [ ] 增加审批结果通知 - [ ] 编写测试这个例子不复杂但已经展示出一个重要原则你不需要一开始什么都想清楚才能开始写 OpenSpec。你可以在写的过程中把模糊的需求逐层压实。最后的方法论如果把这篇文章压缩成一句工作原则就是OpenSpec 不是用来记录“我已经想清楚的需求”而是用来帮助我把“还没想清楚的需求”逐步想清楚。真正实操时记住这 4 句话就够了先写问题不急着写方案。先写行为不急着写实现。先写场景用场景逼出细节。把未知显式列出来而不是藏在脑子里。可复制模板你可以把下面这段直接当作一个 skill 使用。模糊需求细化模板# 1. Proposal ## Why 要解决什么问题 ## Goal 本期最小目标是什么 ## In Scope 这次确定做什么 ## Out of Scope 这次明确不做什么 ## Open Questions 还有哪些关键问题没想清楚 # 2. Spec ### Requirement: [核心动作1] 系统 SHALL ... #### Scenario: 成功 - WHEN ... - THEN ... #### Scenario: 失败 - WHEN ... - THEN ... #### Scenario: 边界 - WHEN ... - THEN ... ### Requirement: [核心动作2] 系统 SHALL ... # 3. Design ## Data Model ## State Machine ## API Design ## Risks ## Decisions # 4. Tasks - [ ] ... - [ ] ... - [ ] ...适合放进项目的说明你也可以把下面这段写进团队规范里当需求不清晰时不直接进入编码。先用 proposal 明确目标、范围和未决问题再用 spec 定义行为和场景复杂实现细节进入 design最后通过 tasks 驱动实现。