4.0 KiB
4.0 KiB
归档规则
Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
目录规则
项目档案路径：
devflow/projects/YYYY-MM-DD-{slug}/
默认创建以下必要文件：
brief.mdevidence.mddecisions.mdacceptance.md
按需创建以下扩展文件：
prd.mdresearch.mddesign.mdtasks.mdalignment.mdadr/*.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：
- 决策难以逆转。
- 缺少上下文会让未来维护者困惑。
- 决策来自真实权衡，而不是简单偏好。
项目内 ADR 存放于：
devflow/projects/YYYY-MM-DD-{slug}/adr/
跨项目可复用决策或经验存放于：
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？