OpenSpec 文档

OpenSpec 帮助你和 AI 编程助手**在编写代码之前，先就要构建什么达成一致。**你描述变更，AI 起草简短的规格说明和任务清单，你们一起审阅同一份计划，然后再开始实施。这样就不会等到做到一半才发现 AI 理解错了方向。

如果你只读两篇文档，请从这两篇开始：

1. 快速入门: 安装、初始化，并交付你的第一个变更。
2. 命令的工作方式: 了解应该在哪里输入 /opsx:propose（提示：在 AI 聊天中，而不是终端）。这几乎是每个人都会遇到一次的困惑。

第二篇文档比看起来更重要。OpenSpec 包含两部分：在终端运行的命令行工具，以及发送给 AI 助手的斜杠命令。弄清两者的区别，就能避免最常见的困惑。

**最值得先养成的习惯：还不确定要构建什么时，先运行 /opsx:explore。**它是一个没有压力的思考伙伴，会阅读你的代码、权衡方案，并在编写代码之前把模糊的想法整理成具体计划。先探索指南解释了为什么值得这样做。

选择适合你的路径

我刚开始接触 OpenSpec。 从快速入门开始，再浏览核心概念速览。遇到不明白的地方，可以查看常见问题和术语表。

我遇到了问题，但还没有计划。 这是最常见的情况，先探索专门介绍如何处理。使用 /opsx:explore 与 AI 一起梳理问题，再决定下一步。

我有一个规模较大的现有代码库。 你不必先把所有内容都写成文档。在现有项目中使用 OpenSpec介绍了如何从真实的存量代码库着手，而不是试图一次性面面俱到。

我只想先把它跑起来。 按照安装指南安装，然后运行 openspec init；接着阅读命令的工作方式，确保第一次斜杠命令用对地方。你也可以在安装指南中找到 AI 辅助安装提示词，让助手代为设置。

我更喜欢通过示例学习。 示例与操作配方会从头到尾演示真实变更，包括小功能、缺陷修复、重构和探索。

AI 刚起草完计划，接下来该做什么？ 先审阅计划。审查变更介绍如何用两分钟检查并及早发现方向错误；编写良好的规格说明则介绍一份值得批准的计划应包含什么。

我和团队一起工作。 团队中的 OpenSpec介绍变更如何对应到分支和拉取请求，以及队友如何在编写代码前审阅计划。

我正在从旧版工作流迁移。 迁移指南解释了变更内容及其原因，并说明如何安全保留现有工作。

我想让 OpenSpec 适配团队流程。 自定义介绍项目配置、自定义 schema 和共享上下文。

有东西坏了。 故障排除整理了常见问题及其解决方法。

文档导航

从这里开始

文档	内容
快速入门	安装、初始化，并端到端完成第一个变更
先探索	使用 /opsx:explore 在做决定前梳理想法
命令的工作方式	斜杠命令在哪里运行、“交互模式”是什么意思，以及终端和聊天的区别
核心概念速览	一页了解规格说明、变更、差异和归档的整体思路
安装	npm、pnpm、yarn、bun、Nix、交由 AI 助手执行的安装提示词，以及如何确认安装成功

日常使用

文档	内容
工作流	常见模式，以及何时使用各个命令
示例与操作配方	可跟随操作的真实变更完整示例
编写良好的规格说明	如何编写清晰的需求和场景，以及如何控制变更范围
审查变更	在编写代码前，用两分钟检查 AI 起草的计划
团队中的 OpenSpec	变更如何融入分支、拉取请求和代码审查
在现有项目中使用 OpenSpec	如何在规模较大的存量代码库中采用 OpenSpec
编辑和迭代变更	更新产物、回退步骤，以及协调手动编辑
命令	所有 /opsx:* 斜杠命令的参考
CLI	所有 openspec 终端命令的参考

深入理解

文档	内容
概念	详细介绍规格说明、变更、产物、schema 和归档
OPSX 工作流	为什么工作流灵活迭代而不是被阶段锁定，以及架构详解
术语表	集中解释所有术语

按需定制

文档	内容
自定义	项目配置、自定义 schema 和共享上下文
多语言	如何用英语以外的语言生成产物
支持的工具	OpenSpec 集成的 30 多种 AI 工具，以及生成文件的位置
社区展示	使用 OpenSpec 构建的项目和相关资源

需要帮助时

文档	内容
常见问题	常见问题的快速解答
故障排除	针对具体问题的解决方法
迁移指南	从旧版工作流迁移到 OPSX

跨仓库协作（Beta）

文档	内容
Stores 用户指南	工作跨越多个仓库或团队时，如何在独立仓库中规划
智能体契约	智能体使用的机器可读 CLI 接口

三十秒了解 OpenSpec

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 是最值得培养的习惯。

其他帮助渠道

• Discord： 在 discord.gg/YctCnvvshC 提问、交流想法并寻求帮助。
• GitHub Issues： 在 github.com/Fission-AI/OpenSpec/issues 报告缺陷或提交功能请求。
• openspec feedback "your message"： 从终端直接发送反馈（这会打开一个 GitHub issue）。

发现文档有错误、过时或令人困惑的地方？这就是一个缺陷。请提交 issue 或 pull request。改进文档是非常有价值的贡献。