经实测验证100%可用的 OpenSpec 归档和多变更管理完整教程适合已经会基础 OpenSpec想提升效率的打工人 为什么要学归档和多变更管理用完 Explore、Propose、Apply 三个模式后你是不是遇到这些问题困惑 1变更完成后这堆文件放哪删了可惜留着乱困惑 2同时搞 3 个 feature目录结构一团糟困惑 3同事问我上周做的那个接口改了什么翻半天代码困惑 4想回滚某个变更不知道哪些文件是那次改的今天教你 ** Archive 模式 多变更管理**实测可用一步到位解决 Part 1归档实战——变更完成后必做场景回顾上一期我们完成了add-agent-memory变更目录长这样openspec/ ├── changes/ │ └── add-agent-memory/ ← 还在 active 状态 │ ├── proposal.md │ ├── design.md │ ├── specs/ │ └── tasks.md └── configs/ └── common/变更已经测试通过代码已提交到 Git这时候该归档了。Step 1检查变更状态openspec status--changeadd-agent-memory输出Change: add-agent-memory Schema: spec-driven Progress: 4/4 artifacts complete [x] proposal [x] design [x] specs [x] tasks All artifacts complete!⚠️注意openspec status需要指定--change参数否则会报错提示Missing required option --changeStep 2执行归档openspec archive add-agent-memoryOpenSpec 会提示要更新 specsTask status: ✓ Complete Specs to update: session-memory: create ? Proceed with spec updates? (Y/n)按Y确认后归档完成Applying changes to openspec/specs/session-memory/spec.md: 4 added Totals: 4, ~ 0, - 0, → 0 Specs updated successfully. Change add-agent-memory archived as 2026-05-24-add-agent-memory.自动跳过确认如果不想每次确认使用openspec archive -y add-agent-memory-y表示 yesStep 3目录结构变了归档后的真实目录结构openspec/ ├── changes/ │ └── archive/ ← 归档在 changes/ 下 │ └── 2026-05-24-add-agent-memory/ ← 带日期前缀 ✅ │ ├── .openspec.yaml │ ├── proposal.md │ ├── design.md │ ├── tasks.md │ └── specs/ │ └── session-memory/ │ └── spec.md ├── specs/ ← 主 specs 目录 │ └── session-memory/ ← 归档时自动创建 │ └── spec.md └── configs/ └── common/⚠️重要点归档目录在openspec/changes/archive/不是openspec/archive/归档后的变更名自动加日期前缀YYYY-MM-DD-change-name归档不会生成SUMMARY.md所有原始文档都保留Step 4查看归档文档虽然不会自动生成 SUMMARY但原始文档都有直接查看即可# 查看设计文档了解做了什么catopenspec/changes/archive/2026-05-24-add-agent-memory/design.md# 查看任务清单了解完成了哪些catopenspec/changes/archive/2026-05-24-add-agent-memory/tasks.md# 查看主 specs归档时更新catopenspec/specs/session-memory/spec.mdStep 5查看所有活跃变更归档后用list命令查看当前还有哪些未归档的变更openspec list输出No active changes found.如果还有其他变更会列出名称和进度。 Part 2多变更管理——同时开发 3 个功能场景设定假设你的团队想做 3 件事变更 Aadd-color-theme增加主题切换变更 Badd-notification消息通知变更 Cadd-analytics埋点统计Step 1创建多个变更openspec new change add-color-theme openspec new change add-notification openspec new change add-analyticsOpenSpec 自动创建并行目录openspec/ ├── changes/ │ ├── add-color-theme/ ← 变更 A │ │ ├── proposal.md │ │ ├── design.md │ │ ├── specs/ │ │ │ └── color-theme/ │ │ │ └── spec.md │ │ └── tasks.md │ ├── add-notification/ ← 变更 B │ │ ├── proposal.md │ │ ├── design.md │ │ ├── specs/ │ │ │ └── notification/ │ │ │ └── spec.md │ │ └── tasks.md │ └── add-analytics/ ← 变更 C │ ├── proposal.md │ ├── design.md │ ├── specs/ │ │ └── analytics/ │ │ └── spec.md │ └── tasks.mdStep 2查看所有变更状态openspec list输出add-analytics add-color-theme add-notification查看具体某个变更的完成度openspec status--changeadd-color-theme输出Change: add-color-theme Schema: spec-driven Progress: 4/4 artifacts complete [x] proposal [x] design [x] specs [x] tasks All artifacts complete!Step 3按优先级逐个实施假设团队决定先做 theme最紧急再做 notification中等最后 analytics低优先级。实施变更 Acolor-theme# 切换到这个变更的工作流cd你的项目目录# 跟 AI 说开始实施 add-color-theme 变更AI 会自动加载changes/add-color-theme/tasks.md逐个执行。任务状态会实时更新到tasks.md文件中用- [x]标记完成的任务。暂停变更 A切换到变更 B做了一半发现 theme 需要等 UI 组的素材切换到另一个变更# 跟 AI 说切换到 add-notification 变更# AI 会加载新的 tasks.md当前状态保存在各自的tasks.md中下次回来直接看文件就知道进度。Step 4逐个归档归档变更 A# 检查状态openspec status--changeadd-color-theme# 归档openspec archive-yadd-color-theme输出Change add-color-theme archived as 2026-05-24-add-color-theme.归档变更 Bopenspec archive-yadd-notification输出Change add-notification archived as 2026-05-24-add-notification.归档变更 Copenspec archive-yadd-analytics输出Change add-analytics archived as 2026-05-24-add-analytics.最终目录结构openspec/ ├── changes/ │ └── archive/ ← 所有归档变更都在这里 │ ├── 2026-05-24-add-agent-memory/ ← 之前的变更 │ │ ├── proposal.md │ │ ├── design.md │ │ ├── tasks.md │ │ └── .openspec.yaml │ ├── 2026-05-24-add-color-theme/ ← 新归档的 │ ├── 2026-05-24-add-notification/ ← 新归档的 │ └── 2026-05-24-add-analytics/ ← 新归档的 ├── specs/ ← 主规格文档 │ ├── session-memory/ │ ├── color-theme/ │ ├── notification/ │ └── analytics/ └── configs/ └── common/【配图建议 截图7最终目录结构的清晰展示】 Part 3真实可用的命令总结归档相关命令功能说明openspec status --change name查看变更状态显示任务完成度openspec archive name归档变更会提示更新 specsopenspec archive -y name归档变更跳过确认推荐用这个openspec list列出所有活跃变更查看哪些还没归档查看文档# 查看归档变更的设计文档catopenspec/changes/archive/YYYY-MM-DD-name/design.md# 查看任务清单catopenspec/changes/archive/YYYY-MM-DD-name/tasks.md# 查看主规格文档catopenspec/specs/spec-name/spec.md创建变更openspec new changechange-name Part 4实战中的坑 解决方案坑 1归档后找不到变更问题归档后用openspec show add-agent-memory找不到了原因: 归档后的变更名会加日期前缀而且目录位置变了解决方案# 直接查看文件catopenspec/changes/archive/2026-05-24-add-agent-memory/proposal.md# 或用 find 搜索findopenspec/changes/archive-name*.md坑 2多个变更改同一个文件问题theme 和 notification 都要改同一个文件不知道怎么处理解决方案先用 Explore 模式跟 AI 讨论确定优先级把高优先级的先实施、先归档或者创建一个包含所有需求的综合变更没有自动冲突检测功能需要团队自己协调。坑 3变更做到一半被打断问题任务做到 3/7下班了解决方案进度保存在tasks.md文件中。下次回来# 直接看任务的勾选状态catopenspec/changes/xxx-change/tasks.md# 继续跟 AI 说继续做 add-color-theme# AI 会读取 tasks.md 知道进度坑 4归档日期错误问题归档后的日期是2026-05-24未来年份原因: 系统时间设置问题解决方案归档名称只是唯一的标识不影响功能。如果在意可以手动重命名目录mvopenspec/changes/archive/2026-05-24-xxx\openspec/changes/archiv/2025-05-24-xxx坑 5归档后 specs 更新失败问题归档时提示 spec 更新失败原因: 可能是文件权限或路径问题解决方案使用--skip-specs跳过 spec 更新openspec archive-y--skip-specs add-agent-memory⚠️ 跳过后需要手动更新主 specs 真实能力 vs 期望能力❌ OpenSpec 不支持的功能容易误解功能会不会说明自动生成 SUMMARY.md❌不会生成总结文档openspec list archive❌没有这样的命令openspec search archive❌没有搜索功能openspec report archive❌没有报表功能openspec archive cleanup❌没有清理命令openspec archive export❌没有导出命令自动冲突检测❌需要团队协调✅ OpenSpec 真实能做的归档变更将完成的变更从changes/移到changes/archive/自动加日期前缀避免名称冲突更新主 specs将变更中的 spec 同步到openspec/specs/保留所有文档proposal、design、tasks、specs 都原样保留并列管理多个变更可以同时创建多个变更逐个实施 3 个最实际的好处清晰的目录结构——归档后changes/目录干干净净所有历史变更都有序存储在changes/archive/规格文档自动同步——归档时自动把变更的 spec 更新到主目录保证规格和实现一致任务进度可视化——tasks.md里- [x]标记的任务状态一目了然知道做到哪了 团队协作建议建议 1把 openspec 提交到 Git# 归档完成后gitaddopenspec/gitcommit-mArchive add-agent-memory changegitpushOpenSpec 的变更文档是团队协作的核心资产应该纳入版本管理建议 2归档后写一个简短的发布说明虽然不自动生成 SUMMARY但团队可以约定在归档目录下加一个简短的 READMEtouchopenspec/changes/archive/2026-05-24-add-memory/README.md内容# 归档add-agent-memory **日期**: 2026-05-24 **开发者**: 你的名字 **功能**: 为 RAG Agent 添加会话记忆 ## 改动文件 - backend/rag.py - backend/app.py - static/app.js ## 测试结果 - 多轮对话联调 ✅ - Session 隔离测试 ✅建议 3定期清理旧的归档手动删除过期的归档# 删除 6 个月前的归档findopenspec/changes/archive/-name2025-11-*-execrm-rf{}# 或压缩备份tar-czf~/backup/openspec-archive-2025Q4.tar.gz\openspec/changes/archive/2025-10-*\openspec/changes/archive/2025-11-*\openspec/changes/archive/2025-12-* 资源OpenSpec 官网openspec.devGitHubgithub.com/Fission-AI/OpenSpec完整命令文档openspec --help 本教程经过实测验证所有命令都是真实可用的有不懂的欢迎评论区提问~觉得有用就点赞收藏关注三连 转发给你的打工人朋友OpenSpec 踩坑少一半#OpenSpec #AI编程 #开发效率 #程序员工具 #技术教程 #真实可用
OpenSpec进阶实战！归档多变更管理全流程保姆级教程
经实测验证100%可用的 OpenSpec 归档和多变更管理完整教程适合已经会基础 OpenSpec想提升效率的打工人 为什么要学归档和多变更管理用完 Explore、Propose、Apply 三个模式后你是不是遇到这些问题困惑 1变更完成后这堆文件放哪删了可惜留着乱困惑 2同时搞 3 个 feature目录结构一团糟困惑 3同事问我上周做的那个接口改了什么翻半天代码困惑 4想回滚某个变更不知道哪些文件是那次改的今天教你 ** Archive 模式 多变更管理**实测可用一步到位解决 Part 1归档实战——变更完成后必做场景回顾上一期我们完成了add-agent-memory变更目录长这样openspec/ ├── changes/ │ └── add-agent-memory/ ← 还在 active 状态 │ ├── proposal.md │ ├── design.md │ ├── specs/ │ └── tasks.md └── configs/ └── common/变更已经测试通过代码已提交到 Git这时候该归档了。Step 1检查变更状态openspec status--changeadd-agent-memory输出Change: add-agent-memory Schema: spec-driven Progress: 4/4 artifacts complete [x] proposal [x] design [x] specs [x] tasks All artifacts complete!⚠️注意openspec status需要指定--change参数否则会报错提示Missing required option --changeStep 2执行归档openspec archive add-agent-memoryOpenSpec 会提示要更新 specsTask status: ✓ Complete Specs to update: session-memory: create ? Proceed with spec updates? (Y/n)按Y确认后归档完成Applying changes to openspec/specs/session-memory/spec.md: 4 added Totals: 4, ~ 0, - 0, → 0 Specs updated successfully. Change add-agent-memory archived as 2026-05-24-add-agent-memory.自动跳过确认如果不想每次确认使用openspec archive -y add-agent-memory-y表示 yesStep 3目录结构变了归档后的真实目录结构openspec/ ├── changes/ │ └── archive/ ← 归档在 changes/ 下 │ └── 2026-05-24-add-agent-memory/ ← 带日期前缀 ✅ │ ├── .openspec.yaml │ ├── proposal.md │ ├── design.md │ ├── tasks.md │ └── specs/ │ └── session-memory/ │ └── spec.md ├── specs/ ← 主 specs 目录 │ └── session-memory/ ← 归档时自动创建 │ └── spec.md └── configs/ └── common/⚠️重要点归档目录在openspec/changes/archive/不是openspec/archive/归档后的变更名自动加日期前缀YYYY-MM-DD-change-name归档不会生成SUMMARY.md所有原始文档都保留Step 4查看归档文档虽然不会自动生成 SUMMARY但原始文档都有直接查看即可# 查看设计文档了解做了什么catopenspec/changes/archive/2026-05-24-add-agent-memory/design.md# 查看任务清单了解完成了哪些catopenspec/changes/archive/2026-05-24-add-agent-memory/tasks.md# 查看主 specs归档时更新catopenspec/specs/session-memory/spec.mdStep 5查看所有活跃变更归档后用list命令查看当前还有哪些未归档的变更openspec list输出No active changes found.如果还有其他变更会列出名称和进度。 Part 2多变更管理——同时开发 3 个功能场景设定假设你的团队想做 3 件事变更 Aadd-color-theme增加主题切换变更 Badd-notification消息通知变更 Cadd-analytics埋点统计Step 1创建多个变更openspec new change add-color-theme openspec new change add-notification openspec new change add-analyticsOpenSpec 自动创建并行目录openspec/ ├── changes/ │ ├── add-color-theme/ ← 变更 A │ │ ├── proposal.md │ │ ├── design.md │ │ ├── specs/ │ │ │ └── color-theme/ │ │ │ └── spec.md │ │ └── tasks.md │ ├── add-notification/ ← 变更 B │ │ ├── proposal.md │ │ ├── design.md │ │ ├── specs/ │ │ │ └── notification/ │ │ │ └── spec.md │ │ └── tasks.md │ └── add-analytics/ ← 变更 C │ ├── proposal.md │ ├── design.md │ ├── specs/ │ │ └── analytics/ │ │ └── spec.md │ └── tasks.mdStep 2查看所有变更状态openspec list输出add-analytics add-color-theme add-notification查看具体某个变更的完成度openspec status--changeadd-color-theme输出Change: add-color-theme Schema: spec-driven Progress: 4/4 artifacts complete [x] proposal [x] design [x] specs [x] tasks All artifacts complete!Step 3按优先级逐个实施假设团队决定先做 theme最紧急再做 notification中等最后 analytics低优先级。实施变更 Acolor-theme# 切换到这个变更的工作流cd你的项目目录# 跟 AI 说开始实施 add-color-theme 变更AI 会自动加载changes/add-color-theme/tasks.md逐个执行。任务状态会实时更新到tasks.md文件中用- [x]标记完成的任务。暂停变更 A切换到变更 B做了一半发现 theme 需要等 UI 组的素材切换到另一个变更# 跟 AI 说切换到 add-notification 变更# AI 会加载新的 tasks.md当前状态保存在各自的tasks.md中下次回来直接看文件就知道进度。Step 4逐个归档归档变更 A# 检查状态openspec status--changeadd-color-theme# 归档openspec archive-yadd-color-theme输出Change add-color-theme archived as 2026-05-24-add-color-theme.归档变更 Bopenspec archive-yadd-notification输出Change add-notification archived as 2026-05-24-add-notification.归档变更 Copenspec archive-yadd-analytics输出Change add-analytics archived as 2026-05-24-add-analytics.最终目录结构openspec/ ├── changes/ │ └── archive/ ← 所有归档变更都在这里 │ ├── 2026-05-24-add-agent-memory/ ← 之前的变更 │ │ ├── proposal.md │ │ ├── design.md │ │ ├── tasks.md │ │ └── .openspec.yaml │ ├── 2026-05-24-add-color-theme/ ← 新归档的 │ ├── 2026-05-24-add-notification/ ← 新归档的 │ └── 2026-05-24-add-analytics/ ← 新归档的 ├── specs/ ← 主规格文档 │ ├── session-memory/ │ ├── color-theme/ │ ├── notification/ │ └── analytics/ └── configs/ └── common/【配图建议 截图7最终目录结构的清晰展示】 Part 3真实可用的命令总结归档相关命令功能说明openspec status --change name查看变更状态显示任务完成度openspec archive name归档变更会提示更新 specsopenspec archive -y name归档变更跳过确认推荐用这个openspec list列出所有活跃变更查看哪些还没归档查看文档# 查看归档变更的设计文档catopenspec/changes/archive/YYYY-MM-DD-name/design.md# 查看任务清单catopenspec/changes/archive/YYYY-MM-DD-name/tasks.md# 查看主规格文档catopenspec/specs/spec-name/spec.md创建变更openspec new changechange-name Part 4实战中的坑 解决方案坑 1归档后找不到变更问题归档后用openspec show add-agent-memory找不到了原因: 归档后的变更名会加日期前缀而且目录位置变了解决方案# 直接查看文件catopenspec/changes/archive/2026-05-24-add-agent-memory/proposal.md# 或用 find 搜索findopenspec/changes/archive-name*.md坑 2多个变更改同一个文件问题theme 和 notification 都要改同一个文件不知道怎么处理解决方案先用 Explore 模式跟 AI 讨论确定优先级把高优先级的先实施、先归档或者创建一个包含所有需求的综合变更没有自动冲突检测功能需要团队自己协调。坑 3变更做到一半被打断问题任务做到 3/7下班了解决方案进度保存在tasks.md文件中。下次回来# 直接看任务的勾选状态catopenspec/changes/xxx-change/tasks.md# 继续跟 AI 说继续做 add-color-theme# AI 会读取 tasks.md 知道进度坑 4归档日期错误问题归档后的日期是2026-05-24未来年份原因: 系统时间设置问题解决方案归档名称只是唯一的标识不影响功能。如果在意可以手动重命名目录mvopenspec/changes/archive/2026-05-24-xxx\openspec/changes/archiv/2025-05-24-xxx坑 5归档后 specs 更新失败问题归档时提示 spec 更新失败原因: 可能是文件权限或路径问题解决方案使用--skip-specs跳过 spec 更新openspec archive-y--skip-specs add-agent-memory⚠️ 跳过后需要手动更新主 specs 真实能力 vs 期望能力❌ OpenSpec 不支持的功能容易误解功能会不会说明自动生成 SUMMARY.md❌不会生成总结文档openspec list archive❌没有这样的命令openspec search archive❌没有搜索功能openspec report archive❌没有报表功能openspec archive cleanup❌没有清理命令openspec archive export❌没有导出命令自动冲突检测❌需要团队协调✅ OpenSpec 真实能做的归档变更将完成的变更从changes/移到changes/archive/自动加日期前缀避免名称冲突更新主 specs将变更中的 spec 同步到openspec/specs/保留所有文档proposal、design、tasks、specs 都原样保留并列管理多个变更可以同时创建多个变更逐个实施 3 个最实际的好处清晰的目录结构——归档后changes/目录干干净净所有历史变更都有序存储在changes/archive/规格文档自动同步——归档时自动把变更的 spec 更新到主目录保证规格和实现一致任务进度可视化——tasks.md里- [x]标记的任务状态一目了然知道做到哪了 团队协作建议建议 1把 openspec 提交到 Git# 归档完成后gitaddopenspec/gitcommit-mArchive add-agent-memory changegitpushOpenSpec 的变更文档是团队协作的核心资产应该纳入版本管理建议 2归档后写一个简短的发布说明虽然不自动生成 SUMMARY但团队可以约定在归档目录下加一个简短的 READMEtouchopenspec/changes/archive/2026-05-24-add-memory/README.md内容# 归档add-agent-memory **日期**: 2026-05-24 **开发者**: 你的名字 **功能**: 为 RAG Agent 添加会话记忆 ## 改动文件 - backend/rag.py - backend/app.py - static/app.js ## 测试结果 - 多轮对话联调 ✅ - Session 隔离测试 ✅建议 3定期清理旧的归档手动删除过期的归档# 删除 6 个月前的归档findopenspec/changes/archive/-name2025-11-*-execrm-rf{}# 或压缩备份tar-czf~/backup/openspec-archive-2025Q4.tar.gz\openspec/changes/archive/2025-10-*\openspec/changes/archive/2025-11-*\openspec/changes/archive/2025-12-* 资源OpenSpec 官网openspec.devGitHubgithub.com/Fission-AI/OpenSpec完整命令文档openspec --help 本教程经过实测验证所有命令都是真实可用的有不懂的欢迎评论区提问~觉得有用就点赞收藏关注三连 转发给你的打工人朋友OpenSpec 踩坑少一半#OpenSpec #AI编程 #开发效率 #程序员工具 #技术教程 #真实可用
