在 Fleet 仓库中用/opsx:apply落地 OpenSpec 变更Claude Code 规范驱动实现工作流全解【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet/opsx:apply是 Fleet 仓库内置的 OpenSpec 工作流命令负责把一份 OpenSpec 变更change中的任务清单逐条实现为真实代码。本文以 .claude/commands/opsx/apply.md 为骨架结合 openspec/README.md、openspec/config.yaml 与 .claude/skills/openspec-apply-change/SKILL.md完整讲解如何选择变更、解析 schema 与状态、读取上下文文件、循环实现任务并在完成或受阻时正确收尾。读完本文你将掌握在 FleetGo 后端 React/TypeScript 前端的设备管理与安全项目中把 spec 驱动的设计文档转化为可提交代码的完整 Agent 工作流并理解其边界规则与可插拔的流水线定位。OpenSpec 与 apply 阶段在整个流程中的位置OpenSpec 是一套先写规范、再写代码的变更工作流在 Fleet 仓库中属于可选工具opt-in tool并非开发流程的强制部分。仓库在 openspec/README.md 中明确说明团队尚未将其定为政策使用它不需要任何 PR 审批。它的价值在于当一次变更大到值得在写任何代码之前留下书面记录时例如横跨 datastore、service、endpoint 和 UI 的跨切面功能或涉及大量文件、需要在实现前先确定形态的重构。整个流程是一个四阶段的流水线explore → propose → apply → archive/opsx:explore— 纯思考阶段理清想法不写代码不产 artifacts除非被要求。/opsx:propose— 生成proposal.md做什么与为什么、design.md怎么做和tasks.md实现步骤存放于openspec/changes/change-name/。/opsx:apply— 实现阶段逐条完成 tasks.md 中的任务也是本文的主角。/opsx:archive— 合并完成后把变更移动到openspec/changes/archive/并把 delta specs 同步到openspec/specs/。仓库还强调可以自由跳过步骤大多数变更只需要proposeapply很小的改动可能只需要explore。这意味着 apply 并不要求所有 artifacts 都完成——只要存在任务即可被调用这是其流体工作流设计的一部分。apply 与上下游命令的衔接propose.md 结束时提示Run/opsx:applyto start implementingarchive.md 在 apply 全部任务完成- [x]后执行归档实现中若发现设计问题apply 会建议更新 artifacts 而非强行硬编码即回环到 propose 阶段补丁。因此/opsx:apply不是一次性的终点命令而是可以随时进入、暂停、恢复的变更操作之一。第一步选择要实现的变更调用格式为/opsx:apply change-name如/opsx:apply add-auth。如果省略名称Agent 必须依次尝试从对话上下文中推断用户是否提到过某个变更如果当前只有一个活跃变更active change自动选中它如果存在多个候选且语义模糊则运行openspec list --json获取可用变更列表并使用 AskUserQuestion 工具让用户显式选择。无论哪种方式选中都必须播报Using change: name并告知覆盖方式例如再运行/opsx:apply other即可切换。这条播报规则保证了实现过程的透明可追溯。第二步用openspec status理解 schema选中变更后第一步是检查其 schema 与 artifacts 状态openspec status --change name --json解析返回的 JSON重点理解两个字段schemaName该变更使用的工作流 schema。Fleet 仓库在 openspec/config.yaml 中将其配置为schema: spec-driven因此任务通常存放在tasksartifact 中artifacts 列表每个 artifact 的类型与完成状态用于判断哪个 artifact 承载任务——命令明确要求不要假设文件名以 CLI 输出为准。spec-drivenschema 意味着变更由 proposal、specs、design、tasks 等 artifacts 构成任务实现前需要满足的依赖关系applyRequires见 propose 命令通常就是[tasks]。第三步获取 apply 指令与上下文文件openspec instructions apply --change name --json这条命令是 apply 的核心数据来源返回内容包含contextFilesartifact ID 到具体文件路径的映射随 schema 不同而变化。对spec-driven而言通常覆盖 proposal、specs、design、tasks其他 schema 则完全以 CLI 输出的 contextFiles 为准进度信息total、complete、remaining任务清单及各自状态基于当前状态的动态指令dynamic instruction。获取后必须读取 contextFiles 中列出的每一个文件再开始动手。这是 Guardrails 中的硬性要求Always read context files before starting (from the apply instructions output)并且Use contextFiles from CLI output, dont assume specific file names——即使熟悉 spec-driven 结构也要以 CLI 输出为准防止文件布局变化导致读到过期上下文。状态分支处理拿到指令后先判断state字段状态含义处理方式blocked缺少必要 artifacts无法实现显示提示建议先运行/opsx:continue对应 skill 侧为openspec-continue-change补齐缺失部分all_done所有任务已完成祝贺用户建议执行归档/opsx:archive其他可以开始实现进入任务循环第四步读取上下文文件对于spec-drivenschema需要读取的上下文文件通常包括proposal.md— 变更的动机与范围what whyspecs/下的 delta specs — 能力规格的增量变更design.md— 技术实现方案howtasks.md— 实现任务清单。这些文件是实现的契约任务描述往往引用 proposal 的范围约束与 design 的技术选型跳读容易导致实现偏离设计意图。Fleet 将 artifacts 视为 Markdown 文档而非契约代码评审仍然是最终事实来源见 openspec/README.md 的 Conventions但上下文文件的指引价值是 apply 阶段不可省略的前置步骤。第五步展示当前进度在开始实现前向用户展示当前使用的 schema 名称进度N/M tasks complete剩余任务概览CLI 给出的动态指令。这一步让用户对接下来要改什么、改多少有明确预期也为后续每完成一个任务的进度播报建立基线。第六步实现任务循环核心循环是直到全部完成或被阻塞播报当前任务明确正在处理任务 3/7任务描述实施代码改动针对该任务做最小且聚焦的修改立即勾选任务在 tasks 文件中把- [ ]改为- [x]继续下一个任务。必须暂停的情况循环不是无脑冲到底遇到以下情况必须停下并等待指引任务不清晰→ 先向用户澄清再实现实现暴露设计问题→ 暂停并建议更新 artifactsproposal/design/tasks而不是绕过设计硬写代码遇到错误或阻塞→ 报告问题等待用户指示用户主动打断。Guardrails 对此的表述非常明确Pause on errors, blockers, or unclear requirements - dont guess在错误、阻塞或需求不明时暂停——不要猜测。If task is ambiguous, pause and ask before implementing任务含糊就先问再做。输出模板让进度可被机器与人类同时理解apply 定义了三种固定输出格式贯穿整个实现过程。实现进行中## 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全部完成## 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! You can archive this change with /opsx:archive.受阻暂停## 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?这套模板的价值在于状态显式化用户一眼即可区分进行中 / 已完成 / 待决策三种状态且每次会话只报告本次会话完成的增量Completed This Session配合总体进度避免把历史会话与新进度混淆。注意上述模板中的 Change/Schema/Progress 字段与openspec status --json输出中的schemaName一一对应模板与 CLI 数据模型是同一套。Guardrails实现的边界规则apply 的护栏可以总结为七条可执行纪律持续推进直到全部任务完成或遇到阻塞不要中途放弃先读上下文动手前必须读取 apply 指令输出的 contextFiles含糊即问任务描述不明确时先暂停询问而非臆测实现发现问题即回环实现暴露设计缺陷时暂停并建议更新 artifacts最小改动每次代码变更保持最小、限定在单个任务范围内即时勾选每完成一个任务立即更新 tasks 文件的复选框不猜不编遇到错误、阻塞或需求不明必须暂停文件路径一律以 CLI 输出为准不臆测文件名。从代码工程角度看第 5、6 条确保了一次一个可验证的步骤任务粒度小 → diff 可控 → 每步完成后检查点自然形成配合第 2 条能够显著降低Agent 在大型变更中跑偏的风险。Fluid Workflowapply 的动作模式集成apply 命令明确支持 OpenSpec 的actions on a change模型具备三个特性随时可调用在 artifacts 全部完成之前只要存在任务、部分实现之后、或其他动作交错进行时都可以运行 apply允许 artifacts 更新如果实现过程揭示设计问题建议更新 proposal/design/tasks而不是被阶段锁死不设阶段锁定工作流是流体式的not phase-locked, work fluidlyapply 与 propose/explore/archive 可以按需来回切换。这回答了常见疑问任务没全部设计好能不能先实现一部分——在 OpenSpec 中完全可行只需保证待实现的任务已存在且上下文清晰。在 Fleet 仓库中的落地细节命令与技能的双轨实现该工作流在仓库中存在两份载体旧格式命令.claude/commands/opsx/apply.md本文主体category 为 Workflow标记experimental新格式技能.claude/skills/openspec-apply-change/SKILL.mdmetadata 标注generatedBy: 1.3.1兼容性要求Requires openspec CLI。两者步骤与 Guardrails 完全一致区别在于新技能增加了 frontmatter 化的描述description声明触发场景与版本元数据。按 openspec/README.md 的说明这两个目录都由 OpenSpec CLI 拥有openspec update会覆盖任何本地修改不要手工编辑如需定制行为应改 openspec/config.yaml若确实需要分叉版本请复制成新名字以免被更新器覆盖。config.yamlschema 与项目上下文openspec/config.yaml 是自定义入口包含schema: spec-driven context: | Fleet: Go backend React/TypeScript frontend for device management and security. Authoritative project guidance lives in .claude/CLAUDE.md — read it before drafting. rules: proposal: [] tasks: []schema: spec-driven决定了 apply 默认读取tasksartifact 中的任务context会在生成每个 artifact 时注入其rules块向 Agent 提供项目背景Fleet 的技术栈与权威指引位置.claude/CLAUDE.mdrules为空列表会被静默跳过可添加如 Include a Non-goals section 之类的结构约束。仓库目录约定路径作用openspec/changes/name/进行中的 proposal、design、tasks 等 artifactsopenspec/changes/archive/已归档已完成的变更openspec/specs/已被接受的规格openspec/config.yaml项目上下文与 AI 必须遵守的规则术语与定位约定Fleet 在 openspec/README.md 的 Conventions 中要求新 artifacts 使用新术语——Fleets而非 Teams、Reports而非 Queries已有代码保持现有命名。同时强调Treatopenspec/artifacts as documentation, not as a contract: code review is still the source of truth把 artifacts 当作文档而非契约代码评审仍是最终事实来源——这与 apply 中最小改动、逐任务推进、发现问题回环更新 artifacts的纪律互为表里。前置条件所有opsx命令都依赖openspecCLI 在$PATH上brew install openspec而读取openspec/下的 Markdown artifacts 本身不需要 CLI。Fleet 的 .claude/README.md 将openspec-*系列技能列为/openspec-propose入口、由 OpenSpec CLI 供应vendored进一步印证了CLI 与 Markdown 分离、CLI 作为驱动源的设计。小结一条可随时进入、暂停与恢复的实现流水线/opsx:apply的本质是一条状态驱动的实现循环openspec status建立 schema 认知 →openspec instructions apply提供上下文文件、进度与动态指令 → 逐个任务最小改动并即时勾选 → 完成或受阻时用固定模板播报。它与 explore、propose、archive 构成完整的 OpenSpec 流水线在 Fleet 仓库中被定位为可选工具跨 datastore/service/endpoint/UI 的大型功能、涉及多文件的重构才值得启用日常 bug 修复与小型改动直接写 PR 描述即可。对希望复刻这套实践的开发者建议从openspec list --jsonopenspec status --change name --json两个只读命令开始熟悉数据模型再逐步体验 propose → apply → archive 的完整闭环。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
