Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00
parent 0e0275d46a
commit f45122dafb
83 changed files with 9733 additions and 15 deletions
@@ -0,0 +1,106 @@
+# 归档规则
+
+Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
+
+## 目录规则
+
+项目档案路径：
+
+```text
+devflow/projects/YYYY-MM-DD-{slug}/
+```
+
+默认创建以下必要文件：
+
+- `brief.md`
+- `evidence.md`
+- `decisions.md`
+- `acceptance.md`
+
+按需创建以下扩展文件：
+
+- `prd.md`
+- `research.md`
+- `design.md`
+- `tasks.md`
+- `alignment.md`
+- `adr/*.md`
+
+不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。
+
+## 产物分档
+
+| 分档 | 适用场景 | 必须文件 | 扩展文件 |
+| --- | --- | --- | --- |
+| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` |
+| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound |
+| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.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` |
+| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
+| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
+| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
+| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
+| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.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 的关键执行信息：
+
+- Phase 4 可以建议 archive，但必须先询问用户。
+- 在用户确认前，不要执行 archive。
+- 如果用户暂不归档，在 acceptance 中记录原因或状态。
+- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
+
+## 归档交接
+
+Phase 4 结束时告诉用户：
+
+- 创建或更新了哪些档案文件。
+- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
+- 还剩哪些风险或后续事项。
+- 明确询问：是否现在 archive OpenSpec change？
+
+