# 第 3 章：上下文文件——让项目自己开口说话
> 与其每次向机器口述背景，不如让目录替你记忆。
## 设计思想
Pi 通过自动加载项目层次的 `AGENTS.md` / `CLAUDE.md` 文件来提供项目特定的指令、约定和常用命令。这样做可以让 agent 在进入项目时立即获得相关上下文，避免每次手动粘贴项目说明或重复输入常用命令。
## 原理
启动时，Pi 会按以下顺序查找并拼接匹配的文件内容：
1. **全局**：`~/.pi/agent/AGENTS.md`
2. **父目录继承**：从当前工作目录开始向上遍历，每级若存在 `AGENTS.md` 或 `CLAUDE.md` 则追加其内容。
3. **当前目录**：当前目录的 `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 和上下文文件。