DevFlow/docs/02-架构设计/文档记录规范-2026-06-14.md

文档记录规范

写文档 / 更新文档时的路由规则:记到哪、优先写哪、怎么避免重复。 创建:2026-06-12 | 维护:文档结构变化时同步

---

一、核心原则

1. 单一真相源(SSOT):每类信息只在一个主文档展开,别同一内容抄多处。
2. 不复制,只引用:他处需要时加 [详情](链接),不抄正文。
3. 决策与流水分离:决策记「为什么这么定」,流水记「做了啥」。别混。
4. 先主后辅:同一变更涉及多处 → 先写真相源,再在引用处加链接。
5. 决策记录范围收紧 — 只记人定事实,不记大模型分析结论(2026-06-14,📐 基准原则):
   • 决策记录只记与大模型能力无关的人定事实 — 业务需求规格 / 人定技术选型 / 人的设计取舍。
   • 不记大模型分析/推断结论(性能瓶颈 / 根因 / 最优架构 / 排查结果) — 这些按需让当时的模型即时产出,不沉淀。
   • 原因:大模型分析结论受当前模型能力天花板约束,模型逐月变强,今天的「最优分析」明天会被更强模型超越 → 记录过时;沉淀 = 固化次优解,阻碍未来用更强模型即时得出更优解。即使埋点/实测「验证」了,也不改其受能力天花板约束、会随模型升级被超越的本质。

---

二、文档职责矩阵(真相源)

文档	唯一职责(记什么)	不记什么
PROGRESS.md(根级)	工作流水:Sprint 做了啥 / 遗留 / 下一步	决策原因、实现细节、需求规格
ARCHITECTURE.md	系统架构全貌:crate 结构 / 数据模型 / Phase 规划	功能点取舍、Sprint 流水
02-架构设计/Phase1架构决策-2026-06-12.md	架构级选型(ADR,系统级)	功能实现层取舍
02-架构设计/功能决策记录-2026-06-14.md	功能需求规格 + 设计决策规格(为什么这么定 + 要做什么)	流水、架构级选型、经验性内容
02-架构设计/经验记录-2026-06-14.md	经验性内容(踩坑/约定/技巧/bug 排查教训)	决策、需求、流水
02-架构设计/功能决策记录-归档-2026-06-14.md	纯流水/老 Sprint/UX 微调/已被取代(归档只读)	(不再维护更新)
03-模块文档/*.md	各 crate 实现细节(单模块内)	跨模块决策、流水
04-功能迭代/DEVFLOW-N.*.md	功能开发过程记录(一次性,开发期)	持续维护的决策
05-代码审查/*.md	审查报告与发现	(若成决策 → 转记功能决策记录)
06-前端开发/*.md	前端规范 / 迁移指南	后端实现
07-项目管理/*.md	Phase 计划 / 任务清单	实现流水(那是 PROGRESS)
08-用户指南/*.md	用户手册 / 配置 / FAQ	内部实现细节
01-技术文档/*.md	技术专题研究(CRUD 模式、IPC 模式)	业务功能

---

三、内容路由表(写东西先查这个)

你要记的内容	主文档(优先写)	按需交叉引用
本 Sprint 做了啥 / 遗留	PROGRESS.md	04-功能迭代/(详过程)
为什么这么实现(选 A 不选 B)	功能决策记录-2026-06-14.md	模块文档、PROGRESS
踩坑 / 约定 / 技巧 / bug 排查教训	经验记录-2026-06-14.md	功能决策记录
架构级选型	Phase1架构决策-2026-06-12.md / ARCHITECTURE.md	—
新需求 / 待办 / 功能规格	功能决策记录-2026-06-14.md(需求维度)	Phase2计划-2026-06-12.md
对话中需求澄清(原以为 X 实为 Y)	功能决策记录-2026-06-14.md(需求澄清)	—
老 Sprint 决策 / UX 微调 / 已被取代	功能决策记录-归档-2026-06-14.md	(归档只读,不再维护)
单模块实现细节	03-模块文档/<对应>.md	—
代码审查发现	05-代码审查/	转决策 → 功能决策记录-2026-06-14.md
前端规范变更	06-前端开发/	—
用户操作说明	08-用户指南/	—

---

四、更新顺序(同一变更涉及多处)

1. 真相源先写完整(按路由表的主文档)
2. PROGRESS 记一笔 + 链接(流水 + 指向详情)
3. 引用处加交叉链接,不抄正文

例:做了「shouldKeepOpen 折叠」

• 真相源:功能决策记录-2026-06-14.md 写决策 / 原因 / 状态 ✅
• 流水:PROGRESS.md 记「审查①已落地」+ 链接到功能决策记录
• 不在模块文档 / ARCHITECTURE 重复抄决策正文

---

五、唯一性记录与检测(防散乱)

核心要求:每类信息一个主文档,不散乱、不重复。 文档治理底线。

唯一真相源

见「二、文档职责矩阵」——每类信息的唯一主文档。

检测方法

1. 记前查重(每次记录时)

• 记决策/需求前,先 grep 查该点是否已存在:

  grep -rl "<关键词>" docs/ PROGRESS.md ARCHITECTURE.md
  

• 已存在 → 更新原条,不新增(见 decision-record skill「维护:查重」)

2. 交叉引用单向(禁双向复制)

• 主文档(真相源)展开内容,引用方只放 [详情](链接)
• ❌ A 写决策正文,B 又抄一遍 → ✅ B 只链接 A

3. 配合交接文档(PROGRESS)

• PROGRESS 是交接文档,只记「做了啥 + 链接」,不展开决策/需求正文
• 决策正文 → 功能决策记录-2026-06-14.md;需求 → 功能决策记录 的「需求与待办」
• 交接路径:读 PROGRESS 知进度 → 读 功能决策记录 知「为什么 + 要做什么」→ 读模块文档知「怎么实现」

4. 定期唯一性扫描(防积累散乱)

• 时机:文档结构变化 / 新增文档 / 每个 Sprint 末
• 方法:对关键决策点跨文档 grep,确认只在主文档展开

  grep -rl "shouldKeepOpen\|connect_timeout" docs/ PROGRESS.md
  

• 发现散乱 → 合并到主文档,他处改链接

不散乱红线

• 同一决策不同时进 功能决策记录 和 Phase1架构决策(功能层 vs 架构层二选一)
• 同一需求不同时在 功能决策记录·需求与待办 和 Phase2计划 展开(一处为主,一处链接)
• PROGRESS不抄决策正文,只记「做了 + 链接」

---

六、与 decision-record skill 的关系

decision-record skill 触发时,按本规范路由:

• 决策 / 需求 → 功能决策记录-2026-06-14.md(主,真相源)
• skill 执行后 → PROGRESS.md 加一笔流水 + 链接(可选,重大决策才加)

Stop hook 触发 skill 时同理,不另立记录位置。

---

七、治理体系实现决策(hook 设计)

本规范 + decision-record skill + 降频 Stop hook 构成文档治理体系。hook 设计取舍:

降频 Stop hook(替代 PreCompact / 每轮自检)

• 决策:用 ~/.claude/hooks/dr-check.sh(settings.json 配 Stop hook)按阈值注入自检提示,触发 decision-record。
• 原因:PreCompact hook 只读输入、无法注入 prompt 触发 skill;Stop hook 支持 additionalContext 注入。每轮 Stop 自检消耗大且打断;降频用纯脚本计数无 API,省 ~90% token。
• 状态:✅ 2026-06-12

触发阈值:≥20 轮 或 (≥2 轮 且 ≥20 分钟)

• 决策:累计 ≥20 轮,或 (>1 轮 且 距上次 ≥20 分钟) 才触发;首次运行静默初始化(计时,本轮不触发)。
• 原因:10 轮约一个功能点推进周期;10 分钟兜底防长对话漏记;兼顾及时与不打扰。
  • → 2026-06-14 阈值翻倍(10→20 轮 / 10→20 分钟)。原阈值触发过频,多数自检轮次无实质决策;翻倍减半打扰。✅ 落地(dr-check.sh)

防循环:stop_hook_active guard

• 决策:hook 检测输入 stop_hook_active=true → 直接 exit 0 放行。
• 原因:Stop hook 注入 additionalContext 会触发主 Claude 继续 → 再次 Stop → 无限循环;guard 放行第二轮(因 hook 继续的)。
• 状态:✅

状态按项目隔离

• 决策:轮次计数 + 上次触发时间戳存 ~/.claude/.dr-state/<项目key>.rounds|.last(键由路径转义),不落项目目录。
• 原因:多项目独立计数不串;不污染 git 仓库。
• 状态:✅

决策记录执行子代理化(2026-06-14)

• 决策:stop hook 自检触发后,记录动作 spawn 后台子代理执行(项目 decision-recorder 子代理,位于 devflow/.claude/agents/),主代理不亲自 grep/写文档。
• 原因:避免记录动作(grep/读写文档)污染主对话上下文、打断主流程;记录规范固化进子代理 system prompt,主代理只传决策内容。
• 状态:✅ 落地(dr-check.sh 的 CTX 已改为指令 spawn 子代理)

---

八、待修(文档不一致)

• docs/INDEX.md 在 07-项目管理/ 树下登记了 PROGRESS.md,但实际 PROGRESS 只在根级,07-项目管理/ 下无此文件 → ✅ 已修(2026-06-12):移除该行,PROGRESS 统一指向根级。

---

相关文档:

• docs/INDEX.md — 文档导航
• docs/02-架构设计/功能决策记录-2026-06-14.md — 需求规格 + 设计决策规格(本规范的主要应用对象)
• docs/02-架构设计/经验记录-2026-06-14.md — 踩坑/约定/技巧/bug 排查教训
• docs/02-架构设计/功能决策记录-归档-2026-06-14.md — 归档只读(纯流水/老 Sprint/UX 微调)
• PROGRESS.md — 工作流水