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

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

@@ -181,7 +181,52 @@ Stop hook 触发 skill 时同理,不另立记录位置。
 
 ---
 
-## 九、待修(文档不一致)
+## 九、AI 生成文档的硬规则(2026-08-02 确立)
+
+> 本节针对 AI 助手生成文档时的系统性问题,确立不可绕过的硬规则。
+> 触发场景:AI 走查 / 审查 / 调研 / 报告生成。
+
+### 规则 1:生成前先查 INDEX.md
+
+**禁止** 凭记忆或假设决定文档放置位置。
+**必须** 先读 `docs/INDEX.md` 的「目录结构」和「新文档放置规则」,确认目标目录,再生成文件。
+**原因**:AI 曾多次在根级新建 `walkthrough-YYYY-MM/` 等临时目录,事后需搬移 + 更新 INDEX,浪费 3 倍工作量。
+
+### 规则 2:生成即归档,不建临时目录
+
+文档直接写入目标目录(如 `05-代码审查/`),文件名带日期,一步到位。
+**禁止** 先建 `walkthrough-YYYY-MM/` 等中间目录,再事后搬移。
+**原因**:临时目录是技术债,残留文件(重复/中间产物)长期不清理。
+
+### 规则 3:同一轮只保留一份
+
+同一轮走查/审查,每个模块只生成一份报告,一份汇总。
+**禁止** 同一轮生成 2 份汇总、2 份同模块报告。
+**原因**:AI 多次生成 `00-汇总报告.md` + `00-summary-walkthrough.md` 等重复文件,内容高度重叠。
+
+### 规则 4:更新 INDEX.md 与生成文档同步
+
+生成文档后,**立即**更新 `docs/INDEX.md` 对应目录的条目。
+**禁止** 生成文档后忘记更新 INDEX。
+**原因**:INDEX 是文档导航入口,遗漏会导致文档"隐身"。
+
+### 规则 5:操作失败 2 次即止损
+
+同一个工具操作(delete_file / rename_file / patch_file)失败 2 次后:
+- **停止重复尝试**
+- **换方案**(如 delete 失败 → 改为 rename 加 `-冗余` 后缀)
+- **或停手汇报**,说明失败原因和当前状态
+**原因**:AI 曾多次对同一失败操作重复 3-4 次,浪费时间和审批额度。
+
+### 规则 6:更新后必须验证
+
+对 INDEX.md / 配置文件等关键文件 patch 后,**立即读取**确认结果正确。
+**禁止** patch 后直接宣称完成。
+**原因**:AI 曾把 6 条走查报告重复插入 INDEX.md 两次(12 条),直到用户指出才发现。
+
+---
+
+## 十、待修(文档不一致)
 
 - ~~`docs/INDEX.md` 在 `07-项目管理/` 树下登记了 `PROGRESS.md`,但实际 PROGRESS 只在根级,`07-项目管理/` 下无此文件~~ → ✅ 已修(2026-06-12):移除该行,PROGRESS 统一指向根级。
 

docs/02-架构设计/滚动规范/经验记录-2026-06-14.md

@@ -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`。