---
url: /blog/jxq3nhjy/index.md
---
**完全不用 Trellis、Superpowers、OpenSpec、Spec Kit**，按 Pi 作者 Mario Zechner 的理念，最好的日常流程不是再找一套“隐藏的自动化工作流”，而是：

> **把上下文、计划、待办、验收标准都写成仓库中可见的文件；先单独调研，再在新的干净会话实现；把任务切小到你能审查和验证的范围。**

Pi 的核心立场是：工具应保持最小、可观察、可分支；不要依赖黑箱 sub-agent、内置 plan mode、自动 todo 或层层权限弹窗。Pi 默认只提供读、写、精准编辑和 shell 四类工具，工作流由你用 `AGENTS.md`、`PLAN.md`、`TODO.md`、Git 和多个 session 自己组成。\[@]\[@]

## 作者思路：文件优先

Mario 的原话逻辑可以概括为：

| 其他 Agent 常内置的功能    | Pi 的替代方式                                     |
| ------------------ | -------------------------------------------- |
| Plan mode          | 直接把计划写入 `PLAN.md`                            |
| 内置 Todo            | 用带 checkbox 的 `TODO.md`                      |
| 隐藏式 sub-agent      | 单独开一个 Pi session 做调研或审查，产出可见文件               |
| 后台命令               | 用 `tmux`，让运行状态可查看、可接管                        |
| 大而全的 system prompt | 用全局与项目级 `AGENTS.md` 明确规则                     |
| 固定工作流              | 根据项目自己用 Markdown prompt template / skills 组合 |

Pi 的 README 明确写着：它没有 built-in todos 和 plan mode，建议分别使用 `TODO.md` 和计划文件；它也不内置 sub-agent，建议要么单开 session，要么自行通过 `bash` 调用 Pi。\[@]\
作者强调的关键不是“更少步骤”，而是**所有步骤和上下文都能看到、修改、提交、复用和审查**。\[@]

***

## 最实用日常流程

对于你日常 Java/Spring Boot 开发，我建议采用这个 **轻量四阶段流程**：

```
0. 项目规则：AGENTS.md
1. 探索/定位：单独的只读 session
2. 方案/任务：PLAN.md + TODO.md
3. 实现/验证：新的实现 session，小步提交
4. 审查/复盘：新的审查 session，更新文档
```

它看起来简单，但已经覆盖了 spec workflow 的核心价值，同时比引入四套框架更容易理解和长期坚持。

```
需求
  ↓
只读探索（找真实上下文）
  ↓
PLAN.md（目标、设计、影响范围、验证方式）
  ↓
TODO.md（最小可验证任务）
  ↓
新会话实施 + 每步测试
  ↓
新会话独立审查
  ↓
Git 提交 + 更新项目知识
```

这里最重要的原则是：

1. **调研与实现分开。**
2. **一个 session 只做一个明确阶段。**
3. **计划和任务写到文件，不依赖聊天记忆。**
4. **任务边界要小到你可以理解 diff、运行验证并承担后果。**
5. **高风险或不熟悉改动，必须单独 review。**

作者认为，在同一会话里临时派 sub-agent 去找上下文，往往意味着没有先规划好；更好的方式是先用独立 session 做上下文收集，产出一个可复用的 artifact，再把它带进一个干净的实现 session。\[@]

## 一次功能的具体做法

以“为管理员增加用户搜索 API”为例。

### 0. 先固定项目规则

在项目根目录放 `AGENTS.md`。Pi 会在启动时自动从全局目录、父目录和当前项目目录加载 `AGENTS.md` 或 `CLAUDE.md`；不同路径的规则会按层级拼接。\[@]

对 Java 项目可用这一版：

```
# AGENTS.md

## Project
- Java 17, Spring Boot 3, Maven.
- Keep Controller, Service, Repository, DTO, Entity responsibilities separate.
- Reuse existing error-response, validation, logging, and auth patterns.

## Before Editing
- For work that spans more than one file, first inspect the relevant implementation,
  tests, configuration, and call sites.
- Before changing public APIs, identify compatibility and authorization impacts.
- Ask before changing database schema, dependencies, CI, deployment configuration,
  or deleting apparently intentional code.

## Implementation
- Keep the requested change narrow; do not refactor unrelated code.
- Add or update tests for behavior changes.
- Do not claim success if commands were not run; state exactly what was not verified.

## Verification
- After source-code changes, run:
  mvn test
- For formatting or static analysis, run the project’s existing commands if present.
- Report modified files, tests run, results, risks, and follow-up items.

## Git Safety
- Never run git reset --hard, git clean -fd, git checkout ., or git add .
- Never commit or push unless explicitly requested.
- Stage explicit file paths only.
```

这套规则不是“绝对安全机制”——模型仍可能违反文字指令——但它给了 Pi 每个 session 稳定、可审查的默认行为。Pi 作者自己也是通过仓库中的 `AGENTS.md` 放入代码质量、测试、依赖安全、Git 操作边界和“用户指令冲突时先确认”等规则。\[@]

### 1. 用只读 Session 做探索

不要一上来启动普通 Pi 然后说“帮我做用户搜索”。

先在项目根目录运行：

```
pi --tools read,grep,find,ls --name "research-user-search"
```

Pi 的 `--tools` 参数可以限制可用工具；`read,grep,find,ls` 是一个只读探索模式，不给它 `edit`、`write` 或 shell 执行能力。\[@]

然后输入：

```
我需要为管理员新增“用户搜索 API”，但现在不要写任何代码或创建文件。

请只读分析当前项目：
1. 找到现有用户管理相关的 Controller、Service、Repository、DTO、Entity 和测试；
2. 找到分页、模糊搜索、统一响应、异常处理、权限校验的既有实现；
3. 找出可复用的代码模式和潜在冲突；
4. 列出预计受影响的文件；
5. 给出需要我确认的问题；
6. 最后输出一份可直接写入 docs/research/user-search.md 的调研报告草稿。

不要猜测；每条结论附带文件路径和类/方法名。
```

你审阅它的输出。若满意，再让它把报告写成文件；或者你自己把关键结论保存到：

```
docs/research/user-search.md
```

为什么要这么做：

* 调研时的 grep、文件内容、失败尝试会污染上下文。
* 实现时不需要携带这些冗长工具输出，只需要带一份整理后的结论。
* 你能检查 Agent 有没有漏读关键模块。
* 这个调研文件下次做相近功能时仍可复用。

这是 Pi 作者明确提倡的模式：**先在独立 session 收集上下文，产出 artifact；再在一个新 session 中使用这个 artifact 实现。**\[@]

### 2. 写 `PLAN.md` 与 `TODO.md`

调研完成后，退出 session，或者用 `/new` 开一个新会话。\
创建：

```
docs/plans/user-search.md
TODO.md
```

建议不要把全项目所有任务都塞进一个永不清理的 `TODO.md`。你可以采用：

```
docs/plans/
docs/research/
docs/tasks/
```

例如本功能的计划：

```
# 用户搜索 API 实施计划

## Goal
管理员可以按照用户名或邮箱模糊查询用户，支持分页。

## Scope
- 增加管理员用户搜索接口
- 复用既有用户 DTO、统一响应格式和权限模型
- 增加 Service、Repository 查询及测试

## Non-goals
- 不修改用户表结构
- 不做 Elasticsearch
- 不改变普通用户权限
- 不改现有用户详情接口

## Evidence
- 现有用户管理入口：`src/.../UserAdminController.java`
- 分页模式：`src/.../OrderController.java`
- 权限注解模式：`src/.../AdminPermission.java`
- 测试样例：`src/test/.../UserServiceTest.java`

## API Contract
- `GET /api/admin/users`
- 参数：`keyword`、`page`、`size`
- keyword 为空时的行为：待确认 / 返回全部 / 返回 400
- 返回：现有分页响应 DTO
- 权限：管理员

## Approach
1. 按现有分页规范定义请求参数与响应 DTO。
2. 在 Repository 增加用户名、邮箱的大小写无关模糊查询。
3. 在 Service 处理参数校验、权限语义和分页。
4. 在 Controller 增加 endpoint。
5. 编写 Repository、Service 或 Controller 层的已有风格测试。

## Risks
- `LIKE %keyword%` 的索引命中与数据量增长风险。
- 用户名和邮箱匹配优先级。
- 空 keyword 的业务语义。
- 管理员角色识别方式需要复用现有实现。

## Verification
- `mvn test`
- 对合法搜索、无结果、分页边界、非管理员访问、非法 page/size 写测试。
- 手动检查接口返回格式与既有管理端 API 一致。

## Current Step
等待确认空 keyword 规则和 page/size 上限。
```

对应的任务文件：

```
# 用户搜索 API 任务

- [ ] T1：确认空 keyword、默认 page/size、最大 size 与排序规则
- [ ] T2：实现或复用查询 DTO 与参数校验
- [ ] T3：实现 Repository 查询，并补充查询层测试
- [ ] T4：实现 Service 逻辑，并补充 Service 测试
- [ ] T5：实现 Controller 与权限校验，并补充 Web 层测试
- [ ] T6：运行 `mvn test`，修复失败
- [ ] T7：独立审查 diff、测试覆盖与 API 兼容性
- [ ] T8：更新 API 文档或变更日志（若项目已有此要求）
```

这就是 Pi 作者建议的 **外部状态**：`PLAN.md` 保存长期路线，`TODO.md` 或任务文件保存进度，checkbox 显示已完成和未完成项。它们比 Agent 内置 todo 更透明、可版本控制、可跨会话共享。\[@]\[@]

### 3. 新开实现 Session

不要把“调研 session”直接接着做实现。新开：

```
pi --name "implement-user-search"
```

第一条消息要非常具体：

```
实现 docs/plans/user-search.md 中已确认的方案。

先依次阅读：
- AGENTS.md
- docs/research/user-search.md
- docs/plans/user-search.md
- docs/tasks/user-search.md
- 计划中列出的现有实现和测试样例

约束：
1. 不要扩展范围，不做无关重构；
2. 每完成一个任务，更新 docs/tasks/user-search.md；
3. 修改前先说明本步将改哪些文件及原因；
4. 先完成 T2，再停下来汇报 diff 和测试计划，等待我继续；
5. 不得提交 Git，不得修改数据库迁移、依赖或 CI 配置。
```

这样你把“继续权限”切成阶段，而不是让它一口气改完十几个文件。

日常建议的粒度：

|任务类型|建议 Agent 一次完成的范围|
|---|---|
|小 bug|一个明确根因、1–3 个文件、一个验证命令|
|新 API|一个 endpoint 的一个垂直切片：DTO + Service + Controller + 对应测试|
|重构|一个模块/一个接口边界，不要“整个项目一起重构”|
|依赖升级|一个依赖或一个小版本范围，并先出影响分析|
|数据库变更|migration + entity + 数据访问 + 回滚说明，必须人工确认后再执行|

“可验证的、有界任务”是作者工作理念的核心：人能审查的任务边界，才适合交给 Agent；关键设计判断仍应由人承担。\[@]

### 4. 每个步骤即时验证

完成一个任务后，直接让 Pi：

```
现在只做以下验证：
1. 显示 git diff；
2. 说明修改与 PLAN.md 哪一节对应；
3. 运行与本步骤相关的最小测试；
4. 如果通过，再更新 tasks 文件；
5. 不要继续下一个任务。
```

每个功能完成前，再运行项目的真实验证命令：

```
mvn test
```

如果你的项目有：

```
mvn verify
mvn spotless:check
mvn checkstyle:check
```

以项目原有的 CI 规则为准，不要为了 AI 临时引入一堆新检查。

Pi 自己的 `AGENTS.md` 也是这种思路：修改源码后必须运行指定检查；改了测试文件必须实际运行对应测试；无法运行时不能声称成功。它还要求改动范围大时先完整阅读文件，而不是靠搜索片段猜上下文。\[@]

## 审查要单独开会话

当实现完成，不要只让刚刚写代码的 Agent 自评“没问题”。

开一个新会话，最好用不同模型，或至少干净上下文：

```
pi --tools read,grep,find,ls --name "review-user-search"
```

输入：

```
作为独立代码审查者，审查当前工作区与 docs/plans/user-search.md 的一致性。

不要修改任何文件，也不要根据作者解释直接相信实现。
请：
1. 阅读计划、任务、改动 diff 和关联代码；
2. 检查功能是否符合验收标准；
3. 检查权限绕过、参数校验、分页边界、异常处理、N+1 查询、
   SQL 模糊匹配性能、测试遗漏和兼容性风险；
4. 把问题按 Critical / High / Medium / Low 分类；
5. 每条都给出文件路径、代码位置、风险理由与修复建议；
6. 如果没有问题，也要明确列出已检查但未发现问题的范围。
```

然后你再决定：

* 有问题：回到实现会话，或新开一个 `fix-review-findings` 会话。
* 没问题：你亲自看 diff，决定是否提交。
* 涉及安全、权限、资金、删除数据、数据库迁移：不要只依赖 Agent review，必须自己读核心代码。

Pi 作者把“把 Pi 再启动一个实例作为审查者”列为较合理的 sub-agent 用法；但他实际更偏向于单独开一个会话审查 Pull Request，再由人加入自己的 review，避免把整个审查过程藏在主 Agent 的黑箱里。\[@]

## 什么时候用 Session 分支

Pi 的 session 是 JSONL，并且是树状历史；可以 `/tree` 回到此前消息节点继续，或 `/fork` 从某条用户消息创建新的会话文件。\[@]

日常可这样使用：

|场景|最佳动作|
|---|---|
|要比较两种技术方案|在需求提出后用 `/fork` 分出 A、B 两个方案 session|
|Agent 开始误解需求|`/tree` 回到误解前，换一条更明确的指令|
|一半发现方案不对|保留现有分支，`/fork` 开新分支，不要强行在污染的上下文中“修正”|
|调研结束要编码|不一定 fork；更推荐新 session，只把 `research.md`、`PLAN.md` 带入|
|要独立 code review|新 session，最好只读工具|
|临时问一个无关问题|`pi --no-session`，不要污染主任务历史|

长上下文会被压缩，而压缩是有损的。对于重要长期工作，核心决策应始终存在 Markdown 文件中，而不应只留在聊天历史里；Pi 虽可用 `/compact` 压缩和 `/tree` 回看原始历史，但这不替代项目 artifact。\[@]

## 你需要的最小文件集合

不使用任何框架时，我建议就维持下面这些，已经足够：

```
your-project/
├── AGENTS.md
├── README.md
├── TODO.md                         # 项目级、长期未完成事项
├── docs/
│   ├── research/
│   │   └── user-search.md          # 探索和证据
│   ├── plans/
│   │   └── user-search.md          # 目标、方案、风险、验证
│   ├── tasks/
│   │   └── user-search.md          # checkbox 任务
│   └── decisions/
│       └── 0001-search-strategy.md # 有长期影响的关键决策
└── src/
```

不必每个小 bug 都生成四份文档。根据工作量分级：

|改动规模|推荐流程|文档要求|
|---|---|---|
|一行或明确的小修复|定位 → 修改 → 单测/验证 → 人工看 diff|不需要 PLAN|
|小功能，1–5 文件|先读关联代码 → 写简短 plan → 实现 → 测试 → review|一个 `docs/plans/*.md` 即可|
|中型功能，多层/多模块|调研 session → research + plan + tasks → 分段实现 → 独立 review|三件套都要|
|高风险功能|先人工设计/评审 → Agent 分小步协作 → 强验证 → 人工 review|加 decision、风险、回滚、验收标准|
|大型重构|先探索所有调用链 → 迁移计划 → 逐批兼容/验证 → 每批独立 review|plan + tasks + 迁移与回滚计划|

## 两个你可以直接保存的 Prompt

Pi 支持 Markdown prompt templates：放在 `~/.pi/agent/prompts/` 可以全局使用，放在 `.pi/prompts/` 则只在当前项目生效；在 Pi 里用 `/命令名` 调用。\[@]

### `/research`

保存为：

```
.pi/prompts/research.md
```

内容：

```
只做调研，不修改文件、不创建文件、不运行会改变环境的命令。

任务：{{task}}

请：
1. 找到相关入口、核心调用链、数据模型、配置和测试；
2. 完整阅读会被广泛修改的文件，不能仅依据搜索片段下结论；
3. 复用项目现有模式，而不是凭空设计新风格；
4. 指出不确定项和需要用户决定的业务规则；
5. 输出：
   - 相关文件及职责；
   - 现有实现模式；
   - 预计影响范围；
   - 风险；
   - 建议实施步骤；
   - 可复制到 docs/research/ 的 Markdown 报告。
6. 每项事实标出文件路径、类名或方法名。
```

调用：

```
/research 为管理员增加用户搜索 API
```

### `/review`

保存为：

```
.pi/prompts/review.md
```

内容：

```
只做代码审查，不修改任何文件。

审查目标：{{task}}

请读取：
- AGENTS.md
- 相关计划或需求文档
- git diff
- 所有被改动文件及必要的调用方/测试

按严重级别输出发现：
- Critical：安全、数据丢失、权限绕过、明显功能错误
- High：可能在常见场景失败、严重兼容性或性能问题
- Medium：边界遗漏、异常处理或测试缺口
- Low：可维护性、命名、风格

每个问题必须包含：
- 文件和行/方法位置；
- 为什么是问题；
- 触发条件；
- 最小修复建议。

最后列出：
- 已验证项目；
- 未能验证项目；
- 测试覆盖缺口；
- 与计划不一致之处。
```

调用：

```
/review 审查 user-search 功能是否符合 docs/plans/user-search.md
```

## 你现在最该坚持的规则

如果只记住 6 条，我建议是：

1. **先读后改**：不熟代码库时，先让 Pi 调研并留下 `research.md`。
2. **计划落盘**：中等以上改动必须先有 `PLAN.md` 或 `docs/plans/*.md`。
3. **任务要小**：一次只让 Agent 交付你能看懂和验证的一小块。
4. **干净会话**：探索、实现、审查分开；不要让一个又长又乱的 session 包办全部。
5. **验收可执行**：每项任务都写出测试命令、预期结果和人工检查点。
6. **人保留判断权**：需求边界、架构、权限、数据迁移、依赖变化和最终合并，始终由你做决定。

这其实就是 Pi 作者倡导的日常工作法：不是让 Agent 自己变成项目经理，而是你作为工程负责人，用**明确上下文、可见文件、有界任务、独立验证和人工审查**来驾驭一个极简但能力足够强的 Agent。\[@]\[@]