OpenSpec 变更驱动开发工作流实战指南基于 OPSX Onboard 全流程引导教程【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本文是一份以本仓库.claude/commands/opsx/目录下的 OPSX 命令族为蓝本的引导式实战教程系统讲解 OpenSpec 变更驱动change-driven开发的完整生命周期从代码库任务扫描、探索模式、创建 change 容器到依次产出 proposal → specs → design → tasks 四类工件artifacts再到逐项实现、验证、归档。读完本文你将掌握一套可复用的想法到落地工作流节奏并理解每个阶段对应的 CLI 命令、文件结构与交互话术可直接在你的任何代码库中复现。一、OPSX 是什么一套变更驱动的引导式工作流OPSX 是本仓库中一组以/opsx:*形式暴露的 Claude Code 命令见 .claude/commands/opsx/其核心是围绕OpenSpec 的 change变更机制组织开发过程。所谓 change是承载一段工作所需的全部思考与规划的容器通常位于openspec/changes/name/目录下内部存放四类工件openspec/changes/name/ ├── proposal.md ← 为什么做Why ├── design.md ← 怎么做How ├── specs/ ← 做什么What按 capability 拆分 └── tasks.md ← 实现清单复选框驱动 Apply 阶段OPSX 命令族完整覆盖了这一生命周期的每个环节命令职责/opsx:explore探索模式动手前先想清楚问题不写代码/opsx:new新建 change按步逐个产出工件/opsx:ff快进模式一次性生成全部工件/opsx:continue继续推进某个既有 change 的下一个工件/opsx:apply依据 tasks 清单实现代码/opsx:verify校验实现与工件是否一致/opsx:archive归档已完成的 change/opsx:sync将 delta spec 同步回主 spec/opsx:bulk-archive批量归档其中/opsx:onboard本文主体正是这套体系的教学入口它以真实代码库任务为载体带你完整走一遍从想法到归档的闭环全程边做边学。二、Preflight初始化检查开始任何 change 之前先确认项目是否已初始化 OpenSpecopenspec status --json 21 || echo NOT_INITIALIZED命令成功输出 JSON 状态 → 项目已初始化可以继续输出NOT_INITIALIZED→ 需要先执行openspec init完成初始化再回来运行/opsx:onboard。这是整个工作流的唯一硬性前置条件未初始化时必须停止不要跳过。三、Phase 1欢迎与流程预览引导开始时会向用户展示本次教学的目标与路线明确这是一次约15–20 分钟的完整周期体验在代码库中挑选一个小而真实的改动任务简要探索问题创建 change工作容器依次构建工件proposal → specs → design → tasks按 tasks 实现代码归档完成的 change。教学要点这个预览不是走过场——它向学习者预告了工件产出顺序而该顺序正是 OpenSpec 默认spec-drivenschema 的工件依赖链proposal 先行specs 依据 proposal 中的 Capabilities 拆分design 记录技术决策tasks 最终拆解为可勾选的实现单元。四、Phase 2任务选择Task Selection4.1 代码库扫描六类快速胜利信号引导者需要先在代码库中扫描适合入门的小任务重点寻找以下六类信号来自 onboard.md Phase 2TODO/FIXME 注释——搜索TODO、FIXME、HACK、XXX缺失的错误处理——吞掉异常的catch块、缺少 try-catch 的危险操作没有测试的函数——将src/与测试目录交叉对照类型问题——TypeScript 中的: any、as any调试残留——非调试代码中的console.log、console.debug、debugger缺失的输入校验——用户输入处理没有校验逻辑。同时查看近期 git 活动以把握改动热点git log --oneline -10 2/dev/null || echo No git history4.2 给出 3–4 个具体建议扫描后向用户呈现结构化的候选任务清单每条建议包含文件位置精确到行号、改动规模估算文件数与行数、以及为什么适合作为首个练习的简短理由。例如**1. [最有前景的任务]** Location: src/path/to/file.ts:42 Scope: ~1-2 files, ~20-30 lines Why its good: [简要理由]若找不到明显的小任务则退化为开放式提问你最近想添加或修复的小功能是什么4.3 范围护栏Scope Guardrail当用户选择的任务过大如多日量级的功能时引导者应温和劝阻这是个有价值的任务但可能超出首次 OpenSpec 演练的理想规模。学习工作流时更小的任务更好——它能让你完整看到整个周期而不会陷入实现细节。并提供三个选项切分到最小可用切片、换一个更小的候选任务、坚持原任务但接受耗时更长。这是一道软性护栏——若用户坚持允许其自行决定不强行干预。五、Phase 3探索模式Explore Demo选定任务后先花 1–2 分钟演示探索模式阅读相关文件、必要时绘制 ASCII 示意图、记录注意事项。核心原则是先思考、后动手## Quick Exploration [简要分析——发现了什么、有哪些注意事项] ┌─────────────────────────────────────────┐ │ [可选有助于理解的 ASCII 示意图] │ └─────────────────────────────────────────┘ Explore mode (/opsx:explore) 就是用来做这类思考的——在实现之前先调查。配套命令 explore.md 对这一阶段有更完整的定义它是一种立场而非流程没有固定步骤、强制顺序或必达输出强调好奇而非说教、开放线程而非盘问、善用图示、扎根真实代码。探索模式中严禁写业务代码但允许产出 OpenSpec 工件proposal/design/specs 本质是捕捉思考不算实现。当探索中浮现决策时可提供捕捉建议将洞见落入对应工件洞见类型落点发现新需求specs/capability/spec.md需求变更specs/capability/spec.md设计决策design.md范围变化proposal.md新工作项tasks.md探索阶段结束时需要暂停等待用户确认再进入下一阶段。六、Phase 4创建 Change 容器change 是 OpenSpec 中承载一段工作全部思考与规划的容器位于openspec/changes/name/容纳 proposal、specs、design、tasks 四类工件。DO以派生的 kebab-case 名称创建 changeopenspec new change derived-name例如add user authentication会被派生为add-user-auth。创建后展示目录结构与各文件用途empty 待填充openspec/changes/name/ ├── proposal.md ← 为什么做空待填充 ├── design.md ← 怎么做空 ├── specs/ ← 详细需求空 └── tasks.md ← 实现清单空配套命令 new.md 补充了更完整的创建流程创建后运行openspec status --change name查看各工件状态ready/blocked/done再运行openspec instructions first-artifact-id --change name获取第一个工件的模板与上下文。注意默认使用 spec-driven schema即 proposal → specs → design → tasks仅当用户显式要求时才用--schema name切换若用户提及show workflows则运行openspec schemas --json供其选择。七、Phase 5Proposal捕捉 Whyproposal 回答为什么做、高层面上涉及什么是整个工作的电梯演讲。引导者草拟提案后暂停等待用户确认再保存。提案模板完整继承自 onboard.md Phase 5## Why [1-2 句话说明问题/机会] ## What Changes [要点列出将发生什么不同] ## Capabilities ### New Capabilities - capability-name: [简要描述] ### Modified Capabilities !-- 若修改既有行为 -- ## Impact - src/path/to/file.ts: [改动内容] - [其他相关文件]保存方式为先获取指令openspec instructions proposal --change name --json再将内容写入openspec/changes/name/proposal.md。关键联动proposal 的Capabilities 部分是后续 specs 的输入——每个列出的 capability 都将需要一个独立的 spec 文件见下节。保存后它是你的为什么文档理解演进时可随时回来修订。八、Phase 6Specs精确定义 Whatspecs 用可测试的精确语言定义做什么。格式采用需求/场景requirement/scenario结构其中 WHEN/THEN/AND 可以被逐字当作测试用例阅读## ADDED Requirements ### Requirement: 名称 系统应做到什么的描述 #### Scenario: 场景名 - **WHEN** 触发条件 - **THEN** 预期结果 - **AND** 附加结果如需创建步骤mkdir -p openspec/changes/name/specs/capability-name将内容保存到openspec/changes/name/specs/capability/spec.md。对于小任务一个 spec 文件通常就足够了。配套命令 continue.md 给出了关键约束每个 capability 建一个 spec 文件文件名用 capability 名而非 change 名每次调用只创建一个工件并严格遵循 schema 定义的工件序列不得跳序。九、Phase 7Design决策 Howdesign 记录如何构建——技术决策、权衡与实现路径。小改动可以很简短并非每个 change 都需要深度设计讨论。模板## Context [关于当前状态的简要背景] ## Goals / Non-Goals **Goals:** - [想达成的目标] **Non-Goals:** - [明确排除的范围] ## Decisions ### Decision 1: [关键决策] [方案说明与理由]保存到openspec/changes/name/design.md。明确记录 Non-Goals非目标是这个模板的价值所在——它防止实现过程中的范围蔓延scope creep。十、Phase 8Tasks拆解实现清单最后将工作拆解为实现任务——以复选框形式驱动 Apply 阶段。任务应小、清晰、顺序合理## 1. [类别或文件] - [ ] 1.1 [具体任务] - [ ] 1.2 [具体任务] ## 2. Verify - [ ] 2.1 [验证步骤]每个复选框成为 Apply 阶段的一个工作单元。保存到openspec/changes/name/tasks.md前需暂停确认用户已准备好实现。十一、Phase 9Apply逐项实现实现阶段的核心纪律是每个任务只做最小且聚焦的改动。对每个任务宣布Working on task N: [描述]在代码库中实现改动自然引用 specs/designspec 说 X所以我这样做 Y在 tasks.md 中勾选- [ ]→- [x]简短播报✓ Task N complete实现期间旁白保持轻量——教学而非说教不过度解释每一行代码。全部任务完成后展示汇总并转入归档。配套命令 apply.md 给出了更完整的工程化流程change 选择指定名称或从上下文推断或openspec list --json列出候选状态检查openspec status --change name --json解析schemaName与工件状态获取指令openspec instructions apply --change name --json返回上下文文件、进度total/complete/remaining与动态指令状态分流state: blocked缺工件→ 建议/opsx:continuestate: all_done→ 祝贺并建议归档暂停时机任务不清晰、实现暴露设计问题、遇到错误或阻塞、用户打断——宁可暂停也不要猜测。该命令还强调流体工作流理念Apply 并非阶段锁死可在工件未全部完成时若 tasks 已存在随时介入也可在实现中发现设计问题时反向更新工件。十二、Phase 10Archive归档与决策留痕change 完成后归档将其从openspec/changes/移入openspec/changes/archive/YYYY-MM-DD-name/openspec archive name归档后的 change 成为项目的决策历史——日后可随时回溯理解某个功能为什么以这种方式构建。配套命令 archive.md 补充了归档前的三道检查工件完成度用openspec status --change name --json检查是否有未done的工件有则警告并请求确认任务完成度统计 tasks.md 中- [x]与- [ ]的数量存在未完成任务时警告并确认delta spec 同步状态若openspec/changes/name/specs/存在 delta specs需与主 specopenspec/specs/capability/spec.md对比展示将要应用的增删改概要后询问立即同步推荐或不同步直接归档若用户选择同步则执行/opsx:sync逻辑。执行归档时先生成目标名YYYY-MM-DD-change-name若目标已存在则失败并给出重命名/清理/换日期三个选项。注意归档是mv目录操作.openspec.yaml会随目录一起移动无需单独处理。归档是告知型而非阻塞型——警告只是知情不阻止归档。十三、Phase 11回顾与命令速查完成一个完整周期后以 8 步节奏回顾完整继承自 onboard.md Phase 11Explore—— 想清楚问题New—— 创建 change 容器Proposal—— 捕捉 WHYSpecs—— 精确定义 WHATDesign—— 决策 HOWTasks—— 拆解为步骤Apply—— 实现工作Archive—— 保留决策记录这套节奏对任何规模的改动都适用——小修复或大功能概莫能外。配套的 verify 命令verify.md还提供了归档前的三维校验报告框架维度检查内容问题级别Completeness完整性任务勾选数、需求覆盖度CRITICALCorrectness正确性需求-实现映射、场景覆盖WARNINGCoherence一致性设计决策遵循度、代码模式一致性SUGGESTION校验遵循不确定时降级原则宁可 SUGGESTION 也不要 WARNING、宁可 WARNING 也不要 CRITICAL每条问题都必须附带可操作的具体建议与文件/行号引用。十四、优雅退出处理教学流程必须尊重用户节奏提供两条退路中途想停没问题你的 change 已保存在openspec/changes/name/。之后可随时用/opsx:continue name继续创建工件或/opsx:apply name直接跳入实现。工作不会丢失。只想要命令速查直接给出 Quick Reference 表格即本文第一节的命令族表并提示可从/opsx:new或/opsx:ff开始。退出时绝不施压。十五、OPSX 工作流的护栏原则总结综合 onboard.md 与配套命令文档可提炼出整套工作流的设计哲学EXPLAIN → DO → SHOW → PAUSE在关键转折点探索后、提案草稿后、任务清单后、归档后遵循解释-执行-展示-暂停节奏暂停等待确认但不频繁打断真实任务优先始终使用代码库中的真实任务教学不模拟、不用假例子onboard 明确要求软性控范围温和引导向小任务但尊重用户选择不跳阶段即使改动很小也走完整周期——教学目标是掌握工作流本身先想后做explore 模式严禁写业务代码只允许捕捉思考到工件每次只前进一步continue 每次只创建一个工件不跳序、不批量批量由/opsx:ff显式完成工件是约束而非内容CLI 返回的context、rules字段用于指导写作绝不复制进工件文件continue.md 特别强调决策留痕归档即历史spec 同步回主 spec让为什么这么做永续可查。这套工作流的本质是把写代码之前的思考过程结构化为可审查、可追溯、可协作的工件链再用复选框任务把实现阶段变成机械而可靠的执行——无论是对单个开发者还是对 AI 辅助编程它都提供了一条从模糊想法到落地代码的、可重复验证的路径。相关文档导航引导教程本体.claude/commands/opsx/onboard.md探索模式.claude/commands/opsx/explore.md新建 change.claude/commands/opsx/new.md快进生成工件.claude/commands/opsx/ff.md续建工件.claude/commands/opsx/continue.md实现任务.claude/commands/opsx/apply.md一致性校验.claude/commands/opsx/verify.md归档.claude/commands/opsx/archive.md批量归档.claude/commands/opsx/bulk-archive.md同步 delta spec.claude/commands/opsx/sync.md【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
