Хвостик: лечим у AI Agent «болезнь чрезмерного проектирования», в реальности кода на 54% меньше

Репозиторий: https://github.com/DietrichGebert/ponytail

Низкий порог: за 10 минут разобраться, и уже через 1 час прогнать первый benchmark — и «вылечить» привычку вашего ИИ-кодера «не может остановиться».

Вступление

Был ли у вас такой опыт — чтобы Claude Code написал селектор дат, он с серьезным видом подцепляет flatpickr, добавляет wrapper-компонент, подключает CSS, а потом начинает обсуждать работу с таймзонами… и в итоге оставляет вам 287 строк.

Вы хотели сказать: «Мне нужен input для выбора даты», а он отдал вам «фреймворк для выбора дат».

Это и есть «болезнь чрезмерного проектирования» у AI Agent: модель натренирована выглядеть «максимально профессионально», поэтому автоматически накидывает абстракции, конфиги, обработку ошибок и покрытие тестами — хотя вам, возможно, достаточно обычного <input type="date">.

Ponytail как раз и создан, чтобы вылечить эту проблему. Его автор Dietrich Gebert выложил проект в открытый доступ, а главная идея — в одной фразе: «Лучший код — тот, который никогда не был написан».

Ponytail — это не модель и не плагин для IDE. Это набор правил в стиле «ленивого, но опытного инженера». Он надевает на AI лестницу из 6 ступеней:

1. Это вообще нужно писать?            → Не нужно: пропускаем (YAGNI)
2. Справится ли стандартная библиотека? → Использовать
3. Справится ли нативная возможность платформы? → Использовать
4. Справится ли уже установленная зависимость? → Использовать
5. Можно ли сделать одной строкой?     → Писать одной строкой
6. Если совсем никак: написать минимальный код, который удовлетворяет требованиям

В реальном репозитории tiangolo full-stack-fastapi-template, в сравнительном эксперименте с 12 ticket’ами, n=4 и Haiku 4.5, Ponytail получил вот эту табличку результатов:

Ponytail — единственный вариант, где падают все показатели, и единственный — где обрезание кода не ухудшает безопасность. Селектор цветов с 287 строк сокращается до 23, селектор дат — с 404 до 23 — потому что он напрямую использует встроенные в браузер <input type="color"> и <input type="date">.

Ponytail совместим с 14 инструментами AI для программирования: Claude Code, Codex, Cursor, Windsurf, Cline, Copilot CLI, Aider, Kiro, Zed, CodeWhale, OpenCode, Pi, Gemini CLI, OpenClaw. Сегодня мы встраиваем эти правила в Claude Code — и за 30 секунд вылечим ваш AI Agent от «болезни чрезмерного проектирования».

Целевая аудитория

• Разработчики 1–5 лет, которые регулярно используют AI Agent для написания кода
• Те, кто чувствует: «AI пишет слишком длинно и тащит кучу зависимостей, которые не нужны»
• Хотят унифицировать стиль кодинга в команде, но не хотят закреплять его железными ESLint-правилами
• Руководители / Tech Lead, которым важна стоимость AI-программирования и неприятно смотреть на счета токенов

Ключевые зависимости и окружение

• Node.js 18+ (обязательно: lifecycle hook Ponytail запускается на Node; пользователям nvm — следите, чтобы Node был в PATH неинтерактивной shell’и)
• Поддерживаемый AI Agent (для демонстрации — Claude Code)
• LLM API Key (для демонстрации — Claude Haiku 4.5 от Defapi, полцены)
• Опционально: Python 3.10+ (нужен при запуске benchmark’а: используется pandas)
• Опционально: Git (клонировать репозиторий)

Полная структура проекта

ponytail/
├── AGENTS.md                  # ключевые правила (этот «ленивый философский манифест» читают все agent’ы)
├── README.md / README.es.md   # README на 3 языках: Китайский / Английский / Испанский
├── package.json               # pi-agent пакет
├── commands/                  # 6 slash-команд
│   ├── 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（посмотреть benchmark-табличку）
│   └── ponytail-help.toml     # /ponytail-help
├── skills/                    # 6 skill-«образов»
│   ├── ponytail/              # основное правило
│   ├── ponytail-review/ ...  # остальные 5
├── hooks/                     # Claude / Codex lifecycle hooks
│   ├── ponytail-config.js     # разбор режима (env + config.json)
│   └── ponytail-instructions.js
├── ponytail-mcp/              # адаптация под MCP (для MCP-only хостов)
│   ├── index.js
│   ├── instructions.js
│   └── test/
├── examples/                  # 12 реальных примеров «чрезмерное проектирование vs одна строка»
│   ├── date-picker.md / color-picker.md（встроено в web）
│   ├── deep-clone.md（structuredClone）
│   ├── debounce.md
│   ├── email-validation.md（75 строк → 3 строки）
│   └── ... всего 12
├── benchmarks/                # promptfoo + agentic benchmark
│   ├── promptfooconfig.yaml   # benchmark в один раунд
│   ├── benchmark-local.py     # agentic benchmark по реальному репозиторию
│   ├── 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 — это marketplace-плагин, который ставится за 30 секунд.

# Добавить репозиторий Ponytail в список marketplace плагинов
/plugin marketplace add DietrichGebert/ponytail

# Установить основной skill (устанавливается на сессию)
/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: Прогоните контрпример

Давайте посмотрим эффект напрямую. Подготовьте два полностью одинаковых prompt’а:

Prompt A (Ponytail выключен): сначала /ponytail off, затем спросите

Add a color picker to the settings page

Вам придет ответ примерно на 287 строк: добавит react-color или сам соберет 5-файловый компонент, добавит валидацию prop, добавит debounce/троттлинг на onChange, добавит accessible label и CSS-переменные.

Prompt B (Ponytail включен): сначала /ponytail full, и задайте тот же вопрос еще раз.

Вы получите:

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

В одну строку. Готово.

В AGENTS.md Ponytail прямо написана эта ключевая часть правил (оригинал):

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 и экономим половину денег на токенах

Ponytail режет объем кода, но чтобы запустить сам AI Agent, нужно дать Claude/GPT токены. Defapi предлагает официальнуюполуценовую линейку Claude / GPT / Gemini — интерфейс полностью совместим.

Переключаемся на Defapi и запускаем benchmark:

Шаг 3.1: Получить Defapi Key

Зайдите на defapi.org, зарегистрируйтесь, возьмите key с префиксом dk-xxx и запишите в .env Ponytail’а:

# В корне репозитория 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": "Опишите слово ponytail одним эмодзи"}
    ]
  }'

Ответ:

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": [{"type": "text", "text": "🦄 (его вообще тут не должно быть)"}],
  "usage": {"input_tokens": 22, "output_tokens": 12}
}

Шаг 3.3: заставить promptfoo работать через Defapi

У Ponytail есть встроенные benchmark’и 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

Сэкономленные деньги (оценка по объему: 12 ticket’ов Ponytail benchmark × n=4 = 48 прогонов):

Ponytail режет 20% стоимости, Defapi режет еще 50%, и вместе дают реальную скидку в 4 раза.

Шаг 4: Прогоните /ponytail-review — режем текущий diff

Одного того, что Ponytail контролирует записи при генерации, недостаточно — у вас уже есть «склад» кода, который появился из-за чрезмерного проектирования. На этом этапе используйте команду review:

# В репозитории, где есть изменения
/ponytail-review

Она проверяет только текущий git diff и выводит результат в фиксированном формате:

L12: удалить unused `cache` parameter; его не передает ни один caller
L34: stdlib Array.prototype.sort стабилен, начиная с ES2019; уберите `lodash.orderby`
L88: native `URLSearchParams` это покрывает; уберите custom `parseQuery`
L102: yagni `BaseRepository` имеет одну реализацию; встроить ее
L150: сжать цикл в `arr.filter(x => x.active).map(x => x.id)`
---
Net removable: 47 строк, 1 зависимость

Теги:

• delete — мертвый код / спекулятивные фичи
• stdlib — заново изобретаем стандартную библиотеку
• native — работу уже делает зависимость / или можно сделать нативной возможностью платформы
• yagni — абстракция с одной-единственной реализацией
• shrink — та же логика, но меньше строк

Последняя строка дает вам «количество строк, которые реально можно удалить» — это и есть метрика, которая квантифицирует ваш tech debt.

Если вывод выглядит как Lean already. Ship., значит код уже достаточно «тонкий» — можно спокойно мержить.

Шаг 5: Прогоните /ponytail-audit — скан всего репозитория

review смотрит diff, audit — все дерево.

/ponytail-audit

Формат похож, но результат отсортирован по тому, где можно снести больше всего:

delete src/utils/cache.ts (412 строк) — используется только в 1 месте; встроить
stdlib src/utils/deep-clone.ts — используйте structuredClone
native src/components/DatePicker/ (287 строк) — <input type="date">
yagni src/repositories/BaseRepository.ts (180 строк) — 1 реализация; встроить
shrink src/api/users.ts:42-78 — та же логика, 60 → 18 строк
---
Net removable: 1,247 строк, 4 зависимости

Практический совет: сначала review, потом audit. review меняет diff, мержите — audit поможет расставить приоритеты для следующей волны очистки.

Шаг 6: Включить в других Agent’ах

Главное преимущество Ponytail — «один набор правил, который работает везде». Для каждого популярного AI-инструмента программирования он подготовил адаптационный файл:

Codex (CLI режим)

codex plugin marketplace add DietrichGebert/ponytail
codex
# открыть /plugins → выбрать Ponytail → установить
# открыть /hooks → доверить два 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 (если вы уже им пользуетесь)

# самая элегантная команда
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-функцию, которая валидирует адреса email" },
  { "id": "deep-clone", "task": "Глубоко клонируйте этот объект: {sample}" },
  { "id": "debounce", "task": "Напишите функцию debounce на 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 — общее число токенов
• cost — в долларах
• time — сквозное время (end-to-end)
• passed_safety — прошел ли безопасностные тесты (валидация входных данных, обработка ошибок, a11y)

Обычно arm’ы ponytail режут LOC по сравнению с baseline на 50–80%.

Шаг 8: Запустить ponytail-mcp (advanced)

Если ваш AI host умеет только MCP (например, некоторые desktop-приложения), у Ponytail есть MCP server адаптация:

cd ponytail-mcp
npm install
node index.js    # запуск stdio MCP server

Добавьте в конфигурацию MCP хоста:

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

Экспонируется:

• Prompt ponytail: возвращает текст правил, опционально mode параметр (lite / full / ultra)
• Tool ponytail_instructions: то же самое, но с structuredContent, для хостов в стиле code-execution

---

Частые проблемы и их диагностика

Q1: Поставил — и нет реакции, startup-текст не показывается?

В 99% случаев проблема в том, что Node не в PATH неинтерактивной shell’и. Проверка:

# это нужно прогнать в новом shell (симуляция non-interactive)
bash -lc 'node -v'      # bash
zsh -lc 'node -v'       # zsh

Если вернуло command not found, либо добавьте source nvm в ~/.bashrc / ~/.zshrc, либо установите system Node:

# macOS
brew install node@20

# Windows
winget install OpenJS.NodeJS.LTS

Q2: «Мне нужен тот класс cache на 120 строк» — что делать, если это жесткая необходимость?

Два решения:

# временно выключить
/ponytail off

# либо локально разрешить: прямо в prompt’е
"Build a 120-line cache class, ignore ponytail for this task"

Ponytail — это набор правил, а не наручники. Явный override от модели он выполнит.

Q3: Ponytail конфликтует с ESLint / Prettier?

Нет, потому что они делают разное:

• Ponytail: отвечает на вопрос «нужно ли это вообще писать» — есть ли абстракция, есть ли зависимость, есть ли этот wrapper
• ESLint: отвечает на «правильно ли написано» — нейминг, стиль, неиспользуемые переменные
• Prettier: отвечает на «красиво ли форматировано» — отступы, точки с запятой, переносы строк

Лучший эффект — включить все три. Ponytail решает, как по сути выглядит код (сверху по пайплайну), а ESLint / Prettier следят за деталями (ниже по пайплайну).

Q4: Как унифицировать правила в команде?

AGENTS.md — файл на уровне репозитория. Достаточно закоммитить его в git:

# в корне репозитория вашей команды
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"

Все agent’ы, которые читают AGENTS.md (CodeWhale, Aider, Zed, Pi, Kiro, Codex extension), будут автоматически соблюдать правила.

Q5: Ponytail ухудшает безопасностные проверки?

Нет, это самый ключевой показатель для Ponytail в benchmark’ах. В сравнительной таблице baseline / caveman / Ponytail — все дают 100% безопасного прохождения, и только «голый YAGNI + одна строка» prompt падает до 95%.

В AGENTS.md Ponytail есть отдельный фрагмент:

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 режим vs always-on режим — что выбрать?

Смотрите на тип вашего host:

---

Дальнейшее чтение / направление для развития

Философские корни 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; если нужно поддержать edge case [email protected], замените на 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».

Интеграция в процесс code review команды

Рассматривайте /ponytail-review как lint: добавьте в шаблон PR пункт:

## 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% «односессионной сказки» раздували за счет conversational baseline, а 54% — это честная цифра.

Про границы Ponytail

У Ponytail резать код можно только при условии, что «код правильный». Он не проверяет:

• верность бизнес-логики (это вы должны покрыть своими тестами)
• достаточно ли производительности (в комментариях ponytail пометки про O(n²) ставит, но автоматически не чинит)
• какие edge-case’ы покрыты (ленивые комментарии перечислят, но тесты вместо вас не добавит)

Это точка старта, а не финиш. После установки Ponytail кода, который пишет AI, становится меньше — но и ваша нагрузка при review снижается. Это две стороны одной монеты.

В заключение одной фразой: Ponytail — это не «меньше кода», это «сначала спроси, нужно ли вообще писать».

Следующий шаг: возьмите полцентовый ключ через Defapi и прогоните Ponytail на своих реальных задачах — вы увидите, что те 60% из счета режутся, наполовину потому что Ponytail режет токены, и наполовину потому что Defapi режет цену за запрос.