基于 OpenSpec 的变更驱动开发：openspec-apply-change 技能实战指南

基于 OpenSpec 的变更驱动开发openspec-apply-change 技能实战指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors导读openspec-apply-change是 OpenSpec 工作流中面向 AI 编码代理Agent的实施变更技能定义了一套从选择变更、读取上下文到逐项完成任务的标准执行协议。本文以 riv/actors 仓库中实际落地的 SKILL.md 为主体完整拆解其 7 步执行流程、CLI 命令与 JSON 契约、任务勾选机制、输出模板与护栏规则帮助你理解如何在规范驱动spec-driven的开发模式中让 Agent 稳定、可控地把一个 OpenSpec change 从任务清单变成真实代码。一、技能定位OpenSpec 的变更上的动作Actions on a Change模型OpenSpec 将一次开发工作组织为一个change——它是围绕一项工作的所有思考与规划的容器通常位于openspec/changes/name/目录下按 schema 持有 proposal、specs、design、tasks 等产物artifacts。在此模型之上openspec-apply-change技能负责其中最关键的环节根据 change 中已定义的任务清单驱动 Agent 逐一实施代码变更。该技能文件本身是一个符合通用格式的 SKILL.md其 frontmatter 声明了元信息name: openspec-apply-change description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. license: MIT compatibility: Requires openspec CLI. metadata: author: openspec version: 1.0 generatedBy: 1.1.1两个值得注意的约束compatibility: Requires openspec CLI整个技能建立在 OpenSpec 命令行工具之上openspec list、openspec status、openspec instructions是获取数据源的关键入口license: MIT与generatedBy字段说明该技能文件可由 OpenSpec CLI1.1.1自动生成具备可移植、可复用的特征。在 riv/actors 仓库中这一技能并非孤立存在而是与一组同源的兄弟技能共同构成完整的变更生命周期工具链均位于 .opencode/skills/ 目录技能职责openspec-new-change新建 change按 schema 逐步创建产物openspec-continue-change续写下一个待创建的产物openspec-apply-change本文主题按任务清单实施代码变更openspec-verify-change验证变更是否满足规范openspec-sync-specs将 delta spec 同步到主 specopenspec-archive-change归档已完成的 changeopenspec-ff-change快进一次性生成全部产物同时技能还有对应的斜杠命令包装slash command便于在对话中直接触发例如 .opencode/command/opsx-apply.md 与 .claude/commands/opsx/apply.md两者内容与 SKILL.md 基本一致只是入口形态不同Claude Code 版本为/opsx:apply name。这体现了 OpenSpec 工作流一份协议、多端接入的设计。二、输入约定与变更选择Step 1技能的第一步是确定要实施的 change其输入约定如下显式指定用户可直接提供 change 名称例如/opsx-apply add-auth上下文推断若未指定先从对话上下文中推断用户是否提到某个 change自动选择若当前只有一个活跃 change可直接自动选中必须询问若存在歧义运行openspec list --json获取可用变更列表并使用AskUserQuestion 工具让用户选择。一个强制要求是选定后必须向用户声明正在实施的 change并说明如何覆盖override。例如Using change:name如需切换可输入/opsx-apply other这一设计的目的在于Agent 在执行长流程时容易跑偏到别的变更上显式声明能让用户随时校验 Agent 的理解是否正确。三、理解 Schema用 openspec status 摸清工作流Step 2选定 change 之后第一步是查询其当前状态以理解所用 schemaopenspec status --change name --json解析返回的 JSON重点理解schemaName当前使用的 workflow schema如spec-driven任务所在的产物对spec-driven而言通常是tasks产物其他 schema 需以 status 输出为准产物状态与 openspec-continue-change 中定义的artifacts数组每个产物有done/ready/blocked状态以及isComplete布尔标志保持一致。在spec-drivenschema 下产物的创建顺序固定为proposal.md → specs/capability/spec.md → design.md → tasks.md其中proposal.md说明 Why、What Changes、Capabilities、Impact其 Capabilities 一节至关重要——每个 capability 都会对应一个 spec 文件specs/ /spec.md按 proposal 中列出的 capability 逐个创建用 capability 名而非 change 名design.md记录技术决策、架构与实现方案tasks.md将实现拆解为带复选框checkbox的任务清单。只有确认 schema 与任务产物位置后Agent 才知道任务清单到底存在哪个文件、以什么格式呈现——这是后续所有实施动作的前提。四、获取实施指令openspec instructions applyStep 3状态确认后下一步是获取专门针对实施阶段的动态指令openspec instructions apply --change name --json该命令返回一个结构化 JSON包含四类关键信息contextFiles上下文文件路径列表随 schema 变化可能是 proposal/specs/design/tasks也可能是 spec/tests/implementation/docsProgress进度total 总数、complete 已完成、remaining 剩余Task list with status任务列表及各自状态Dynamic instruction基于当前状态生成的动态指令。拿到指令后必须先根据state字段分派处理state: blocked缺少必需产物向用户展示提示信息并建议改用 openspec-continue-change 技能或/opsx-continue命令先把缺失产物补齐state: all_done全部完成向用户祝贺并建议归档该 change对应 openspec-archive-change 技能其他状态进入正式实施流程。这条命令是智能体化的核心它把下一步该干什么的判断权交给 CLI 的图状状态机artifact graph而不是让 Agent 凭经验猜测从而保证即使 schema 不同Agent 也能获得正确引导。五、读取上下文文件动手前必须完成的一步Step 4实施任何任务之前Agent 必须读取contextFiles中列出的所有文件。这些文件因 schema 而异spec-drivenproposal、specs、design、tasks其他 schema完全遵循 CLI 输出的contextFiles字段不要自行假设文件名。这一步骤在护栏中也被反复强调Always read context files before starting (from the apply instructions output)。原因是 tasks.md 中的每条任务往往只写了做什么而为什么做、边界是什么、验收标准是什么藏在 proposal 与 spec 中——跳过上下文直接写代码是实施阶段最常见也最昂贵的错误。六、实施任务循环最小化改动与勾选驱动Step 6读取上下文并展示进度schema 名称、N/M tasks complete、剩余任务概览、CLI 动态指令之后进入核心循环。对每个待办任务声明正在处理的任务含序号与描述做出所需的代码变更保持改动最小且聚焦Keep changes minimal and focused在 tasks 文件中将对应复选框由- [ ]改为- [x]继续下一个任务直到全部完成或遇到阻塞。循环中必须暂停Pause的四种情况任务含义不清晰 → 先向用户澄清再实施实施过程暴露设计问题 → 建议更新相关产物如 spec/design遇到错误或阻塞 → 报告并等待用户指引用户主动打断。暂停原则的底层逻辑是不要猜测dont guess。Agent 可以自主推进可消化的任务但一旦触及歧义、设计缺陷或环境障碍必须把决策权交还用户避免在错误方向上持续产出代码。七、三种输出模板让过程透明可审计技能为实施过程的三个关键节点规定了标准化输出格式保证用户随时能看到 Agent 的进展与结论。实施过程中Output During Implementation## Implementing: change-name (schema: schema-name) Working on task 3/7: task description [...implementation happening...] ✓ Task complete Working on task 4/7: task description [...implementation happening...] ✓ Task complete全部完成Output On Completion## Implementation Complete **Change:** change-name **Schema:** schema-name **Progress:** 7/7 tasks complete ✓ ### Completed This Session - [x] Task 1 - [x] Task 2 ... All tasks complete! Ready to archive this change.遇到问题暂停Output On Pause## Implementation Paused **Change:** change-name **Schema:** schema-name **Progress:** 4/7 tasks complete ### Issue Encountered description of the issue **Options:** 1. option 1 2. option 2 3. Other approach What would you like to do?这套模板的价值在于它把 Agent 的工作状态压缩成用户可快速扫读的结构化信息change、schema、进度、问题、选项并始终以一个问题收尾把下一步的决定权显式交还给用户。八、护栏Guardrails全解析技能末尾列出 8 条护栏是实施阶段的硬性约束逐条解读如下Keep going through tasks until done or blocked默认持续推进不因差不多而提前收手Always read context files before starting动手前必须读上下文且来源是 apply 指令输出而非猜测If task is ambiguous, pause and ask before implementing歧义即暂停If implementation reveals issues, pause and suggest artifact updates实施暴露问题时不硬扛而是建议更新产物这正是允许产物更新能力的体现Keep code changes minimal and scoped to each task改动最小化、与任务一一对应避免顺手改无关代码Update task checkbox immediately after completing each task勾选要即时保证 tasks.md 始终反映真实进度Pause on errors, blockers, or unclear requirements - dont guess错误/阻塞/需求不明一律暂停绝不猜测Use contextFiles from CLI output, dont assume specific file names文件路径以 CLI 输出为准不假设固定文件名这是schema 可插拔得以成立的前提。这些护栏本质上是把良好的结对编程习惯固化成了机器可执行的协议防止 Agent 出现过度自信的自主性。九、流动工作流集成Fluid Workflow Integration技能末尾特别说明其支持actions on a change模型与传统的阶段锁定phase-locked流程不同可随时调用即使产物尚未全部完成只要已存在任务也可以先实施也支持部分实施后再回到产物创建还能与其他动作交错进行允许产物更新如果实施过程暴露了设计问题Agent 应建议更新产物而不是被流程阶段卡住——写代码与写规范之间可以双向流动。这与 openspec-continue-change 技能每次调用只创建一个产物、按顺序推进的策略互为补充continue 负责向前补齐产物apply 负责向下推进实现两者可交替执行构成一个灵活的螺旋式开发循环。十、仓库中的完整落地形态在 riv/actors 仓库中这套工作流有完整、可对照的文件落地技能定义.opencode/skills/openspec-apply-change/SKILL.md本文主体及其 9 个兄弟技能命令包装OpenCode.opencode/command/opsx-apply.md 等 10 个/opsx-*命令覆盖 apply、archive、bulk-archive、continue、explore、ff、new、onboard、sync、verify命令包装Claude Code.claude/commands/opsx/apply.md 及其同目录下的 archive、bulk-archive、continue、explore、ff、new、onboard、sync、verify 命令其中 onboard.md 还维护了完整的命令速查表并将 change 描述为围绕一项工作的所有思考与规划的容器位于openspec/changes/name/持有 proposal、specs、design、tasks 等产物。从这些文件可以推断本仓库采用的是 OpenSpec 的实验性工作流experimental workflow通过openspec init初始化、openspec new change name创建变更、按 schema 顺序生成产物最终由 apply 技能驱动实施、archive 技能完成归档。实际使用时你只需确保已安装 openspec CLI 并完成openspec init即可按上述流程在任意支持 AskUserQuestion 的 Agent 环境中复现这套规范驱动开发闭环。结语openspec-apply-change技能的实质是把从任务清单到代码落地的过程标准化为一条可预测、可暂停、可续跑的 Agent 执行协议以openspec instructions apply的动态输出为唯一事实来源以最小化改动 即时勾选为进度基准以歧义即暂停、绝不猜测为安全底线。理解了它你就掌握了让 AI 代理在大型代码库中安全地按规范批量实施变更的核心方法论。【免费下载链接】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），仅供参考