ponytail

1. 專案概覽

ponytail 是一套輕量級的技能與規則集，專為 AI 程式碼代理器（包括 Claude Code、Codex、Cursor 及其他 20 多個平台）設計。它訓練代理器僅撰寫最少且必要的程式碼——在生成任何新內容前先重複使用現有資源——在不犧牲安全性的前提下，將 AI 生成的程式碼量減少約一半。

2. 背景與定位

• 核心使命：現代程式碼代理器往往傾向過度產出——將簡單任務包裝在多餘的抽象層中、重新發明現有的工具函式，或忽略原生平台功能。ponytail 編碼了一套刻意的「決策階梯」，代理器在撰寫任何程式碼前必須逐步執行，使預設行為變為克制而非冗贅。其理念可總結於標語：「他沉默不語。他只寫一行。它就能運作。」
• 與類似專案的差異：ponytail 並非程式碼產生器、Linter 或風格指南，而是一套生成前規則集——它改變的是代理器最初決定撰寫的內容，而非事後輸出的格式。它明確設計為與 "caveman" 等工具互補（caveman 縮減代理器的對話長度，而 ponytail 縮減代理器的程式碼量），並以可攜式規則檔案或 Hook 的形式發布，而非獨立應用程式，因此幾乎可以安裝到任何 AI 程式碼工具中。

3. 功能分類

🪜 決策階梯

代理器在撰寫程式碼前會執行的 7 項順序檢查——判斷某項功能是否真的需要、是否已存在，或能否透過標準函式庫、原生平台功能或已安裝的相依套件解決。

• 這真的需要存在嗎？（YAGNI 檢查）
• 此程式碼庫中是否已有？
• 標準函式庫是否能處理？
• 是否有原生平台功能可用（例如 <input type="date">）？
• 是否有已安裝的相依套件具備此功能？
• 能否用一行程式碼解決？
• 僅當以上皆失敗時：撰寫最小可行的自訂程式碼

🧰 技能與指令

5 個斜線風格的指令，讓開發者能直接從代理器工作階段中檢視並強制執行極簡主義。

• /ponytail-review — 標記目前差異比對中的過度工程問題
• /ponytail-audit — 掃描整個儲存庫以找出不必要的程式碼
• /ponytail-debt — 將延後處理的 ponytail: 捷徑收集至帳本中
• /ponytail-gain — 顯示目前工作階段的基準測試指標
• /ponytail-help — 快速參考文件

🎚️ 強度等級

4 種可設定模式，控制代理器刪減程式碼的積極程度，可依專案或工作階段切換。

• lite — 溫和提醒，保留較多細節
• full — 平衡的刪減（預設值）
• ultra — 積極的極簡主義
• off — 停用規則集

🔌 平台整合

支援 20 多種 AI 程式碼代理器與編輯器，每個平台皆有原生安裝路徑（外掛管理器、擴充功能或直接複製規則檔案）。

• Claude Code、Codex、GitHub Copilot CLI
• Cursor、Windsurf、Cline
• Gemini CLI、Devin CLI、OpenCode、Aider、Zed 等

4. 主要亮點

• 程式碼減少約 54%，安全性不變 — 在 FastAPI + React 範本的實際功能需求單上進行測量，ponytail 將程式碼行數減少了 54%、Token 數量減少 22%、成本降低 20%、時間節省 27%，同時保持安全性（驗證、錯誤處理、安全性、無障礙性）維持在 100%。
• 跨代理器生態系可攜 — 以 AGENTS.md 加上各平台專屬規則副本（.cursor/rules/、.windsurf/rules/、.github/copilot-instructions.md 等）的形式發布，確保無論團隊使用何種程式碼代理器，皆能套用相同的紀律。
• 刻意的執行順序 — 決策階梯僅在代理器理解問題之後才執行，因此極簡主義絕不會以犧牲正確性為代價。
• 內建審查工具 — /ponytail-review 和 /ponytail-audit 將「減少程式碼」從一次性習慣轉變為整個程式碼庫中持續且可稽核的實踐。
• 零強制設定 — 開箱即用，預設為 full 強度；若團隊希望調整積極程度，可透過環境變數或設定檔進行微調。
• 乾淨的解除安裝路徑 — 專屬的 uninstall.js 腳本會清除模式旗標、設定檔及狀態列整合，因此採用此工具的風險極低且易於還原。

5. 依角色劃分的使用情境

• 一般開發者：獲得更接近謹慎人類工程師所撰寫的代理器生成程式碼——減少不必要的包裝元件、相依套件或抽象層，降低審查與維護負擔。
• 專案經理與技術主管：使用 /ponytail-gain 及已發布的基準測試方法論，量化 AI 輔助工作流程實際帶來的成本與時間節省。
• DevOps/SRE、安全工程師、資料與研究科學家：雖非直接目標對象——ponytail 對領域不具特定性，但其安全保證（驗證、錯誤處理、安全性、無障礙性「絕不被最小化」）意味著在上述任何情境中應用時，都不會為了簡潔而犧牲安全。

6. 快速入門

尋找所需資訊 — 從核心規則集與指令參考開始：

/ponytail-help

安裝與整合 — 針對 Claude Code：

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

其他平台（Codex、Gemini CLI、Cursor、Windsurf 等）皆有對應的一鍵安裝指令，或者可以直接從儲存庫複製規則檔案（.cursor/rules/、.windsurf/rules/、AGENTS.md）。

貢獻 — 在提交變更前，請驗證規則一致性並執行測試：

node scripts/check-rule-copies.js
npm test

7. 專案結構

ponytail/
├── AGENTS.md                 # 核心規則集（許多平台會自動載入）
├── skills/                   # 可執行技能（review、audit、debt、gain、help）
├── hooks/                    # 生命週期 Hook（平台專屬）
│   ├── hooks.json
│   └── qoder-hooks.json
├── .cursor/rules/            # Cursor/Windsurf/Cline 規則副本
├── .windsurf/rules/
├── .clinerules/
├── .github/copilot-instructions.md
├── scripts/
│   ├── check-rule-copies.js  # 驗證各代理器副本的一致性
│   ├── build-openclaw-skills.js
│   └── uninstall.js          # 清理本機狀態檔案
├── benchmarks/                # 測量方法論與結果
├── examples/                  # 修改前後的程式碼範例
└── LICENSE                    # MIT

關鍵檔案：AGENTS.md 包含權威的決策階梯規則集，所有平台專屬規則檔案皆以此為鏡像；scripts/check-rule-copies.js 則防止這些副本出現不同步的情況。

8. 相關生態系

• 相依項目：依賴其所安裝的 AI 程式碼代理器（Claude Code、Codex、Cursor、Gemini CLI 等）——ponytail 本身是規則集與技能，並非獨立執行環境。在 Claude Code 和 Codex 等平台上使用生命週期 Hook 時，PATH 中需包含 Node.js。
• 互補專案："caveman" 是一個伴隨規則集，用於減少代理器的對話冗長度，與 ponytail（減少代理器程式碼冗長度）搭配使用時功能不會重疊。

9. 授權條款

MIT 授權。

• ✅ 可自由使用、複製、修改及散布，包括用於商業目的。
• ✅ 可整合至專有或閉源的 AI 工具中。
• ❌ 不提供任何擔保；作者不對使用所造成的損害負責。
• ℹ️ 原始版權聲明與授權文字必須保留在軟體的副本或重要部分中。

10. 常見問題

問：ponytail 會與其他代理器行為工具（如 "caveman"）衝突嗎？
答：不會——caveman 減少代理器的對話長度，ponytail 減少代理器撰寫的程式碼。兩者設計上可搭配使用。

問：基準測試數據來自合成測試嗎？
答：不是——主要基準測試是在 tiangolo 的全端 FastAPI + React 範本上，針對實際功能需求單使用 Claude Haiku 4.5 進行測量，而非隔離的單次生成測試。

問：極簡主義是否會犧牲安全性或無障礙性？
答：不會——驗證、錯誤處理、安全性及無障礙性已被明確排除在決策階梯允許刪減的範圍之外。

問：如何調整 ponytail 的積極程度？
答：執行 /ponytail [lite | full | ultra | off]，或透過環境變數或 ~/.config/ponytail/config.json 設定 PONYTAIL_DEFAULT_MODE。

問：如何乾淨地移除 ponytail？
答：在使用平台的移除外掛指令前，先執行 node scripts/uninstall.js，以清除模式旗標、設定檔及狀態列項目。

11. 快速連結

• 儲存庫：https://github.com/DietrichGebert/ponytail
• 核心規則集：儲存庫根目錄下的 AGENTS.md
• 貢獻指南：node scripts/check-rule-copies.js 與 npm test（見儲存庫根目錄）
• 授權條款：MIT（儲存庫中的 LICENSE 檔案）

12. 總結

ponytail 將「少寫程式碼」從一種願景轉化為 AI 程式碼代理器可強制執行且可衡量的習慣，在維持安全性與無障礙性保證不變的前提下，將生成的程式碼量減少約一半。它最適合高度依賴 AI 程式碼代理器進行工作流程的團隊，確保輸出保持精簡且易於維護——只需在您偏好的代理器平台上安裝一次，決策階梯便會在每個任務中自動執行。