ADR 0004: 文档同步流程与任务目录组织
状态: Proposed 日期: 2026-07-10 上级: ADR 0003
背景
项目当前存在两个组织性问题：
- 任务目录混乱：
docs/dev/tasks/下 14 个.md文件平铺，分别属于 "docs-and-pages" 和 "vitepress-migration" 两个 feature，无法区分归属、依赖关系和创建顺序 - 文档同步缺失：代码变更后
docs/guides/用户文档没有同步机制，可能导致文档与代码脱节
决策
1. 任务目录采用 YYYY-MM-DD-NNN-slug/ 命名格式
格式：YYYY-MM-DD-NNN-slug/，如 2026-07-09-001-docs-and-pages/
选择理由：
| 方案 | 排序 | 可读性 | 扩展性 | 结论 |
|---|---|---|---|---|
NNN-slug/（仅编号） | 按编号无序（编号可能跨天） | 简洁 | 同一天多个 feature 时编号冲突 | ❌ |
YYYY-MM-DD-slug/（日期+slug） | 按时间排序 | 清晰 | 同一天多个 feature 无法区分 | ❌ |
YYYY-MM-DD-NNN-slug/（日期+编号+slug） | 字典序=时间序 | 清晰 | 每天独立编号，无限扩展 | ✅ |
关键点：
YYYY-MM-DD放在最前面，利用字符串字典序等于时间序的特性，无需额外排序逻辑NNN从001开始，每天独立递增，解决同一天多个 feature 的命名冲突slug提供人类可读的描述，方便git mv后快速定位
备选方案：
- 纯编号（
001-docs-and-pages/）：简洁但跨天时编号不连续，排序无意义 - UUID 前缀：完全放弃可读性，不适合人工浏览的目录结构
2. 设计态（tasks/）与实现态（changelog/）分离
决策：新增 docs/dev/changelog/ 目录，与 docs/dev/tasks/ 分离。
设计态（tasks/）：
- 记录原始设计意图和任务拆解
- 在
/design和/tasks阶段创建 - 一旦创建，不再修改（保留设计原貌）
实现态（changelog/）：
- 记录实际实现与设计的偏差
- 在
/review阶段由 reviewer 追加 - 每个 feature 一个 changelog 文件，生命周期与 feature 绑定
分离理由：
- 保留原始设计意图，便于复盘和审计
- 避免在同文件中混入"设计"和"实际"导致信息混乱
- 变更追溯清晰：tasks 看设计，changelog 看偏差
备选方案：
- 在 task 文件中直接追加偏差记录：会污染原始设计，不利于对比
- 不记录偏差：失去可追溯性，不符合工程实践
3. 文档同步嵌入 flow-code 而非独立 command
决策：将文档同步检查作为 flow-code 技能内的固定步骤，而非独立的 /doc-sync 命令。
理由：
- 文档同步是编码流程的有机组成部分，不是独立活动
- 独立 command 增加认知负担（8 个变 9 个 command），且容易遗漏
- 嵌入 flow-code 确保每次编码后自动触发检查，无需开发者记忆
- 符合"一个 slash command 完成一件事"的设计原则
备选方案：
- 独立
/doc-sync命令：增加命令数量，且可能被跳过 - 嵌入 flow-review：发现太晚，应在编码阶段就完成同步
4. 人工 checklist 而非自动检测
决策：文档同步使用人工 checklist 评估，不做自动检测。
理由：
- 代码变更与文档影响的映射本质上是语义判断，无法机械推导
- 自动检测需要维护代码→文档的映射规则，投入产出比低
- 人工 checklist 简单可靠，开发者最了解自己的变更影响范围
- 对于 4 个 guides 文档的规模，人工评估成本极低
未来扩展：当文档规模增长到 20+ 个文件时，可考虑 AI 辅助分析 diff 并推荐受影响的文档，但最终仍由人工确认。
后果
正向
- 任务目录按 feature 组织，按时间排序，一目了然
- 设计意图与实现偏差分离记录，可追溯
- 文档同步嵌入编码流程，不会遗漏
- 所有变更仅影响内部文件组织，对最终用户透明
风险
- 旧 task 文件路径的外部引用（如有）会 404 — 影响极小，文档站尚未广泛传播
getSidebar()新增嵌套目录处理逻辑，增加维护成本 — 但仅限dev/tasks一个特殊路径- Changelog 依赖 reviewer 自觉追加 — 通过 flow-review 技能强制检查