終端裡的 AI 程式助手越來越多：Claude Code、Cursor、各種「多代理＋Plan Mode＋MCP」大禮包。功能清單看起來很強，但你有沒有遇過這種感覺——工具一更新，行為就變了；你以為它在「幫你想」，其實有一段上下文是 UI 看不到的；出錯時又不知道該查哪一層？

（有點像咖啡店改菜單：你點的還叫同名，內容卻換了豆。AI 工具也會這樣，而且通常不會在杯子上貼告示。）

Pi Coding Agent 的作者 Mario Zechner，正是從這類痛點出發，選擇重做一個極小核心，而不是再往既有工具堆功能。這篇不寫假評測、也不喊誰全面勝利；目標很單純：用作者為什麼要發明 Pi 當鏡頭，幫你看懂兩種哲學，再決定自己要的是 Pi 的可控性，還是 Claude Code 的現成工作流。

讀完你會帶走：作者動機怎麼對到設計、四個原則怎麼想、一張決策表幫你 30 秒對號入座。

目錄

先講清楚：這不是「Claude Code 不好」

作者公開說法裡，Claude Code 常被當成「既有 Coding Agent 變複雜」的對照物——但那是對他自己工作流的取捨，不是對所有人的判決。

  • Claude Code 適合：想要內建 Plan、子代理、MCP、斜線指令，少自己組裝。
  • Pi 適合：想看見上下文與中間產物、把工作流放在檔案／CLI／tmux，願意自己決定要加什麼。

讀完這篇，你應該能回答一句話：「我比較怕黑箱變動，還是比較怕自己組工具的成本？」

答得出來，比背一百個功能還有用——功能清單只告訴你「有什麼」；真正幫你判斷怎麼修、怎麼選的，是你對工具的使用原則。

作者為什麼要重新做一個 Coding Agent？

既有工具遇到的問題（作者說法）Pi 的設計回應你實際該怎麼用
Claude Code 從早期較簡單，逐漸變成作者用不到很多功能的複雜工具；發布常改 system prompt／工具定義，既有工作流與模型行為跟著變核心「不需要就不建」；短 system prompt；差異放到外部擴充固定自己的提示、AGENTS.md、驗證流程；升級後重新檢查，不要假設行為永遠不變
Context engineering 很重要，但其他 harness 可能在 UI 看不到的地方注入上下文Session、工具呼叫、來源與產物保持可見；規劃寫成檔案，不藏在黑箱代理裡要求 Agent 把研究／計畫／檢查結果寫成可讀檔，人工看完再進下一階段
內建子代理把上下文傳遞與錯誤藏在另一層，出錯難追查不提供專用子代理工具；需要時用 bash 再開一個 Pi，或用 Extension／Package 自己組任務邊界與輸出格式清楚才拆 session，中間產物一律存檔

一句話總結作者動機：

當 Coding Agent 變得複雜、常改又不透明時，最可靠的回應不是再加一層功能——而是縮小核心、提高可觀測性，讓使用者自己決定要加什麼。

官方定位也呼應這點：「讓 Pi 適應你的工作流，而不是反過來。」——翻成口語：工具來遷就你的終端習慣，不是你遷就它的儀式流程。

Pi 的四個設計原則（對照 Claude Code 怎麼想）

1. 極簡核心，不是功能競賽

作者文章描述：Pi 的 system prompt 與預設工具定義合計可低於約 1,000 tokens；預設核心大致是讀、寫、編輯與 bash。極簡不是叫大家永遠只用四個工具，而是把 MCP、子代理、Plan Mode 等能力移到 Extensions、Skills、Prompt Templates、Packages——按痛點再加。

Claude Code 走另一條路：代理人循環（收集上下文 → 執行動作 → 驗證結果）＋較豐富的內建工具與斜線指令（如 /compact、/diff、/model），並以 CLAUDE.md、Skills、MCP 擴充。對「我想立刻開工」的人，這通常比較省事。

白話對照：Claude Code 像開箱即用的咖啡機；Pi 像手沖壺——多一步，但你看得見水溫、粉量和時間。

2. 可觀測性優先

Pi 偏好把計畫寫成 markdown：人可以編、跨 session 重用、能進版本控制。「Agent 做了什麼」變成可檢查的產物，而不是只信最後一句摘要。這跟**產物驅動開發（ADD）**很合：規格／計畫／進度先落檔，人工過目再寫碼。

Claude Code 也有規範檔與驗證迴圈，但作者批評的重點是：若規劃與子工作藏在內部狀態，除錯成本會變高。你若本來就習慣「先看 diff／計畫再准執行」，兩套都能做；差別在於狀態預設放在哪——檔案系統，還是工具內建流程。

3. 用組合取代內建一體化

Pi 刻意不內建官方建議替代什麼時候值得自己組
MCP小型 CLI＋README，或自行加 Extension工具少、要控 token、輸出想直接寫檔串接
子代理tmux 再開 Pi、Extension、Package要看見子過程，或真的要平行任務
Plan Mode計畫寫入檔案，或自行擴充計畫要跨 session、共同編輯、版控
背景 bashtmux長跑測試、開發伺服器、互動除錯
權限彈窗容器／隔離帳號／自訂確認不可信程式碼或機密資料

作者對大型 MCP 的具體顧慮是：工具說明每次塞進上下文，token 貴，輸出還常得繞回 Agent 才能保存。他提的替代是「小型 CLI + README + bash」——需要時才讀，輸出可直寫檔。

Claude Code 完整支援 MCP，對「接資料庫／瀏覽器／外部服務、不想自己包 CLI」的人是加分。你要選的是：內建方便 vs 按需載入、看得見成本。

4. 安全責任放回執行環境

Pi 預設不走「權限彈窗＝安全」這條路；作者認為 Agent 一旦能讀寫檔、跑指令，單靠彈窗很難形成完整邊界。這不是宣稱 Pi 比較安全，而是要求你用容器、隔離帳號、網路限制等真邊界。含機密的主機開 YOLO，風險在你，不能照抄作者個人設定。

Claude Code 的客戶端／權限與隔離設計，對不想自己管沙箱的人通常比較「有提示、有流程」。兩邊都不是魔法盾——差在預設假設誰負責安全。

比喻對應的做法實際效果
門上貼「請勿打擾」Agent 跳出權限彈窗，你點「允許」只是提醒／確認，對方真要闖還是進得去
門鎖上了容器、隔離帳號、網路限制物理／技術邊界，進不去才是真隔離

彈窗是禮貌的提示；隔離才是真的鎖門。兩者看起來都在「管安全」，保護力差很多。

決策表：我該選 Pi 還是 Claude Code？

用這張表做決定（可兩邊都裝，但同一目錄同時寫檔要隔離）：

你的情境較適合先確認這件事
想快速用完整內建流程，不想自己組工具Claude Code能否接受 system prompt／工具／版本變動
想逐步檢查上下文與中間產物、計畫要進 GitPi（或同等可觀測工作流）是否願意維護 markdown、CLI、tmux
Anthropic 訂閱深度使用者、愛斜線指令與內建 TaskClaude CodeMCP／Skills 的 token 與權限範圍
本地模型、控 token、設定要可移植（AGENTS.md、.pi/）Pi短 prompt 在你的模型／專案規模是否夠用（要實測）
要查瀏覽器、DB、外部服務，且想少寫 glueClaude Code＋MCP，或 Pi＋按需 CLI／Extension工具描述成本、輸出能否存檔
不可信程式碼或機密檔案先隔離，再選任一 Agent隔離是否真限制檔案與網路，而不只是警告

30 秒口訣

  • 怕黑箱與升級打破工作流 → 先試 Pi。
  • 怕自己組裝與維護成本 → 先用 Claude Code。
  • 都要一點 → 主流程用 Claude Code／IDE；終端批次、低成本實驗、可版控的 Agent 設定用 Pi。

推薦工具／資源

工具適合誰備註
Pi Coding Agent想要極簡核心、可觀測產物、按需擴充的終端使用者先用裸 Pi 跑通小任務，再加 Package／Extension
Claude Code想要內建代理人循環、MCP、斜線指令的 Anthropic 生態使用者用 CLAUDE.md 固定專案規範；升級後抽查行為
延伸閱讀想系統學 Pi 工作流站內：Pi Coding Agent 完整指南

客觀取捨：Pi 把「省心的一體化」換成「可控的組合成本」；Claude Code 相反。Pi 和 Claude Code 各有取捨，誰贏取決於你的風險與願不願意自己維護，不是全世界都該選同一個。

結語：選哲學，再選按鈕

作者發明 Pi，不是為了「功能贏過 Claude Code」，而是為了在複雜、常改、不透明的 Coding Agent 浪潮裡，留下一個看得見、擴得動、核心夠小的 harness。

帶走三點：

  1. 動機：縮小核心＋可觀測性，對抗黑箱與工作流被升級拆掉。
  2. 取捨：Claude Code 用整合換省心；Pi 用組合換控制權。
  3. 下一步：用上面的決策表對號入座，不要只比功能勾選清單。

先挑一個小任務（例如修一個測試失敗）——若你要「開箱即用」，用 Claude Code 跑完並看 /diff；若你要「計畫與驗證都落檔」，用 Pi 把計畫寫成 markdown 再改碼。跑完一次，比再讀十篇比較文更準。

審完再來一杯。下一杯建議：直接動手，別再收藏文章了。

參考資料