OpenSpec驱动编程
OpenSpec 通常指用于 AI 编程的开源规格驱动开发（Spec-Driven Development，SDD）工具。它让你先明确“要做什么、如何验收”，再让 AI 根据规格实现代码，而不是直接用一句提示词让 AI 开始修改项目
它不是新的编程语言，也不是代码检查工具，而是规范文档 + 变更管理 + AI 协作流程。通过把需求和实现计划保存在项目文件中，使它们可以被 Git 管理，也能供 AI 和团队成员共同参考
核心工作流：提出变更 → 明确规格 → 制定任务 → 实现与验证 → 归档并更新规格
例如，给登录功能增加短信验证码：
- 变更提案（Proposal）：为什么增加验证码，影响哪些模块
- 规格（Spec）：有效期、重发限制、错误处理等行为
- 设计与任务（Design & Task）：接口、存储方案、前后端修改清单
- 实现与验证：AI 按任务修改代码，执行测试
- 归档（Archive）：完成变更，将新行为并入项目规格
规格中的行为可以写成：
### Requirement: 验证码有效期 系统必须在验证码发出 5 分钟后拒绝该验证码。 #### Scenario: 验证码已过期 注：Scenario是情景的意思 - WHEN 用户提交超过有效期的验证码 - THEN 系统拒绝登录 - AND 返回“验证码已过期”
这种写法比输入一句话“做好验证码登录”更容易执行和验收。
典型结构如下，具体文件会随版本和工作流变化：
openspec/ ├── specs/ # 当前系统行为的规格。系统的当前真相，归档时由变更的 Delta 语义合并而来，一般不手改。 └── changes/ # 提案中，进行中 ├── add-sms-login/ # 一个正在进行的变更
│ ├── .openspec.yaml # 变更元数据（id/schema/状态），CLI 自动管理 │ ├── proposal.md # 变更目的、范围和影响 │ ├── design.md # 技术设计 │ ├── tasks.md # 实现任务 │ └── specs/ # 本次变更涉及的规格增量（Delta） └── archive/ # 已完成、可追溯的变更
环境搭建和安装
要求安装Node.js ≥ 20.19.0，下载地址：https://nodejs.org/en/download/current
安装好后执行node --version看能否输出node.js的版本号
安装官方已经发布到npm源上的openspec最新版本
npm install -g @fission-ai/openspec@latest // 卸载：npm uninstall -g @fission-ai/openspec
安装好后，重新开一个命令行窗口，执行openspec --version（输出1.13.1）或openspec --help，看看是否会报错
执行where openspec就可以看到openspec已经被安装到如下位置：
C:\Users\Administrator\AppData\Roaming\npm\openspec
C:\Users\Administrator\AppData\Roaming\npm\openspec.cmd
在项目中初始化openspec
进入项目的根目录F:/UE4Test1
openspec init --language zh-CN --tools codebuddy // 输出如下内容
▌ OpenSpec structure created √ Setup complete for CodeBuddy Code (CLI) OpenSpec Setup Complete Created: CodeBuddy Code (CLI) 6 skills and 6 commands in .codebuddy/ Config: openspec/config.yaml (schema: spec-driven) Getting started: Start your first change: /opsx:propose "your idea" Note: 6 more workflows are available (new, continue, ff, bulk-archive, verify, onboard). Add them with `openspec config profile`. Learn more: https://github.com/Fission-AI/OpenSpec Feedback: https://github.com/Fission-AI/OpenSpec/issues
会在项目中创建openspec相关的skills和commands，同时创建出openspec的标准工作目录
--language zh-CN，用该中文撰写OpenSpec输出的文档（artifacts），会把语言写入项目openspec/config.yaml的context中
Language: zh-CN All artifacts must be written in zh-CN. Keep OpenSpec structural headings and SHALL/MUST keywords in English.
若改用其他语言，可直接编辑 openspec/config.yaml 的 context，或重新执行 openspec init --language <code>
若想让所有项目默认中文，可执行 openspec config set language zh-CN（全局配置，当前未改）
| 语言 | 可写值 |
|---|---|
| 简体中文 | zh-CN、zh、Chinese、中文、简体中文 |
| 繁体中文 | zh-TW、zh-HK、繁體中文 |
| 英语 | en、en-US、English |
| 日语 | ja、Japanese、日本語 |
| 韩语 | ko、Korean、한국어 |
| 法语 | fr、French |
| 德语 | de、German |
| 西班牙语 | es、Spanish |
| 俄语 | ru、Russian |
--tools codebuddy会生成使用profile: core生成6个核心workflow
在 .codebuddy/ 下生成 6 个 skills 和 6 个 opsx:* 命令（CodeBuddy 专用）【'propose', 'explore', 'apply', 'update', 'sync', 'archive'】
openspec共有 12 个 workflow（ALL_WORKFLOWS 还含 new、continue、ff、bulk-archive、verify、onboard）
当前已启用：core profile（6 个）
| workflow | 生成的 skill | 命令 | 作用 | 产出 |
|---|---|---|---|---|
explore（先理解再动手） |
openspec-explore |
/opsx:explore |
/openspec:explore [探索问题] 把"AI 的猜测"变成"AI 的实际观察"，后面的 proposal 建立在真实代码结构上，而不是想象上
例如在存量项目上，AI 不了解当前项目架构就生成提案，会产出一份通用模板式的方案 —— 看起来合理，但和实际代码完全对不上 然后在 apply 阶段不断纠偏，纠偏消耗的上下文比重写还多
一般在如下情况下使用： ① 存量代码库中不熟的模块 ② 改动涉及多个子系统 ③ 不确定该改哪里 ④ 技术方案有分歧时
示例：/openspec:explore 我要给武器增加后坐力机制，但不确定当前武器系统是如何设计的。先读 src/weapon/、src/engine/ 和入口文件，告诉我现状。 |
探索的价值主要在于把相关的上下文加载进当前会话 如果结论重要（比如那张方案对比表），可在后续propose阶段，指明将其写入 design.md /openspec:propose 基于刚才的探索生成提案。
design.md 里必须包含刚才那张方案对比表，并写清：
- 为什么选组件方案
|
propose（固化改什么） |
openspec-propose |
/opsx:propose |
/openspec:propose [需求描述] 生成完整提案（design + specs + tasks），描述需求并拿出可实施方案
示例：/openspec:propose 基于刚才的探索，用组件方案来为武器增加后坐力机制的提案
这一步之后，检查Markdown文件格式合法性，不正确要进行修复 openspec validate --strict // 检查全部md文件格式是否正确合法 openspec validate add-weapon-recoil --strict // 只检查add-weapon-recoil这个变更的md文件格式是否正确合法 然后人工读一遍 proposal.md 和 spec.md，有问题及时调整（在提案阶段改需求成本是最低的）
情况1：细节偏差。例如需求描述基本对，个别数值/条件要改 解决方法：直接手动修改提案的spec.md、proposal.md和design.md，修改完再检查md文件格式 注意不要把 spec 改成了实现细节（例如代码逻辑如何写） ❌ #### Scenario: 后坐力计算 - **WHEN** Tick 被调用 - **THEN** 调用 FMath::Lerp 插值 RecoilOffset ✅ #### Scenario: 停火恢复 - **WHEN** 玩家停止射击超过 0.3 秒 - **THEN** 准心以每秒 20 度回归原位
情况2：结构性问题。例如要改的地方很多，tasks.md要重拆 解决方法：让AI来改 ❌ 这个提案不太好，重新生成一下 ❌ 后坐力那块写得不对，改改 ✅ 修改 add-weapon-recoil 提案，有三个问题： 1. spec.md 缺少"停火恢复"的行为。补一个 Requirement， 覆盖：停火 0.3 秒后开始恢复、恢复速度 20度/秒、 恢复中再次射击从当前值继续累积 2. tasks.md 第 2 节粒度太粗，"实现后坐力系统"要拆成 至少 4 条可独立验证的子任务 3. proposal.md 缺 Out of Scope。明确写出本次不做： 后坐力的视觉表现（镜头抖动/准心动画）、 不同武器的差异化曲线
可以手动和AI混合修改（手动改确定的部分） 我已经手动调整了 spec.md 的数值，并删掉了弹道可视化的需求。 现在： 1. 读一遍更新后的 spec.md 2. 据此重新生成 tasks.md，去掉弹道可视化相关任务 3. 在 proposal.md 的 Out of Scope 里补上"弹道可视化"
情况3：方向性错误。例如AI完全理解错了需求，方案建立在错误的代码认知上，改动量超过一半 解决方法：删掉提案rmdir /s /q openspec\changes\add-weapon-recoil，重新explore并发起提案
把提案改动提交到git仓库 git add openspec/ git commit -m "docs: 武器后坐力提案（已调整数值和范围）" 好处： |
openspec/changes/add-weapon-recoil/ ├── specs/weapon/spec.md // 行为增量（delta） ├── tasks.md // 可勾选的步骤 └── design.md // 技术决策（可选） |
apply（按规范写代码） |
openspec-apply-change |
/opsx:apply |
/openspec:apply add-weapon-recoil
AI 会按如下步骤执行： ① 读 changes/add-login-rate-limit/ 整个目录
为什么勾选框重要，是为了记录进度状态。 例如：会话断了、电脑重启了、隔了三天回来，只要说：/openspec:apply add-weapon-recoil 继续
建议分批apply，有如下好处： ① 一次性会生成多个文件，review 成本极高
/openspec:apply add-weapon-recoil 先只做第 1 节 完成后，执行验证！例如：通过编译，执行Automation自动化测试（用AI辅助搭建好这些工作流） 验证不成功，则继续改；验证没问题，则可以将这部分成果提交到git仓库 git commit -m "feat: 限流核心实现" // 提交git仓库
/openspec:apply add-weapon-recoil 继续做第 2、3 节 。。。 。。。 |
|
update |
openspec-update-change |
/opsx:update |
修订已有规划产物并保持互相一致（注意：刷新生成文件请跑 openspec update 命令本身） |
|
sync |
openspec-sync-specs |
/opsx:sync |
把 delta specs 同步回主 specs，不归档 change | |
archive（归档） |
openspec-archive-change |
/opsx:archive |
实施完成后归档change /openspec archive add-weapon-recoil
行为增量（delta）的spec.md会合并进主规范文档 openspec/specs/weapon/spec.md（记录项目的当前真相） 并把openspec/changes/add-weapon-recoil/目录移到 openspec/changes/archive/2026-09-21-add-weapon-recoil/ 合并后再校验一次Markdown格式，并将归档提交到git仓库 git add . && git commit -m "chore: 归档 add-weapon-recoil"
|
这些workflow分为两个独立工作路径：
【生命周期】一个变更从生到死，AI 主导 explore → propose → apply → archive （可选） （必需） （必需） （必需） 【维护操作】与变更无关，随时执行，CLI 确定性操作 update / sync
| workflow | 谁执行 | 频率 | 本质 |
|---|---|---|---|
| explore | AI | 按需 | 读代码，产出理解 |
| propose | AI | 每个变更一次 | 写规范 |
| apply | AI | 每个变更一次 | 写代码 |
| archive | CLI + AI | 每个变更一次 | 合并 + 压缩 |
| update | CLI | 升级工具时 | 刷新 AI 指令文件 |
| sync | CLI | 按需 | 对齐状态 |
额外 6 个：默认未安装
| # | workflow | 生成的 skill | 命令 | 作用 |
|---|---|---|---|---|
| 7 | new |
openspec-new-change |
/opsx:new |
用实验式 artifact 工作流逐步创建 change（OPSX 单件模式，一次做一个产物） |
| 8 | continue |
openspec-continue-change |
/opsx:continue |
创建下一个 artifact，逐步推进 change（配合 new 使用） |
| 9 | ff |
openspec-ff-change |
/opsx:ff |
Fast-forward：一次性生成实施所需的全部 artifacts |
| 10 | bulk-archive |
openspec-bulk-archive-change |
/opsx:bulk-archive |
批量归档多个已完成的 change（"archive all"） |
| 11 | verify |
openspec-verify-change |
/opsx:verify |
归档前校验实现与 change 产物是否一致、完整 |
| 12 | onboard |
openspec-onboard |
/opsx:onboard |
引导式教学：带讲解走一遍完整工作流，并做真实代码改动 |
启用全部 12 个workflow
openspec config profile # 交互式勾选 workflow（可多选）
openspec update # 按新 profile 重新生成 skills/命令，会保留config.yaml语言设置启用后 .codebuddy/skills/ 会有 12 个目录、.codebuddy/commands/opsx/ 会有 12 个 .md
codebuddy下可以直接使用生成的这6个Commands 注：通过/opsx:xxx来指定对应的Command
codebuddy下可以直接使用生成的这6个Skills 注：通过/openspec-xxx来指定对应的Skill
openspec/config.yaml
项目级别的全局配置，openspec会始终载入里面的内容作为上下文，尽量保证简短准确
具体内容包括：
schema: —— 【工作流】默认会使用spec-driven缺省工作流
context: —— 【项目上下文】注入到每一次 AI 提示中的 <context> 块（使用语言、技术栈、测试方式、向后兼容要求等）
rules: —— 【按产物的规则】，可选，只对匹配产物生效（如 proposal: 下的规则，只在生成 proposal 时注入）
operations.apply/archive.guidance —— 可选，建议性操作指引，不约束产物内容
schema（工作流）
openspec/config.yaml文件的起始处记录了当前项目使用的schema（工作流）
schema: spec-driven
按 project → user → package 三级查找同名 schema，前者遮蔽后者
| 级别 | 路径 | 用途 |
|---|---|---|
| project | <项目根>/openspec/schemas/<name>/ |
随代码入库，团队共享 |
| user | 全局数据目录%LOCALAPPDATA%\openspec下的 schemas/<name>/ |
本机跨项目，路径依平台而定 |
| package | ...\node_modules\@fission-ai\openspec\schemas\spec-driven |
内置，只读，升级会被覆盖 |
执行openspec schemas命令，会输出如下信息：
Available schemas:
spec-driven
Default OpenSpec workflow - proposal → specs → design → tasks
Artifacts: proposal → specs → design → tasks // 制品：提出需求案 -> 生成需求案 -> 技术设计案 -> AI执行任务流
注：缺省schema（spec-driven）所在目录C:\Users\Administrator\AppData\Roaming\npm\node_modules\@fission-ai\openspec\schemas\spec-driven
openspec/project.md
project.md并非openspec规范约定文件，因此需要在 config.yaml 里加了一行显式指针，让二者接上
在CodeBuddy IDE中，输入如下语句来告诉Agent来帮忙完善项目上下文信息
为opensepc补充项目介绍（引擎用是上级目录的UnrealEngine），技术栈，编码规范，整体架构和约束等信息，写到单独的project.md文件中
openspec/config.yaml的context中就会添加如下内容：
context: |
Language: zh-CN
All artifacts must be written in zh-CN.
Keep OpenSpec structural headings and SHALL/MUST keywords in English.
Project: FPSTest, a Unreal Engine first-person gameplay sample.
Engine source lives in ../UnrealEngine; do not modify engine code.
Project conventions (tech stack, code style, architecture, constraints) SHALL be read from openspec/project.md before writing any artifact.
并生成单独的openspec/project.md，避免将体量大的规范（几百行）直接放到openspec/config.yaml中
注意：建议每次开始需求前或定期执行下 “阅读 openspec/project.md文件，并填写项目详情、技术栈、相关规范等信息。”
因为中间如果有代码变更或者使用vibe coding进行一些修复，但是没有同步更新文档，会导致这个project.md落后于代码
常见问题
| 问题 | 原因 | 处理 |
|---|---|---|
| AI 改了 tasks 之外的文件 | proposal 没写 Out of Scope | 补上，重开会话 |
| AI 说"任务已完成"但代码不对 | 任务粒度太粗 | 拆细任务重来 |
| 实施中发现规范有误 | 提案阶段没想清楚 | 停下改 spec，别在代码里将就 |
最后一条特别重要：发现规范写错了，正确做法是回去改 spec.md，不是让代码偏离规范。否则 specs/ 会变成谎言 —— 比没有 spec 更糟，因为 AI 会拿它当真。
openspec常用命令
openspec view
OpenSpec Dashboard ════════════════════════════════════════════════════════════ Summary: ● Specifications: 0 specs, 0 requirements ● Active Changes: 0 in progress ● Completed Changes: 0 ════════════════════════════════════════════════════════════ Use openspec list --changes or openspec list --specs for detailed views
openspec list // 查看进行中的变更
Changes: verse-umg-binding-middleware 0/50 tasks 4d ago research-verse-ui-binding 0/26 tasks 4d ago
openspec list --specs // 查看所有规范
Specs: combat-target-range requirements 7 server-selection requirements 9 ui-diagnostics requirements 4 ui-panel-hierarchy requirements 8 verse-actor-system requirements 7 verse-input-movement requirements 6
浙公网安备 33010602011771号