用 AGENTS.md 深化项目约定

AGENTS.md 是什么

入门课你已经用过它了：Pi 启动时会从几个位置自动加载 AGENTS.md（或 CLAUDE.md）。官方文档说得很清楚，它加载的位置有三个层级：

层级	位置	作用
全局	~/.pi/agent/AGENTS.md	你的个人全局约定
父目录	从当前目录逐级向上找	父项目的约定
当前目录	当前工作目录	本项目约定

约定会从父目录一路「继承」下来，然后当前目录的再叠加上去。 也就是说，全局的规矩始终在，项目层再加项目自己的。

---

AGENTS.md 放什么

官方文档给了一句很实用的指引：用上下文文件来记录项目约定、命令、安全规则和偏好。

对照 md-tools，就是这四样：

1. 项目约定：代码风格、目录结构、命名规范
2. 命令：stats / convert / rename 三个命令怎么用、接受什么参数
3. 安全规则：每个操作执行前都要先打印「将做什么」，确认后才执行（尤其是 rename 改名）
4. 偏好：默认要纯文本输出、错误要友好提示等

写的时候别贪多，只写「AI 不看就会做错」的事。看一条就要能省一次返工。

---

让 AGENTS.md 真的被读进去

写入文件很简单，但写完要确认 Pi 真的加载了它。两种做法：

启动时看 TUI 顶部：启动头会显示已加载的上下文文件列表，md-tools/AGENTS.md 应该在里面。

或者用命令行一次性确认：

pi -p "告诉我校验一下：你的系统提示词里引用了 md-tools 的哪些约定？"

如果它答得上 rename 要预览、操作前要确认，说明加载成功。

---

覆盖与禁用：AGENTS.override.md

官方文档提到一个进阶点：如果某个目录里有 AGENTS.override.md，Pi 会用它代替那个目录里的 AGENTS.md / CLAUDE.md。其他目录的上下文文件仍然照常加载。

这个特性适合什么场景？比如某个子目录需要「推翻」父级的某条约定、只用自己的规矩时。对 md-tools 来说，暂时用不上，但知道有这层「覆盖」机制，以后遇到「上级规矩不适用」时就知道怎么解。

如果想彻底关掉上下文文件加载，用：

pi --no-context-files   # 或简写 pi -nc

---

落地练习：写一份「能约束 Pi」的 AGENTS.md

1. 打开 md-tools/AGENTS.md，把这三个命令的用法、以及「每个操作执行前先预览并确认」的安全规则写进去
2. 用 pi 启动，观察顶部是否显示已加载 AGENTS.md
3. 对 Pi 说「帮我用 md-tools 把 a.md 改名为 b.md」，看它是否先预览再确认才动手

怎么判断做对了？——启动时能看到加载了该文件，且 Pi 执行 rename 时会先展示预览并等你确认，而不是直接改名。

卡住了怎么办？ 没加载 → 检查文件是不是就叫 AGENTS.md、路径对不对。它直接改名了 → 说明安全规则没写清楚，回去把「先预览再确认」写得再具体一点。想验证是否生效 → 用 pi -nc 关掉后对比一下行为差异。

---

常见坑：把 AGENTS.md 写成「论文」

最常见的问题，是把 AGENTS.md 写成一整段没人读的散文。AI 虽然会读，但太长、太泛的约定等于没写——它记不住，也难遵循。

正确做法是：用短句、分条、每条能落地。宁可 10 条各一句话，也不要 1 段三百字。真正能约束行为的约定，都是「你一看就知道执行到没执行」的那种。

---

小结

1. AGENTS.md / CLAUDE.md 从全局、父目录、当前目录三层加载并叠加
2. 放的是：项目约定、命令、安全规则、偏好
3. 用 AGENTS.override.md 可覆盖某个目录的约定
4. 用 --no-context-files / -nc 可关闭加载
5. 写短句、分条、能落地，别写成没人读的长文

下一节，我们进入系统提示词——如何用 SYSTEM.md 替换、用 APPEND_SYSTEM.md 追加默认提示词。