【Spec Coding】OpenSpec：AI 原生规格驱动开发（SDD）框架

告别靠聊天记录驱动开发的混乱时代用结构化的规格管理让 AI 编程助手更可控、更可靠。前言AI 编程助手如 Claude Code、Cursor 等已经极大地提升了开发效率但一个普遍的问题是需求只存在于聊天记录中。当你和 AI 来回对话几十轮后很难追踪当前到底实现了什么、“为什么要这样设计”。更糟糕的是换一个 AI 会话或换一个工具之前的上下文全部丢失。OpenSpec正是为了解决这个问题而生的——它在你和 AI 之间建立了一层轻量级的规格层让你在写任何代码之前先对齐要构建什么。一、OpenSpec 是什么OpenSpec 是一个AI 原生的规格驱动开发框架核心思路是用结构化的 Markdown 文件管理项目的行为真相而不是靠聊天记录来追踪需求。它提供了一套标准的命令行工具和 AI 斜杠命令覆盖从需求调研、规格定义、代码实现到归档的全生命周期。与传统开发的对比方式需求管理可追踪性AI 协作不用框架散落在聊天记录里几乎为零不可预测GitHub Spec Kit严格阶段门控好但笨重需 Python 环境AWS Kiro锁定 IDE 和模型好仅支持 ClaudeOpenSpecMarkdown 文件管理完善25 工具自由选择二、核心概念2.1 生成文档的目录结构your-project/ ├── openspec/ │ ├── specs/ # 主规格目录系统当前行为的真相来源 │ │ └── domain/ # 按领域组织如 auth/、payments/ │ │ ├── spec.md # 行为规格WHAT WHY │ │ └── design.md # 技术设计HOW可选 │ ├── changes/ # 进行中的变更 │ │ └── change-name/ # 每个变更一个文件夹 │ │ ├── proposal.md # 变更提案为什么做、做什么 │ │ ├── design.md # 技术设计怎么做 │ │ ├── tasks.md # 实现任务清单 │ │ ├── .openspec.yaml # 变更元数据schema、创建日期 │ │ └── specs/ # Delta 规格增量变更 │ │ └── domain/ │ │ └── spec.md │ │ └── archive/ # 已完成的变更存档 │ │ └── YYYY-MM-DD-name/ # 带日期前缀的归档文件夹 │ └── config.yaml # 项目配置文件 │ ├── .claude/skills/ # Claude Code 技能文件如选择了 claude ├── .cursor/skills/ # Cursor 技能文件如选择了 cursor ├── .cursor/commands/ # Cursor OPSX 命令文件 └── ... # 其他 AI 工具配置2.2 Delta SpecOpenSpec 的灵魂Delta Spec 是 OpenSpec 最核心的设计。它用三个标记来描述这次改了什么# Delta for Auth ## ADDED Requirements ### Requirement: Two-Factor Authentication 系统必须要求用户在登录时提供第二因素认证。 #### Scenario: OTP required - GIVEN 一个启用了 2FA 的用户 - WHEN 用户提交了正确的用户名和密码 - THEN 系统应展示 OTP 验证页面 ## MODIFIED Requirements ### Requirement: Session Timeout 系统应在 30 分钟无操作后使会话过期。 之前60 分钟 ## REMOVED Requirements ### Requirement: Remember Me 被 2FA 功能取代已弃用Archive 时发生了什么当你执行/opsx:archive时ADDED的需求追加到主规格文件MODIFIED的需求替换原有版本REMOVED的需求从主规格中删除整个 change 目录移入openspec/changes/archive/作为审计历史这意味着你的openspec/specs/始终是项目当前行为的唯一真相来源。三、安装与初始化3.1 安装 CLInpminstall-gfission-ai/openspeclatest3.2 初始化项目cdyour-project openspec initopenspec init会自动检测你已安装的 AI 工具Claude Code、Cursor、Windsurf 等 25 工具并生成对应的斜杠命令配置文件。3.3 验证安装openspec--versionopenspec list# 查看当前活跃的变更此时应为空四、完整开发流程OpenSpec 默认使用Core Profile核心流程只有三步/opsx:propose ──► /opsx:apply ──► /opsx:archive4.1 第一步提出变更Propose当你要开发一个新功能时只需在 AI 助手以 Claude Code 为例中输入/opsx:propose add-user-loginAI 会自动创建openspec/changes/add-user-login/目录并生成四个标准产物文件内容作用proposal.md为什么要做这个功能、影响范围对齐动机specs/用 ADDED/MODIFIED/REMOVED 标记的 Delta Specs定义行为design.md技术方案、架构决策指导实现tasks.md分步骤的实现任务清单带 checkbox跟踪进度这一步的关键价值在于在写任何代码之前你和 AI 先就要构建什么达成共识。4.2 第二步实现Apply确认 proposal 和 specs 没问题后直接/opsx:applyAI 会按照tasks.md中的清单逐项实现代码边做边打勾✓ 1.1 创建用户模型 User model ✓ 1.2 实现密码哈希存储 ✓ 1.3 添加 JWT token 生成逻辑 ✓ 2.1 创建 /api/login 路由 ✓ 2.2 实现登录表单校验 ✓ 2.3 添加单元测试 ... 全部任务完成4.3 第三步归档Archive功能开发完成、测试通过后/opsx:archiveAI 会自动将 Delta Specs 合并进主规格库并将 change 移入归档目录Archiving add-user-login... ✓ Merged specs into openspec/specs/auth/spec.md ✓ Moved to openspec/changes/archive/2025-05-15-add-user-login/ Done! Ready for the next feature.此时你的主规格文件已经包含了最新的需求定义随时可以开始下一个功能。五、需求不明确时先 Explore如果你还不确定具体要做什么例如性能优化、架构重构、Bug 排查在 propose 之前先用/opsx:exploreAI 会帮你分析代码库、调研方案再决定怎么做。例如You: /opsx:explore AI: 你想探索什么 You: 我想提升页面加载性能但不确定瓶颈在哪。 AI: 让我分析一下... [分析 bundle 大小、检查慢查询、审查组件渲染模式] 我发现了三个主要瓶颈 1. 未优化的大图片占比最高 2. ProductList 中的同步数据获取 3. Context 变化导致的频繁重渲染 你想先解决哪个 You: 先解决数据获取的问题。 You: /opsx:propose optimize-product-list-fetching六、流程全景图是否是否项目初始化openspec init需求明确/opsx:propose功能名/opsx:explore调研分析AI 生成proposal / specsdesign / tasks人工审查对齐需求/opsx:applyAI 按 tasks 实现代码验证实现可选/opsx:verify/opsx:archive合并 specs归档 change下一个功能项目完成 七、常用命令速查CLI 命令openspec init# 初始化项目自动检测 AI 工具openspec update# 更新 AI 指令文件openspec list# 查看所有活跃变更openspec showname# 查看变更或规格详情openspec validatename# 校验 spec 格式openspec view# 交互式仪表盘openspec archivename# 归档已完成的变更openspec config profile# 管理 profilecore / customAI 斜杠命令命令Profile作用/opsx:proposeCore一步生成所有规划产物/opsx:exploreCore先调研再规划/opsx:applyCore按 tasks.md 实现代码/opsx:archiveCore合并规格、归档变更/opsx:newCustom创建新变更/opsx:continueCustom逐步生成规划产物/opsx:ffCustom跳过审查快速推进/opsx:verifyCustom验证实现与 specs 一致性/opsx:bulk-archiveCustom批量归档/opsx:onboardCustom新成员快速了解项目结构八、进阶功能8.1 动态指令生成OpenSpec 的 AI 不靠硬编码提示词工作。每次调用斜杠命令时AI 会运行时执行openspec status--json# 获取当前变更状态openspec instructions--json# 获取动态组装的操作指令这确保了 AI 的行为随项目状态自适应而不是执行固定脚本。8.2 可定制的 Schema 系统通过openspec/schemas/目录你可以自定义工作流模板。社区也提供第三方 schema bundle类似插件生态可以集成更多工具和工作流。8.3 Profile 切换如果你需要更细粒度的工作流控制openspec config profile# 切换到 custom profileopenspec update# 应用配置生成额外的斜杠命令九、为什么选择 OpenSpec与同类工具的对比vs. GitHub Spec KitSpec Kit 功能全面但偏重有严格的阶段门控、大量 Markdown 模板和 Python 环境依赖。OpenSpec 更轻量允许自由迭代没有刚性阶段锁。vs. AWS KiroKiro 功能强大但锁定了 IDE 和模型仅支持 Claude。OpenSpec 支持 25 AI 工具你可以用自己喜欢的任何工具。vs. 什么都不用没有规格管理的 AI 编程 模糊的提示词 不可预测的结果。OpenSpec 在不增加过多仪式感的前提下带来了可预测性和可追踪性。核心优势先对齐再构建人和 AI 在写代码前就 spec 达成一致结构化管理每个功能独立文件夹proposal / specs / design / tasks 四件套灵活迭代随时修改任何产物没有刚性阶段门控工具自由不锁定 IDE不锁定模型支持 25 AI 工具审计历史每次 archive 都是完整的变更记录十、总结OpenSpec 填补了 AI 辅助编程中需求管理这一关键空白。它不是要增加你的负担而是用轻量级的 Markdown 文件 结构化的 Delta Spec 机制让 AI 编程助手的工作成果更可控、更可追踪。三步上手今天就试试npminstall-gfission-ai/openspeclatestcdyour-project openspec init然后在你的 AI 助手中输入/opsx:propose your-first-feature体验先对齐再构建的开发方式。参考链接OpenSpec GitHub 仓库OpenSpec 官方文档