168 lines
6.6 KiB
Markdown
168 lines
6.6 KiB
Markdown
# 归档规则
|
||
|
||
archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。
|
||
|
||
## Archive 强制执行顺序
|
||
|
||
Archive 阶段必须按以下顺序执行，不得跳过或重排：
|
||
|
||
### Step 1: 创建 devflow 档案（必需）
|
||
|
||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
|
||
（从 proposal.md 提取：背景、目标、范围、非目标）
|
||
|
||
- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
|
||
（创建时从 decisions.md 提取 evidence-driven 记录）
|
||
|
||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
|
||
（整理为最终版：关键决策、权衡、风险）
|
||
|
||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
|
||
（记录：静态验证、脚本验证、浏览器/人工验证、未验证）
|
||
|
||
### Step 2: 更新索引（必需）
|
||
|
||
- [ ] 在 `devflow/index.md` 末尾追加或更新一行：
|
||
`| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | {status} |`
|
||
|
||
### Step 3: 标记 OpenSpec（必需）
|
||
|
||
- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
|
||
|
||
### Step 4: 向用户汇报（必需）
|
||
|
||
- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在于磁盘）
|
||
- [ ] 汇报验证情况（按静态验证、脚本验证、浏览器/人工验证、未验证分类）
|
||
- [ ] 列出剩余风险或后续事项
|
||
- [ ] 询问：**是否现在归档 OpenSpec？**
|
||
|
||
### Step 5: 用户确认后执行 OpenSpec Archive（可选）
|
||
|
||
- [ ] 调用 `openspec-archive-change`
|
||
- [ ] 记录 archive 结果
|
||
|
||
**自检**：在执行 Step 4 前，检查 Step 1-3 是否都完成。
|
||
|
||
---
|
||
|
||
## 目录规则
|
||
|
||
项目档案路径：
|
||
|
||
```text
|
||
devflow/projects/YYYY-MM-DD-{slug}/
|
||
```
|
||
|
||
archive 阶段按 `references/scales.md` 的当前分档创建以下文件：
|
||
|
||
- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
|
||
- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
|
||
- `decisions.md`：保持为最终版，整理格式。
|
||
- `acceptance.md`：从实现结果和验证结果提取。
|
||
|
||
同时维护仓库级索引：
|
||
|
||
- `devflow/index.md`
|
||
|
||
按需创建以下扩展文件：
|
||
|
||
- `prd.md`
|
||
- `research.md`
|
||
- `design.md`
|
||
- `tasks.md`
|
||
- `alignment.md`
|
||
- `adr/*.md`
|
||
|
||
不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。
|
||
|
||
## 产物分档
|
||
|
||
分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 archive 阶段的创建顺序、提取映射和索引规则。
|
||
|
||
## 提取映射
|
||
|
||
| 来源 | 提取内容 | 写入位置 |
|
||
| --- | --- | --- |
|
||
| `decisions.md`（过程日志） | question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍 | `decisions.md`（整理格式为最终版） |
|
||
| `decisions.md`（过程日志） | evidence-driven 结论、代码/文档证据 | `evidence.md` |
|
||
| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
|
||
| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
|
||
| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
|
||
| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
|
||
| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
|
||
| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
|
||
| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
|
||
| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||
| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
|
||
|
||
## 索引维护规则
|
||
|
||
`devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。
|
||
|
||
最小字段：
|
||
|
||
| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
|
||
规则：
|
||
|
||
- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
|
||
- archive 阶段新建或更新项目档案时，必须新增或更新对应行。
|
||
- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
|
||
- 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
|
||
- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
|
||
|
||
## 验收记录规则
|
||
|
||
必须真实记录验证情况，并按类型分类：
|
||
|
||
- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。
|
||
- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。
|
||
- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。
|
||
- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。
|
||
|
||
记录要求：
|
||
|
||
- 如果验证通过，记录命令/步骤和覆盖范围。
|
||
- 如果验证失败，记录失败摘要和是否阻塞验收。
|
||
- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
|
||
|
||
## ADR 规则
|
||
|
||
同时满足以下条件时创建 ADR：
|
||
|
||
1. 决策难以逆转。
|
||
2. 缺少上下文会让未来维护者困惑。
|
||
3. 决策来自真实权衡，而不是简单偏好。
|
||
|
||
项目内 ADR 存放于：
|
||
|
||
```text
|
||
devflow/projects/YYYY-MM-DD-{slug}/adr/
|
||
```
|
||
|
||
跨项目可复用决策或经验存放于：
|
||
|
||
```text
|
||
devflow/compound/YYYY-MM-DD-decision-{slug}.md
|
||
```
|
||
|
||
## 归档确认
|
||
|
||
OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
|
||
|
||
- archive 阶段可以建议 archive，但必须先询问用户。
|
||
- 在用户确认前，不要执行 archive。
|
||
- 如果用户暂不归档，在 acceptance 中记录原因或状态。
|
||
- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
|
||
|
||
## 归档交接
|
||
|
||
archive 阶段结束时告诉用户：
|
||
|
||
- 创建或更新了哪些档案文件。
|
||
- `devflow/index.md` 是否已更新。
|
||
- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
|
||
- 还剩哪些风险或后续事项。
|
||
- 明确询问：是否现在 archive OpenSpec change？
|