Fleet 仓库的 OpenSpec 变更提案实战用 openspec-propose 一步生成 proposal / design / tasks【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleetopenspec-propose是 Fleet 仓库中随 OpenSpec CLI 一起分发的 Claude Code 技能用于把一个新功能或大改动在动代码之前先落成结构化文档proposal.md做什么、为什么、design.md怎么做、tasks.md实现步骤。本文将完整拆解该技能的执行流程、底层 CLI 命令与产物结构并结合 openspec/README.md、openspec/config.yaml 与仓库中的命令入口说明如何在 Fleet 的 Go 后端 React/TypeScript 前端开发环境下把模糊需求一键转成可评审、可实施的变更提案。一、OpenSpec 在 Fleet 仓库中的定位OpenSpec 是一套规范驱动spec-driven的变更工作流先写提案、设计和任务再进入实现。在 Fleet 仓库里它被明确定义为可选工具opt-in toolopenspec/README.md 开篇即声明它不是开发流程的强制组成部分团队尚未将其采纳为政策任何 PR 都不要求必须使用它。适合使用 OpenSpec 的场景改动大到需要在写代码前留下书面记录的变更——例如横跨数据存储datastore、服务service、API 端点endpoint和前端 UI 的功能涉及几十个文件、实现前需要先对齐形状的重构希望与协作者人或 AI评审、又不想立刻提交代码的 RFC 式设计。应该跳过的场景日常大部分工作都不需要它——bug 修复、小功能、依赖升级、文档微调以及一条 PR 描述就能说清楚的改动。这套工具链包含四个技能openspec-explore思考、openspec-propose提案、openspec-apply-change实现、openspec-archive-change归档对应完整流程explore → propose → apply → archive。其中 propose 是从想法到文档的关键一跃。二、openspec-propose 技能是什么技能本体位于 .claude/skills/openspec-propose/SKILL.md是一个带 YAML frontmatter 的 Markdown 文件--- name: openspec-propose description: Propose a new change with all artifacts generated in one step. license: MIT compatibility: Requires openspec CLI. metadata: author: openspec version: 1.0 generatedBy: 1.3.1 ---其中compatibility: Requires openspec CLI是硬性前提该技能的斜杠命令会调用openspecCLI因此它必须在$PATH上。安装方式在 openspec/README.md 中给出brew install openspec注意阅读openspec/目录下的 Markdown 产物并不需要 CLI只有生成产物时才需要。仓库同时保留了一个同内容的传统命令入口 .claude/commands/opsx/propose.md与技能版描述一致根据 .claude/README.md 的说明Skills 是旧.claude/commands/格式的演进形态新增了自动调用、工具限制与隔离执行等能力。目录归属说明vendored filesopenspec-propose与另外三个openspec-*技能、以及.claude/commands/opsx/下的命令文件都是由 OpenSpec CLI自带并托管vendored的文件。openspec/README.md 明确警告openspec update会覆盖这些目录中的任何本地修改不要手工编辑如需自定义行为应通过openspec/config.yaml修改或把技能复制成新名字以避免被更新器覆盖。三、整体执行流程拆解openspec-propose的目标是在一步之内创建变更并生成全部产物。技能文档定义了从输入到收尾的五个阶段下面逐一展开。阶段 1确认输入技能的输入有两种形态一个 kebab-case 格式的变更名或者一段对想构建什么的描述。如果用户没有给出清晰输入技能要求先用 AskUserQuestion 工具开放式、无预设选项询问What change do you want to work on? Describe what you want to build or fix.随后从描述中推导出 kebab-case 名称例如add user authentication →add-user-auth。技能明确强调在理解用户想构建什么之前不要继续。阶段 2创建变更目录openspec new change name该命令会在openspec/changes/name/下搭建一个脚手架变更并生成.openspec.yaml。阶段 3获取产物构建顺序openspec status --change name --json解析返回的 JSON得到两个关键信息applyRequires实现前必须完成的产物 ID 数组例如[tasks]artifacts全部产物及其状态与依赖关系列表。阶段 4按依赖顺序循环创建产物直到 apply-ready技能要求用TodoWrite 工具跟踪产物进度然后按依赖顺序先处理无未决依赖的产物循环执行对每个状态为ready依赖已满足的产物先取指令openspec instructions artifact-id --change name --json解析指令 JSON。该 JSON 包含六个关键字段其含义如下表字段含义使用方式context项目背景约束 Agent 行为不得写入产物文件rules产物专属规则约束 Agent 行为不得写入产物文件template输出文件应遵循的结构作为产出文件的骨架逐节填充instruction该产物类型的 schema 级指导指导如何撰写outputPath产物应写入的位置目标文件路径dependencies已完成的、供读取上下文的产物开始创建前先阅读阅读已完成的依赖文件获取上下文以template为结构创建产物文件并将context与rules作为约束应用——但不把它们复制进文件。每完成一个产物输出简短进度Created 。继续直到所有applyRequires产物完成每创建一个产物就重跑openspec status --change name --json检查applyRequires中的每个产物 ID 在artifacts数组里是否都已status: done全部完成即停止。如果某产物需要用户输入上下文不明确用 AskUserQuestion 工具澄清后再继续创建。阶段 5展示最终状态openspec status --change name全部产物完成后技能要求总结输出变更名与位置、已创建产物清单含简要描述、就绪声明 All artifacts created! Ready for implementation.以及下一步提示 Run/opsx:applyor ask me to implement to start working on the tasks.四、三种产物的职责划分每次 propose 会产出三份 Markdown 产物恰好对应三个层面的问题产物文件回答的问题内容侧重proposal.mdwhat why做什么、为什么做、范围design.mdhow怎么做、技术方案与决策tasks.mdimplementation steps可执行的分步实现清单openspec/README.md 对流程的总结与此一致propose 阶段在openspec/changes/change-name/下生成这三份文件apply 阶段实现任务传变更名如/opsx:apply add-foo或由上下文推断archive 阶段在合并后将变更移入openspec/changes/archive/并更新openspec/specs/下的规格。五、产物创建守则Artifact Creation Guidelines技能文档专门列出四条创作规范它们共同保证产物质量与流程可复用性遵循指令每个产物类型按其instruction字段撰写schema 定义了产物应包含的内容。先读依赖创建新产物前必须先阅读依赖产物获取上下文。以模板为骨架用template作为输出文件的结构填充其各节。约束不落盘context和rules是给 Agent 的约束而非文件内容——绝不能把context、rules、project_context块复制进产物它们指导写作但永远不应出现在输出中。六、守卫规则Guardrails与仓库级约束技能在守卫规则中强调创建实现所需的全部产物由 schema 的apply.requires定义创建新产物前始终读取依赖产物上下文严重不清晰时才提问但优先做出合理决策以保持推进节奏若同名变更已存在先询问用户是继续它还是新建一个每次写入后验证产物文件确实存在再进入下一步。在 Fleet 仓库层面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: []这段配置说明了两点Fleet 采用spec-drivenschema每个产物生成时会把先读 .claude/CLAUDE.md 再起草的项目上下文注入产物的rules块。rules下留空的proposal/tasks列表会被静默跳过可以随时追加结构约定例如proposal下加一条- Include a Non-goals section.。此外openspec/README.md 补充了两条仓库约定撰写产物时需要注意产物是 Markdown与它们所描述的代码一起提交新产物中使用新术语Fleets不再叫 Teams、Reports不再叫 Queries现有代码保持原名称不变openspec/下的产物应视为文档而非契约代码评审仍是最终事实来源source of truth。七、从 propose 到实现与 apply 的衔接propose 的产出即 apply 的输入。openspec-apply-change 会读取contextFilesspec-driven schema 下为 proposal、specs、design、tasks按tasks.md中的任务清单逐个实现每完成一项把- [ ]勾选为- [x]直到全部完成或遇到阻塞。二者共同构成先文档、后代码的闭环explore思考→ proposeproposal/design/tasks→ apply按任务实现→ archive归档更新 specs按 openspec/README.md 的建议各步骤可以自由跳过多数变更只需propose apply小改动可能只用到explore。八、在 Fleet 开发中的实践要点结合技能与仓库配置在 Fleet 上使用openspec-propose时值得记住以下几点先装 CLI确保openspec在$PATHbrew install openspec否则斜杠命令无法生成产物。按需使用它是 opt-in 工具。单条 PR 描述能说清的改动直接写 PR 描述更快横跨 datastore / service / endpoint / UI 的大功能才值得走 propose。命名用 kebab-case变更名同时是目录名openspec/changes/name/例如add-user-auth。依赖顺序由 CLI 裁决不要猜测产物顺序以openspec status --change name --json返回的artifacts依赖关系为准逐个把ready产物推进到done。约束与内容分离context/rules是过程约束产物文件只保留模板填充后的实际内容。别手改 vendored 文件.claude/skills/openspec-*/与.claude/commands/opsx/归 OpenSpec CLI 所有openspec update会覆盖改动要定制就改 openspec/config.yaml。通过这套流程Fleet 团队可以在写任何代码之前先用 proposal / design / tasks 三份文档把变更的形状固定下来让人或 AI 都能在实现前评审、修订并达成共识——这正是 spec-driven 工作流在大型设备管理项目中的价值所在。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考