当我从放弃 Claude Code 转向 Pi 并且搭建了自己的一套 Coding Harness 才知道什么叫做效率

前述

我把主力 Coding Agent 从 Claude Code 切到 pi 已经三周多，最直观的感受并不是 Pi 有多厉害，而是可以搭一套属于自己的 Harness，效率高了不止一点

Pi 的缓存命中经常跑到 98% 以上，连续对话确实快👇（CH == cache hit）

但这只是结果。真正拉开差距的是，我终于能自己决定 Agent 怎么工作：哪些规则常驻、哪些能力按需加载、哪些任务丢给子 Agent、什么情况下必须停下来问我

Claude Code 很好用，开箱即用。但用久了会发现，它不好调。上下文和验证跟着产品走，子 Agent 怎么分工也不透明，任务一复杂就看不清它为什么这么拆、结果又被谁用掉了。还有就是，A\ 会夹带私货，为了限制第三方 API 设了不少关卡（太阴了）

而且最近 Pi 的热度可谓是火爆，我相信大家已经受够了重重的 Harness ，所以不妨和我一起来搭建属于自己的 Pi 吧

我想要的 Coding Agent 其实就几件事：读改代码、跑 Shell、加载项目规则、按需叫 SubAgent、改完能验证。pi 刚好把核心做得很小，其他都交给你自己拼。门槛是高了一点点🤏，但也让我第一次把 Harness 搭成了自己想要的样子

我的 Harness 分为三层

不是装得越多越强，我现在就分三层。

第一层是 AGENTS.md，管纪律。 全局一份，项目级一份，写的都是不怎么变的东西：改前先看结构和调用路径，只做必要改动，不顺手重构，需求模糊先提问，改完跑最相关的测试，最后看 diff。不确定就说假设。Agent 启动就拿到，不用每轮重写进 Prompt。

第二层是 Skills，管能力，按需加载。 我常驻的就几个：tdd、diagnosing-bugs、code-review、research，再加上一个自己写的管并行的 parallel-agent。一个 Skill 只管一种活，需要时再展开。堆多了反而容易路由错，不常用的，我就用 skillful 直接隐藏掉，这样子上下文十分干净

第三层是 Packages，管控制面。 这层也是我想重点聊的。我现在全局装了 10 个，挑几个常用的说说

1️⃣ pi-subagents 整个并行调度的底座。所有多 Agent 都走 workflowScript，runs.all 跑独立 lanes，

runs.run

跑串行阶段，fresh 隔离上下文，父 Agent 负责汇总和拍板。没有它，其他都是散的。

2️⃣ pi-skillful 管 Skills 的发现和加载。支持从仓库外层继续发现 .agents/skills/，支持 $ 显式展开，也支持把不常用的 Skill 隐藏，避免全部塞进系统提示词。我现在就隐藏了 10 个简历和 PPT 相关 Skill，需要时再切出来。

3️⃣

eko24ive/pi-ask

在歧义处停下来。目标文件、改原文还是新建、验收标准不明确时，用结构化的 ask_user 先问清选项。听起来不像效率功能，但它少一次推倒重写就赚回来了。

4️⃣ pi-simplify 只盯最近改动。扫重复和不必要的复杂度，不借 review 名义重构整个项目。

5️⃣

zigai/pi-mention-skill

把 Skill 调用从 / 改成 $。输入 $ 就能模糊搜 Skill 并展开到当前 Prompt，Skills 不用常驻也能随用随取。

6️⃣

tavily/pi-extension

给 researcher 加联网能力。web_search 先找，web_fetch 再抽正文，查资料和改代码分在不同 Agent 里，错误更好定位。

7️⃣

narumitw/pi-goal

管长目标的 /goal。给 session 一个显式目标，跑到完成、阻塞或等待外部事件才停，有 goal_complete / goal_blocked / goal_wait 三把闸，不让循环空转。

8️⃣ pi-context-usage 看 Context 烧到哪了。/context 给点阵图，/context details 展开 system prompt、工具和对话轮次的占比，快满了我会先做 compaction 或换 lane。

9️⃣

narumitw/pi-btw

开侧边线程。/btw 问临时问题，不污染主对话，答案只在需要时带回主线程。调 API 命名、查一段报错时很好用。

🔟

-labs/pi-fff 换掉 find / grep。基于 Rust 的 FFF，常驻索引、frecency 排序、git 感知，不用每次起子进程。找文件和扫代码的体感是最明显的，可以看我这一篇介绍 👇

你的 pi 正在用 grep 往 Context 里塞垃圾，我实测了一下午终于换掉了… pi 内置的 grep 其实就是 rg –json 套壳，limit 100 + 截断 50KB + 默认带 –hidden，搜一次 TODO 这种高频词，直接30 多条平铺甩进上下文。Token 烧了，关键文件还被埋在后面这个问题 Codex 早就用优化过的 rg 解决，pi

显示更多

来自 pi.dev

全局的 AGENTS.md 里的话我固定了一条 Coding Loop，保证每一步可验证：

确认目标和验收 → 读代码和规则 → 最小改动 → 跑最相关的测试或检查 → 看 diff → 需要时让 fresh reviewer 再看一遍。没有证据就不说完成

工作流怎么跑：先问清，再侦察，最后才改

有了分层，流程反而变简单了。我现在的默认路径是：

有歧义就先用 ask_user 问清，再让 scout 只读侦察，确认入口、调用链和风险；确认后再让 worker 去改；改完起全新的 reviewer 并行看 diff、测试和边界，父 Agent 汇总后再修一轮。

关键约束只有一条：同一个目录同一时间只留一个 writer。reviewer 可以并行，因为只读。多 writer 同时改一个目录，谁先落盘都不代表谁对。真需要并行实现，就上 managed worktree，最后由父 Agent 合并。

并行也不是把同一句话复制给两个 Agent。一个看本地，一个看外部，这样才有意义。

小任务别强行套全流程。一个 Agent 能解决的，就别为了并行而并行

我踩过的坑

最早我装过 pi-todo，以为长任务一定要待办列表。实际跑下来，coding 任务要追的是子 Agent 状态、产物和验证证据，不是 checkbox。pi-subagents 的 workflow 和 artifact 已经够用，我就移除了。

还有一个教训是别堆 Skill 和 Package。之前几十个全放开，路由更差，管理成本也高。现在策略是：默认只留常用的，需要时再用 $ 拉出来。第三方 Package 能跑任意代码，装之前看一眼源码和权限就行。

pi-fff 这种带索引的，进大仓库会有一小段预热时间，这是正常滴

不用照搬我的配置，照这个思路拼就行

不用跟我装得一模一样，pi 的好处就是你可以按自己习惯拼。给你一个最小可用的思路：

1. 先定纪律。 在 ~/.pi/agent/AGENTS.md 写清楚你的边界，比如：简单优先、最小改动、需求模糊先问、改完必跑测试必看 diff。项目级再补一条该项目的特殊约束就够

2. 再挑能力。 Skills 别全装，就留你每周都会用的 4 到 6 个，其他隐藏掉，User 级别和 Repo 级别分开管。Packages 也是，先把 pi-subagents 和 pi-skillful 装上，再按痛点加两三个，比如需要经常问你就加 pi-ask，找文件慢就加 pi-fff