Ponytail 是 MIT 授權的開源 AI agent 技能,把「最懶的資深工程師」的判斷裝進你的 agent:寫 code 前,先沿一條六階決策階梯往下問——「這需要存在嗎?標準庫能做嗎?平台原生功能有嗎?」最後才寫最小可行的程式。在真實 Claude Code session 的測試中,相對無技能 baseline 平均少寫約 54% code(over-build 情境最高 94%),同時保留每一道安全護欄。本手冊涵蓋安裝、四種強度、指令總覽、官方用法與一段實戰示範。
Ponytail 由 Dietrich Gebert 開源,本質是一份注入 AI agent 的規則集(ruleset),外加幾個技能與指令。它的人設來自每間公司都有的那位資深工程師:綁馬尾、戴橢圓眼鏡,在公司比版本控制還久;你給他五十行,他看一眼,什麼都不說,用一行換掉。Ponytail 把那個人放進你的 agent。
它解決的是 AI agent 的一個傾向:過度建構(over-build)。你要一個日期選擇器,agent 可能去裝 flatpickr、寫一個 wrapper component、加一張樣式表,還順便開啟時區的討論。Ponytail 介入的點在於,寫任何 code 前先沿一條六階決策階梯往下走,停在第一個成立的階。
關鍵不是「最少 token」,而是只寫任務需要的。程式之所以小,是因為它必要,不是因為被壓行數。官方在真實 repo(FastAPI + React)上用 headless Claude Code 跑 12 個功能任務(Haiku 4.5、n=4)測得:相對無技能 baseline,Ponytail 是唯一在 LOC、token、成本、時間四項全降、且安全分維持 100% 的一組。
Claude Code 與 Codex 的 plugin 會跑兩個極小的 Node.js 生命週期 hook,所以 node 需在 PATH 上。最常見的兩個 host 安裝如下:
skill-capable 的 host 用各自的套件指令安裝;instruction-only 的編輯器則複製對應的 rules 檔即可,規則仍會常駐。
| 工具 | 安裝方式 |
|---|---|
| Gemini CLI / Antigravity CLI | gemini extensions install <repo URL>(或 agy plugin install) |
| OpenCode | 從本 repo 的 checkout 執行,於 opencode.json 加 plugin 路徑 |
| Pi agent harness | pi install git:github.com/DietrichGebert/ponytail |
| OpenClaw | clawhub install ponytail |
| Cursor / Windsurf / Cline / Kiro / Zed | 複製對應的 rules 檔(.cursor/rules/、.windsurf/rules/ 等) |
| CodeWhale / VS Code(Codex 擴充) | 讀專案根目錄的 AGENTS.md,零設定 |
node 不在(非互動 shell 的)PATH 上,技能照常運作,只是常駐啟用會安靜地停用,而不是在每個 prompt 報錯。Nix / nvm 使用者要特別確認非互動 shell 的 PATH。
Ponytail 預設每個 session 常駐,強度分四級。/ponytail 不帶參數會回報當前等級;帶 lite / full / ultra / off 切換。指令需要 skill-capable host(Claude Code、Codex、OpenCode、Gemini、pi);在 Codex 裡它們是技能,用 @ 觸發。
PONYTAIL_DEFAULT_MODE 改全域預設。ponytail: 標記延後的捷徑收集成帳本,讓「之後再說」不會變成「永遠不做」。這是 Ponytail 的核心機制。寫 code 前,agent 沿這條階梯往下,停在第一個成立的階——能用標準庫就不裝套件,有平台原生功能就不自己寫:
| 階 | 問題 → 行動 |
|---|---|
| 1 | 這需要存在嗎? → 不需要就跳過(YAGNI) |
| 2 | 標準庫能做嗎? → 用它 |
| 3 | 有平台原生功能嗎? → 用它 |
| 4 | 已安裝的依賴能做嗎? → 用它 |
| 5 | 一行能解決嗎? → 一行 |
| 6 | 到這裡才寫:能動的最小實作 |
以下八條全部來自官方 README 與 docs,不含社群傳聞或未驗證的數字。每張卡標注出處段落。
用 PONYTAIL_DEFAULT_MODE 環境變數(lite/full/ultra/off),或 ~/.config/ponytail/config.json 的 defaultMode 欄位,設定每個新 session 的等級。預設 full。
官方原話:/ponytail ultra exists for when the codebase has wronged you personally。日常用 full 即可,ultra 砍得最積極。
寫完一段就跑 /ponytail-review,它審查當前 diff 的過度工程,回傳可刪項目;/ponytail-audit 則擴大到整個 repo。
真的要走捷徑時,用 ponytail: 註解標記。之後跑 /ponytail-debt 把這些延後項收集成帳本,避免「之後」變「永遠不做」。
指令需 Claude Code、Codex、OpenCode、Gemini 或 pi。Cursor、Windsurf、Cline、Copilot、Kiro、Antigravity 等 instruction-only adapter 只載常駐 ruleset,沒有指令與模式開關。
來源 · 官方 README「Commands」Claude Code / Codex plugin 跑兩個 lifecycle hook,需要 node 在 PATH。不在的話技能仍可用,只是常駐啟用會安靜停用而非報錯。Nix/nvm 注意非互動 shell。
把 AGENTS.md 複製到你的專案根目錄,或從本 repo 的 checkout 執行 codewhale,規則即生效。VS Code 的 Codex 擴充同樣讀 AGENTS.md。
官方 FAQ:不需要 config 檔。可選的 config.json 或 env 變數只用來設預設等級,沒有任何必填項。
以下取自 README 的招牌例子:同樣要一個日期選擇器,無技能的 agent 會去裝套件、寫 wrapper、加樣式表;掛上 Ponytail 後,它停在決策階梯的「平台原生」那一階——瀏覽器本來就有 <input type="date">。接著示範 /ponytail-review 在一段已寫好的 diff 上回傳刪除清單。
砍掉的是 包裝,不是 功能:被刪的是重複包原生 API 的工具函式和多餘樣式表,而 validateDate() 這種信任邊界驗證留著。這正是 Ponytail 與單純「寫一行」prompt 的差別——後者在 benchmark 會掉掉一道安全護欄,Ponytail 不會。
示範中的行數是說明性數值。實際省幅取決於任務本身:有真正 over-build 陷阱(date picker、color picker)時最大,程式本來就精簡時接近零。
/ponytail 指令與模式切換。
node 在(非互動 shell 的)PATH 上,Nix / nvm 環境尤其要檢查。
裝好、跑通 full 之後,下面幾步把 Ponytail 從「單一 host 的提醒」推到「整個團隊與工具鏈的一致規範」。
1. 設好團隊預設等級。用 PONYTAIL_DEFAULT_MODE 或 config.json 的 defaultMode 統一每個新 session 的強度,讓團隊不必每次手動切。
2. 把 review 接進你的流程。每個 PR 前跑 /ponytail-review 拿刪除清單,週期性跑 /ponytail-audit 掃整個 repo,把過度工程當成可量測的待辦。
3. 管理你的 ponytail 技術債。用 ponytail: 標記延後的捷徑,定期 /ponytail-debt 收成帳本,讓「之後再說」有歸還的一天。
4. 跨工具統一規範。用 docs/agent-portability.md 對照哪個檔對應哪個 agent,把同一套規則同步到 Cursor、Windsurf、Cline、Kiro 等 instruction-only 編輯器。
5. 自己量一遍。用 /ponytail-gain 看成效計分板,或依 benchmarks/ 在你自己的 repo 與模型上重現量測,別只信別人的數字。
① benchmarks/results/2026-06-18-agentic.md——完整方法、逐任務表格與限制。
② examples/——更多「倖存者」:被精簡前後的真實對照。
③ docs/agent-portability.md——哪些檔對應哪個 agent 的完整對照。