DietrichGebert/ponytail: Ленивый подход к AI-агентам

DietrichGebert/ponytail: Ленивый подход к AI-агентам

Плагин ponytail учит AI-агентов думать как опытный разработчик, избегая лишнего кода. Узнайте, как он работает и почему это важно для эффективной автоматизации.

Установка и настройка

Установка и настройка

Ponytail — плагин для Claude Code, который заставляет агента писать меньше кода и думать больше, как опытный разработчик. Он не заменяет Claude Code, а дополняет его: перехватывает запросы, анализирует контекст и предлагает минимальные изменения вместо перезаписи целых файлов.

Для работы плагину нужен запущенный Claude Code и доступ к API Anthropic. Самый надёжный способ развернуть его — через Docker, чтобы не засорять основную систему зависимостями и иметь предсказуемую среду.

Установка через Docker

Я предпочитаю поднимать такие инструменты через Docker Compose — так проще управлять переменными окружения и пересобирать контейнер при обновлении.

Создайте отдельную директорию для плагина:

bashКопировать
mkdir -p ~/ponytail
cd ~/ponytail

Файл docker-compose.yml:

yamlКопировать
version: "3.8"

services:
  ponytail:
    image: dietrichgebert/ponytail:latest
    container_name: ponytail
    restart: unless-stopped
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_CODE_URL=http://claude-code:8080
      - LOG_LEVEL=info
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    networks:
      - ponytail-net

networks:
  ponytail-net:
    driver: bridge

Переменная ANTHROPIC_API_KEY обязательна — без неё плагин не сможет обращаться к модели. Вынесите её в .env, чтобы не светить токен в репозитории:

bashКопировать
ANTHROPIC_API_KEY=sk-ant-...

Запустите контейнер:

bashКопировать
docker compose up -d

Проверьте, что контейнер поднялся и не падает:

bashКопировать
docker compose logs -f ponytail

Если в логах нет ошибок подключения к API, можно переходить к конфигурации.

Первоначальная конфигурация

Ponytail настраивается через файл CLAUDE.md в корне проекта — именно там агент забирает инструкции о том, как себя вести. Это не опция, а основной способ управления плагином.

Пример минимального CLAUDE.md:

markdownКопировать
# Claude Code Instructions

## Role
Вы — опытный разработчик. Ваша задача — предлагать минимальные изменения кода, избегать лишней абстракции и не перезаписывать файлы целиком, если достаточно точечной правки.

## Principles
- Пишите столько кода, сколько нужно для решения задачи, и не больше.
- Предпочитайте явное неявному.
- Перед изменением файла оцените, можно ли обойтись без нового абстракционного слоя.
- Если функция уже существует — используйте её, не дублируйте логику.

## Output format
- Предлагайте изменения в формате unified diff.
- Объясняйте, почему именно такое решение, а не просто показывайте код.

Положите этот файл в корень репозитория, с которым работает Claude Code. Ponytail подхватит его при следующем запуске агента.

Теперь проверьте, что плагин видит конфигурацию. В Claude Code выполните любой запрос на изменение кода — агент должен ответить предложением с diff, а не полной перезаписью файла.

Если нужно ограничить доступ к определённым директориям, добавьте в docker-compose.yml секцию с путями:

yamlКопировать
    volumes:
      - ./config:/app/config:ro
      - /home/alexey/projects:/workspace:ro

Параметр :ro делает директорию доступной только на чтение — агент не сможет случайно удалить файлы вне рабочей области.

Для более глубокой настройки инструкций агента полезно ознакомиться с CLAUDE.md для Claude Code по наблюдениям Карпати. Если беспокоит безопасность изолированных сред, посмотрите ECC: оптимизация и безопасность агентных оболочек.

Принцип работы

Принцип работы

Большинство AI-агентов работают как первокурсники на первом практикуме: видят задачу и сразу хотят написать всё с нуля. Новый сервис? Создашь репозиторий, настроишь CI/CD, поднимешь базу, нарисуешь фронтенд. А потом оказывается, что заказчику нужен был только скрипт, который раз в час парсит CSV и кладёт результат в таблицу.

Ponytail делает обратное. Плагин для Claude Code заставляет агента сначала спросить себя: «А нужно ли вообще писать код?» Если можно решить задачу существующими средствами — агент берёт их. Если нужно что-то новое — пишет минимум, достаточный для решения, и останавливается.

Формирование промптов

Ponytail перехватывает промпты, которые Claude Code отправляет агенту, и добавляет в системную инструкцию правило «ленивого» мышления. Агент не получает прямую команду «напиши код», он получает задачу с ограничением: решить её с минимальным вмешательством в кодовую базу.

Вот как выглядит типичный промпт без ponytail:

Реализуй функцию экспорта отчётов в PDF. Нужно взять данные из базы,
сформировать таблицу и отправить пользователю на почту.

Агент тут же начнёт выбирать библиотеку для генерации PDF, настраивать шаблон, подключать SMTP-сервер и писать десятки строк кода.

С ponytail тот же запрос transformaется примерно в следующее:

Задача: экспорт отчётов в PDF.

Ограничения:
- Не пиши новый код, если задача решается существующими инструментами.
- Если код всё же нужен — минимальный объём, без обёрток и абстракций.
- Предпочитай готовые решения и CLI-утилиты над самописными сервисами.

Агент смотрит на инфраструктуру и видит, что в компании уже есть wkhtmltopdf и внутренний почтовый шлюз. Вместо нового микросервиса он пишет скрипт из пяти строк:

bashКопировать
#!/bin/bash
# Берём отчёт из базы, конвертируем в PDF и отправляем
psql -d reports -c "COPY (SELECT * FROM monthly_report) TO STDOUT WITH CSV" \
  | wkhtmltopdf - report.pdf \
  && mutt -s "Месячный отчёт" -a report.pdf -- user@example.com < /dev/null

Никаких новых зависимостей, никаких Docker-контейнеров, никакой документации на полсотни страниц. Код есть, но его столько, сколько нужно, и не больше.

Механизм ленивого мышления

Ponytail работает на уровне агентных навыков (agent-skills). Когда Claude Code вызывает инструмент, плагин проверяет, соответствует ли действие принципу «минимума кода». Если агент пытается создать новый файл, где достаточно существующего, ponytail блокирует действие и предлагает пересмотреть подход.

Механизм строится на трёх вопросах, которые агент задаёт себе перед каждым действием:

1. Существует ли готовое решение? — Может быть, в репозитории уже есть скрипт, который делает 80% того, что нужно?
2. Можно ли обойтись без кода? — Иногда достаточно изменить конфиг, добавить переменную окружения или поправить правило в Nginx.
3. Какой минимальный код решит задачу? — Если писать всё же нужно, пишется только то, без чего задача не решится.

Пример из реальной практики. Нужно было собирать логи с трёх серверов и отправлять в централизованное хранилище. Без ponytail агент предложил бы поднять отдельный сервис с Vector или Fluent Bit, настроить конфиги, пробросить порты. С ponytail он посмотрел, что на серверах уже стоит systemd и journald, и предложил просто перенаправить логи через существующий syslog-сервер:

iniКопировать
# /etc/systemd/journald.conf.d/forward.conf
[Journal]
ForwardToSyslog=yes
ForwardToWall=no

bashКопировать
# rsyslog уже работает, добавляем правило в существующий конфиг
echo '*.* @@logs.example.com:514' >> /etc/rsyslog.d/99-forward.conf
systemctl restart rsyslog

Пять минут работы вместо двух часов на развёртывание нового стека.

Это и есть суть «ленивого» подхода. Не лень в плохом смысле, а лень как инженерное качество: не делать лишних движений, не вводить лишних зависимостей, не создавать лишних точек отказа. Чем меньше кода вы пишете, тем меньше кода нужно поддерживать, тестировать и документировать.

Если вам интересно, как формировать правильные инструкции для Claude Code, посмотрите CLAUDE.md для Claude Code по наблюдениям Карпати — там разобраны принципы работы с агентными оболочками, которые хорошо дополняют идеи ponytail. А если хотите увидеть примеры того, как агенты применяются на практике, почитайте о QA-агентах Momentic и о DeepSeek Harness как плагине.

Интеграция с Claude Code

Интеграция с Claude Code

Подключение плагина

Ponytail устанавливается как нативный плагин Claude Code. Он не требует отдельного сервера и не тянет лишних зависимостей — всё работает внутри сессии Claude Code через механизм agent-skills.

Во-первых, проверьте, что у вас установлена последняя версия Claude Code. Плагин рассчитан на работу с Claude Code, а не с веб-интерфейсом Claude.

bashКопировать
claude --version

Если версия устарела, обновитесь. Затем добавьте ponytail в конфигурацию агента. В Claude Code навыки подключаются через файл CLAUDE.md в корне проекта или через глобальный конфиг ~/.claude/CLAUDE.md. Я предпочитаю проектный конфиг — так настройки живут рядом с кодом и не утекают в чужие проекты.

Создайте файл CLAUDE.md в корне репозитория:

markdownКопировать
# Agent Skills

- name: ponytail
  source: https://github.com/DietrichGebert/ponytail
  version: latest
  description: Ленивый подход к AI-агентам — минимум кода, максимум предсказуемости

С практической точки зрения, достаточно указать имя и источник. Claude Code сам подтянет плагин при следующем запуске. Если вы используете закрытый репозиторий или свой форк, укажите путь к локальной копии:

markdownКопировать
# Agent Skills

- name: ponytail
  source: ./vendor/ponytail
  version: 1.0.0

После добавления конфига перезапустите Claude Code. Плагин активируется автоматически — никаких дополнительных команд вроде claude plugin install не требуется.

Если мы посмотрим на логи Claude Code после первого запуска с ponytail, там должно появиться сообщение о загрузке навыка. Это подтверждает, что плагин подхвачен и готов к работе.

Примеры использования

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

Пример. Нужно добавить эндпоинт, который принимает JSON и записывает его в PostgreSQL. Без ponytail агент может нагенерировать целую архитектуру с репозиториями, сервисами, DTO и промежуточным слоем валидации. С ponytail он предложит прямое решение:

typescriptКопировать
import { createClient } from '@libsql/client';

const client = createClient({
  url: process.env.DATABASE_URL!,
});

export default async function handler(req: Request) {
  if (req.method !== 'POST') {
    return new Response('Method not allowed', { status: 405 });
  }

  const body = await req.json();
  await client.execute({
    sql: 'INSERT INTO events (payload, created_at) VALUES (?, datetime("now"))',
    args: [JSON.stringify(body)],
  });

  return new Response('OK', { status: 200 });
}

Никаких лишних абстракций. Код читается сверху вниз, ошибки ловятся на уровне базы данных, а не в кастомных обёртках.

Ещё один сценарий — работа с файлами. Агент без ponytail может предложить подключить тяжелую библиотеку для чтения CSV. Ponytail предложит встроенные средства языка:

pythonКопировать
import csv

def read_events(path: str):
    with open(path, newline='') as f:
        reader = csv.DictReader(f)
        for row in reader:
            yield row

Сравните с тем, что обычно предлагают агенты: подключение pandas, создание DataFrame, промежуточная валидация схемы. Ponytail выбирает то, что достаточно для задачи и ничего больше.

Если вы уже используете CLAUDE.md для описания правил работы агента, ponytail дополняет его, а не заменяет. Подробнее о структуре CLAUDE.md можно почитать в материале CLAUDE.md для Claude Code по наблюдениям Карпати.

Плагин особенно полезен, когда нужно быстро автоматизировать рутину без раздувания кодовой базы. Если вас интересуют другие подходы к агентной автоматизации, посмотрите статьи про QA-агенты Momentic и про оптимизацию агентных оболочек ECC.

Часто задаваемые вопросы

Можно ли запустить ponytail без Docker, прямо на сервере?

Можно, но я не рекомендую. Плагин тянет за собой зависимости от Claude Code и Anthropic SDK, которые легко конфликтуют с системными пакетами. Docker даёт предсказуемую среду и упрощает обновление — достаточно пересобрать контейнер, а не чистить виртуальное окружение вручную.

Нужно ли отдельно платить за ponytail, если уже есть подписка на Claude Code?

Сам плагин бесплатный, но доступ к API Anthropic оплачивается отдельно. Ponytail не встроен в Claude Code, он работает как сторонний сервис и обращается к модели через ваш ключ ANTHROPIC_API_KEY. Расходы зависят от количества запросов, которые агент отправляет при анализе кода.

Куда писать инструкции для агента — в CLAUDE.md или в docker-compose.yml?

В CLAUDE.md. Этот файл лежит в корне проекта и читается плагином при каждом запросе, а docker-compose.yml отвечает только за запуск контейнера и переменные окружения. Если вы измените правила в CLAUDE.md, ponytail подхватит их без перезапуска контейнера.

Будет ли ponytail работать с локальными моделями вместо Anthropic?

Нет, в текущей версии плагин заточен под API Anthropic и не поддерживает локальные модели. Переменная CLAUDE_CODE_URL указывает на адрес самого Claude Code, а не на стороннюю модель. Если вам нужны локальные LLM, придётся искать другое решение или ждать обновления от автора.

Что делать, если агент всё равно переписывает целые файлы?

Скорее всего, в CLAUDE.md не прописаны чёткие правила минимальных изменений, или агент не видит контекст файла. С практической точки зрения, достаточно добавить в инструкцию требование править только затронутые строки. Убедитесь, что ponytail действительно перехватывает запросы — посмотрите логи контейнера. Если проблема повторяется, добавьте пример правильного патча прямо в CLAUDE.md.