文档: 全库走查报告(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
@@ -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 统一指向根级。