Ponytail 入門：15 分鐘從安裝到第一次極簡重構
〈YAGNI 原則與懶人工程學〉談了 Ponytail 的哲學與 7 階階梯，這一課要把那些觀念落成「手感」。15 分鐘內你會完成三件事：把 Ponytail 裝進你的 AI 編碼代理、選好適合新手的強度等級、對一個檔案跑出第一份過度設計報告。
1. 安裝 Ponytail
Ponytail 是外掛，不是獨立 CLI。在支援 /plugin 的代理（OpenCode、Claude Code 等）中執行：
/plugin marketplace add DietrichGebert/ponytail && /plugin install ponytail@ponytail支援的平台超過 10 個，包含 Claude Code、Codex、OpenCode、GitHub Copilot CLI、Gemini CLI、Antigravity CLI、Qoder、Hermes Agent、OpenClaw、Devin CLI、Pi agent 等，完整清單見主題首頁的 supportedPlatforms。
安裝完成後，Ponytail 規則集會自動注入到主要代理與子代理。如果想限定注入的子代理範圍，可設定環境變數 PONYTAIL_SUBAGENT_MATCHER 為正則表達式（新手不需要動這個）。
2. 確認與切換強度等級
Ponytail 有 4 個強度等級，差別在「多嚴格地執行 7 階階梯」：
| 等級 | 行為 | 適合 |
|---|---|---|
lite |
輕量建議，少砍 | 不確定時的試水 |
full |
預設值，平衡的 7 階執行 | 新手首選 |
ultra |
最激進，連可能過頭的安全防護也檢視 | 老手清技術債 |
off |
完全停用 Ponytail | 暫時關掉做對照 |
確認當前等級：
/ponytailPonytail 會回報目前的 level。要切換：
/ponytail full要讓等級跨重啟保留（v4.9.0 新增）：
/ponytail default full注意：v4.9.0 之後，單獨 /ponytail 只會「回報」當前 level，不再重設回 default。新手一律留在 full 就好，前 5 次實戰不要切 ultra。
3. 6 個核心指令，先認識 3 個
Ponytail 共 6 個核心指令，新手只需要先記前 3 個：
| 指令 | 用途 | 何時用 |
|---|---|---|
/ponytail |
回報當前等級、切換等級 | 每次開工確認狀態 |
/ponytail-review |
審查「變更或單一檔案」的過度設計 | 改完一段程式、想自檢 |
/ponytail-help |
顯示所有指令與等級的速查卡 | 忘記指令時 |
/ponytail-audit |
掃描整個 codebase，產出負債表 | 接手新專案、大掃除 |
/ponytail-debt |
把刻意延後的簡化記成負債表 | 沒清完想留下追蹤 |
/ponytail-gain |
顯示累積的壓縮效益計分板 | 想看長期影響 |
後 3 個會在〈實戰範例 010〉與後續課程詳談。
4. 第一次實戰：對一個小檔案跑 /ponytail-review
挑一個你最不滿意的 utils 檔案，通常是「看起來很有架構、但其實只有一個地方在用」的 Helper。例如 src/utils/dateFormatter.ts。
/ponytail-review src/utils/dateFormatter.tsPonytail 會輸出一份分類報告，每一項附帶：
- 位置：檔名與行號
- 可刪的內容：哪一段被判定為過度設計
- 可用什麼取代：通常是標準庫或一行表達式
- 安全防護是否受影響：這行新手一定要看
完整的對話與重構過程見〈實戰範例 009〉，它把一個 70 行的日期 Helper 砍成 10 行單一函式，是新手建立直覺最好的起點。
5. 該避開的 3 個新手誤區
誤區 1：把極簡當成「砍掉所有 if 與 try-catch」
Ponytail 預設不會動安全防護。null / undefined 檢查、try-catch、無障礙屬性都屬於「必要功能」，不是過度設計。報告中的 Safety preserved 那行就是在重申這點。若你看到 Ponytail 似乎建議砍掉防護，多半是你切到 ultra，切回 full 即可。
誤區 2：把等級設成 ultra 想一次砍到底
ultra 會連可能合理的安全防護都拿出來檢視，新手容易過頭誤刪。前 5 次實戰都留在 full，等你看熟報告分類再考慮升級。
誤區 3：對「整個 codebase」跑 /ponytail-review
/ponytail-review 針對「變更或單一檔案」，要掃整個專案請改用 /ponytail-audit。把這兩個搞混，會拿到空報告或浪費時間。
6. 跟 caveman 互補，不要互打
Ponytail 與 caveman 這類外掛是互補關係：caveman 壓縮「輸出文字」，Ponytail 壓縮「程式碼本身」。兩者可以同時掛，新手建議先單獨用 Ponytail 一週，熟悉報告分類後再搭配其他外掛，避免一次收到太多訊號。
7. 學完這課，你應該能
- 說出 4 個強度等級的差異，並解釋為何新手留在
full。 - 對任一檔案執行
/ponytail-review，並讀懂報告裡的位置、可刪內容、替代方案、安全防護四個欄位。 - 解釋
/ponytail與/ponytail default <mode>的差別（前者回報、後者設預設）。 - 判斷什麼時候該用
/ponytail-audit而不是/ponytail-review。
下一課我們會深入 7 階階梯的每一階，並用實戰範例 001 至 010 示範不同語言、不同場景的簡化手法。