告别“AI 乱改代码”：OpenSpec 小白完全指南
参考资料：
- GitHub: Fission-AI/OpenSpec
- 官方文档: openspec.dev
- 官方工作流文档: docs/workflows.md
让 AI 先跟你“对齐需求”，再乖乖写代码
前言：你是否遇到过这些问题？
用 AI 写代码的时候，你是不是经常遇到这种情况：
- 你只是想加个“深色模式”，结果 AI 把整个页面布局都改了
- 今天写的功能，过两天 AI 就不记得了，又得从头解释
- AI 生成的代码总是“差不多能用”，但总有细节不对
这不是你不行，而是 AI 的问题——它在“猜”你想要什么。
OpenSpec 就是来解决这个问题的。它让 AI 在写代码之前，先跟你“对齐需求”，然后严格按照你们商量好的方案来写代码。
一、OpenSpec 是什么？
一句话解释： OpenSpec 是一个让 AI“按规矩办事”的开发框架，核心理念是 “行动，而非阶段 (Actions, Not Phases)”。
传统工作流会强制你经历“规划 → 实施 → 完成”的固定阶段，且很难回头。但 OpenSpec 不同，它的命令是你可以随时执行的动作，依赖关系只是告诉你“现在可以做什么”，而不是“下一步必须做什么”。这让你能更灵活地工作。
二、两种工作模式：你想怎么使用 OpenSpec？
OpenSpec 提供了两套命令体系，你可以把它们理解为两种“干活方式”。你可以在任何时候通过一条命令切换，不是二选一的死规定。
先看一张对比表，快速了解区别
| 对比维度 | 方式一：快速模式 | 方式二：精细模式 |
|---|---|---|
| 官方名称 | 核心模式 (Core Profile) | 扩展模式 (Expanded Profile) |
| 适合谁 | 想快点把事干完的人 | 想每一步都看清楚再走的人 |
| 命令数量 | 5 个 | 11 个（包含快速模式的命令） |
| 上手难度 | 极低 | 低（只是多了几个命令） |
| 典型场景 | 日常小功能、修 Bug | 复杂功能、不确定的需求、学习阶段 |
| 能否切换 | ✅ 随时可以切换 | ✅ 随时可以切换 |
方式一：快速模式（Core Profile）—— “别废话，直接干”
这是什么： 最简单直接的干活方式。你告诉 AI 要做什么，它自动帮你把规划、实施、归档都搞定。
适合谁：
- 刚接触 OpenSpec，想最快上手
- 需求明确，你知道要做什么
- 追求效率，不想被太多步骤打断
包含的命令（就 5 个，很好记）：
| 命令 | 大白话解释 | 什么时候用 |
|---|---|---|
/opsx:propose |
“我要干个活，帮我出个方案” | 开始一个新功能或修复 |
/opsx:apply |
“方案没问题，开始写代码” | 确认方案后，让 AI 动手 |
/opsx:sync |
“把这次改动记录到主规范里” | 代码写完了，更新项目文档 |
/opsx:archive |
“这个活干完了，归档吧” | 功能完成，整理存档 |
/opsx:explore |
“我不太确定怎么搞，帮我分析下” | 需求模糊时，先调研 |
一个完整的干活流程（快速模式）：
你：/opsx:propose 给登录页面加一个“记住我”的复选框
AI：好的，我创建了一个变更，规划文档如下：
- 为什么做：提升用户体验，减少重复登录
- 怎么做：在登录表单加复选框，用 localStorage 存储
- 具体任务：改前端、改后端 token 过期逻辑
你看可以吗？
你：可以，开始写代码吧
你：/opsx:apply
AI：正在按任务清单写代码...
✓ 修改了 Login.vue，添加了复选框
✓ 修改了 auth.js，支持 remember 参数
✓ 更新了 token 过期时间逻辑
全部完成！
你：/opsx:archive
AI：已归档，下次 AI 就知道你的项目有“记住我”功能了
一句话总结快速模式： 告诉 AI 要做什么 → 确认方案 → 让它写代码 → 完事归档。3 步搞定。
方式二：精细模式（Expanded Profile）—— “慢一点，每个步骤我都要看”
这是什么： 把“规划”这一步拆成了多个小步骤，你可以一步步确认，而不是让 AI 一口气全生成。适合需求不明确、或者你想深度参与每个环节的时候。
适合谁：
- 需求还不太清楚，需要边想边做
- 复杂功能，希望每个文档都仔细审查
- 新手想理解 OpenSpec 的工作逻辑
多出来的命令（快速模式没有的）：
| 命令 | 大白话解释 | 什么时候用 |
|---|---|---|
/opsx:new |
“创建一个空活” | 只创建文件夹，先不生成内容 |
/opsx:continue |
“生成下一个文档” | 一个文档一个文档地推进 |
/opsx:ff |
“一口气把所有文档都生成” | 需求明确，但又想用精细模式 |
/opsx:verify |
“检查一下代码写得对不对” | 写完后，让 AI 自检一遍 |
/opsx:bulk-archive |
“一次性归档多个完成的活” | 同时做了好几个功能，一起归档 |
/opsx:onboard |
“让 AI 先读一遍我的老代码” | 老项目第一次接入 OpenSpec |
一个完整的干活流程（精细模式，逐个确认）：
你：/opsx:new 给文章详情页加一个“点赞”功能
AI：已创建变更文件夹，准备好创建 proposal（方案说明）
你：/opsx:continue
AI：我来写 proposal.md...
- 为什么要做：提升用户互动
- 做成什么样：点击小红心，数字+1，不能重复点赞
- 涉及改动：前端 UI、后端 API、数据库
请确认是否继续？
你：确认，继续
AI：好的，下一步是写 specs（功能规格）...
可以继续输入 /opsx:continue
你：/opsx:continue
AI：specs 已生成，内容是：
- 场景1：用户未点赞时，显示空心❤️
- 场景2：用户点击后，变成实心❤️，数字+1
- 场景3：用户再次点击，没有效果（防止重复）
请确认，或告诉我要修改的地方
你：没问题，继续
AI：接下来是 design.md（技术方案）...
（以此类推，直到全部文档生成）
一个完整的干活流程（精细模式，快速生成全部文档）：
上面那种“一步一确认”适合复杂功能。如果你需求明确，但又想用精细模式的好处（比如后面的 verify 验证功能），可以用 /opsx:ff 一次性生成所有文档：
你：/opsx:new 给文章详情页加一个“点赞”功能
AI：已创建变更文件夹
你：/opsx:ff
AI：已一次性生成全部规划文档：
✓ proposal.md（为什么做、做什么）
✓ specs/（具体场景规格）
✓ design.md（技术方案）
✓ tasks.md（任务清单）
请审查，确认后输入 /opsx:apply 开始实施
一句话总结精细模式： 你可以选择“一步一确认”（/opsx:continue），也可以选择“快速出方案再微调”（/opsx:ff），比快速模式多了验证和批量归档的能力。
如何切换两种模式？
1. 查看当前模式：
openspec config profile
2. 切换模式：
# 进入配置选择
openspec config profile
# 根据提示选择 core（快速模式）或 expanded（精细模式）
# 更新配置
openspec update
新手建议： 从快速模式开始，先用 /opsx:propose → /opsx:apply → /opsx:archive 跑通一个简单功能。等熟悉了，再考虑切换到精细模式，体验更多命令。
两种模式的关系图解
┌─────────────────────────────────────────────────────────────┐
│ OpenSpec │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
│ │ 快速模式 (core) │ │ 精细模式 (expanded) │ │
│ │ │ │ │ │
│ │ 5 个命令： │ │ 11 个命令： │ │
│ │ • /opsx:propose │ │ • 包含快速模式全部命令 │ │
│ │ • /opsx:apply │ │ • + /opsx:new │ │
│ │ • /opsx:sync │ │ • + /opsx:continue │ │
│ │ • /opsx:archive │ │ • + /opsx:ff │ │
│ │ • /opsx:explore │ │ • + /opsx:verify │ │
│ │ │ │ • + /opsx:bulk-archive │ │
│ │ │ │ • + /opsx:onboard │ │
│ └─────────────────────┘ └─────────────────────────┘ │
│ │
│ ⬅ 更简单、更快 更灵活、更可控 ➡ │
└─────────────────────────────────────────────────────────────┘
我该选哪个？决策指南
| 你的情况 | 推荐模式 | 理由 |
|---|---|---|
| 第一次用 OpenSpec | 快速模式 | 命令少，不容易晕 |
| 加一个小按钮、修一个小 Bug | 快速模式 | 杀鸡不用牛刀 |
| 做一个复杂功能（如支付、聊天） | 精细模式 | 需要仔细审查每个环节 |
| 需求还没想清楚 | 精细模式 | 用 /opsx:continue 边想边做 |
| 老项目接入 | 精细模式 | 需要 /opsx:onboard 命令 |
| 想同时做多个功能 | 精细模式 | 需要 /opsx:bulk-archive |
| 纯好奇，想看看完整功能 | 精细模式 | 体验所有命令 |
核心建议： 不用纠结，从快速模式开始就行。哪天发现需要某个精细模式才有的命令（比如想用 /opsx:verify 检查代码质量），再切换过去。两种模式可以随时来回切换，不影响已有的变更。
三、安装与初始化
环境要求
- Node.js 20.19.0 或更高版本
安装步骤
# 1. 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest
# 2. 进入你的项目目录
cd your-project
# 3. 初始化 OpenSpec
openspec init
初始化完成后，你的项目里会多出一个 openspec/ 文件夹，结构如下：
openspec/
├── specs/ # 已实现功能的“真相之源”（主规范）
├── changes/ # 进行中的变更
│ ├── [变更名称]/ # 每个变更一个独立文件夹
│ └── archive/ # 已完成的变更归档处
└── AGENTS.md # AI 助手的工作指引
四、所有命令详解（官方完整列表）
一）斜杠命令（在 Claude Code / Cursor 等 AI 聊天框输入）
| 命令 | 用途 | 适用模式 | 说明 |
|---|---|---|---|
/opsx:propose |
创建变更+规划文档 | 核心/扩展 | 核心模式的主命令，一步创建提案 |
/opsx:explore |
探索性思考/调研 | 核心/扩展 | 需求不清晰时，让AI帮你调研分析 |
/opsx:new |
创建变更脚手架 | 扩展 | 仅创建变更文件夹，不生成文档 |
/opsx:continue |
逐步创建下一个文档 | 扩展 | 每次生成一个缺失的文档（proposal → specs → design → tasks） |
/opsx:ff |
快速生成全部规划文档 | 扩展 | 一次性生成 proposal/specs/design/tasks |
/opsx:apply |
实施任务清单 | 核心/扩展 | 按 tasks.md 逐条写代码 |
/opsx:verify |
验证实施质量 | 扩展 | 检查完成度、正确性、一致性 |
/opsx:sync |
合并增量规范 | 核心/扩展 | 手动将变更中的 specs 同步到主规范 |
/opsx:archive |
归档变更 | 核心/扩展 | 完成变更，移至归档目录 |
/opsx:bulk-archive |
批量归档 | 扩展 | 一次性归档多个已完成变更 |
/opsx:onboard |
为新/老项目生成初始规范 | 扩展 | 扫描代码，反向生成规范文档 |
二）CLI 命令（在终端输入）
| 命令 | 用途 |
|---|---|
openspec init |
初始化 OpenSpec |
openspec list |
列出所有活跃变更 |
openspec list --specs |
列出所有规范 |
openspec show <change-id> |
查看变更详情 |
openspec config profile |
切换工作流模式（core/expanded） |
openspec update |
更新配置（切换模式后执行） |
五、完整工作流模式讲解
OpenSpec 官方文档定义了以下几种典型工作流模式，你可以根据场景选择。
工作流一：快速功能 (Quick Feature)
适用场景： 小型功能、Bug修复、需求明确的任务
流程：
/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive
示例对话：
你：/opsx:new add-logout-button
AI： 已创建 openspec/changes/add-logout-button/
你：/opsx:ff
AI： 正在创建所有规划文档...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
准备实施！
你：/opsx:apply
AI： 正在逐项完成任务...
✓ 在头部添加了退出按钮
✓ 实现了 session 清理
✓ 添加了确认对话框
所有任务完成！
你：/opsx:archive
AI： ✓ 合并规范到主目录
✓ 变更已归档
工作流二：探索性开发 (Exploratory)
适用场景： 性能优化、调试、架构决策、需求不明确
流程：
/opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply
示例对话：
你：/opsx:explore
AI： 你想探索什么方向？
你：我想改善页面加载性能，但不确定瓶颈在哪。
AI： 让我帮你分析...
[分析 bundle 大小、识别慢查询、检查渲染模式]
我发现三个主要瓶颈：
1. 未压缩的大图
2. ProductList 中的同步数据获取
3. Context 变化导致的重复渲染
你想先解决哪个？
你：先解决数据获取问题。
你：/opsx:new optimize-product-list-fetching
AI： 已创建变更。是否创建 proposal？
你：/opsx:continue
AI： 正在基于我们的探索创建 proposal...
[结合调研结果撰写提案]
是否创建 specs/design？
你：/opsx:continue
...
工作流三：并行变更 (Parallel Changes)
适用场景： 多任务并行、紧急打断、团队协作
流程：
# 变更 A：正在实施
/opsx:new add-dark-mode → /opsx:ff → /opsx:apply（进行中）
# 突发打断，切换上下文
/opsx:new fix-login-redirect → /opsx:ff → /opsx:apply → /opsx:archive
# 切换回变更 A
/opsx:apply add-dark-mode
批量归档（当多个变更完成时）：
你：/opsx:bulk-archive
AI： 发现 3 个已完成变更：
- add-dark-mode（任务全部完成）
- fix-login-redirect（任务全部完成）
- update-footer（任务全部完成）
检查规范冲突...
⚠ add-dark-mode 和 update-footer 都修改了 specs/ui/
检查代码库以解决冲突...
两个变更都已实施。将按时间顺序合并。
是否归档全部 3 个变更？
你：是
AI： ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-redirect
✓ 已归档 update-footer
按顺序合并规范：add-dark-mode → update-footer
工作流四：老项目/现有系统接入 (Onboarding)
适用场景： 已有代码库首次接入 OpenSpec
流程：
# 1. 初始化
openspec init
# 2. 生成初始规范
/opsx:onboard
# 3. 此后即可使用上述任一工作流
onboard 命令效果： AI 会扫描现有代码，反向生成 specs/ 目录下的初始规范文档。
六、命令使用决策树（帮你选对命令）
开始
│
├─ 首次使用？ → openspec init
│
├─ 老项目接入？ → /opsx:onboard
│
├─ 需求不清晰？ → /opsx:explore（探索调研）
│
├─ 默认快速模式（core）：
│ └─ /opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive
│
├─ 扩展精细模式（expanded）：
│ │
│ ├─ 开始新功能：
│ │ ├─ /opsx:new <功能名>
│ │ ├─ 需求明确？ → /opsx:ff
│ │ └─ 边走边想？ → /opsx:continue（重复直到文档完整）
│ │
│ ├─ 写代码： → /opsx:apply
│ │
│ ├─ 归档前检查： → /opsx:verify
│ │
│ ├─ 归档单个： → /opsx:archive
│ │
│ └─ 归档多个： → /opsx:bulk-archive
七、何时更新一个变更 vs 创建一个新变更？
应该更新现有变更的情况：
- 相同意图，细化执行方式：方案调整，但目标不变
- 范围收缩：先做 MVP，后续功能以后再加
- 基于学习的修正：发现代码库实际情况与预期不符
- 设计微调：基于实施中的新发现做小改进
应该创建新变更的情况：
- 意图发生根本变化：完全不是原来要做的事了
- 范围爆炸：变成了另一个不同的工作
- 原变更可独立完成：原功能已经可以算“做完了”
- 继续修改会让人困惑：变更记录变得混乱不清
判断示例：
“添加深色模式”
- “还需要支持自定义主题” → 新变更（范围爆炸）
- “系统主题检测比预期复杂” → 更新（相同意图）
- “先上线开关，后续再做偏好设置” → 先归档原变更，再创建新变更
八、最佳实践
1. 保持变更聚焦
一个逻辑工作单元一个变更。不要把“加功能X”和“重构Y”混在一起。
2. 需求不明时先用 /opsx:explore
在投入变更之前，先用探索命令理清思路。
3. 归档前用 /opsx/verify 检查
命令会帮你检查三个维度：
- 完成度：任务都做了吗？场景都覆盖了吗？
- 正确性：实现符合规范意图吗？
- 一致性：代码结构符合设计文档吗？
4. 变更命名要清晰
- ✅ 好：
add-dark-mode，fix-login-redirect，optimize-product-query - ❌ 避免：
feature-1，update，wip
九、常见问题
Q：核心模式和扩展模式怎么选？
A：新手或追求快速开发用核心模式（默认）。需要精细控制每个生成步骤时，切换到扩展模式。
Q：/opsx:propose 和 /opsx:new 有什么区别？
A：
/opsx:propose（核心模式）：创建变更并自动生成 proposal，一步到位/opsx:new（扩展模式）：只创建变更文件夹，需要配合/opsx:ff或/opsx:continue生成文档
Q：/opsx:ff 和 /opsx:continue 有什么区别？
A：
/opsx:ff：一次性生成所有缺失的规划文档，适合需求明确时快速启动/opsx:continue：每次只生成下一个缺失的文档，适合边走边探索
Q：老项目能用吗？
A：可以。使用 /opsx:onboard 命令，AI 会自动扫描现有代码生成初始规范。
Q：多个变更可以并行开发吗？
A：可以。OpenSpec 支持多个 changes/ 文件夹同时存在，用 openspec list 查看所有活跃变更。
十、总结
OpenSpec 不是一个复杂的框架，而是一套灵活的工作习惯——先对齐，再动手。
核心模式（默认）：记住这 4 个命令
| 阶段 | 命令 |
|---|---|
| 开始 | /opsx:propose |
| 写代码 | /opsx:apply |
| 同步规范 | /opsx:sync |
| 收尾 | /opsx:archive |
扩展模式：记住这 5 个命令
| 阶段 | 命令 |
|---|---|
| 开始 | /opsx:new |
| 生成方案（快速） | /opsx:ff |
| 生成方案（逐步） | /opsx:continue |
| 写代码 | /opsx:apply |
| 验证 | /opsx:verify |
| 收尾 | /opsx:archive |
老项目接入，加一步：
| 阶段 | 命令 |
|---|---|
| 首次接入 | /opsx:onboard |
如果你想告别“AI 猜需求、乱改代码”的烦恼，不妨花 5 分钟在你的项目里跑一遍：
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
然后根据你的喜好，在 AI 聊天框里输入：
- 默认模式：
/opsx:propose 你的第一个功能 - 扩展模式：
/opsx:new 你的第一个功能→/opsx:ff
试试看，你会爱上这种“说清楚就能做对”的感觉。
附加问题：
问题一：/opsx:propose 能生成所有文档吗？
答案是：能，但不是默认行为，需要配置。
根据官方文档，/opsx:propose 的行为取决于你的配置：
默认情况（没有额外配置）
/opsx:propose 只生成 proposal.md，不会自动生成 specs/、design.md、tasks.md。
/opsx:propose → 只生成 proposal.md
然后你需要用其他方式补充剩余文档：
- 如果切到精细模式：用
/opsx:continue逐个生成 - 或者手动告诉 AI 继续写
配置后（设置 proposalWorkflow = "full"）
/opsx:propose 会一次性生成全部规划文档（proposal + specs + design + tasks），效果等同于精细模式的 /opsx:ff。
# 如何配置
openspec config set proposalWorkflow full
配置后的效果：
/opsx:propose → ✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
官方文档原文佐证
proposalWorkflow— Set to"full"to generate all planning artifacts (specs, design, tasks) with/opsx:propose. Default is"simple"(proposal only).
所以： 如果你希望 /opsx:propose 一步到位生成全部文档，需要先运行 openspec config set proposalWorkflow full 开启完整模式。
问题二：Core 模式为什么还需要 /opsx:sync？
这是个非常好的观察！你可能会想：既然归档（archive）时也会合并规范，为什么还要单独一个 sync 命令？
核心原因：/opsx:sync 是“手动挡”，/opsx:archive 的合并是“自动挡”
| 命令 | 作用 | 时机 | 是否可选 |
|---|---|---|---|
/opsx:sync |
把变更中的规范合并到主规范目录 | 开发过程中、归档前 | 可选，不强制 |
/opsx:archive |
归档变更，同时也可以合并规范 | 功能完全完成后 | 归档是强制的 |
为什么需要单独的 sync？三个典型场景：
场景 1：开发过程中就想更新主规范
想象你在做一个大功能，可能要几天才能完成。但团队其他成员（或 AI 的其他会话）需要知道最新的规范变化。这时候你可以先用 sync 把已确定的部分同步到主规范，而不必等到全部功能完成。
开发第1天：写完 specs/ → /opsx:sync → 主规范更新了
开发第2天：AI 读取主规范，知道已有这个功能，不会重复造轮子
开发第3天：继续开发，最终 archive
场景 2：你不想自动合并，想手动控制
archive 时合并规范是自动的，但你可能想：
- 先看看合并后的效果
- 手动调整合并方式
- 或者根本不合并（比如这个变更只是重构，不改变功能规范）
这时候你可以：
/opsx:archive --skip-specs # 归档但不合并规范
# 然后手动用 /opsx:sync 在合适的时机合并
场景 3：你用的是“变更驱动”的工作流
有些团队的工作习惯是：先写代码，后补规范。代码上线后，再用 sync 把代码中实际实现的功能“反向同步”到规范中，确保规范文档与线上代码一致。
流程图解
使用 /opsx:sync 的场景：
┌─────────────────────────────────────────────────────────┐
│ │
│ 开发过程中 ──→ /opsx:sync ──→ 主规范更新 ──→ 其他人/AI 可见 │
│ │
└─────────────────────────────────────────────────────────┘
使用 archive 自动合并的场景：
┌─────────────────────────────────────────────────────────┐
│ │
│ 功能完成 ──→ /opsx:archive ──→ 自动合并规范 + 归档变更 │
│ │
└─────────────────────────────────────────────────────────┘
你完全可以只用 archive 的自动合并，不用 sync。
sync 是给你多一个选择。
修正后的快速模式流程
基于以上澄清，快速模式（Core Profile）的完整流程实际上是：
默认配置（proposalWorkflow = “simple”）
/opsx:propose → 只生成 proposal.md
↓
（此时缺少 specs/design/tasks，需要手动让 AI 补充）
↓
/opsx:apply → 实施代码
↓
/opsx:sync → 手动合并规范（可选）
↓
/opsx:archive → 归档（会自动提示是否合并规范）
推荐配置（proposalWorkflow = “full”）
# 先配置一次
openspec config set proposalWorkflow full
配置后：
/opsx:propose → 生成全部文档（proposal/specs/design/tasks）
↓
/opsx:apply → 实施代码
↓
/opsx:archive → 归档（自动合并规范）
这样 /opsx:sync 就变成可选的了，大部分情况下你可以不用它。
给新手的简化建议
忘掉复杂配置，你只需要记住：
-
第一次使用前，运行这一条命令开启“完整提案”模式：
openspec config set proposalWorkflow full -
日常干活只需要 3 个命令：
/opsx:propose “我要做什么” → AI 生成全部方案 /opsx:apply → AI 写代码 /opsx:archive → 完事归档 -
/opsx:sync先不用管，等你需要“开发到一半就想更新规范”时再了解它。
问题三：变更已经创建了，但发现方案需要调整，该怎么办？
这个问题官方文档里确实讲得比较清楚。核心答案是：直接改文件就行，OpenSpec 不像传统流程那样是死板的“阶段”，你随时可以回头修改。
核心原则：行动，不是阶段
OpenSpec 的设计理念是 “行动，而非阶段”——命令是你随时可以做的事，而不是把你卡在某个阶段里。这意味着：
- 你可以在实施过程中回头修改规划
- 你可以在写代码后发现需求理解错了，回去改 specs
- 你可以在任何阶段调整任何文档
更新变更的三种方式
方式一：直接说人话（最简单）
直接在对话里告诉 AI 你要改什么，它会帮你更新对应的文档。
你：等一下，proposal.md 里有个地方要改：深色模式要支持自动跟随系统，不是手动切换
AI：好的，我更新了 proposal.md 和 specs/ 中对应的场景描述。
已经把“用户手动切换”改成了“跟随系统主题偏好”。
这种方式适合小调整，AI 会自动定位并修改正确的文件。
方式二：手动改文件，AI 接着干活（适合你明确知道要改什么）
如果你很清楚要改什么，可以直接去 openspec/changes/<变更名>/ 下修改对应文件：
| 想改什么 | 改哪个文件 |
|---|---|
| 需求范围、功能描述 | proposal.md |
| 技术实现方案 | design.md |
| 任务清单 | tasks.md |
| 功能规格细节 | specs/ 子目录下的 spec.md |
改完后，继续用 /opsx:apply 等命令，AI 会自动读取最新的文件内容继续干活。
方式三：删除后重建（适合推倒重来）
如果变更内容完全跑偏了，还不如重来：
# 1. 直接删除变更文件夹
rm -rf openspec/changes/你的变更名
# 2. 重新创建
/opsx:new 新的变更名
官方建议：什么时候应该“更新”，什么时候应该“重新开始”？
根据官方文档，这是一个常见问题：
✅ 应该更新现有变更的场景：
- 相同意图，调整执行方式：目标没变，只是方法要改
- 范围收缩：先做 MVP，其他功能以后再加
- 基于新发现修正：写着写着发现代码库实际情况跟预期不一样
- 设计微调：实施中发现了更好的实现方式
❌ 应该创建新变更的场景：
- 意图完全变了：不是原来要做的那个事了
- 范围爆炸：从一个“加个按钮”变成了“重构整个页面”
- 原变更可以独立完成：原功能已经算“做完了”，新改动是另一回事
- 继续修改会让人困惑：变更历史变得一团糟，不如重新开始
实际例子
场景：你在做“添加深色模式”功能
情况1：发现系统主题检测比预期复杂
→ 用更新 ✅（目标还是深色模式，只是实现方式要调整）
情况2：把这个功能做完后，又想加“自定义主题色”
→ 新变更 ❌（原功能已可独立上线，自定义主题色是新需求）
情况3：写着写着发现，不如顺便把整个UI组件库升级了
→ 新变更 ❌（范围爆炸了，这是另一个大工程）
一个完整例子：变更过程中修改方案
# 1. 创建变更
/opsx:new add-dark-mode
# 2. 生成方案
/opsx:ff
# 3. AI 开始实施
/opsx:apply
# === 写着写着，发现问题了 ===
你：等一下，我改主意了。深色模式要默认跟随系统，不要手动切换按钮。
AI：好的，我来更新规划文档。
- 已更新 proposal.md：把“手动切换”改成“自动跟随系统”
- 已更新 specs/：场景从“点击按钮切换”改为“监听系统主题变化”
- 已更新 tasks.md：移除“创建切换按钮”任务，增加“监听系统偏好”任务
任务清单已更新，要继续实施吗？
你：继续
AI：继续按新的 tasks.md 实施...
和老版本的区别
注意：OpenSpec v1.0（OPSX）之前，流程是死板的 proposal → apply → archive，不允许中途修改。v1.0 之后改成了灵活的行动驱动模式，你随时可以回头改。 所以你不用担心“是不是已经进入实施阶段就不能改方案了”——没有这回事。
问题四：更改以前的变更（已归档的变更）
这是一个非常好的问题！需要区分两种不同的“更改”场景：
场景区分
| 场景 | 变更状态 | 流程 |
|---|---|---|
| 更改正在进行的变更 | 在 changes/ 中，未归档 |
直接修改文件，或用 /opsx:continue//opsx:ff 重新生成 |
| 更改以前的变更（已归档） | 在 changes/archive/ 中 |
创建新变更，因为归档意味着“已完成并部署” |
核心原则：归档 = 已封存，不要再改
OpenSpec 的设计哲学是：
specs/是已实现功能的“真相之源”，archive/是历史记录，不可变。
当一个变更被归档后：
- 它的规范已经被合并到
specs/主目录 - 它的文件夹被移动到
changes/archive/YYYY-MM-DD-<name>/ - 它代表已经完成并部署的工作
如果你想去改一个已归档的功能，说明：
- 要么是发现 Bug（修复 Bug）
- 要么是功能迭代（增强/修改行为）
这两种情况都应该创建新变更，而不是去修改归档。
正确的流程：创建新变更
假设你以前实现了“深色模式”功能并已归档，现在想“把深色模式从手动切换改成跟随系统”：
# ❌ 错误做法：去改 archive 里的东西
# 不要这样操作！
# ✅ 正确做法：创建新变更
/opsx:new update-dark-mode-follow-system
# 然后正常走流程
/opsx:ff # 或 /opsx:continue
# 在 proposal.md 中说明：
# “修改现有的深色模式功能：从手动切换改为跟随系统偏好”
为什么不能直接改归档？
1. 规范已经合并到 specs/
归档时，变更中的规范增量已经被合并到 openspec/specs/ 主目录。如果你去改归档文件，主规范不会同步更新，造成不一致。
2. 归档是历史审计记录
archive/ 的作用是保留“什么时候做了什么”的历史记录。如果随意修改，追踪变得混乱。
3. 依赖关系
后续的变更可能基于当前的 specs/ 创建。直接改归档会让 AI 读不到你的修改。
那如果只是想改一个之前没发现的错别字呢？
即使只是改“proposal.md”里的一个错别字，逻辑也是一样的：
- 如果变更还在进行中（在
changes/下）→ 直接改 - 如果已经归档（在
changes/archive/下）→ 不建议改。错别字只在归档文件中，不影响功能。如果实在纠结，可以手动编辑，但需要知道这不会同步到任何地方
总结对比
| 你想做什么 | 操作 |
|---|---|
| 改正在进行中的变更 | 直接说“把 XX 改成 YY”，或用编辑器改文件 |
| 改已归档的错别字 | 可以手动改（不影响功能），也可以忽略 |
| 改已归档的功能逻辑 | 创建新变更：/opsx:new 描述修改内容 |
| 在已归档功能上加新功能 | 创建新变更 |
| 修复已归档功能的 Bug | 创建新变更 |
一句话记住
归档 = 已完成，改功能请开新变更，不要动归档。
这也符合 Git 的哲学：你不会去改一个已经合并到主分支的历史 commit，而是会开一个新的 commit 或 PR 来做修改。OpenSpec 的归档设计是一样的道理。
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
5
0- 0
已为社区贡献5条内容
所有评论(0)