Fleet 仓库中的 OpenSpec spec-driven 变更工作流从 explore 到 archive 的完整指南【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleetOpenSpec 是一套先写规范、再写代码spec-driven的变更设计与追踪工作流适用于那些横跨数据层、服务层、接口层与界面层的大型改动。本文以 Fleet 仓库中的实际落地为例完整讲解 OpenSpec 的适用场景、四阶段工作流explore → propose → apply → archive、目录约定、CLI 用法与自定义方式帮助你在仓库内为大型代码变更留下书面记录并与人工或 AI 协作者在动手写代码之前就对齐方案。OpenSpec 在 Fleet 仓库中的定位可选的辅助工具在 Fleet 仓库中OpenSpec 是可选的opt-in辅助工具而不是开发流程的强制组成部分。团队并未将其采纳为强制政策任何 PR 都不要求必须使用 OpenSpec。这一点在 openspec/README.md 中有明确说明其定位是为大型代码变更提供先书面记录、后实现的路径产物是可读的 Markdown 文档与代码一同提交代码评审仍然是最终的真理来源source of truthOpenSpec 产物仅作为文档而非契约。这意味着使用 OpenSpec 不会改变现有的 PR 评审流程也不会增加强制门槛——它只是在你认为这次改动足够大、值得先写下来时提供一个结构化的工具支撑。何时使用、何时跳过OpenSpec 的价值在于为大型变更提前固化设计与范围因此 README 给出了非常明确的取舍边界场景建议横跨数据存储、服务、接口和 UI 的横切特性cross-cutting feature使用 OpenSpec涉及数十个文件、需要在实现前对齐结构的重构使用 OpenSpec想与协作者人或 AI评审的 RFC 式设计且不想过早承诺代码使用 OpenSpecBug 修复、小特性、依赖升级、文档微调跳过一个 PR 描述就能讲清楚的内容跳过——直接写 PR 描述README 中的判断标准非常务实如果一次改动可以放进单个 PR 描述里那就直接写 PR 描述只有当改动大到写代码之前就希望有一份书面记录时才值得引入 OpenSpec。安装与前置条件OpenSpec 的斜杠命令slash commands会调用openspecCLI因此它必须在$PATH中brew install openspec需要注意阅读openspec/目录下的 Markdown 产物本身并不需要安装 CLI只有执行 propose / apply / archive 等生成与同步操作时才需要。在 Fleet 仓库中CLI 与编辑器侧的集成痕迹随处可见.claude/settings.json 中显式允许了Bash(openspec *)命令模式说明 OpenSpec 命令被授权在 Claude 环境下执行.claude/commands/opsx/ 下提供了explore.md、propose.md、apply.md、archive.md四个斜杠命令的定义.claude/skills/ 下存在openspec-explore、openspec-propose、openspec-apply-change三个 skill其元数据标注的generatedBy: 1.3.1表明当前仓库配套的是 OpenSpec CLI 1.3.1 生成的 skill。四阶段工作流explore → propose → apply → archiveREADME 将完整流程概括为一条简洁的流水线explore → propose → apply → archive下面结合仓库中四个斜杠命令的实际实现逐一展开。阶段一/opsx:explore —— 只思考不实现这是流程的起点用于把想法想透。根据 .claude/commands/opsx/explore.md 的定义explore 模式是一种立场stance而非固定步骤的工作流没有固定步骤、没有必选产出AI 扮演的是思考伙伴而非执行者。explore 模式的核心约束是**思考而非实现允许读文件、搜索代码、调查代码库但严禁写代码或实现功能**唯一允许创建的 OpenSpec 产物是 proposals、designs、specs——因为记录思考不等于实现功能。该命令支持多种输入形态一个模糊的想法如 real-time collaboration一个具体的问题如 auth system is getting unwieldy一个变更名如add-dark-mode在该变更的上下文中探索一个对比问题如 postgres vs sqlite for this或者什么都不传直接进入探索模式。命令还规定了探索时应持有的姿态保持好奇而非说教、开放多条线索而非审讯式提问、善用 ASCII 图来澄清思维、以实际代码库为锚点进行讨论。探索开始时建议先运行openspec list --json检查当前是否存在进行中的变更以便把讨论与已有产物关联起来。当想法逐渐成形时可以主动提议要不要创建一份 proposal但不强迫。阶段二/opsx:propose —— 一次生成全部产物当想法成熟进入 propose 阶段。根据 .claude/commands/opsx/propose.md该命令会创建变更并一次性生成所有产物proposal.md——做什么what与为什么whydesign.md——怎么做howtasks.md——实现步骤。命令的输入是变更名kebab-case或对要构建内容的描述例如 add user authentication 会被推导为add-user-auth。其执行步骤在仓库中记录得很完整若没有输入先用提问工具询问用户想构建什么没有明确理解需求前不得继续运行openspec new change name在openspec/changes/name/下创建带.openspec.yaml的脚手架运行openspec status --change name --json获取产物构建顺序解析applyRequires实现前必须完成的产物 ID 列表spec-driven schema 下通常是tasks与全部产物的依赖关系按依赖顺序逐个生成产物对每个ready的产物运行openspec instructions artifact-id --change name --json获取context项目背景作为约束而非输出内容、rules产物级规则同样只是约束、template输出文件的结构、instruction该产物类型的 schema 指引、outputPath写入位置与dependencies需要先读的已完产物创建产物后重新运行 status 命令直到applyRequires中的全部产物都标记为done最后展示整体状态。这里有一个值得注意的工程细节context和rules是给 AI 的约束不是写进文件的内容产物文件中不应出现context、rules之类的块。如果某个产物的上下文严重不清晰应该提问澄清但也要在保持推进与停下确认之间做出合理取舍。阶段三/opsx:apply —— 按任务清单实现产物就绪后进入实现阶段。根据 .claude/commands/opsx/apply.md/opsx:apply的输入可以是变更名如/opsx:apply add-auth也可以省略并让 AI 从对话上下文推断若有多个进行中的变更且无法判断则先运行openspec list --json让用户选择。apply 的典型执行路径运行openspec status --change name --json理解 schemaspec-driven 下 tasks 通常承载实现任务运行openspec instructions apply --change name --json获取contextFiles需要阅读的上下文文件路径列表spec-driven 下通常包括 proposal、specs、design、tasks、进度total / complete / remaining与基于当前状态的动态指令处理三类状态blocked缺少产物提示用/opsx:continue、all_done祝贺并建议归档、否则继续实现先读完全部 contextFiles再开始实现逐个实现任务保持改动最小化、聚焦每个任务每完成一个就在 tasks 文件中把- [ ]勾选为- [x]然后继续下一个。命令的守卫原则guardrails很明确任务含糊就暂停提问实现过程中暴露设计问题就暂停并建议更新产物出错或受阻就停下汇报不要在不确定时猜测。apply 还强调fluid workflow它可以在产物未全部完成时被调用、可以在部分实现后与其它动作交错进行实现中发现问题允许回头更新产物——工作流并不被阶段锁死。阶段四/opsx:archive —— 归档并同步规范实现完成并合并后进入归档阶段。根据 .claude/commands/opsx/archive.md归档的完整流程是若未指定变更名先展示进行中的变更排除已归档的让用户选择不猜测、不自动选择运行openspec status --change name --json检查产物完成度若有未完成产物则警告并请求确认读取 tasks 文件统计未完成任务- [ ]存在未完成任务同样先警告再确认检查openspec/changes/name/specs/下是否存在 delta specs若有逐个与openspec/specs/capability/spec.md对照评估将要发生的增、改、删、重命名并展示汇总摘要提供 Sync now推荐 / Archive without syncing 等选项执行归档mkdir -p openspec/changes/archive以YYYY-MM-DD-change-name作为目标名移动变更目录例如mv openspec/changes/name openspec/changes/archive/YYYY-MM-DD-name若目标已存在则报错并建议改名或更换日期展示归档摘要包含变更名、使用的 schema、归档位置、spec 同步状态与警告信息。归档时有两点值得注意移动目录时.openspec.yaml会随目录一起移动无需单独处理归档不因警告而阻塞只需如实告知并取得用户确认。目录结构什么内容放在哪里README 用一小节就讲清了整个openspec/目录的职责划分结合当前仓库可以完整对应路径内容openspec/changes/name/进行中的提案与任务proposal.md、design.md、tasks.md 及可能的 delta specsopenspec/changes/archive/已完成的变更归档按YYYY-MM-DD-name命名openspec/specs/已接受的规范accepted specifications按能力组织为capability/spec.mdopenspec/config.yaml项目上下文与 AI 必须遵守的规则在 Fleet 仓库中openspec/changes/与openspec/specs/当前均为空目录说明仓库目前没有进行中的 OpenSpec 变更也没有已沉淀的接受规范——这套工作流处于就绪未用状态正等待第一个大型变更的到来。项目级配置openspec/config.yamlFleet 仓库的 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——当前使用 spec 驱动的 schema即产物包含 proposal、design、specs、tasks 等并通过apply.requires声明实现前置条件context——向 AI 注入的项目背景Fleet 是Go 后端 React/TypeScript 前端的设备管理与安全平台并明确权威项目指南位于.claude/CLAUDE.md起草前必须阅读rules——按产物类型注入到每个产物rules块的规则列表proposal和tasks当前均为空空列表会被静默跳过意味着目前没有额外结构约束如需强制某些结构约定例如proposal 必须包含 Non-goals 章节可以在这里添加字符串条目。供应商文件Vendored files不要手工编辑README 特别强调了一类不可手工编辑的目录OpenSpec CLI 拥有这些目录的所有权openspec update会用新版本覆盖任何本地改动.claude/skills/openspec-*/.claude/commands/opsx/这正是本仓库中对应目录的实际情况.claude/skills/下的openspec-explore、openspec-propose、openspec-apply-change三个 skill以及.claude/commands/opsx/下的四个命令全部由 OpenSpec CLI 1.3.1 生成。正确的自定义方式是通过openspec/config.yaml调整行为如果确实需要一个有分歧的 skill应当复制到新名称下这样更新器就不会覆盖它。直接改动 vendored 目录会在下一次openspec update时被无差别覆盖。仓库约定与术语README 最后列出了三条仓库级约定它们是维护openspec/产物时的行为准则产物是 Markdown且与其描述的代码一同提交——文档与实现保持同步演进不做分离式维护新产物使用新术语Fleets不再用 Teams、Reports不再用 Queries已有代码保持原有命名。这反映了 Fleet 产品词汇的演进也意味着 OpenSpec 产物是先行采用新术语的文档层将openspec/产物视为文档而非契约代码评审仍然是真理来源产物不应被当作不可违背的接口约束。结合仓库源码的工作流全景综合以上内容在 Fleet 仓库中使用 OpenSpec 的完整路径可以归纳为探索/opsx:explore只读代码、发散思考必要时运行openspec list --json了解现状提案/opsx:propose nameopenspec new change建脚手架 →openspec status --json读依赖 →openspec instructions artifact逐个生成 proposal / design / tasks期间始终遵守openspec/config.yaml注入的 context 与 rules实现/opsx:apply先读 contextFiles再按 tasks 逐项实现并勾选- [x]发现问题随时回改产物归档/opsx:archive核对产物与任务完成度、评估 delta specs 是否同步到openspec/specs/、以YYYY-MM-DD-name移入openspec/changes/archive/。每一步都有对应的 CLI 命令与仓库内的命令/技能定义可查见 .claude/commands/opsx/ 与 .claude/skills/产物全部沉淀在openspec/下的 Markdown 文件中。这套工作流适合为 Fleet 这样Go 后端 React 前端的跨层项目设备管理、安全策略、数据存储到 UI 全链路提供大型变更的书面设计记录——当改动大到值得在写代码之前先对齐方案时它就是为 AI 与人共同评审而生的文档基础设施。最后提醒两点使用前提一是阅读产物无需安装 CLI但执行 propose / apply / archive 必须保证openspec在$PATHbrew install openspec二是本仓库当前openspec/changes/与openspec/specs/均为空任何首个变更都将是这套工作流在仓库中的第一次实际落地。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考