ポニーテール：治療する AI Agent の「過剰設計病」、実測でコード 54% 減

リポジトリ：https://github.com/DietrichGebert/ponytail

難易度は低め、10 分で使い方を掴み、1 時間で最初のベンチマークが回せる。AI が「コード書くの止まらない」癖を、ちょっと治してみよう。

まえがき

こんな経験はありませんか――Claude Code に日付選択器を書かせたら、きちんと flatpickr を入れてきて、ラッパーコンポーネントを書き、CSS を足し、ついにはタイムゾーンの扱いまであなたと議論し始め、最後は 287 行をあなたに手渡してくる。

あなたが言いたいのは「日付を選べる入力欄がほしい」なのに、渡されるのは「日付選択のフレームワーク」だ。

これが AI Agent の「過剰設計病」です。モデルは「それっぽくプロっぽい」ように訓練されているため、自動的に抽象化レイヤーを足し、設定項目を増やし、エラーハンドリングやテストカバレッジまで盛り込みがち。でも本当は、<input type="date"> ひとつで済むかもしれない。

Ponytail は、この病を治すためのものです。Dietrich Gebert がオープンソースとして公開していて、核となる考え方は一言だけ：「最高のコードは、書かれなかったコードである」。

Ponytail はモデルでも IDE プラグインでもなく、「怠け者の上級エンジニア」流のルールセットです。AI に“6 段ステップ”を取り付けます：

1. そもそも書く必要がある？          → ない：スキップ（YAGNI）
2. 標準ライブラリでできる？            → 使う
3. プラットフォームのネイティブ機能でできる？ → 使う
4. すでに入っている依存でできる？     → 使う
5. 1 行コードでできる？               → 1 行で書く
6. それでも無理：要件を満たす最小のコード

tiangolo の full-stack-fastapi-template の実リポジトリ上で、12 個の feature ticket、n=4、Haiku 4.5 を使った対照実験では、Ponytail がこの成績表を取りました：

Ponytail は あらゆる指標が下がる 唯一の案であり、かつ コードを削っても安全性を落とさない 唯一の案です。カラーピッカーは 287 行から 23 行へ、日付選択器は 404 行から 23 行へ――それは、ブラウザ標準の <input type="color"> と <input type="date"> をそのまま使ったから。

このルールは 14 種類の AI プログラミングツールに対応しています：Claude Code、Codex、Cursor、Windsurf、Cline、Copilot CLI、Aider、Kiro、Zed、CodeWhale、OpenCode、Pi、Gemini CLI、OpenClaw。今日は、このルールを Claude Code に入れて、30 秒であなたの Agent の「過剰設計病」を治します。

対象読者

• 日常的に AI Agent でコードを書く 1〜5 年目の開発者
• 「AI のコードが長すぎる」「使わない依存を大量に入れてしまう」という体感がある人
• チームでコーディング方針を揃えたいが、ガチガチの ESLint ルールに縛られたくない人
• AI プログラミングのコスト、token の請求が痛い小さめのオーナー／Tech Lead

コア依存と環境

• Node.js 18+（必須。Ponytail の lifecycle hook は Node で動きます。nvm 利用者は、非対話シェル用の PATH に入れることに注意）
• 対応する AI Agent（デモは Claude Code）
• LLM API Key（デモは Defapi の Claude Haiku 4.5、半額）
• 任意：Python 3.10+（ベンチマーク実行時に pandas を使います）
• 任意：Git（リポジトリをクローン）

完全なプロジェクト構造

ponytail/
├── AGENTS.md                  # コアルール（すべての agent が読む「怠け者哲学」）
├── README.md / README.es.md   # 英中西の三か国語 README
├── package.json               # pi-agent パッケージの定義
├── commands/                  # 6 つの slash command
│   ├── ponytail.toml          # /ponytail [lite|full|ultra|off]
│   ├── ponytail-review.toml   # /ponytail-review（今の diff を削る）
│   ├── ponytail-audit.toml    # /ponytail-audit（リポジトリ全体をスキャン）
│   ├── ponytail-debt.toml     # /ponytail-debt（取り立て Ponytail：コメント）
│   ├── ponytail-gain.toml     # /ponytail-gain（ベンチ成績表を見る）
│   └── ponytail-help.toml     # /ponytail-help
├── skills/                    # 6 つの skill イメージ
│   ├── ponytail/              # メインルール
│   ├── ponytail-review/ ...   # 残り 5 つ
├── hooks/                     # Claude / Codex lifecycle hook
│   ├── ponytail-config.js     # モード解析（env + config.json）
│   └── ponytail-instructions.js
├── ponytail-mcp/              # MCP サーバー対応（MCP-only のホスト用）
│   ├── index.js
│   ├── instructions.js
│   └── test/
├── examples/                  # 12 個の実例「過剰設計 vs 1 行」比較
│   ├── date-picker.md / color-picker.md（web 組み込み）
│   ├── deep-clone.md（structuredClone）
│   ├── debounce.md
│   ├── email-validation.md（75 行 → 3 行）
│   └── ... 全 12 個
├── benchmarks/                # promptfoo + agentic ベンチ
│   ├── promptfooconfig.yaml   # 単発ラウンドのベンチ
│   ├── benchmark-local.py     # agentic 実リポジトリのベンチ
│   ├── agentic/               # 12 個の ticket スクリプト
│   └── results/2026-06-18-agentic.md  # 完全データ
├── docs/
│   ├── agent-portability.md   # どの agent にどのファイルを入れるか
│   └── platform-native.md
├── .openclaw/                 # OpenClaw 用 skill（自動生成）
├── .cursor/ .windsurf/        # Cursor / Windsurf のルールファイル
├── .clinerules/               # Cline のルール
├── .kiro/steering/            # Kiro のルール
└── tests/                     # ルール整合性のテスト

---

手取り足取りチュートリアル

ステップ 1：Ponytail を Claude Code に入れる

Claude Code 内では Ponytail はプラグインのマーケットプレイス。30 秒で完了。

# Ponytail リポジトリをあなたの plugin marketplace の一覧に追加
/plugin marketplace add DietrichGebert/ponytail

# メイン skill（1 セッションにつき 1 回）をインストール
/plugin install ponytail@ponytail

インストール後、新しいセッションを開くと、startup で現在のモードが表示されます（デフォルトは full）。例えばこんな出力が見えます：

Ponytail v0.1.0  [full]  Lazy senior dev mode active
1. Need to build?  2. Stdlib?  3. Platform?  4. Installed dep?
5. One line?       6. Minimum that works.

強度を変えたいなら、こう入力：

/ponytail lite     # ライト（1〜2 段目を保護）
/ponytail full     # デフォルト
/ponytail ultra    # 強め（抽象化レイヤーも容赦なく削る）
/ponytail off      # オフ
/ponytail          # 引数なし＝現在の段を表示

永続化も可能：

# 永久にデフォルトを ultra に
export PONYTAIL_DEFAULT_MODE=ultra

または config を用意：

// ~/.config/ponytail/config.json
// Windows: %APPDATA%\ponytail\config.json
{ "defaultMode": "ultra" }

ステップ 2：反例で効果を比較する

直接見ましょう。まったく同じプロンプトを 2 つ用意します。

Prompt A（Ponytail をオフ）：まず /ponytail off を打ってから、尋ねる。

Add a color picker to the settings page

するとだいたい 287 行の回答が返ります。react-color を入れるか、あるいは自作で 5 ファイルのコンポーネントを作り、prop の検証を足し、onChange のスロットリングを入れ、アクセシビリティ用の label を足し、CSS 変数も追加する。

Prompt B（Ponytail をオン）：先に /ponytail full を入れて、同じことをもう一度聞く。

返ってくるのは：

// ponytail: browser has one
<input type="color" />

1 行。以上。

Ponytail の AGENTS.md には、このコアルールがそのまま書いてあります（原文）：

Before writing any code, stop at the first rung that holds:
1. Does this need to be built at all? (YAGNI)
2. Does the standard library already do this? Use it.
3. Does a native platform feature cover it? Use it.
4. Does an already-installed dependency solve it? Use it.
5. Can this be one line? Make it one line.
6. Only then: write the minimum code that works.

最後の一行：「Only then」に注目。これは「書くな」ではなく、まず最初の 5 ステップを全部踏め、という意味です。

ステップ 3：Defapi で通して、token 代を半分に

Ponytail はコード量を減らしますが、AI Agent 自体を回すには Claude / GPT に token を焼く必要があります。Defapi は公式の半額 Claude / GPT / Gemini を提供しており、インターフェースは完全互換です。

Defapi に切り替えてベンチマークを回します：

ステップ 3.1：Defapi Key を取得

defapi.org に登録して dk-xxx で始まる key を入手し、Ponytail の .env に書き込みます：

# ponytail リポジトリのルートで
cat > .env <<'EOF'
ANTHROPIC_API_KEY=dk-あなたのdefapi-key
ANTHROPIC_BASE_URL=https://api.defapi.org
EOF

ステップ 3.2：curl でそのまま動くか確認

curl -s https://api.defapi.org/api/v1/messages \
  -H "Authorization: Bearer dk-あなたのdefapi-key" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "絵文字1つで ponytail という単語を説明して"}
    ]
  }'

返り値：

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": [{"type": "text", "text": "🦄（そもそも出てくるべきじゃない）"}],
  "usage": {"input_tokens": 22, "output_tokens": 12}
}

ステップ 3.3：promptfoo を Defapi で動かす

Ponytail には promptfoo のベンチが内蔵されています。benchmarks/promptfooconfig.yaml を編集：

providers:
  - id: anthropic:messages:anthropic/claude-haiku-4.5
    config:
      baseURL: https://api.defapi.org
      apiKey: ${ANTHROPIC_API_KEY}

実行：

npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

節約できるお金（Ponytail ベンチの 12 ticket × n=4＝48 回実行の規模感で推定）：

Ponytail は 20% コストを削り、Defapi はさらに 50% 削る。2 つを合わせると実請求が 4 分の 1 になります。

ステップ 4：/ponytail-review で今の diff を削る

Ponytail が書き込み時にガードしてくれるだけでは不十分です。すでに「過剰設計」の塊として積み上がったコードがあるから。ここで review コマンドを使います：

# 変更があるリポジトリ内で
/ponytail-review

これは 現在の git diff だけを審査し、出力形式は固定です：

L12: delete unused `cache` parameter; no caller passes it
L34: stdlib Array.prototype.sort is stable since ES2019; drop `lodash.orderby`
L88: native `URLSearchParams` covers this; remove custom `parseQuery`
L102: yagni `BaseRepository` has one implementation; inline it
L150: shrink loop into `arr.filter(x => x.active).map(x => x.id)`
---
Net removable: 47 lines, 1 dependency

タグ体系：

• delete — 死んだコード／投機的な機能
• stdlib — 標準ライブラリの再発明
• native — 依存に任せるまでもない／プラットフォーム標準で済む
• yagni — 実装が 1 つしかない抽象化
• shrink — 同じロジックで行数が少ない

最後の行には「純粋に削除できる行数」が出ます。これが tech debt の定量指標です。

出力が Lean already. Ship. なら、コードが十分スリムなので安心して merge できます。

ステップ 5：/ponytail-audit でリポジトリ全体をスキャン

review は diff、audit は木全体。

/ponytail-audit

出力形式は似ていますが、「一番削れる」順に並ぶ点が違います：

delete src/utils/cache.ts (412 lines) — only used in 1 place; inline
stdlib src/utils/deep-clone.ts — use structuredClone
native src/components/DatePicker/ (287 lines) — <input type="date">
yagni src/repositories/BaseRepository.ts (180 lines) — 1 impl, inline
shrink src/api/users.ts:42-78 — same logic, 60 → 18 lines
---
Net removable: 1,247 lines, 4 dependencies

実務のおすすめ：先に review、次に audit。review は diff を直し、マージした後、audit が次のクリーニング優先度を出してくれます。

ステップ 6：他の Agent でも有効化する

Ponytail のコア優位性は「一度ルールを入れれば、どこでも効く」こと。主要な AI コーディングツールごとに適合ファイルも用意されています：

Codex（CLI モード）

codex plugin marketplace add DietrichGebert/ponytail
codex
# /plugins → Ponytail を選んでインストール
# /hooks → 2 つの lifecycle hook を信頼して新スレッドを開始

Cursor

まず .cursor/rules/ponytail.mdc をプロジェクトにコピー：

cp .cursor/rules/ponytail.mdc ~/your-project/.cursor/rules/

またはグローバルに：

cp .cursor/rules/ponytail.mdc ~/.cursor/rules/

Windsurf

cp .windsurf/rules/ponytail.md ~/.codeium/windsurf/memories/

GitHub Copilot CLI

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

OpenClaw（すでに使っている場合）

# いちばんスマートな 1 行
clawhub install ponytail

または手動コピー：

cp -r .openclaw/skills/ponytail ~/.openclaw/skills/

Gemini CLI

gemini extensions install https://github.com/DietrichGebert/ponytail

Pi / Aider / Kiro / Zed / CodeWhale

これらの agent は直接 AGENTS.md を読みます：

# プロジェクト単位
cp AGENTS.md ~/your-project/AGENTS.md

# グローバル（pi / Aider / CodeWhale はこれで認識）
cp AGENTS.md ~/.pi/AGENTS.md

完全対応表（プロジェクト docs/agent-portability.md から抜粋）：

ステップ 7：自分の benchmark を回してみる

Ponytail の実データは、思いつきではなく benchmarks/benchmark-local.py を回して得たものです。あなたも自分の実タスクから 5 つ選んで再現してみることができます：

ステップ 7.1：prompts を用意

benchmarks/prompts.json を編集（または既成の 5 つを使う）：

[
  { "id": "date-picker", "task": "設定ページに日付ピッカーを追加する" },
  { "id": "color-picker", "task": "設定ページにカラーピッカーを追加する" },
  { "id": "email-validate", "task": "メールアドレスを検証する Python 関数を書く" },
  { "id": "deep-clone", "task": "このオブジェクトをディープクローン：{sample}" },
  { "id": "debounce", "task": "JavaScript でデバウンス関数を書く" }
]

ステップ 7.2：3 つの arm を対照実験

# baseline：何も足さない
npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

# ponytail：skill を入れた plugin arm
PONYTAIL_DEFAULT_MODE=full npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

ステップ 7.3：結果を見る

benchmarks/output.json を確認します。各 prompt が各 arm の下でどうなったか含まれています：

• loc — コード行数
• tokens — 合計 token
• cost — USD
• time — エンドツーエンド時間
• passed_safety — 安全テスト（入力検証、エラーハンドリング、a11y）を通過したか

通常、ponytail arm は baseline に比べて LOC が 50〜80% 減ります。

ステップ 8：pony tail-mcp（上級）を動かす

AI host が MCP しか使えない場合（例えば一部のデスクトップアプリ）、Ponytail には MCP サーバーの適応もあります：

cd ponytail-mcp
npm install
node index.js    # stdio MCP サーバーを起動

ホスト側の MCP 設定に追加：

{
  "mcpServers": {
    "ponytail": {
      "command": "node",
      "args": ["ponytail-mcp/index.js"]
    }
  }
}

公開されるもの：

• Prompt ponytail：ルールテキストを返す（任意で mode パラメータ：lite / full / ultra）
• Tool ponytail_instructions：同上だが structuredContent を付けて返し、コード実行系の host 向け

---

よくある質問の切り分け

Q1：入れたのに反応がない、startup の文字が出ない？

99% は Node が非対話シェルの PATH に入っていないことが原因です。確認：

# 新しいシェルで実行（非対話をシミュレート）
bash -lc 'node -v'      # bash
zsh -lc 'node -v'       # zsh

command not found が返る場合は、nvm を ~/.bashrc / ~/.zshrc に source するか、いっそ system Node を入れてください：

# macOS
brew install node@20

# Windows
winget install OpenJS.NodeJS.LTS

Q2：「あの 120 行の cache クラスが欲しい」— 強い要求がある場合は？

次の 2 つの解決策：

# 一時的にオフ
/ponytail off

# もしくはローカルに許可：prompt 内で直接言う
"Build a 120-line cache class, ignore ponytail for this task"

Ponytail はルールセットであって、足枷ではありません。モデルが明示的な override を受け取れば従います。

Q3：Ponytail は ESLint / Prettier と衝突しますか？

衝突しません、役割が違う：

• Ponytail：『書くべきか』を管理――抽象が必要か、依存が入っているか、ラッパーを作る必要があるか
• ESLint：『書き方が正しいか』を管理――命名、スタイル、未使用変数
• Prettier：『見た目の整形』を管理――インデント、セミコロン、改行

3 つを同時に有効にすると最も効果が出ます。Ponytail は最上流でコードの“長さ”や構造を決め、ESLint / Prettier は下流で細部を整えます。

Q4：チームでルールを統一するには？

AGENTS.md はリポジトリ級のファイルで、git にコミットすればOK：

# あなたのチームリポジトリのルートで
curl -o AGENTS.md https://raw.githubusercontent.com/DietrichGebert/ponytail/main/AGENTS.md
git add AGENTS.md
git commit -m "chore: adopt ponytail team-wide coding rules"

AGENTS.md を読む agent（CodeWhale、Aider、Zed、Pi、Kiro、Codex extension）は自動的に従います。

Q5：Ponytail は安全テストを劣化させますか？

しません。ここが Ponytail のベンチで最重要の指標です。比較表では baseline / caveman / Ponytail は 100% 安全に通過で、落ちたのは裸の「YAGNI + 1 行」プロンプトだけで 95% です。

Ponytail の AGENTS.md には、次の段落が特に用意されています：

Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs.

翻訳：どこを怠けるかは場所次第。ビジネスロジックや UI の包装は省けるなら省いていい。でも、入力検証、エラーの保険、安全、a11y は省いてはいけません。

Q6：CI でどう回しますか？

/ponytail-review のロジックを独立したスクリプトにして（Ponytail リポジトリの benchmarks/correctness.test.js に参考実装があります）、その上で：

# .github/workflows/ponytail.yml
name: ponytail
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node scripts/ponytail-review.js origin/main
        env:
          ANTHROPIC_API_KEY: ${{ secrets.DEFAPI_KEY }}
          ANTHROPIC_BASE_URL: https://api.defapi.org

PR で失敗＝いまの diff が「Ponytail 的にまだ痩せられる」と判断されたということです。

Q7：MCP モードと always-on モード、どちらを選ぶべき？

ホスト次第で：

---

追加で読む / 発展の方向性

Ponytail の哲学の根っこ

• Rich Hickey の「Simple Made Easy」講演（Clojure の父が語る「易しさ」と「簡単」の違い）
• Sandi Metz の「The Magic Tricks of Testing」（最小限のテストカバレッジ原則）
• Ted Neward の「Thirty Years of 'WTF'」（企業コード肥大の風刺）
• 6 段ステップ梯子の別表現：Coad の「Just Enough Architecture」

自分で ponytail 風のコメントを書く

ponytail: コメントは「将来このコードを読む開発者」に向けたメモです。約束のフォーマット：

// ponytail: <理由>，<既知の制約 / アップグレードの道>

例：

# ponytail: stdlib の re モジュールで十分。email-validator は入れる必要なし
# 既知の制約：RFC 5322 の全エッジケースは検証しない；[email protected] の edge case に対応したいなら email-validator に差し替える
import re
def is_valid_email(email: str) -> bool:
    return bool(re.match(r'^[^@]+@[^@]+\.[^@]+$', email))

/ponytail-debt コマンドは、すべての ponytail: コメントを走査して tech debt の台帳（ledger）を生成します。「later」は「never」になりません。

チームのコードレビュー工程への統合

/ponytail-review を lint のように回して、PR テンプレに 1 行追加：

## Ponytail review
- [ ] Ran `/ponytail-review` on this diff
- [ ] Net removable lines: ___
- [ ] If > 0, justification: ___

完全な benchmark データ

benchmarks/results/2026-06-18-agentic.md は、12 ticket × 3 arm × 4 ラウンドの完全な方法論＋制約説明です。読む価値があります。特に「fair agentic baseline」の部分――以前の 80〜94% の「単発の神話」は、会話ベースラインを人為的に膨らませたものだったのに対し、54% が“誠実な数字”です。

Ponytail の境界について

Ponytail がコードを削れる前提は「コードが正しいこと」です。Ponytail は検証しません：

• ビジネスロジックが正しいか（ここはあなたがテストを書く必要があります）
• パフォーマンスが十分か（O(n²) などは ponytail のコメント内で指摘はされますが、自動修正はしません）
• 境界ケースのカバー率（lazy なコメントは列挙しますが、テストを追加してはくれません）

Ponytail は スタート地点であって 終点ではありません。Ponytail を入れると AI が書くコードは減りますが、あなたがレビューする負担も軽くなります――この 2 つは同じコインの表裏です。

最後の一文でまとめると：Ponytail は「少ないコード」を目指すのではなく、「そもそも書く必要があるか」を先に問うものです。

次のおすすめ： Defapi で半額の Claude key を取り、Ponytail と一緒に自分の実タスクを回してみてください。請求から削れた 60% が、Ponytail が token を減らした分と、Defapi が単価を下げた分のちょうど半々であることが分かるはずです。