适用范围

OpenSpec 适合新项目、已有项目迭代、功能增强、缺陷修复和多人协作场景，尤其适合需求容易漂移、上下文容易丢失、AI 参与较多的开发过程。

团队内推荐优先用于以下情况：

• 新功能开发，需要先对齐目标和边界。
• 老项目改造，需要把变更影响显式化。
• 多人协作，需要共享同一份规范而不是靠口头同步。
• AI 辅助开发较多，希望减少“写着写着跑偏”的问题。
• 需求复杂或不够清晰，需要先澄清再编码。

核心原则

团队统一采用“先约定，再构建”的开发原则，即先形成结构化规范，再进入编码、验证和归档阶段。

统一遵循以下原则：

• 没有形成共识的需求，不直接进入实现。
• 需求、设计、任务拆分到不同文件，不混写成一份大文档。
• 当前系统正式规则放在specs/，本次变更放在changes/，二者分开维护。
• 稳定规则最终要回写到主 specs，保持单一事实来源。
• AI 应围绕规范工作，而不是仅依据一次性 prompt 自由发挥。

目录结构

推荐项目内统一使用如下目录结构：

openspec/ ├── AGENTS.md ├── project.md ├── specs/ │ └── <capability>/ │ └── spec.md └── changes/ └── <change-id>/ ├── proposal.md ├── design.md ├── tasks.md └── specs/ └── <capability>/ └── spec.md

其中：

• project.md记录全局项目上下文。
• specs/保存当前系统的正式规范。
• changes/保存每次变更的工作区。
• AGENTS.md为 AI 工具提供统一的项目说明和工作约束。

文件职责

AGENTS.md

AGENTS.md可以理解为“给 AI 看的 README”，用于告诉不同 AI 助手如何读取项目上下文、如何遵循 OpenSpec 工作流以及何时优先查阅规范文件。

适合写入：

• AI 在什么场景下必须先读openspec/
• 项目中如何创建、更新和应用 change
• 输出格式约束、代码修改边界、审查要求

project.md

project.md用于定义整个项目的长期上下文，是团队和 AI 的共用背景说明。

适合写入：

• 项目目标与范围
• 技术栈与架构约束
• 代码风格、命名规范、测试要求、分支策略
• 业务背景、外部依赖、关键限制条件

proposal.md

proposal.md说明本次为什么要改、改什么、不改什么，是每个变更的起点。

适合写入：

• 背景问题
• 目标与范围
• 影响面与风险
• 明确不做的事项

spec.md

spec.md用于定义系统行为，是最接近“正式需求契约”的文件。它关注系统应该做什么、边界条件是什么、如何验收，而不是内部实现细节。

适合写入：

• Requirement（能力条目）
• Scenario（成功、失败、边界场景）
• 输入输出行为、业务规则、错误条件、验收标准

design.md

design.md解释系统准备如何实现 spec，适合承接技术架构、状态流转、模块划分、数据结构、接口策略等内容。

适合写入：

• 架构决策与方案选择
• 数据模型、接口设计、模块边界
• 风险、权衡和替代方案

tasks.md

tasks.md把需求和设计拆成可执行任务，便于开发按顺序推进，也方便测试和评审跟踪完成度。

建议任务具备以下特点：

• 粒度清晰，可单独完成
• 能映射到 spec 中的 Requirement 或 Scenario
• 有明确完成标准

推荐工作流

团队推荐统一采用以下流程推进项目开发：

1. 初始化项目并建立openspec/目录结构。
2. 补齐project.md和AGENTS.md，形成项目级规则。
3. 每个新需求或改动建立一个changes/<change-id>/目录。
4. 在proposal.md中说明目标、范围和影响。
5. 在变更spec.md中写清行为和场景。
6. 需求复杂时补design.md，明确实现方案。
7. 在tasks.md中拆任务并执行实现。
8. 实现完成后对照 spec 验证，通过后归档并同步回主 specs。

可以把这套流程简单理解成：

• propose：先提变更
• specify：再写规范
• design：必要时补设计
• build：按任务实现
• verify：对照 spec 验证
• archive：同步回主规范

什么时候用 explore

当需求不清晰、边界不确定、方案有多种可能时，团队建议先进入 explore，而不是直接起草完整 proposal。

适合 explore 的情况包括：

• 用户只给了一个模糊目标
• 需求涉及较大架构调整
• 团队对实现路径存在明显分歧
• 需要先调查现有系统、依赖或历史逻辑

explore 阶段的目标不是直接产出代码，而是回答这些问题：

• 这次到底要解决什么问题？
• 范围边界在哪里？
• 哪些地方还没想清楚？
• 哪些能力适合拆成独立 Requirement？

如何写一个 change

每个需求都应该作为独立 change 管理，而不是把多个不相关修改塞进同一个变更目录中，这样更有利于评审、实现和归档。

一个标准 change 至少包括：

• proposal.md：为什么做
• spec.md：系统应该怎么表现
• tasks.md：怎么落地实施
• design.md：复杂需求才需要补充

建议命名方式采用动词 + 能力，例如：

• add-email-login
• improve-report-export
• fix-order-status-filter

这种命名方式更便于团队理解变更意图和后续归档管理。

如何写 spec

团队内部写 spec 时，不要写成产品长文，也不要只写一句空泛目标，而应拆成 Requirement 和 Scenario。

建议统一遵循：

• 一个 Requirement 描述一个能力
• 每个 Requirement 至少包含一个成功场景
• 复杂需求要补失败场景和边界场景
• 任何会影响实现与验收的规则都要写入 spec

最小 spec 示例

## ADDED Requirements ### Requirement: Email Login 系统 SHALL 支持用户通过邮箱和密码登录。 #### Scenario: Login succeeds with valid credentials - GIVEN 用户已注册 - AND 输入了正确的邮箱和密码 - WHEN 用户提交登录请求 - THEN 系统返回登录成功结果 - AND 返回用户信息和 token #### Scenario: Login fails with wrong password - GIVEN 用户已注册 - AND 输入了错误密码 - WHEN 用户提交登录请求 - THEN 系统返回认证失败结果

这种写法比“支持邮箱登录”更适合驱动开发和测试，因为它明确了输入条件和预期结果。

相关概念

• Given：前提是什么
• When：发生了什么动作
• Then：预期结果是什么
• And：补充同一类条件或结果
• But：补充例外或相反情况

它本质上是在帮你把一个需求写成“在什么情况下，做了什么事，系统应该怎样表现”的结构。

如何区分 spec 和 design

团队在使用 OpenSpec 时，最常见的问题之一，就是把业务规则和技术实现混写在同一个文件里。

可以用下面这个判断标准：

• 如果某条内容改变后，用户感知到系统行为变了，应写进 spec。
• 如果某条内容改变后，用户无感，只是工程实现方式变了，更适合写进 design。

例如：

• “超过 3 天需要二级审批”应写进 spec，因为它影响业务行为。
• “审批链通过规则引擎实现”更适合写进 design，因为它属于实现方案。

如何在简单项目中简化使用

对于简单项目或个人项目，不必完整采用所有工件，可以只保留最小必要结构，以降低文档成本。

推荐最小版本：

openspec/ ├── project.md ├── specs/ │ └── app.md └── changes/ └── <change-id>/ ├── proposal.md └── tasks.md

在这种模式下：

• project.md写项目背景和基本约束
• proposal.md兼顾目标、规则和验收条件
• tasks.md驱动实现
• 只有在需求变复杂时，再补充独立spec.md或design.md

日常协作要求

团队在日常协作中，建议把 OpenSpec 放在“需求评审”和“开始开发”之间，先评审 proposal 和 spec，再允许进入编码。

协作建议如下：

• 产品或需求方补充目标、范围和业务规则
• 开发补充 design 和 tasks，并按任务实现
• 测试根据 spec 的 Scenario 生成验收用例
• AI 工具围绕 openspec 文件工作，不直接绕开规范改代码

归档要求

变更完成并通过验证后，必须归档，将本次 change 中已经确认生效的规则合并回主 specs，保持主规范与真实系统一致。

如果不做归档，团队很容易出现以下问题：

• 主 specs 过期
• 后续开发无法准确理解当前系统状态
• AI 基于旧规范生成错误实现

常见错误

团队在使用 OpenSpec 时，最常见的问题包括：

• 只写 proposal，不写 spec，导致需求仍然模糊
• 只写成功路径，不写失败和边界场景
• 把数据库表结构、接口实现等技术细节全部塞进 spec
• 一个 change 混入多个不相关需求，导致评审和归档混乱
• 实现完成后不回写主 specs，导致规范逐渐失效
• 把 OpenSpec 当成额外文档负担，而不是开发前的对齐工具

团队落地建议

初次落地时，不建议一开始要求所有项目和所有需求都完整使用 OpenSpec，更适合先选一个中等复杂需求做试点，跑通完整闭环。

建议采用以下节奏：

• 先建立项目级project.md和AGENTS.md
• 选 1 个真实需求写完整 change
• 让产品、开发、测试共同评审 proposal、spec、tasks
• 严格按 spec 验收，再进行归档
• 试点稳定后，再推广到更多功能和团队协作场景

一句话结论

在通用项目开发中，OpenSpec 最好的用法不是“多写几份文档”，而是把需求、设计、任务和归档明确分层，让团队与 AI 先围绕规范达成一致，再进入编码和交付。

如果你要，我下一条可以继续直接输出一个配套的：

• AGENTS.md模板
• project.md模板
• 一个完整的change示例