最后一块拼图：让 Pi 懂你的项目
前面学的是「怎么用 Pi」。现在到实战模块——我们做一个真实项目，把前面的技能串起来。
项目是贯穿全程的：md-tools，一个 Markdown 文档处理工具箱。在动手写代码前，先教会 Pi「在这个项目里该怎么干活」——这就靠 上下文文件 AGENTS.md。
md-tools 正式落地。我们先写 AGENTS.md 让它懂规矩，然后搭骨架、最终用 pi 实现出来。上下文文件：AGENTS.md / CLAUDE.md
Pi 启动时会加载 AGENTS.md 或 CLAUDE.md，来源包括：
~/.pi/agent/AGENTS.md— 全局指令（对你所有项目生效）- 父目录（从当前工作目录往上逐级找）
- 当前目录
如果某目录里有 AGENTS.override.md，Pi 会用它替代那个目录的 AGENTS.md/CLAUDE.md（其他目录的上下文文件仍正常叠加）。
上下文文件用来写：项目约定、命令、安全规则、偏好。想禁用加载用 --no-context-files 或 -nc。
写一份 AGENTS.md
在 md-tools 目录里建 AGENTS.md，告诉 Pi 项目规矩：
# md-tools 项目指令
- 本项目是命令行工具，用 Node.js 编写，无外部框架。
- 处理的是 Markdown 文件：支持统计字数、转换格式、批量重命名等。
- 每个操作默认先预览「将做什么」，确认后才真正执行。
- 代码尽量简短，单文件能实现就不拆多个。
- 跑完记得用 `node test.js` 验证结果。
系统提示词文件
想替换默认系统提示词，用：
.pi/SYSTEM.md— 项目级~/.pi/agent/SYSTEM.md— 全局
想追加（不替换）默认提示词，用任一位置的 APPEND_SYSTEM.md。
入门阶段一般不用动系统提示词，知道有这回事即可，进阶课再细讲。
项目信任（Project Trust）
交互启动时，Pi 会在遇到含项目级设置/资源/项目技能的目录时，先询问是否信任。信任后 Pi 才能加载 .pi/settings.json、项目资源、安装项目包、执行项目扩展。
- 用
/trust保存某目录的信任决定（写进~/.pi/agent/trust.json） - 非交互模式（
-p/--mode json/rpc）不弹信任框，用全局defaultProjectTrust（ask/always/never） - 可用
--approve/--no-approve临时覆盖单次运行
入门阶段：遇到信任提示就确认（对自己项目），等进阶课再深究。
落地练习：写一份自己的 AGENTS.md
- 建
md-tools目录，cd进去 - 建
AGENTS.md，写 3-5 条你的项目约定（参考上面的示例） - 启动
pi，问它「这个项目的 AGENTS.md 里写了哪些约定？复述一遍」 - 确认它能准确复述
怎么判断做对了？——Pi 能逐条复述出你的约定，而不是笼统说「我记得有约定」。
卡住了怎么办？ 它复述不全 → 约定写得太空泛，回去改具体。它说不记得 → 确认 AGENTS.md 在目录根、文件名拼写对。改了文件没生效 → 重启 pi 或 /reload。
常见坑：写一堆空话
最常见的坑，是 AGENTS.md 里写「请写出高质量代码」这种空泛口号。
Pi 没法执行「高质量」这种模糊要求。要写成可判定规则：「跑完用 node test.js 验证」「文件名用 kebab-case」「删除前先预览」。标准很简单——换个同事看不懂该怎么照做，就是太模糊。
小结
AGENTS.md/CLAUDE.md是上下文文件，Pi 启动自动加载- 加载来源：全局
~/.pi/agent/、父目录、当前目录 AGENTS.override.md可替换某目录的约定SYSTEM.md替换/APPEND_SYSTEM.md追加系统提示词- 项目信任：
/trust保存决定，非交互模式走全局设置 - 写具体可判定的约定，别写空话
下一节，搭项目骨架。