一、核心痛点解析：为何需要OpenSpec？

在实际的AI编程工程实践中，大语言模型并不总能保持我们预期的稳定表现。随着上下文窗口不断膨胀，问题逐渐暴露——一方面，大量无关信息如同垃圾邮件般涌入上下文，模型极易将噪声误判为关键信号，这便是所谓的“上下文污染”；另一方面，在冗长的多轮对话中，模型会像走神的学生一样逐渐偏离最初的需求目标，产生所谓的“注意力偏移”。

单纯依靠扩大大语言模型的参数规模来解决这些工程顽疾，事实已经证明效果并不理想。此刻，OpenSpec所倡导的“规格驱动开发”（Spec-Driven Development）范式，展现出了独特的吸引力。其核心理念其实相当直接：在编写任何一行代码之前，先由人类工程师与AI协同协商，并共同锁定一份机器可读、人类可评审的规格文档。需求是什么、技术方案如何设计、实施步骤有哪些——所有这些都以Markdown文件形式持久化存储在项目之中。这样一来，AI每次开始工作时，不再依赖你的口头描述，而是直接从这份规格文档出发。

同样遵循“先写规范再写代码”原则的开源SDD框架，OpenSpec（github.com/fission-ai/…）展现了极高的工程性价比。无论你使用的是Claude Code、Cursor还是Aider，它都能无缝接入其规格管理层。而且，它对现有代码库的场景支持非常友好。相比之下，Spec Kit虽然擅长新项目从零开始的场景，但OpenSpec显然更适合那些已经投入生产并持续运行的项目。

二、安装与初始化指南

2.1 安装步骤

前置条件非常简单：需要Node.js 20.19.0或更高版本。然后通过一行命令即可完成安装：npm install -g @fission-ai/openspec@latest

2.2 初始化流程

进入你的项目目录，执行命令 openspec init。CLI工具会询问你使用哪些AI工具（如Claude Code、Cursor、Copilot等），随后自动向对应目录写入Skill和斜杠命令文件。如果你使用的是Claude Code，直接选择它即可。

注意：初始化完成后，需要重启IDE才能使配置生效。

之后，你的项目目录中会新增一个 openspec/ 文件夹：

openspec/├── specs/├── changes/└── config.yaml # 项目配置文件

如果初始化时选择了Claude Code，还需要注意Space的选择，用Enter键确认即可。

2.3 配置项目上下文信息

这一步经常被开发者忽略，但它对最终输出质量的影响是决定性的。在 openspec/config.yaml 文件中，你需要告诉AI你的项目是什么样的：

schema: spec-driven
context: |
  项目概述
  XX系统是数据平台的核心调度引擎，负责将不同类型的任务提交到对应类型的执行引擎组件上运行。
  核心功能：
  - 向上：接收平台各应用提交的任务
  - 内部：负责任务的负载均衡与优先级调度
  - 向下：将各种类型的任务真正提交到具体的执行引擎组件上
  技术栈、模块结构、代码规范、测试规范、Git提交规范……
rules:
  proposal:
  - 提案应简洁明了，包含背景、目标、方案概述
  - 方案设计需考虑向后兼容性
  tasks:
  - 每个任务应可独立完成和测试
  - 任务粒度适中，避免过大或过细

context 字段的内容会注入到所有工件的生成过程中——一次配置完毕后，再也不需要在每次对话开头重复交代技术栈了。rules 则针对特定工件类型提出了额外要求。你可以先让AI生成初稿，再根据自己的需求修改。强烈建议将这个规范文件在团队内按照项目维度持续迭代。如果需要更新规范，尽量让Claude自己来完成——AI最能理解AI生成的规范。

三、项目结构与关键产物解读

OpenSpec的项目结构非常清晰，易于理解：

openspec/├── specs/     # 系统当前行为的「源真相」  ← 描述系统现在是什么样的├── changes/   # 每个变更的独立工作目录    ← 记录我们打算改什么├── archive/   # 已完成变更的归档目录      ← 历史记录└── config.yaml # 项目配置文件

Specs（主规格）是系统当前行为的权威描述，回答的是“系统现在是怎么运作的”这个问题。Changes（变更）则记录你正在进行的修改——每个功能、每个Bug修复都独立存放在一个文件夹中，彼此互不干扰。它回答的是“我们打算怎么改”。

每个变更都被组织在独立的文件夹中，包含以下4个工件，它们之间有明确的依赖关系：

proposal.md → specs/ → design.md → tasks.md
为什么做？    做什么？   怎么做？    具体步骤

• proposal.md：描述变更的初衷和影响范围。
• specs/：具体的逻辑规格，通常包含“Scenario”描述，通过具体的输入输出消除模糊性。这里存放的是 Delta Specs（增量规格），仅描述本次变更涉及的行为变化。
• design.md：技术设计方案，包括数据库变更、接口调整等内容。
• tasks.md：原子化的任务清单，作为AI的执行路径图。

这个依赖关系本质上是“使能”关系，而不是“门禁”限制。意思是：有了proposal才能生成specs，有了specs才能生成design——但这只是AI生成工件时所需的输入顺序，并不强制要求你必须按这个顺序来执行。实际上，你完全可以先写design再补充specs，整个流程非常灵活。

Delta Specs与Main Specs的关系：

• openspec/specs/：Main Specs，系统当前的完整行为，是“源真相”
• openspec/changes//specs/：Delta Specs，本次变更带来的行为变化
• 归档时，Delta Specs会自动合并到Main Specs，保持源真相的持续更新

四、核心命令与使用场景详解

OpenSpec分为默认快速模式和扩展全量模式，新安装默认启用快速模式。

4.1 工作流模式选择

快速模式

适合简单的开发场景，仅提供4个核心命令，流程极简：/opsx:propose → /opsx:apply → /opsx:archive

核心命令包括：/opsx:propose（创建变更并规划制品）、/opsx:explore（梳理思路）、/opsx:apply（实现任务）、/opsx:archive（完成变更归档）。新手可以通过onboard命令学习整个工作流程。

扩展模式

适合复杂开发、团队协作场景，包含脚手架、校验、批量操作等专属命令。开启方式很简单：依次执行 openspec config profile 和 openspec update。

# 选择 workflows only
openspec config profile
# 更新，之后需要重启
openspec update

扩展模式额外支持：/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive 等命令。

4.2 核心命令速查表

CLI命令（终端执行）：

4.3 典型使用场景

场景一：已有项目如何接入OpenSpec

项目已经拥有大量代码，但没有任何规格文档，现在想开始使用OpenSpec。

渐进式引入策略：

1. openspec init 初始化项目
2. /opsx:explore 让AI分析现有代码，按模块梳理当前行为
3. 基于探索结果，逐步往 openspec/specs/ 里编写规格（AI可以帮你生成初稿）
4. 后续新功能按正常流程走——每次归档都会让主规格更加完整

经历几个变更归档之后，你会发现 openspec/specs/ 已经积累了一份相当可用的系统行为文档，而这一切都是在正常开发过程中自然生长出来的，没有增加额外负担。

场景二：技术预研阶段的探索式调研

还在评估阶段，希望AI帮你搞清楚某个问题领域，并产出决策依据。

推荐路径：/opsx:explore → （多轮对话）→ （方向确定后再 /opsx:propose 或 /opsx:new）

示例对话：

你: /opsx:explore 我们计划引入消息队列来解耦订单和库存系统，目前在RabbitMQ和Kafka之间纠结，帮我分析各自的优劣势和适用场景。
AI:让我分析一下你的业务场景和技术约束...
当前系统状态: 订单系统日均50万单，峰值QPS约200，库存扣减要求强一致性，团队Java栈为主，运维经验有限。
对比分析: RabbitMQ吞吐量万级/秒，延迟微秒级，消息可靠性强，运维复杂度低；Kafka吞吐量十万级/秒，延迟毫秒级，消息可靠性需配置，运维复杂度高。
建议: 在当前规模下，RabbitMQ更为合适。

explore全程不产生任何文件，对项目零副作用。

场景三：需求方向明确但细节待厘清

你只有一个大方向——“搜索结果不够精准”、“导出功能太慢”——但不确定具体该怎么做。

推荐路径：/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply → /opsx:archive

为什么使用 continue 而不是 ff？因为需求本身就不够清晰，每一步生成的工件都可能需要你手动修正。continue 给你在每个工件节点上审查和调整的机会，避免AI在错误的方向上一路狂奔。

场景四：需求明确，快速落地实现

你已经想好了要做什么、做成什么样，只需要AI来执行。

Core Profile路径（最快）：/opsx:propose → 审查 → /opsx:apply → /opsx:verify → /opsx:archive

Expanded Profile路径（更可控）：/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

这两条路径效果相同，区别只在于 propose 是一步到位，而 new + ff 让你在创建骨架后还有一个“要不要继续”的决策点。

场景五：开发中断后恢复进度

昨天做了一半的功能，今天打开新对话要继续。或者临时切去修了个Bug，现在想切回来。

推荐路径：（新对话）→ /opsx:apply

这是OpenSpec最实用的价值之一。所有规格和任务清单都以文件形式存在项目里，AI直接读取 tasks.md，查看哪些任务已经标记完成、哪些还没完成，然后从断点继续。如果被打断期间你手动修改了部分代码，AI也能感知实际代码状态，智能跳过已完成的部分。

场景六：实现完成后发现问题或遗漏

apply执行完毕，但看了眼代码，感觉哪里不对——有个需求没实现、逻辑有问题，或者你想在原有基础上再加点东西。

处理方式都一样：直接修改工件文件，然后重新执行 /opsx:apply。OpenSpec的任务清单并不是一次性的——tasks.md 你随时可以编辑，apply每次都会检查哪些任务尚未完成。

场景七：多任务并行与切换

手头同时推进好几个功能，需要在它们之间自由切换。

推荐路径：每个变更独立存放在 openspec/changes// 里，完全隔离，切换上下文时只需要在 apply 时指定不同的变更名称。用 openspec list 随时查看活跃变更的状态。全部完成后使用 /opsx:bulk-archive 一次性归档，系统会自动检测冲突。

场景八：系统化Bug修复流程

线上出现了Bug，需要定位根因、设计修复方案、验证修复效果。

推荐路径：/opsx:explore → /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive

Bug修复场景的优势在于：/opsx:explore 能帮你在动手前系统性地梳理问题，避免“修了一个Bug引出了两个新Bug”。修复方案被文档化后，也方便后续复盘和知识沉淀。

场景九：大型重构与架构迁移

需要对现有模块进行大规模重构，或者从旧架构迁移到新架构。

推荐路径：/opsx:explore → /opsx:new → /opsx:continue → ... → 分阶段 /opsx:apply → /opsx:archive

大型重构的注意点：在 specs/ 中明确记录“迁移前行为”和“迁移后行为”，tasks.md 按阶段拆分，每个阶段可独立验证和上线。

场景十：多人协作与代码审查

团队成员各自开发，需要同步进度、合并规格、进行代码审查。

协作模式有两种：同一变更的分工协作（通过 --scope 参数指定）；并行变更后批量合并（使用 /opsx:bulk-archive）。团队协作最佳实践：将 openspec/specs/ 纳入版本控制，作为团队的“共享知识库”；使用 /opsx:sync 定期同步规格，避免归档时才发现冲突。

五、OpenSpec实践：从需求到归档全流程

以“列表查询支持多条件筛选”这个小功能来进行实践演示：

需求场景比较明确，初始化OpenSpec后，直接通过 /opsx:propose 生成所有的规格、设计、任务文档：

OpenSpec产物如下，需求规格、设计方案、任务列表都被存放在新生成的变更文件夹下：

审查了design.md文档，发现其中有些考虑不太恰当，通过 /opsx:explore 进行了深入探索。经过多轮对话交互后，审查了proposal.md、spec.md、design.md，感觉场景和设计方案已经符合要求，开始应用并生成代码：

中途不小心关闭会话后，通过 /opsx:apply 或 /opsx:continue 可以再切回工作状态：

所有任务执行完成后，tasks.md中的事项前会被标记 [x] 表示已完成：

最后通过 /opsx:archive 归档此次需求变更。

推荐的归档流程

/opsx:apply → /opsx:verify → （修复问题）→ /opsx:archive

不要急着归档。verify能帮你发现实现与规格之间的不一致之处。这些问题在归档前修复的成本远低于归档后。归档会提醒但不会阻止任务未全部完成的情况；如果变更还没有sync过，archive会在归档时自动同步；归档是不可逆的操作，所以最好先verify一下。

整个流程跑下来，OpenSpec产出的效果令人满意，生成的文档也有利于开发人员的知识对齐，可以尝试在团队内部推广。

回顾实践过程，有几个值得强调的关键点：

第一，前期沟通清楚至关重要。 在执行 /opsx:propose 或 /opsx:ff 之前，花时间把需求想透彻、把场景列全面，远比匆忙开工后再反复返工高效。如果对需求本身还有疑虑，善用 /opsx:explore 先行探索。

第二，AI Coding不等同于Vibe Thinking。 所谓Vibe Thinking，就是那种“我有个大概想法，让AI自己看着办”的心态——这在简单场景或许能蒙混过关，但在复杂工程中注定会翻车。OpenSpec的工作流设计恰恰是反Vibe的：它要求你在每个节点停下来审查、确认、修正。

第三，AI无法替代一切。 它可以帮你生成初稿、补全细节、执行任务，但它不会主动问“这个边界条件你想怎么处理”。实践中，对 proposal.md、specs/、design.md 都进行了或多或少的审查和修改，这才是OpenSpec发挥价值的真正原因。

第四，返工成本与前期投入的权衡。 虽然OpenSpec允许你在生成代码后发现问题、回退变更、重新调整规格，但这种返工的代价往往被低估。相比之下，在规划阶段多花半小时把规格想清楚，能省下后面数小时的调试和返工时间。

六、最佳实践指南

6.1 项目上下文先行配置

在动手编写第一个变更之前，先把 config.yaml 的 context 字段填好。技术栈、模块划分、代码规范、API风格——这些信息写进去后，后续所有变更的工件生成都能自动继承。这是使用OpenSpec的前置条件，投入十分钟，收益贯穿整个项目周期。

6.2 善用explore避免方向性错误

当你对需求、技术方案或现有代码有疑虑时，先用 /opsx:explore 进行探索。它不产生任何文件，对项目零副作用，却能帮你发现被忽略的边界条件、识别潜在风险点、梳理模块依赖关系、验证方案可行性。

6.3 变更迭代还是新建的判断

6.4 变更职责保持单一

每个变更应该只解决一个问题、只承载一个职责。如果发现变更范围膨胀到“顺便再做点别的”，或者命名时想用 misc-xxx 这种模糊名称，说明职责边界已经模糊，应该拆分成多个独立变更。

6.5 规划阶段选用高推理模型

/opsx:propose、/opsx:ff、/opsx:continue 这些命令需要模型理解需求全貌、做出架构决策，推理能力直接影响工件质量。建议使用Claude Opus、GPT-5.4等高推理模型。/opsx:apply 阶段主要是按任务执行，对推理要求相对较低，可以选用响应更快的模型。

6.6 执行前清空对话历史

执行 /opsx:apply 时，建议开启新对话窗口。让AI从干净的状态读取工件文件，避免探索阶段、讨论阶段的对话噪音干扰代码生成质量。

6.7 归档不仅是清理，更是知识沉淀

每次归档都会将Delta Specs合并到Main Specs，这意味着 openspec/specs/ 会逐渐成为项目的“活文档”。定期审查Main Specs，新成员onboarding时，Main Specs是理解系统行为的最佳入口。

6.8 多变更并行时定期检查状态

手头同时推进多个变更时，养成定期执行 openspec list 的习惯：既能感知每个变更的进度，避免遗忘；也能发现是否有变更已经完成但未归档；还能规划优先级，决定先完成哪个。建议在每天结束工作前执行一次。

七、常见问题与故障排查

7.1 变更管理问题

7.2 团队协作问题

附录 术语表