lxy/DevFlow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
583058acd68889761ad0cec635a41f03a814b111
DevFlow/docs/02-架构设计/滚动规范/文档记录规范-2026-06-14.md
绝尘 998a2f243d 文档: 架构方案文档(意图识别论证+多主题愿景/论证+文档物理分类+边界清晰化) 
squash合并:
- 意图识别层论证(8维度+10业界佐证)
- 多主题上下文管理愿景+并存论证+补充论证(多轮agentic)
- 架构设计文档物理分类(四子目录+INDEX+命名规范+引用同步+边界清晰化)
- 前端架构技术债清单归档
2026-06-19 15:04:04 +08:00

11 KiB
Raw Blame History

文档记录规范

写文档 / 更新文档时的路由规则:记到哪、优先写哪、怎么避免重复。 创建: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 子代理)

八、文档命名规范(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:

  • 滚动规范与决策记录 / 已编号方案 / 专项设计 / 构想与审查

九、待修(文档不一致)

  • 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 — 工作流水
Reference in New Issue View Git Blame Copy Permalink