第 4 课：上下文文件

从这里开始，pi 会逐渐变得像"属于你"的。上下文文件（context files）是 Markdown 文件，给 pi 提供持久的工作方式指令——每次会话都会自动加载。

三驾马车：AGENTS.md 及其同类

Pi 在启动时从三个位置加载上下文文件：

1. ~/.pi/agent/AGENTS.md — 适用于每个项目的全局指令
2. 父目录 — 从当前工作目录向上逐级查找（所以 monorepo 根目录共享的 AGENTS.md 适用于所有子项目）
3. 当前目录 — 项目专属指令

所有匹配的文件会被拼接起来，指令从全局 → 父目录 → 项目逐层累积。CLAUDE.md 同样有效（机制相同）——如果你和 Claude Code 用户共享仓库，这会很方便。

里面放什么

把它看作模型动手前要读的"项目简报"。示例：

# Project Instructions

- Run `npm run check` after code changes.
- Never run production migrations locally.
- Keep responses concise.
- Tests live in `test/`, use vitest.
- Use conventional commits: feat:, fix:, chore:

好的候选内容：

• 命令与检查 — npm run check、cargo test、lint 命令
• 约定 — 代码风格、提交格式、目录结构
• 安全规则 — "绝不碰生产凭据"、"不要推到 main"
• 偏好 — 详略程度、语言、输出格式

信任问题

当一个项目目录包含项目级设置、资源或项目的 .agents/skills 时，pi 会先询问是否信任。信任之前，pi 只加载上下文文件和全局/用户扩展。信任之后，它才会加载 .pi/settings.json、项目扩展并安装缺失的包。用 /trust 保存决定（下次重启生效）。这是一道安全边界：项目文件可以运行代码，所以 pi 确保你主动选择信任。

替换系统提示词

除了上下文文件，你还可以替换整个默认系统提示词：

• .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）— 替换默认提示词
• APPEND_SYSTEM.md（任一位置）— 追加而不替换

这属于进阶用法；先从 AGENTS.md 开始。

CLI 控制

pi --no-context-files    # -nc：禁用上下文文件加载
pi --system-prompt "..." # 单次运行替换提示词
pi --append-system-prompt "..." # 单次运行追加

工作流技巧

• 保持简短。 过长的上下文文件浪费 token 并稀释重点。一份精炼的 10 行 AGENTS.md 胜过 200 行的。
• 它们在启动时加载。 修改后重启 pi 或运行 /reload——它会热重载上下文文件（以及快捷键、扩展、技能、提示词和主题）。
• 项目级 vs 全局： 真正通用的规则（你的语气、偏好的工具）放进 ~/.pi/agent/AGENTS.md；项目专属的内容放进仓库的 AGENTS.md。由于文件会拼接，全局指令之上会叠加项目指令。
• 它们随仓库一起传播。 提交 AGENTS.md——每个协作者和未来的每次 pi 会话都会受益。这也是其他代理（如 Claude Code）会读取的标准文件。

现在就来试试

1. 在你的工作区创建一个 AGENTS.md，写上 3–5 条你在意的规则。
2. 运行 /reload。
3. 问 pi 一个与你的规则相关的问题——比如"提交前我应该运行哪些检查？"——观察它引用你的文件。

---

作业： 写一个全局的 ~/.pi/agent/AGENTS.md（例如你偏好的提交风格，或你喜欢简洁回答），/reload，然后确认 pi 会遵循它。