团队内部 README：在通用项目开发中使用 OpenSpec

适用范围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.mdAGENTS.md可以理解为“给 AI 看的 README”用于告诉不同 AI 助手如何读取项目上下文、如何遵循 OpenSpec 工作流以及何时优先查阅规范文件。适合写入AI 在什么场景下必须先读openspec/项目中如何创建、更新和应用 change输出格式约束、代码修改边界、审查要求project.mdproject.md用于定义整个项目的长期上下文是团队和 AI 的共用背景说明。适合写入项目目标与范围技术栈与架构约束代码风格、命名规范、测试要求、分支策略业务背景、外部依赖、关键限制条件proposal.mdproposal.md说明本次为什么要改、改什么、不改什么是每个变更的起点。适合写入背景问题目标与范围影响面与风险明确不做的事项spec.mdspec.md用于定义系统行为是最接近“正式需求契约”的文件。它关注系统应该做什么、边界条件是什么、如何验收而不是内部实现细节。适合写入Requirement能力条目Scenario成功、失败、边界场景输入输出行为、业务规则、错误条件、验收标准design.mddesign.md解释系统准备如何实现 spec适合承接技术架构、状态流转、模块划分、数据结构、接口策略等内容。适合写入架构决策与方案选择数据模型、接口设计、模块边界风险、权衡和替代方案tasks.mdtasks.md把需求和设计拆成可执行任务便于开发按顺序推进也方便测试和评审跟踪完成度。建议任务具备以下特点粒度清晰可单独完成能映射到 spec 中的 Requirement 或 Scenario有明确完成标准推荐工作流团队推荐统一采用以下流程推进项目开发初始化项目并建立openspec/目录结构。补齐project.md和AGENTS.md形成项目级规则。每个新需求或改动建立一个changes/change-id/目录。在proposal.md中说明目标、范围和影响。在变更spec.md中写清行为和场景。需求复杂时补design.md明确实现方案。在tasks.md中拆任务并执行实现。实现完成后对照 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-loginimprove-report-exportfix-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示例