规范优先的工作流
在编写代码之前先定义需求。
OpenSpec面向 AI 助手的规范驱动开发
一个用于构建和管理 AI 助手项目的轻量级规范。
欢迎。在这里您可以找到关于 OpenSpec 的一切。
OpenSpec 帮助您和您的 AI 编程助手在编写任何代码之前就构建内容达成一致。 您描述变更需求，AI 起草一份简短的规范和任务列表，双方查看同一份计划，然后才开始实际工作。再也不必在项目进行到一半时才发现 AI 构建了错误的内容。
如果只阅读两页文档，请选择以下两页：
第二点的实际影响比看起来更大。OpenSpec 包含两个部分：一个在终端中运行的命令行工具，以及您提供给 AI 助手的斜杠命令。弄清楚二者的区别能帮助您避免最常见的困惑。
最值得首先养成的习惯：当您不确定要构建什么时，从
/opsx:explore开始。 它是一个零风险的思考伙伴，会阅读您的代码、权衡选项，在任何工件或代码存在之前，将模糊的想法打磨成具体的计划。您可以参考 先探索 指南了解详情。
我是全新用户。 从快速开始开始，然后浏览核心概念概览。当遇到不理解的内容时，可以参考常见问题和术语表。
我有问题但没有计划。 这是常见情况，并且有专门的解决方案：先探索。在做出任何承诺之前，使用 /opsx:explore 与 AI 一起思考清楚。
我有一个大型现有代码库。 您不需要为其编写完整文档。在现有项目中使用 OpenSpec 展示了如何在真实的存量代码上开始使用，而无需过度投入。
我只想快速让它工作起来。 安装，运行 openspec init，然后阅读命令如何工作，确保您的第一个斜杠命令在使用正确的位置。或者使用 AI 辅助安装提示 将设置工作交给您的助手。
我喜欢通过示例学习。 示例与配方 页面完整展示了真实变更的流程：一个小功能、一个 bug 修复、一次重构、一次探索。
AI 刚刚起草了一份计划——接下来怎么办？ 阅读它。审查变更 展示了如何用两分钟快速检查，在问题还容易修正时及时发现错误方向；编写优秀的规范 则介绍了值得批准的计划应该具备哪些要素。
我团队协作。 团队中的 OpenSpec 展示了变更如何映射到分支和拉取请求，以及团队成员如何在编写代码之前审查计划。
我从旧工作流迁移过来。 迁移指南 解释了发生了什么变化以及原因，并承诺您现有的工作成果是安全的。
我想根据团队流程定制 OpenSpec。 自定义 涵盖了项目配置、自定义 schema 和共享上下文。
遇到了问题。 故障排除 收集了人们实际遇到的故障及其修复方法。
| 文档 | 内容 |
|---|---|
| 快速开始 | 安装、初始化并完整运行您的第一个变更 |
| 先探索 | 在做出承诺之前使用 /opsx:explore 思考清楚一个想法 |
| 命令如何工作 | 斜杠命令在哪里运行、"交互模式"是什么意思、终端与聊天的区别 |
| 核心概念概览 | 一页掌握全部核心模型：规范、变更、差异、归档 |
| 安装 | npm、pnpm、yarn、bun、Nix、将设置交给 AI 助手的提示，以及如何验证安装成功 |
| 文档 | 内容 |
|---|---|
| 工作流 | 常见模式以及何时使用每个命令 |
| 示例与配方 | 真实变更的完整演练，可直接复制使用 |
| 编写优秀的规范 | 优秀的需求和场景应该是什么样子，以及如何合理控制变更规模 |
| 审查变更 | 在编写任何代码之前对草拟计划进行两分钟快速检查 |
| 团队中的 OpenSpec | 变更如何适配分支、拉取请求和审查 |
| 在现有项目中使用 OpenSpec | 在大型存量代码库中采用 OpenSpec |
| 编辑与迭代变更 | 更新工件、回退、协调手动编辑 |
| 命令 | 每个 /opsx:* 斜杠命令的参考 |
| CLI | 每个 openspec 终端命令的参考 |
| 文档 | 内容 |
|---|---|
| 概念 | 关于规范、变更、工件、schema 和归档的详细说明 |
| OPSX 工作流 | 为什么工作流是灵活的而非阶段锁定的，以及架构深度解析 |
| 术语表 | 所有术语在一处统一定义 |
| 文档 | 内容 |
|---|---|
| 自定义 | 项目配置、自定义 schema、共享上下文 |
| 多语言 | 生成非英语语言的工件 |
| 支持的工具 | OpenSpec 集成的 30+ AI 工具，以及文件存放位置 |
| 社区展示 | 使用 OpenSpec 构建以及为 OpenSpec 构建的项目和资源 |
| 文档 | 内容 |
|---|---|
| 常见问题 | 对用户最常问的问题的快速解答 |
| 故障排除 | 针对具体故障的具体修复方案 |
| 迁移指南 | 从旧工作流迁移到 OPSX |
| 文档 | 内容 |
|---|---|
| Stores：用户指南 | 当工作涉及多个仓库或团队时，在独立仓库中制定计划 |
| Agent 契约 | Agent 驱动的机器可读 CLI 接口 |
1. 安装 npm install -g @fission-ai/openspec@latest
2. 初始化 cd your-project && openspec init
3. 探索 （在您的 AI 聊天中） /opsx:explore ← 可选，但值得养成的好习惯
4. 提议 （在您的 AI 聊天中） /opsx:propose add-dark-mode
5. 构建 （在您的 AI 聊天中） /opsx:apply
6. 归档 （在您的 AI 聊天中） /opsx:archive步骤 1 和 2 在终端中完成。其余步骤在您的 AI 助手的聊天中完成。这个区分是最值得记住的一点，命令如何工作 详细解释了原因。步骤 3 是可选的，但在不确定时从 /opsx:explore 开始是最值得养成的好习惯。
openspec feedback "your message" 可直接从终端发送反馈（会打开一个 GitHub issue）。在文档中发现错误、过时或不清晰的内容？那是一个 bug。请提交 issue 或 PR。文档改进是最有价值的贡献方式之一。