绝尘
cf017f81e2
重构：删 5 零引用 crate（df-evolve/plugin/stages/task/traceability）+ 清死模块、ai.rs 拆 11 子 module、ai.ts 拆 6 composable、i18n 拆目录 功能：知识库全栈（df-project/scan + CRUD + 时间线 + 前端）、Settings 拆分、appSettings KV 迁移、模型池、LLM 并发 Semaphore 修复：审批持久化根治、ConditionEngine 默认拒绝、NodeRegistry unimplemented 清除、promote 补偿删除、工具结果截断 50KB、路径校验防 symlink 逃逸 文档：B-03 人工审批设计、决策记录三分档、规格契约自检、经验记录、todo 看板、PROGRESS 更新 详见 PROGRESS.md。src-tauri/儿童每日打卡应用/ 与本项目无关，已排除。
168 lines
8.9 KiB
Markdown
168 lines
8.9 KiB
Markdown
# 文档记录规范
|
|
|
|
> 写文档 / 更新文档时的**路由规则**:记到哪、优先写哪、怎么避免重复。
|
|
> 创建:2026-06-12 | 维护:文档结构变化时同步
|
|
|
|
---
|
|
|
|
## 一、核心原则
|
|
|
|
1. **单一真相源(SSOT)**:每类信息只在一个主文档展开,别同一内容抄多处。
|
|
2. **不复制,只引用**:他处需要时加 `[详情](链接)`,不抄正文。
|
|
3. **决策与流水分离**:决策记「为什么这么定」,流水记「做了啥」。别混。
|
|
4. **先主后辅**:同一变更涉及多处 → 先写真相源,再在引用处加链接。
|
|
5. **决策记录范围收紧 — 只记人定事实,不记大模型分析结论**(2026-06-14,📐 基准原则):
|
|
- 决策记录**只记**与大模型能力无关的人定事实 — 业务需求规格 / 人定技术选型 / 人的设计取舍。
|
|
- **不记**大模型分析/推断结论(性能瓶颈 / 根因 / 最优架构 / 排查结果) — 这些按需让当时的模型即时产出,不沉淀。
|
|
- 原因:大模型分析结论受当前模型能力天花板约束,模型逐月变强,今天的「最优分析」明天会被更强模型超越 → 记录过时;沉淀 = 固化次优解,阻碍未来用更强模型即时得出更优解。即使埋点/实测「验证」了,也不改其受能力天花板约束、会随模型升级被超越的本质。
|
|
|
|
---
|
|
|
|
## 二、文档职责矩阵(真相源)
|
|
|
|
| 文档 | 唯一职责(记什么) | 不记什么 |
|
|
|---|---|---|
|
|
| `PROGRESS.md`(根级) | 工作流水:Sprint 做了啥 / 遗留 / 下一步 | 决策原因、实现细节、需求规格 |
|
|
| `ARCHITECTURE.md` | 系统架构全貌:crate 结构 / 数据模型 / Phase 规划 | 功能点取舍、Sprint 流水 |
|
|
| `02-架构设计/Phase1架构决策.md` | 架构级选型(ADR,系统级) | 功能实现层取舍 |
|
|
| `02-架构设计/功能决策记录.md` | 功能**需求规格 + 设计决策规格**(为什么这么定 + 要做什么) | 流水、架构级选型、经验性内容 |
|
|
| `02-架构设计/经验记录.md` | 经验性内容(踩坑/约定/技巧/bug 排查教训) | 决策、需求、流水 |
|
|
| `02-架构设计/功能决策记录-归档.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) | `功能决策记录.md` | 模块文档、PROGRESS |
|
|
| 踩坑 / 约定 / 技巧 / bug 排查教训 | `经验记录.md` | 功能决策记录 |
|
|
| 架构级选型 | `Phase1架构决策.md` / `ARCHITECTURE.md` | — |
|
|
| 新需求 / 待办 / 功能规格 | `功能决策记录.md`(需求维度) | `Phase2计划.md` |
|
|
| 对话中需求澄清(原以为 X 实为 Y) | `功能决策记录.md`(需求澄清) | — |
|
|
| 老 Sprint 决策 / UX 微调 / 已被取代 | `功能决策记录-归档.md` | (归档只读,不再维护) |
|
|
| 单模块实现细节 | `03-模块文档/<对应>.md` | — |
|
|
| 代码审查发现 | `05-代码审查/` | 转决策 → `功能决策记录.md` |
|
|
| 前端规范变更 | `06-前端开发/` | — |
|
|
| 用户操作说明 | `08-用户指南/` | — |
|
|
|
|
---
|
|
|
|
## 四、更新顺序(同一变更涉及多处)
|
|
|
|
1. **真相源先写完整**(按路由表的主文档)
|
|
2. **PROGRESS 记一笔 + 链接**(流水 + 指向详情)
|
|
3. **引用处加交叉链接**,不抄正文
|
|
|
|
**例**:做了「shouldKeepOpen 折叠」
|
|
- 真相源:`功能决策记录.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 是**交接文档**,只记「做了啥 + 链接」,不展开决策/需求正文
|
|
- 决策正文 → `功能决策记录.md`;需求 → `功能决策记录` 的「需求与待办」
|
|
- 交接路径:读 PROGRESS 知进度 → 读 `功能决策记录` 知「为什么 + 要做什么」→ 读模块文档知「怎么实现」
|
|
|
|
**4. 定期唯一性扫描(防积累散乱)**
|
|
- 时机:文档结构变化 / 新增文档 / 每个 Sprint 末
|
|
- 方法:对关键决策点跨文档 grep,确认只在主文档展开
|
|
```bash
|
|
grep -rl "shouldKeepOpen\|connect_timeout" docs/ PROGRESS.md
|
|
```
|
|
- 发现散乱 → 合并到主文档,他处改链接
|
|
|
|
### 不散乱红线
|
|
|
|
- 同一决策**不**同时进 `功能决策记录` 和 `Phase1架构决策`(功能层 vs 架构层二选一)
|
|
- 同一需求**不**同时在 `功能决策记录·需求与待办` 和 `Phase2计划` 展开(一处为主,一处链接)
|
|
- PROGRESS**不**抄决策正文,只记「做了 + 链接」
|
|
|
|
---
|
|
|
|
## 六、与 decision-record skill 的关系
|
|
|
|
`decision-record` skill 触发时,按本规范路由:
|
|
|
|
- **决策 / 需求** → `功能决策记录.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-架构设计/功能决策记录.md` — 需求规格 + 设计决策规格(本规范的主要应用对象)
|
|
- `docs/02-架构设计/经验记录.md` — 踩坑/约定/技巧/bug 排查教训
|
|
- `docs/02-架构设计/功能决策记录-归档.md` — 归档只读(纯流水/老 Sprint/UX 微调)
|
|
- `PROGRESS.md` — 工作流水
|