常见问题解答
针对人们最常提出的问题的快速解答。如果你的问题实际上是"某个东西坏了"之类的问题，故障排除是更合适的页面。如果你想查找术语定义，请参阅术语表。
基础问题
用一句话描述 OpenSpec 是什么？
它是一个轻量层，让你和你的 AI 编码助手在编写任何代码之前，先以书面形式就构建内容达成一致。
为什么我需要这个？
因为 AI 助手即使犯错时也表现得非常自信。当需求只存在于聊天线程中时，AI 会用猜测来填补空白，而你直到代码写完之后才会发现。OpenSpec 将达成一致的时间提前，此时修正错误的成本很低。完整论述请参阅核心概念速览。
我必须对所有事情都使用它吗？
不必。在需要达成一致的地方使用它，也就是大多数非琐碎的工作。对于单个字符的拼写错误修复，这种流程可能不值得，这完全没问题。
我能把它用在大型现有代码库上吗，还是只能用于新项目？
现有代码库正是它的主要应用场景。OpenSpec 以现有代码库为先：你不必预先记录整个应用。你只需为每次变更所触及的部分编写规格，随着时间推移，你的规格会围绕你实际所做的工作逐渐充实。有一份专门的指南：在现有项目中使用 OpenSpec。
它是否绑定某个特定的 AI 工具？
不是。OpenSpec 支持 30 多种助手，包括 Claude Code、Cursor、Devin Desktop、GitHub Copilot、Gemini CLI、Codex 等。完整列表和各工具的详细信息请参阅支持的工具。
运行命令
我在哪里输入 /opsx:propose？
在 AI 助手的聊天窗口中输入，而不是在你的终端里。这是最常见的混淆点，因此它有一个专门的页面：命令如何工作。简短版本：openspec ... 在终端中运行，/opsx:... 在聊天中运行。
如何"启动交互模式"？
没有需要单独启动的模式。你像平常一样打开 AI 助手，然后在聊天窗口中输入一个斜杠命令。斜杠命令就是你"进入"OpenSpec 的方式。（唯一真正具备终端交互特性的功能是 openspec view，这是一个用于浏览规格和变更的面板。）完整解释请参阅命令如何工作。
我输入了斜杠命令但没有反应。为什么？
最可能的原因是你在终端而不是 AI 聊天窗口中输入了命令，你使用的拼写方式你的工具未识别，或者命令尚未安装。如果文件缺失——或者你从未设置过该工具——请运行 openspec init；openspec update 只会刷新已存在的文件。然后重启你的助手，并使用"开始使用"部分打印出的形式——请参阅如何调用。故障排除中有完整的检查清单。
为什么在一个工具中是 /opsx:propose 而在另一个工具中是 /opsx-propose？
每个 AI 工具呈现自定义命令的方式略有不同，OpenSpec 会按照你的工具加载其所写文件的方式来拼写这些命令。一个名为 opsx-propose.md 的命令文件被输入为 /opsx-propose；一个放在 commands/opsx/ 下的命令文件被输入为 /opsx:propose。使用技能而非命令的工具则使用技能名称——Codex 需要 $openspec-propose，Kimi Code 需要 /skill:openspec-propose。openspec init 的"开始使用"行已经为你选择的工具打印了正确的形式；完整表格请参阅如何调用。
技能和命令有什么区别？
两者都是 OpenSpec 写入的文件，让助手能够运行工作流。技能（.../skills/openspec-*/SKILL.md）是较新的跨工具标准；命令（.../commands/opsx-*）是较旧的各工具特定斜杠文件。你不需要选择。你只需输入斜杠命令，OpenSpec 会安装你的工具所使用的那一种。
工作流程
如果我不确定要构建什么，应该从哪里开始？
从 /opsx:explore 开始。它是一个没有风险的思考伙伴，会读取你的代码库、列出各种方案，并将模糊的问题转化为具体的计划，而且这一切都发生在任何变更或代码存在之前。它在默认方案中，因此始终可用。当计划清晰后，它会移交到 /opsx:propose。这是最值得养成的习惯，因为它能阻止急切的 AI 自信地构建错误的东西。请参阅先探索。
最简单的流程是什么？
/opsx:explore (可选) 然后 /opsx:propose <你想要的内容> 然后 /opsx:apply 然后 /opsx:archive使用 explore 来思考清楚，使用 propose 来起草计划，使用 apply 来构建，使用 archive 来归档。当你已经确切知道自己想要什么时，可以跳过 explore。
/opsx:propose 和 /opsx:new 有什么区别？
/opsx:propose 是默认的一步命令：它同时创建变更并起草所有计划工件。/opsx:new 属于扩展命令集，只搭建一个空变更的框架，让你使用 /opsx:continue 逐一创建工件（或使用 /opsx:ff 一次性全部创建）。除非你想要一步一步地控制，否则使用 propose。请参阅命令。
什么是 core 和 expanded 方案？
方案决定安装哪些斜杠命令。核心方案（默认）提供 propose、explore、apply、update、sync、archive。扩展方案增加了 new、continue、ff、verify、bulk-archive 和 onboard，以提供更精细的控制。使用 openspec config profile 切换，然后使用 openspec update 应用。
我需要运行 /opsx:sync 吗？
通常不需要。Sync 会将变更的增量规格合并到你的主规格中，而 /opsx:archive 会主动提出为你执行此操作。只有当你希望在归档之前合并规格时才手动运行 sync，例如在一个长期运行的变更中。请参阅命令。
我开始之后如何编辑提案、规格或任务？
直接编辑文件即可。每个工件都是 openspec/changes/<name>/ 下的纯 Markdown 文件，没有锁定阶段或特殊编辑模式。你可以手动修改，或者让 AI 帮你修改（例如"更新设计以使用队列"），然后继续。AI 始终基于当前的文件内容工作。完整指南：编辑与迭代变更。
在实现了一部分之后，我能回去修改计划吗？
可以，任何时候都可以。工作流是灵活的，因此审查和编辑并不是你会被锁定的阶段。编辑工件，然后继续。如果你想要对代码是否仍然符合计划进行结构化检查，可以运行 /opsx:verify。请参阅编辑与迭代变更。
我手动编辑了代码。如何使其与规格保持一致？
在归档之前将它们重新同步，因为归档会让你的规格成为事实记录。如果代码现在是正确的，请更新增量规格以匹配你实际交付的内容；如果规格是正确的，则继续构建直到代码与之一致。/opsx:verify 会揭示不匹配之处。请参阅编辑与迭代变更。
什么时候应该更新现有变更，什么时候应该开始新变更？
当这是同一项工作的细化时，更新它。当意图发生了根本改变，或者范围膨胀成了不同的工作时，重新开始。在工作流中有一个决策流程图和示例。
如果我的会话上下文耗尽了，或者需求在实现中途发生了变化，怎么办？
这正是规格发挥作用的地方。因为计划保存在文件中（而不仅仅在聊天历史中），你可以清空上下文，开启一个新的 AI 会话，然后用 /opsx:apply 继续；它会读取工件并从第一个未勾选的任务开始恢复。如果需求发生变化，请编辑工件以匹配新的现实并继续。保持干净的上下文窗口也会产生更好的结果；在实现之前清空它。
我应该把 openspec/ 文件夹提交到 git 吗？
应该。你的规格、进行中的变更和归档都是项目历史的一部分。像其他源码一样提交它们。特别是归档，它会成为你的系统为何以当前方式工作的持久记录。
规格与变更
规格和设计中分别放什么？
规格描述可观察的行为：系统做什么、它的输入、输出和错误条件。设计描述你将如何构建它：技术方案、架构决策、文件变更。如果实现可以改变而不改变外部可见行为，那就属于设计，而不是规格。概念有更深入的阐述。
什么是增量规格？
一种只描述变更内容的规格，使用 ADDED、MODIFIED 和 REMOVED 部分，而不是重新陈述整个规格。这是 OpenSpec 干净地处理对现有系统进行修改的方式。请参阅概念。
归档的变更去哪里？
归档到 openspec/changes/archive/YYYY-MM-DD-<name>/，所有变更工件都会保留。该变更会从你的活动列表中移出。明确声明 retire_capabilities: true 的变更，在移除某个能力规格的最后一项需求时，也可以删除该主能力规格。
配置与自定义
我如何告诉 AI 我的技术栈？
把它放在 openspec/config.yaml 的 context: 下。这段文本会被注入到每个计划请求中，因此 AI 始终了解你的技术栈和约定。请参阅自定义。
我可以生成英语以外的其他语言的规格吗？
可以。在你的配置的 context: 中添加一条语言指示。多语言中有几种语言的复制粘贴片段。
我可以修改工作流本身吗？
可以，使用自定义模式。模式定义哪些工件存在以及它们之间如何相互依赖。使用 openspec schema fork spec-driven my-workflow 派生默认模式，然后编辑它。请参阅自定义。
模型、隐私与升级
我应该使用哪个 AI 模型？
OpenSpec 在高推理能力的模型上效果最佳。README 推荐在规划和实现阶段都使用 Codex 5.5 和 Opus 4.7 之类的模型。同时保持你的上下文窗口干净：在实现之前清空它，以获得最佳效果。
OpenSpec 会收集数据吗？
它会收集匿名的使用统计：仅命令名称和版本。不收集参数、路径、内容或个人数据，并且在 CI 环境中会自动关闭。可以通过 export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1 选择退出。
如何升级？
分两步。升级包（npm install -g @fission-ai/openspec@latest），然后在每个项目内运行 openspec update，以刷新生成的技能和命令。
如何卸载 OpenSpec？
没有卸载命令，因为它只是一个全局包加上你项目中的文件。移除该包（npm uninstall -g @fission-ai/openspec），并可选地删除 openspec/ 目录和生成的工具文件。逐步说明（包括哪些可以安全保留）在安装：卸载中。
获取帮助
我在哪里提问题或报告错误？
- Discord： discord.gg/YctCnvvshC
- GitHub Issues： github.com/Fission-AI/OpenSpec/issues
- 从你的终端：
openspec feedback "你 的 消 息 "会为你打开一个 GitHub issue。
这些文档有错误或令人困惑。我该怎么办？
告诉我们，或者修复它。文档 PR 非常欢迎且受到重视。打开一个 issue 或提交一个 pull request。