一套讓 agent 先問該不該寫的規則。
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% 的一組。
該存在嗎
標準庫
平台原生
已裝依賴
一行
最小可行
He says nothing. He writes one line. It works. 他什麼都不說。他寫一行。它就動了。
14 種 agent, 各自一行裝好。
Claude Code 與 Codex 的 plugin 會跑兩個極小的 Node.js 生命週期 hook,所以 node 需在 PATH 上。最常見的兩個 host 安裝如下:
# 在 Claude Code 對話框輸入這兩行
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
# 桌面版 Claude 沒有 /plugin 指令:改從 UI 安裝
# Customize → personal plugins 旁的 + → Create plugin and add marketplace
# → Add from repository → 貼上 repo URL# Codex CLI
codex plugin marketplace add DietrichGebert/ponytail
# 開 /plugins 選 Ponytail 安裝,再到 /hooks 檢視並信任兩個 lifecycle hook
# GitHub Copilot CLI
copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail其他 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,零設定 |
四個強度, 五個指令。
Ponytail 預設每個 session 常駐,強度分四級。/ponytail 不帶參數會回報當前等級;帶 lite / full / ultra / off 切換。指令需要 skill-capable host(Claude Code、Codex、OpenCode、Gemini、pi);在 Codex 裡它們是技能,用 @ 觸發。
Level · 01
/ponytail lite
輕量提醒
最低干預。在不打斷節奏的前提下,於明顯 over-build 時輕推一下。
Level · 02
/ponytail full
預設強度
預設值。每一輪都套用完整決策階梯。可用 PONYTAIL_DEFAULT_MODE 改全域預設。
Level · 03
/ponytail ultra
最強模式
官方說明:留給「codebase 得罪過你」的時候。最積極地砍多餘建構。
Level · 04
/ponytail off
關閉
暫時停用。啟動與切換時會顯示目前模式。
Command · 05
/ponytail-review
diff 審查
審查當前 diff 的過度工程,回傳一份「刪除清單」。
Command · 06
/ponytail-audit
全 repo 稽核
稽核整個 repo 的過度工程,範圍不限於這次 diff。
Command · 07
/ponytail-debt
技術債帳本
把你用 ponytail: 標記延後的捷徑收集成帳本,讓「之後再說」不會變成「永遠不做」。
Command · 08
/ponytail-gain
成效計分板
顯示 benchmark 量到的影響:少寫的 code、省下的成本、加快的速度。
Command · 09
/ponytail-help
快速參考
上述指令的快速參考。
六階決策階梯,逐階問清楚
這是 Ponytail 的核心機制。寫 code 前,agent 沿這條階梯往下,停在第一個成立的階——能用標準庫就不裝套件,有平台原生功能就不自己寫:
| 階 | 問題 → 行動 |
|---|---|
| 1 | 這需要存在嗎? → 不需要就跳過(YAGNI) |
| 2 | 標準庫能做嗎? → 用它 |
| 3 | 有平台原生功能嗎? → 用它 |
| 4 | 已安裝的依賴能做嗎? → 用它 |
| 5 | 一行能解決嗎? → 一行 |
| 6 | 到這裡才寫:能動的最小實作 |
依官方文件, 這樣用最有效。
以下八條全部來自官方 README 與 docs,不含社群傳聞或未驗證的數字。每張卡標注出處段落。
預設是 full,可用 env 改全域
用 PONYTAIL_DEFAULT_MODE 環境變數(lite/full/ultra/off),或 ~/.config/ponytail/config.json 的 defaultMode 欄位,設定每個新 session 的等級。預設 full。
來源 · 官方 README「Install」段落
ultra 留給「被 codebase 得罪」時
官方原話:/ponytail ultra exists for when the codebase has wronged you personally。日常用 full 即可,ultra 砍得最積極。
來源 · 官方 README「Install」段落
review 給你一份刪除清單
寫完一段就跑 /ponytail-review,它審查當前 diff 的過度工程,回傳可刪項目;/ponytail-audit 則擴大到整個 repo。
來源 · 官方 README「Commands」
用 ponytail: 標記延後,再用 debt 收回
真的要走捷徑時,用 ponytail: 註解標記。之後跑 /ponytail-debt 把這些延後項收集成帳本,避免「之後」變「永遠不做」。
來源 · 官方 README「Commands」
指令需要 skill-capable host
指令需 Claude Code、Codex、OpenCode、Gemini 或 pi。Cursor、Windsurf、Cline、Copilot、Kiro、Antigravity 等 instruction-only adapter 只載常駐 ruleset,沒有指令與模式開關。
來源 · 官方 README「Commands」
node 要在 PATH 上
Claude Code / Codex plugin 跑兩個 lifecycle hook,需要 node 在 PATH。不在的話技能仍可用,只是常駐啟用會安靜停用而非報錯。Nix/nvm 注意非互動 shell。
來源 · 官方 README「Install」段落
CodeWhale 讀 AGENTS.md,零設定
把 AGENTS.md 複製到你的專案根目錄,或從本 repo 的 checkout 執行 codewhale,規則即生效。VS Code 的 Codex 擴充同樣讀 AGENTS.md。
來源 · 官方 README「Install」段落
不需要設定檔
官方 FAQ:不需要 config 檔。可選的 config.json 或 env 變數只用來設預設等級,沒有任何必填項。
來源 · 官方 README「FAQ」
一個日期選擇器, 從一堆檔案到一行。
以下取自 README 的招牌例子:同樣要一個日期選擇器,無技能的 agent 會去裝套件、寫 wrapper、加樣式表;掛上 Ponytail 後,它停在決策階梯的「平台原生」那一階——瀏覽器本來就有 <input type="date">。接著示範 /ponytail-review 在一段已寫好的 diff 上回傳刪除清單。
$ You ›
幫我加一個日期選擇器,讓使用者選預約日期。
hl: rung 3 平台原生? → 命中。瀏覽器有原生 date input
claude: Claude(ponytail)›
不用裝 flatpickr,不用 wrapper component,不用樣式表。
瀏覽器本來就有一個:
ok: <!-- ponytail: browser has one -->
ok: <input type="date">
$ You › /ponytail-review
claude: DELETE LIST —
hl: · dateUtils.ts:formatForPicker() 包了原生 toISOString(),刪
hl: · DatePicker.css(整檔)原生控制項自帶樣式,刪
· validateDate() 保留 — 信任邊界驗證,不在砍的清單上
ok: 淨變動:-86 行 · 安全護欄:全數保留 ✓
你要一個日期選擇器。 瀏覽器本來就有一個。
這段示範的重點
砍掉的是 包裝,不是 功能:被刪的是重複包原生 API 的工具函式和多餘樣式表,而 validateDate() 這種信任邊界驗證留著。這正是 Ponytail 與單純「寫一行」prompt 的差別——後者在 benchmark 會掉掉一道安全護欄,Ponytail 不會。
示範中的行數是說明性數值。實際省幅取決於任務本身:有真正 over-build 陷阱(date picker、color picker)時最大,程式本來就精簡時接近零。
知道它不省什麼。
把懶惰內建到每個 session。
裝好、跑通 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 的完整對照。
The code you never wrote scales infinitely. 你從沒寫的程式,可以無限擴展。 零 bug、零 CVE,永遠 100% 上線。