Ralph Wiggum

Вы наверняка бывали здесь: просите AI-агента реализовать фичу, он пишет код, объявляет победу, и… тесты падают. Промптите снова. Он пытается другой подход. Всё ещё сломано. Три итерации спустя вы делаете это сами.

Ralph Wiggum переворачивает эту динамику. Вместо надежды на совершенство с первой попытки, вы проектируете для итерации. Агент продолжает работать пока работа не будет действительно завершена — тесты проходят, типы проверяются, линтинг чист. Никаких преждевременных выходов. Никаких ложных побед.

Основная идея

В простейшем случае Ralph — это bash-цикл:

while :; do cat PROMPT.md | claude ; done

Вот и всё. передавайте агенту одну и ту же задачу повторно. Каждая итерация строится на основе предыдущей через git-историю и отслеживание прогресса. Агенту не нужно быть идеальным — ему нужно быть настойчивым.

Философия: Итерация побеждает перфекционизм. Детерминистические неудачи — это данные. Продолжайте пока не успех.

Как это работает

Ralph оборачивает стандартный цикл AI-инструмента внешним слоем верификации:

┌──────────────────────────────────────────────────────┐
│ Ralph Loop (внешний)                                 │
│ ┌────────────────────────────────────────────────┐   │
│ │ AI SDK Tool Loop (внутренний)                   │   │
│ │ LLM ↔ tools ↔ LLM ↔ tools ... пока не готово   │   │
│ └────────────────────────────────────────────────┘   │
│ ↓                                                    │
│ verifyCompletion: "Задача действительно завершена?"   │
│ ↓                                                    │
│ Нет? → Внедрить обратную связь → Запустить ещё итерацию│
│ Да? → Вернуть финальный результат                    │
└──────────────────────────────────────────────────────┘

Ключевые механизмы:

Стоп-хук: Перехватывает попытки выхода и проверяет критерии завершения перед тем как позволить агенту остановиться.
Отслеживание прогресса: Файл progress.txt отслеживает что сделано, какие решения приняты и какие блокеры встречены.
Git-коммиты: Каждая итерация коммитит работу, создавая контекст для будущих итераций.
Циклы обратной связи: Типы, тесты и линтинг верифицируют качество перед продолжением.
Верификация: Пользовательские критерии завершения определяют когда задача действительно выполнена.

Два режима работы

HITL (Human-In-The-Loop)

Запускайте одну итерацию за раз. Наблюдайте за работой агента. Вмешивайтесь когда нужно.

Это парное программирование с AI. Вы видите каждое решение, ловите ошибки рано и направляете курс.

Лучше всего для:

Изучения техники
Уточнения промптов
Рискованных задач, где вы хотите глаз на каждое изменение

AFK (Away From Keyboard)

Установите максимальное количество итераций и позвольте работать. Вернитесь к результатам.

Это ночная работа. Вы определяете чёткие критерии успеха, ограничиваете итерации и позволяете агенту выполнять механические задачи пока вы спите.

Лучше всего для чётко определённой работы:

Миграции тестов
Улучшения покрытия
Крупных рефакторингов с чёткими паттернами

Критично для режима AFK: Используйте Docker-песочницы. Вы даёте агенту автономный доступ к вашей системе. Изолируйте его.

docker sandbox run claude

Когда Ralph работает

Ralph превосходен в задачах с чёткими критериями завершения:

Тип задачи	Почему это работает
Крупные рефакторинги	Конвертация class-компонентов в hooks, Jest в Vitest
Миграции фреймворков	Конвертации тестовых наборов с чёткими состояниями до/после
TDD-рабочие процессы	Реализация фичей пока тесты не пройдут
Покрытие тестами	Добавление тестов к непокрытому коду пока порог покрытия не достигнут
Greenfield-сборки	REST API, полные фичи с определёнными спецификациями
Механическая очистка	Исправления линтинга, удаление дубликатов, устранение code smell

Когда Ralph не работает

Некоторые задачи сопротивляются итерации:

Неоднозначные требования: Если вы не можете определить “готово”, цикл не может верифицировать завершение.
Архитектурные решения: Эти требуют человеческого суждения, а не настойчивости.
Код, чувствительный к безопасности: Auth, платежи и криптография требуют человеческого ревью независимо от результатов тестов.
Задачи исследования: “Разобраться почему приложение тормозит” не имеет чёткой точки остановки.
Одноразовые операции: Если вам нужны немедленные результаты, накладные расходы цикла не стоят того.

Практические советы

Определите чёткий scope

Используйте структурированные критерии завершения:

{
  "category": "functional",
  "description": "Новая кнопка чата создаёт беседу",
  "steps": ["Нажать кнопку", "Верифицировать беседу", "Проверить состояние приветствия"],
  "passes": false
}

Агент точно знает что значит “готово”.

Отслеживайте прогресс

Ведите progress.txt с:

Завершёнными задачами
Принятыми решениями и почему
Встреченными блокерами
Изменёнными файлами

Это даёт будущим итерациям контекст о прошлой работе.

Используйте циклы обратной связи

Блокируйте коммиты если ВСЕ циклы обратной связи не пройдены:

Проверка типов TypeScript
Юнит-тесты
E2E-тесты (Playwright, Cypress)
Линтинг
Pre-commit хуки

Если любая проверка падает, итерация не завершена.

Делайте маленькие шаги

Держите одно логическое изменение на коммит. Разбивайте крупные задачи на подзадачи и запускайте циклы обратной связи после каждого изменения. Вам важно качество, а не скорость.

Ограничивайте итерации

HITL: Наблюдайте каждую итерацию
AFK: Установите max-iterations (10-20 для маленьких задач, 30-50 для крупных)
Никогда не используйте бесконечные итерации

50-итерационный цикл на большой кодовой базе может стоить $50-100+ в API-кредитах. Начните с 10-20 итераций чтобы понять потребление токенов перед масштабированием.

Коммитьте после каждой фичи

Хорошая git-гигиена создаёт чистую git-историю и чёткие точки отката. Если итерация 15 сломала что-то, вы можете откатиться к итерации 14.

Начало работы

Claude Code Plugin

/plugin install ralph-loop@claude-plugins-official
/ralph-loop "Add JSDoc comments to all exported functions" --max-iterations 10

NPM-пакет

npm install ralph-loop-agent ai zod

const agent = new RalphLoopAgent({
  model: "anthropic/claude-opus-4.5",
  instructions: "You are a helpful coding assistant.",
  stopWhen: iterationCountIs(10),
  verifyCompletion: async ({ result }) => ({
    complete: result.text.includes("DONE"),
    reason: "Task completed successfully",
  }),
});

Сдвиг в навыках

Традиционный AI-кодинг спрашивает: “Как мне написать идеальный промпт?”

Ralph спрашивает: “Как мне спроектировать условия при которых итерация ведёт к успеху?”

Вы перестаёте направлять AI пошагово и начинаете проектировать циклы, которые сходятся к решениям. Работа агента — настойчивость. Ваша работа — определить что значит “готово” и обеспечить чтобы циклы обратной связи ловили неудачи.

Это непрерывная автономия — агент работает пока работа не будет действительно завершена, а не просто пока LLM не перестанет вызывать инструменты.

Ресурсы

Официальные

Ralph Wiggum as a Software Engineer
GitHub - vercel-labs/ralph-loop-agent — Основной NPM-пакет
Ralph Wiggum - AI Loop Technique for Claude Code — Полный гайд и примеры

Туториалы

11 Tips For AI Coding With Ralph Wiggum — Практические советы для автономных циклов
The Ralph Wiggum Approach: Running AI Coding Agents for Hours — DEV Community туториал

Инструменты сообщества

ralph-claude-code — Rate limiting, tmux dashboards, circuit breakers
ralph-orchestrator — Отслеживание токенов, лимиты расходов, контрольные точки

Используете Ralph в продакшене? Поделитесь своим опытом—что сработало, что не сработало и что вы узнали.