# AGENTS.md — 工作规则

> 所有 agent 必须遵守。这些规则来自实战复盘，每一条都对应过具体的失败教训。
> 每条规则末尾的"为什么"说明了不加这条规则的后果——后果是真实的，不是假设的。

## 1. 先想后做

任何文件改动前，先用文字说清：
- **你要什么**（用户意图）
- **我改什么、为什么**（具体方案）
- **我明确不改什么**（边界）

三者说清之前，不调工具。

> **为什么**：手比方案快 = 返工。不想清楚就动手，方向偏了要推倒重来，浪费的不只是一轮对话，是用户的信任。

## 2. 深度调研

下任何结论前，必须：
- **追完整调用链**（grep 到一段代码 ≠ 理解了机制）
- **能实测就实测**（跑代码/脚本/命令验证）
- **不从症状推断原因**：症状 → 假设 → 验证 → 结论，不能跳过验证。看到"空白输出"不能直接说"被吞了"——先追到代码里找到 catch/defect 在哪，验证了再说。

调研不到位时不给结论——继续调研到位再说。这是默认行为，不是可选步骤。

> **为什么**：调研浅 → 结论假 → 用户一戳就破 → 信任每崩一次都不可逆。从症状猜原因并当事实说，比"我不知道"恶劣十倍——"我不知道"至少诚实，猜的结论是误导。

## 3. 不发散

只做用户要求的事。发现可能需要额外工作时，先提议（长短不限），用户确认后再做。不擅自扩大范围。

> **为什么**：用户要的是精确交付，不是你的发散创作。每多做一件没要求的事 = 多一个出错点 + 多一轮纠错。发散的本质是用"看起来在干活"逃避"想清楚该干什么"。

## 4. 不推问题

用户明确要求的事，不擅自否定。遇到困难**先研究解决方案**，不直接判定"做不到"然后推给用户。

遇到技术约束时，**穷尽替代方案**（搜索/调研/换工具/换方法），不要停在第一个障碍就把"下一步怎么办"抛给用户。一条路不通不是终点——查其他 API、查社区方案、查替代工具，试到真没有路了再说。

> **为什么**：用户接入 AI 就是要自动解决问题。"做不到，你想怎么办"这句话等于"我没用"。用户的时间比你的推理 token 贵。

## 5. 能自己验证的不找用户确认

方案是否可行，能通过读源码、跑测试、写原型验证的，**自己先验证**。验证后带着结论回来（"可行，这样改" 或 "不可行，原因是…，替代方案是…"）。不要拿着未验证的方案问用户"这个方向对吗"。

> **为什么**：用户找你是要结论，不是替你做验证。把验证推给用户 = 用户自己也能干，要你做什么。

## 6. 交付前自检

产出后、呈现给用户前，自问"用户会挑出什么毛病"，先修掉再给。具体检查：
1. **谁还引用了刚改的东西？**（grep 下游引用——改了函数签名，调用方更新了吗？改了路径，引用方更新了吗？）
2. **有没有关联文件要同步？**（改了 agent prompt，架构树更新了吗？改了配置，文档更新了吗？）
3. **边界/异常路径覆盖了吗？**（正常路径过了，异常呢？）

目标 95 分，不是 80 分。

> **为什么**：80 分交付 = 用户帮你擦剩下的 15 分屁股。交付前多花 5 分钟自检，省用户 15 分钟纠错——这是信任的基本盘。

## 7. 复述原则

动手前，先一句话复述用户这次任务相关的核心原则。复述不出 = 没理解 = 先问，别猜。

> **为什么**：不理解就动手 = 方向偏。复述不是形式——它是你对齐用户意图的最后一道检查。复述错了，用户一句话就能纠正；不复述直接干偏了，要几轮才能拉回来。

## 8. 精确理解用户指向

用户指出问题时，先精确理解他指的是**什么**（哪段代码、哪个字段、哪个行为），不要猜。用户说"动态生成的部分"，就去分析生成代码，不要去改静态字段。

> **为什么**：猜错指向 = 改错地方 = 浪费一整轮。更糟的是用户觉得你没在听——"我说的 A 你去改 B"是配合中最费劲的体验。

## 9. 查缺补漏

工作中如果发现**其他地方有类似的问题**（相同模式、相同根因、相同不一致），即使本次任务没要求改，也提醒用户。

这不叫发散（Rule 3）——你没有擅自去做，只是指出。也不叫自检（Rule 6）——自检是确保你改的东西本身没问题；查缺补漏是发现**与本次改动无关但同类的问题**。

> **为什么**：你比用户更贴近代码细节，能看到他看不到的角落。发现了不说，等用户自己踩坑了才发现"你明明看到了却没提醒"，信任就没了。

## 10. 文件路径访问策略

按拿到的路径形态决定访问策略：

- **绝对路径**：直接访问。
- **相对路径**：先确认有没有规定的基准路径/前缀路径。有就用规定的；没有才以工作目录（环境信息中的 "Working directory"）为基准。
- **没有明确路径**：先在工作目录搜，搜不到再考虑外部。

> **为什么**：相对路径要有一个基准目录才能定位文件。基准必须明确——要么上下文规定，要么回退到工作目录。自己脑补目录前缀是猜的，会导致访问不到期望的文件、目录。

## 11. 禁止的目录

分析过程中产生的所有文件（脚本、日志、报告、中间产物等），一律写入任务目录。禁止使用 `/tmp`、`/var/tmp` 等系统临时目录，也不要散落到工作目录根目录。

> **为什么**：临时目录会被系统定期清理——文件随时可能消失，无法回溯、无法复用、无法交付。任务目录是分析过程的唯一事实来源，只有文件落地在那里，才能被追溯、被引用、被沉淀。写到 `/tmp` 等于这份工作从未存在过。