与其每次向机器口述背景，不如让目录替你记忆。
设计思想
Pi 通过自动加载项目层次的 AGENTS.md / CLAUDE.md 文件来提供项目特定的指令、约定和常用命令。这样做可以让 agent 在进入项目时立即获得相关上下文，避免每次手动粘贴项目说明或重复输入常用命令。
原理
启动时，Pi 会按以下顺序查找并拼接匹配的文件内容：
- 全局：
~/.pi/agent/AGENTS.md - 父目录继承：从当前工作目录开始向上遍历，每级若存在
AGENTS.md或CLAUDE.md则追加其内容。 - 当前目录：当前目录的
AGENTS.md或CLAUDE.md。 如果在某个目录中存在AGENTS.override.md，则该目录的AGENTS.md/CLAUDE.md被完全替换（但其他目录的文件仍然参与拼接），实现 层叠覆盖（全局默认 → 项目继承 → 局部覆盖）。
此外，还可以通过以下方式完全替换或追加系统提示：
- 项目级：
.pi/SYSTEM.md（替换系统 prompt） - 全局级：
~/.pi/agent/SYSTEM.md - 追加而不覆盖：
APPEND_SYSTEM.md（同上两个位置均可）
用法
- 在项目根目录或任意父目录放置
AGENTS.md，编写项目说明、编码规范、常用命令（例如pi @src/main.ts "解释此文件"）。 - 使用
AGENTS.override.md在特定分支或临时目录覆盖上下文，便于测试不同指令集。 - 若需要纯净环境，可启动时加上
--no-context-files（-nc）禁用自动加载。 - 通过编辑
.pi/SYSTEM.md或~/.pi/agent/SYSTEM.md来自定义系统行为；使用APPEND_SYSTEM.md则在保留默认提示的基础上追加内容。 - 交互中可用
@引用文件把内容注入当前提示（如@design.txt），实现按需上下文。 - 修改上下文文件后，执行
/reload或重启 pi 生效；/reload会同时重载 keybindings、extensions、skills、prompts、themes 和上下文文件。