📌Spec-Driven Develop是一个面向 AI Coding Agent 的规范驱动开发工作流。它的进度导出功能可一键把开发进度同步为结构化 JSON，轻松导入 Linear、Jira、Notion 等项目管理工具；配套的Archive 归档机制则会在项目收尾时自动把分析、计划、进度文档存档留痕，方便日后溯源。本教程带你完整掌握这套"进度外同步 + 归档留痕"的组合拳。

为什么需要进度导出与归档？

用 AI Coding Agent 做大型改造（重写、迁移、重构）时，进度往往散落在 Markdown 文件里：

• ❌ 团队协作时，进度只存在于MASTER.md的复选框中，其他成员在 Linear/Jira 上看不到
• ❌ 项目做完后，分析文档、任务分解、进度记录被删除，出了问题无法回溯
• ❌ 换平台（比如从 Cursor 换到 Claude Code）后，之前的规划数据难以迁移

Spec-Driven Develop 用两个轻量机制解决了这些问题：

一键导出进度：把 MASTER.md 同步到 Linear / Jira

准备工作

先获取项目源码（仅需 Python 3 标准库，无任何第三方依赖）：

git clone https://gitcode.com/gh_mirrors/sp/spec_driven_develop

最快配置方法：一条命令生成结构化 JSON

进入你正在用工作流开发的项目目录，指向进度文件夹执行：

python scripts/export-progress.py docs/progress/

脚本会解析docs/progress/下的MASTER.md和各阶段明细文件，直接输出一棵完整的 JSON 数据树，包含：

• 项目元信息：任务名称、开始日期、最后更新时间
• 阶段列表：每个 Phase 的完成数 / 总任务数 / 完成标记
• 任务明细：每个 Task 的优先级（Priority）、工作量（Effort）、验收标准（Acceptance）
• 汇总摘要：总阶段数、总任务数、完成百分比（progress_percent）

导出逻辑的核心在 scripts/export-progress.py 的export_progress()函数（L109-L139）：它先解析 MASTER.md 的项目级元数据，再按phase-N-*.md文件名匹配补齐每个阶段的任务细节，最后计算出进度百分比。

导入外部工具

拿到 JSON 后，你可以：

1. Linear / Jira：通过它们的 API 或批量导入功能，把phases映射为 Epic / 里程碑，tasks映射为 Issue，priority、effort字段直接对应原生字段
2. Notion：导入为数据库视图，按done字段区分状态
3. 自建看板：summary.progress_percent一个字段就能驱动进度条

💡提示：脚本默认解析当前目录下的docs/progress/，也可以通过第一个参数指定任意进度目录路径，适合对历史归档进度做批量导出。

数据从哪来：MASTER.md 进度文件解析规则

导出的准确性取决于进度文件的规范性。工作流在 Phase 4 生成的进度文档遵循 progress.md 模板，其中两类结构化标记是解析的关键：

① 阶段复选框（位于 MASTER.md 的 Phase Checklist 区域）：

- [x] Phase 1: Adaptive Control Foundation (1/1 tasks) - [ ] Phase 2: Workflow Integration (2/4 tasks)

[x]/[ ]决定阶段是否完成，(N/M tasks)提供任务计数。

② 任务复选框（位于各阶段明细文件）：

- [ ] **Task 2.1**: 描述 - Priority: P0 - Effort: M - Acceptance: 如何验证完成

任务编号、优先级、工作量、验收标准都会被逐字段提取。这就是为什么保持工作流按模板更新进度文件，导出的数据就能自动保持与 Linear/Jira 同步——Markdown 文件就是"数据源"，JSON 只是它的结构化投影。

Archive 归档机制：项目收尾时的自动留痕

触发条件

当所有任务完成（GitHub 模式下所有 Issue 关闭，或 LOCAL_ONLY 模式下所有复选框勾选），工作流自动进入 SKILL.md 定义的Phase 6: Archive，执行 7 个标准动作：

1. 向用户宣布任务全部完成 🎉
2. 根据 Phase 2 确定的任务名生成规范化的目录名（小写、连字符）
3. 把工作产物整体迁移到docs/archives/<project-name>/
4. （GitHub 模式）关闭各 Phase 的 Milestone，保留为永久记录
5. 更新归档索引 docs/archives/README.md，只追加、不删除已有条目
6. 清理根目录下已搬空的analysis/、plan/、progress/目录
7. 建议用户把归档提交到版本控制

归档目录结构

归档目标结构定义在 archive.md 模板中：

docs/archives/<project-name>/ ├── analysis/ # 项目分析文档 ├── plan/ # 任务分解、依赖图、里程碑 ├── progress/ # MASTER.md 与阶段明细 ├── governance/ # 指令/记忆 surface 快照 └── skill/ # 任务专属 Skill（如有）

⚠️一个易踩的坑：根目录的AGENTS.md、CLAUDE.md等活跃治理文件归档后依然保留，归档目录里只是它们的"快照"。快照只负责留痕，不会干扰后续工作流继续运行。

真实案例：adaptive-control-layer 归档

本仓库就包含一份完整归档实例——docs/archives/adaptive-control-layer/。查看其 progress/MASTER.md 可以看到：

• Phase Checklist三个阶段全部[x]，任务数分别为 1/1、4/4、1/1
• Issue Mapping表记录了 6 个任务的最终状态（全部 closed）
• Session Log追加式记录了每次工作会话的摘要（"drift_score=0. Ready for archive"）

配合 plan/task-breakdown.md，半年后回看也能完整还原"当时为什么这么拆任务"——这就是归档留痕的价值：它不只是一堆文档，而是一份可执行的决策快照。

常见问题 FAQ

Q：进度导出会修改进度文件吗？不会。脚本是纯只读解析，安全可重复执行，适合放进 CI 定期生成 JSON。

Q：GitHub 模式下没有 phase-N-*.md 明细文件，还能导出吗？可以。GitHub 模式下任务状态主要在 Issue 中，MASTER.md 的 Phase Checklist 依然会被解析，phases的计数数据完整；tasks数组为空属于正常情况。

Q：归档后想恢复进度文件怎么办？直接git log找到归档提交即可；归档本身建议提交版本控制，这也是 Phase 6 最后一步的官方建议。

相关文件速查

✅小结：用export-progress.py把 Markdown 进度一键投影到 Linear/Jira 实现跨工具同步；用 Phase 6 Archive 把每次工作流完整留痕。两者都零依赖、纯 Markdown 驱动，是长周期 AI 协作开发中"数据不丢、状态可见"的完整闭环。