文档: 全库走查报告(docs/05-代码审查 00-05)+ 规范更新

2026-08-02 10:44:10 +08:00
parent 3f2cf5fa3a
commit 8eb689af37
9 changed files with 866 additions and 2 deletions
@@ -122,6 +122,13 @@
 - **状态**：✅ 已实施（reasoning 存主表 + extracted 事件 context.reasoning 双写，前端优先取主表降级取事件）
 - **教训**：LLM 输出字段与代码消费字段须对账——prompt 要求 LLM 产出的字段，代码侧漏消费是常见隐性 bug。

+### AI 生成文档:先查 INDEX.md,生成即归档,失败 2 次即止损[2026-08-02]
+
+- **现象**:AI 走查生成 6 份报告时,新建了 `docs/walkthrough-2026-08/` 临时目录(违反 INDEX.md 规定的 `05-代码审查/`)。事后搬移文件 + 清理残留 + 更新 INDEX.md,多出 3 倍工作量。同时生成了重复的汇总报告(`00-汇总报告.md` + `00-summary-walkthrough.md`)。
+- **根因**:AI 凭记忆决定文档位置,未先查 INDEX.md;生成时缺乏去重意识;失败后反复重试同一操作(delete/rename 超时 3 次以上)。
+- **状态**:✅ 已写入 `文档记录规范-2026-06-14.md` §九「AI 生成文档的硬规则」(6 条):①生成前查 INDEX ②生成即归档不建临时目录 ③同轮只保留一份 ④同步更新 INDEX ⑤失败 2 次即止损 ⑥更新后必须验证。
+- **教训**:文档生成是"先查规则再动手"的典型场景。AI 的默认行为是"边生成边决定",但文档结构是约定好的,必须先读 INDEX.md 确认放置规则。失败止损同样重要——同一操作失败 2 次就应该换方案或停手,不要死磕。
+
 ### prompt_tokens=0：深挖证伪非代码 bug（疑 GLM 订阅端点 message_start 缺 input_tokens）[#54 实测发现]

 - **现象**：`ai_conversations.prompt_tokens=0`（completion=1496 正常）。GLM-订阅（anthropic 协议）1 对话 24 消息，所有 assistant 消息 `usage=None`。