AGENTS.md 与提示词模板

前面几章我们把 pi 装好、配好了模型，但它现在还是个”通用助手”，没有你自己的味道。本章就讲两件事：怎么让 pi 按你的规矩办事（AGENTS.md），怎么把你常用的提示词变成像 /review 这样的快捷命令（提示词模板）。

本章基于 pi v0.84.1。

---

AGENTS.md：pi 的行为规范

AGENTS.md 是一个 Markdown 文件，放在项目根目录（或全局用户目录）。pi 在启动时会自动读取它，然后把它作为系统提示词（system prompt）的一部分注入到每次对话中。

你可以把它理解成 pi 的”员工手册”——规定编码风格、禁止行为、上下文优先级等。pi 在每次回复前都会”看到”这份手册。

放在哪

AGENTS.md 有两种放置位置：

位置	作用范围	使用场景
项目根目录 ./AGENTS.md	当前项目	每个项目的编码规范、技术栈约定、团队协作规则
~/.pi/agent/AGENTS.md	所有项目	个人偏好——你希望 pi 在任何项目都遵守的规则

pi 启动时会先加载全局 AGENTS.md，再加载项目的 AGENTS.md。项目级的规则优先级更高——如果两者有冲突，项目级覆盖全局级。

怎么写

AGENTS.md 没有固定格式，就是一份普通的 Markdown 文档。写得好不好，直接影响 pi 的表现。以下是几条实践建议。

1. 先定义角色和语气

告诉 pi 它是谁、跟谁说话：

# AGENTS.md

你是一个专注于 Python 后端开发的助手。你总是用中文回答技术问题，
但代码注释和变量名保持英文。

2. 编码规范要具体

模糊的规则等于没规则。“写好代码”对 pi 来说毫无意义。要给出具体约束：

## 编码规范

- Python 代码用 ruff 格式化，行宽 100
- 函数不超过 40 行
- 不写超过 3 层嵌套的 if/for
- 类型注解必写，不用 `Any` 除非确实必要
- 数据库查询用 SQLAlchemy 2.0 风格，不写 raw SQL

3. 写明禁止行为

pi 再聪明也可能做出你不想要的事。明确禁止：

## 禁止行为

- 不要修改 `migrations/` 目录下的文件
- 不要往 `package.json` 里加未经确认的依赖
- 不要删除任何以 `_legacy` 结尾的文件
- 不要自动创建新文件，先和我确认

4. 设定上下文优先级

pi 能看到的信息很多——项目文件、对话历史、系统提示。告诉它什么最重要：

## 上下文优先级

1. 当前对话中用户的明确指令 > 本文档的规则
2. 项目根目录的 `.env.example` 是环境变量的唯一参照
3. 如果 `README.md` 中有部署说明，用它覆盖你的默认做法

一份完整的 AGENTS.md 范例

把上面几块拼起来，就是一份实用的 AGENTS.md：

# AGENTS.md - 项目规范

## 角色

你是一个 React + TypeScript 前端助手。回答用中文，代码保持英文。

## 编码规范

- 用 Prettier 默认配置格式化
- 组件用函数式写法，不用 class component
- 状态管理用 Zustand，不用 Redux
- CSS 用 Tailwind，不写裸 CSS 文件
- 文件名用 kebab-case：`user-profile.tsx`
- 每个组件导出带 JSDoc 说明 props 类型

## 禁止行为

- 不要修改 `src/api/` 下的自动生成的 API client
- 不要升级 package.json 里锁定的版本号
- 不要删除注释——特别是带 `// HACK:` 或 `// TODO:` 的

## 技术栈

- React 18 + TypeScript 5
- Zustand 4
- React Router 6
- Tailwind CSS 3
- Vitest + Testing Library（测试）

---

提示词模板：常用提示一键触发

有些对话你会反复用——比如”审查暂存的代码变更""生成 commit message""帮我重构这个模块”。每次都打一遍很烦，而且容易漏掉你本应关注的检查点。

提示词模板（Prompt Templates）就是为解决这个问题设计的。它把一段完整的提示词存在 .md 文件里，使用时在编辑器中敲 /模板名 就能展开。

模板放在哪

pi 从四个位置加载模板：

位置	作用范围	说明
~/.pi/agent/prompts/*.md	全局	所有项目可用
.pi/prompts/*.md	当前项目	项目信任后才加载
Pi Packages 的 prompts/ 目录	包级别	随 package 分发
--prompt-template <path>	CLI 临时	命令行直接指定文件

如果不想加载任何自动发现的模板，启动时加 --no-prompt-templates。通过 --prompt-template 显式指定的模板仍然会加载。

模板格式

模板就是一个带 YAML Frontmatter 的 Markdown 文件。文件名（不含 .md）就是命令名。

一个最简单的代码审查模板 review.md：

---
description: 审查当前的 git 暂存变更
---
审查暂存区中的更改（git diff --cached），重点关注：
- 潜在的 bug 和逻辑错误
- 安全问题
- 错误处理和边界情况
- 性能问题

存到 ~/.pi/agent/prompts/review.md 后，在编辑器中敲 /review 就会展开整段提示词。

description 是可选的，但强烈建议写——它会在自动补全下拉菜单中显示，帮你快速分辨模板用途。如果不写，pi 会用文件的第一行非空文本作为描述。

参数系统

模板不只是死文本，它支持参数替换，让同一个模板适应不同场景。

语法	含义	示例
$1, $2, $3…	位置参数	$1 代表第一个参数
$@ 或 $ARGUMENTS	所有参数的合并	所有参数用空格连接
${1:-默认值}	带默认值的参数	有值时用参数，否则用默认值
${@:N}	从第 N 个参数开始	${@:2} 取第 2 个起的所有参数
${@:N:L}	从第 N 个起取 L 个	${@:2:3} 取第 2~4 个参数

来看一个带参数的模板——生成组件：

---
description: 用指定框架创建组件
argument-hint: "<组件名> [功能描述]"
---
用 React + TypeScript 创建一个名为 $1 的组件，功能包括：$@

使用方式：

/component Button "onClick 事件处理" "disabled 状态支持" "loading 加载状态"

展开后效果：

用 React + TypeScript 创建一个名为 Button 的组件，功能包括：onClick 事件处理 disabled 状态支持 loading 加载状态

argument-hint：提示参数

在 Frontmatter 中加 argument-hint 可以告诉用户这个模板需要什么参数。用 <尖括号> 表示必填参数，[方括号] 表示可选参数：

---
description: 从 URL 审查 PR，分析代码和问题
argument-hint: "<PR-URL> [审查重点]"
---
审查以下 PR 的代码变更，重点关注 $2 方面的问题：${1:-安全性、性能、可维护性}
PR 地址：$1

在自动补全下拉菜单中会显示为：

→ pr   <PR-URL> [审查重点]  — 从 URL 审查 PR，分析代码和问题

这个提示能大幅降低用错参数的概率。

常用模板范例

以下是几个实用模板，你可以直接拿去用。

Git 提交信息生成（commit.md）：

---
description: 根据 git diff 生成规范的提交信息
---
查看 git diff --cached 的内容，生成一条规范的 git commit 信息。

遵循 Conventional Commits 规范，格式：type(scope): description
类型包括：feat, fix, refactor, docs, test, chore

只输出提交信息本身，不要多余的解释。

代码重构（refactor.md）：

---
description: 重构指定的代码模块
argument-hint: "<文件路径或模块名>"
---
重构 $1 的代码，目标：
1. 提高代码可读性
2. 消除重复代码
3. 改善错误处理
4. 保持现有功能不变

修改前请先说明你的重构计划。

Bug 排查（debug.md）：

---
description: 系统性排查和修复指定的 Bug
argument-hint: "<Bug 描述>"
---
我需要你帮我排查和修复以下 Bug：$1

请按步骤进行：
1. 理解 Bug 的预期行为和实际行为
2. 找到相关的代码文件
3. 分析可能的原因
4. 提出修复方案
5. 实现修复

每一步都要说明你的发现和推理。

项目状态总结（summarize.md）：

---
description: 总结当前项目的最近变更
argument-hint: "[要点数量]"
---
用 ${1:-7} 个要点总结当前项目的主要变更和状态。
重点关注：新增功能、修复的 Bug、重构的模块、性能变化。

加载规则

几个容易踩坑的点：

• prompts/ 目录中的模板发现是非递归的——子目录里的模板不会被自动发现。如果需要加载子目录中的模板，要在 settings.json 的 prompts 数组中显式添加路径
• --no-prompt-templates 禁用自动发现后，通过 --prompt-template 显式指定的模板仍然会加载
• 模板文件修改后用 /reload 就能热重载生效——它会把上下文文件、扩展、技能、提示词模板和主题一起重新加载，不需要重启 pi

---

小结

AGENTS.md 管的是”pi 是什么样的人”——它的编码风格、行为准则、项目规范。提示词模板管的是”pi 经常要干的事”——把重复性提示固化、参数化。两者配合在一起，你的 pi 就不再是一台出厂设置的通用的机器，而是一个懂你习惯的工作伙伴。