Web框架后端CLI【免费下载链接】gfA powerful framework for faster, easier, and more efficient project development.项目地址https://gitcode.com/GitHub_Trending/gf/gf点击查看免费下载本篇技术指南围绕当前仓库中.agents/prompts/opsx/archive.md定义的归档工作流展开系统讲解在 gfGoFrame项目基于 OpenSpec 的变更驱动开发SDD模式下如何在实验性工作流中把一个已完成迭代的变更change安全归档到openspec/changes/archive/。读完本文你将掌握变更选择、artifact 与任务完成度校验、delta spec 同步评估、归档执行与结果摘要输出的完整流程并能直接用于日常迭代收尾。一、为什么需要归档变更生命周期中的最后一环在 gf 仓库的开发工作流中任何非平凡的改动都由 OpenSpec 变更驱动。按照 AGENTS.md 中「Development Workflow Rules」的约定一次迭代的完整生命周期是/opsx:explore探索讨论 →/opsx:propose生成正式变更提案 →/opsx:apply逐项执行tasks.md中的任务 →/gf-review代码与规范评审 →/opsx:archive归档收尾。其中有一个关键规则值得强调一个 OpenSpec 变更在被归档之前始终视为 active活跃。即使openspec list --json已显示status: complete只要变更目录仍然直接位于openspec/changes/下、尚未被移动到openspec/changes/archive/就必须继续按活跃变更处理。因此归档不只是「收尾动作」更是变更生命周期中具有状态语义的正式步骤。/opsx:archive对应的提示词文件位于 .agents/prompts/opsx/archive.md与同目录下的 explore.md、propose.md、apply.md 共同构成一套完整的变更管理工作流。二、归档流程总览整个归档过程由六个顺序步骤构成每一步都有明确的输入、判断与输出可以看到归档并非一个单纯的mv命令而是一套「先校验、再确认、后移动、终汇报」的受控流程。三、输入规范与变更选择归档命令支持可选参数/opsx:archive add-auth显式提供变更名直接使用该名称进入校验流程未提供名称先尝试从对话上下文中推断当前正在处理的变更推断不明确或产生歧义必须运行openspec list --json获取全部可用变更并使用AskUserQuestion 工具让用户显式选择。文档明确要求只展示「尚未归档」的活跃变更并且如果可用同时展示每个变更所使用的 schema。这里有一条硬性护栏不要猜测或自动选择一个变更始终让用户自己决定Do NOT guess or auto-select a change。这一点与 propose.md 中「不明确就询问」的原则一脉相承确保归档操作永远作用于用户真正想要收尾的迭代。四、完成度校验artifact 与任务双重检查归档前需要确认变更的工作是否真正完成分两层校验4.1 检查 artifact 完成状态运行命令openspec status --change name --json解析返回的 JSON重点关注两个字段字段含义schemaName变更所使用的 workflflow例如spec-drivenartifactsartifact 列表每项带有done或其他状态如果存在未完成非done的 artifact不要直接拒绝归档而是显示警告列出所有未完成的 artifact向用户请求确认是否继续归档用户确认后继续执行。结合 propose.md 可以看到 artifact 体系的全貌一个变更通常包含proposal.md做什么、为什么、design.md怎么做、tasks.md实现步骤以及按 schema 定义的增量 spec 文档这些 artifact 之间存在依赖关系openspec status --json输出的applyRequires与artifacts数组正是驱动 propose 阶段按依赖顺序构建 artifact 的依据。4.2 检查任务完成状态读取任务文件通常为tasks.md统计任务完成情况统计- [ ]未完成与- [x]已完成的数量若存在未完成任务显示警告包含未完成数量请求用户确认后继续若不存在tasks.md文件直接跳过任务相关警告不阻塞归档流程。这里的核心设计原则是警告只是提示不构成归档的硬性阻塞。归档的目标是把已完成的工作沉淀下来即使存在少量遗留项也应当允许用户知情后自行决策。五、Delta Spec 同步评估归档前的关键决策点5.1 检查 delta spec 是否存在delta spec 位于变更目录下openspec/changes/name/specs/如果该目录不存在任何 delta spec则跳过同步提示直接进入归档执行。5.2 同步评估与提示若存在 delta spec需要逐一完成比对将每个 delta spec 与对应的主 spec 对比主 spec 位于openspec/specs/capability/spec.md分析会应用到主 spec 上的变更类型新增adds、修改modifications、删除removals、重命名renames在提示用户之前先展示一份合并后的变更摘要让用户清楚知道同步将产生什么影响。随后根据当前同步状态给出不同的选项组合场景提示选项需要同步存在未同步变更Sync now (recommended)/Archive without syncing已同步无待同步变更Archive now/Sync anyway/Cancel若用户选择同步文档给出的执行方式是使用Task 工具subagent_type: general-purpose调用Skill 工具触发openspec-sync-specs并将前面分析出的 delta spec 摘要一并传递给子代理提示语模板Use Skill tool to invoke openspec-sync-specs for change name. Delta spec analysis: include the analyzed delta spec summary无论用户是否选择同步最终都继续执行归档Proceed to archive regardless of choice只是摘要中会如实记录同步状态。六、执行归档目录创建、日期命名与冲突处理6.1 归档操作归档的核心操作分为三步# 1. 创建归档目录若不存在 mkdir -p openspec/changes/archive # 2. 生成目标名称使用当前日期前缀 # 格式YYYY-MM-DD-change-name # 3. 移动变更目录到归档目录 mv openspec/changes/name openspec/changes/archive/YYYY-MM-DD-name例如在 2026-10-01 归档add-auth变更目标路径即为openspec/changes/archive/2026-10-01-add-auth/6.2 目标冲突处理移动之前必须先检查目标目录是否已存在若已存在归档失败并报错文档给出三种处理建议重命名现有归档若现有归档是重复副本删除它需人工确认等待不同日期再执行归档。若不存在正常执行移动。6.3 配置随目录保留归档时不需要单独处理.openspec.yaml——它随整个变更目录一起移动从而完整保留该变更的 schema 与元数据。这正是文档护栏中「Preserve .openspec.yaml when moving to archiveit moves with the directory」的含义。七、结果输出四种标准摘要模板归档完成后必须向用户展示清晰的完成摘要文档定义了四种标准输出模板7.1 成功输出无警告## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** ✓ Synced to main specs All artifacts complete. All tasks complete.7.2 成功输出无 delta specs## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** No delta specs All artifacts complete. All tasks complete.7.3 成功输出带警告## Archive Complete (with warnings) **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** Sync skipped (user chose to skip) **Warnings:** - Archived with 2 incomplete artifacts - Archived with 3 incomplete tasks - Delta spec sync was skipped (user chose to skip) Review the archive if this was not intentional.该模板特别强调若这些警告并非有意为之应当复查归档内容。7.4 错误输出归档目标已存在## Archive Failed **Change:** change-name **Target:** openspec/changes/archive/YYYY-MM-DD-name/ Target archive directory already exists. **Options:** 1. Rename the existing archive 2. Delete the existing archive if its a duplicate 3. Wait until a different date to archive摘要中必须覆盖的信息包括变更名称、使用的 schema、归档位置、spec 同步状态已同步 / 跳过同步 / 无 delta spec以及任何警告未完成 artifact / 任务的说明。八、Guardrails归档流程的七条铁律文档在末尾总结了归档流程必须遵守的护栏规则它们是整个流程正确性的保障护栏说明始终提示变更选择未提供变更名时必须让用户选择绝不猜测或自动选取使用 artifact 图校验完成度检查以openspec status --json的 artifact 状态为准警告不阻塞归档发现未完成项仅需告知并确认不得阻止归档保留.openspec.yaml移动目录时配置随目录保留无需单独处理展示清晰摘要无论成败都要向用户完整交代发生了什么同步走 Skill 工具若执行同步通过 Skill 工具调用openspec-sync-specsagent 驱动同步前必先评估只要存在 delta spec必须先做同步评估并展示合并摘要再请求用户确认九、归档在 gf 开发工作流中的位置结合 AGENTS.md 中的流程规则归档是每次迭代收尾的强制环节且前后衔接紧密用户在/opsx:apply完成后收到「All tasks complete! You can archive this change with/opsx:archive」的提示见 apply.md 的输出模板归档执行前必须先用/gf-review技能完成一次完整的变更评审确保代码质量与 spec 一致性归档后该变更目录移出openspec/changes/活跃区其生命周期正式结束新的迭代可以基于主 spec 继续推进。值得注意的是归档时同步 delta spec 的动作会让openspec/specs/capability/spec.md主规范吸收本次迭代沉淀的新需求这正是「spec-driven」工作流的核心价值每一次归档不仅是代码的收尾也是项目规范资产的持续演进。十、小结/opsx:archive用一套简洁而完整的六步流程把「归档一个变更」从危险的裸mv提升为受控、可审计、可追溯的正式操作。它通过三层校验artifact 状态、任务状态、delta spec 同步状态在归档前暴露风险通过标准化的摘要模板在归档后呈现结果再以七条护栏兜住所有边界情况。对于采用 OpenSpec 变更驱动开发的团队这套模式可以直接作为迭代收尾的标准参考实现。赞分享Web框架后端CLI【免费下载链接】gfA powerful framework for faster, easier, and more efficient project development.项目地址https://gitcode.com/GitHub_Trending/gf/gf点击查看免费下载相关推荐Druid 仓库 OpenSpec 实验工作流实战使用 /opsx:archive 归档已完成变更Druid 仓库 OpenSpec 实验工作流实战使用 /opsx:archive 归档已完成变更 本文以 .cursor/commands/opsx arc数据库后端Fleet 仓库中的 OpenSpec 变更归档工作流/opsx:archive 命令完整解析与实践指南Fleet 仓库中的 OpenSpec 变更归档工作流 /opsx:archive 命令完整解析与实践指南 本指南以 Fleet 开源仓库中的 /opsx:a后端前端企业应用运维网络安全OpenSpec 变更归档工作流实战基于 openspec-archive-change 技能将已完成变更安全归档OpenSpec 变更归档工作流实战基于 openspec archive change 技能将已完成变更安全归档 导读 openspec archive c数据库灾备上一篇5分钟快速上手免费在线无人机日志分析工具UAV Log Viewer终极指南下一篇Slang 目标管线索引导读读懂 linkAndOptimizeIR 的按目标过滤视图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考