# 文档记录规范

> 写文档 / 更新文档时的**路由规则**:记到哪、优先写哪、怎么避免重复。
> 创建: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 查该点是否已存在:
  ```bash
  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,确认只在主文档展开
  ```bash
  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 子代理)

---

## 八、文档命名规范(2026-06-19 确立)

> 本节确立 `docs/02-架构设计/` 及同类设计文档目录的命名格式,便于检索 / 排序 / 关联跟踪项。规范为**对现状的归纳**,不强制回溯重命名(重命名引用代价大,见 §十一 riskNote)。

### 格式

统一为 `<前缀>-<主题>-<日期>.md`,前缀按文档性质分三类:

| 类别 | 前缀 | 格式 | 示例 |
|---|---|---|---|
| 功能 / bug / review 方案 | 功能编号(`F-NN` / `B-NN` / `CR-NN`)或 bug ID(`B-YYMMDD-NN`) | `<编号>-<主题>-<日期>.md` | `F-09-多会话并发架构设计-2026-06-19.md` / `B-03-人工审批响应机制-2026-06-14.md` |
| 滚动维护文档(跨 Sprint 持续追加) | 无编号 | `<主题>-<日期>.md` | `功能决策记录-2026-06-14.md` / `经验记录-2026-06-14.md` |
| 专题设计 / 构想 / 审查报告 | 主题(含领域前缀如 `aichat` / `工作流` / `任务推进`) | `<主题>-<日期>.md` | `aichat审查报告-2026-06-14.md` / `工作流脚本执行边界-2026-06-15.md` |

### 约定

1. **日期 = 创建日期**(YYYY-MM-DD),不随更新变(更新在正文「实施状态」块体现,不改文件名日期)。
2. **前缀 = 跟踪项编号**时,与 `todo.md` / `待审查.md` 的编号一一对应,便于双向定位。
3. **被取代 / 过时文档不删**:文件顶部加 `## 实施状态` 块或 `> 过时` 标注,索引「状态」列标 🗄。例:`F-09B-多会话并发设计-2026-06-16.md` 被 `F-09-...-2026-06-19.md` 取代,旧版保留回溯。
4. **同主题多版本**:新版用相同主编号 + 不同日期(`F-09` 与 `F-09B` 为历史命名,新设计统一用主编号 + 日期,不再加 `B` 后缀)。

### 检索

按性质四类查阅,见本目录 [INDEX.md](../INDEX.md):
- 滚动规范与决策记录 / 已编号方案 / 专项设计 / 构想与审查

---

## 九、待修(文档不一致)

- ~~`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` — 工作流水