Ralph Loop + ревью-гейт

Что это

Ставишь задачу один раз — агент сам крутит работу по кругу, пока не доведёт до результата.

Обычно ты дёргаешь AI вручную: спросил → ответ → поправил → спросил заново. На большой задаче так теряется контекст и забывается, что было в начале. Ralph переворачивает схему: ты пишешь ТЗ, режешь его на мелкие задачи и запускаешь цикл. Каждый круг — это новый агент с чистым контекстом, который берёт одну задачу, пишет код, прогоняет тесты, коммитит и переходит к следующей. Память между кругами живёт не в переписке, а в git-истории, progress.txt и prd.json — поэтому модель не тупеет к концу большого проекта: у неё всегда свежая голова и понятный следующий шаг.

Пакет — обёртка над оригинальным Ralph (20k★, паттерн Geoffrey Huntley), которая добавляет то, чего там нет: обязательный ревью-гейт перед merge. Сырой цикл гонит до «готово» без проверки — удобно, но опасно. Здесь ветка не считается готовой, пока её не подписали два независимых ревьюера.

Установка

Одна команда — и три скилла встают в Claude Code или Codex.

curl -fsSL https://raw.githubusercontent.com/sergeyramas/ralph-loop-setup/main/install.sh | bash

Что и куда встаёт:

• ~/.claude/skills/{prd,ralph,ralph-loop-setup}/ — три скилла, глобально;
• scripts/ralph/ralph.sh — раннер цикла, в твоём проекте;
• scripts/ralph/CLAUDE.md — промпт, который Ralph скармливает каждому свежему агенту (не путать с корневым CLAUDE.md проекта);
• tasks/ — папка под ТЗ.

Перезапусти агента, чтобы скиллы подхватились. Либо вообще не возись руками — скинь любому агенту файл AGENT-INSTALL.md из репозитория, и он поставит всё сам и заскаффолдит проект.

Написать ТЗ — /prd

Опиши, что хочешь собрать. Агент задаст уточняющие вопросы и соберёт нормальную спеку.

/prd

Дальше словами: «собери дашборд заказов с фильтрами, статусами и поиском». Агент задаст 3–5 уточняющих вопросов с вариантами A/B/C/D — отвечаешь коротко, типа 1A, 2C, 3B. На выходе готовый tasks/prd-<feature>.md. Никакого кода на этом шаге — только ТЗ.

Нарезать на задачи — /ralph

Превращает ТЗ в список атомарных задач, каждая размером ровно в один заход.

/ralph

Создаёт scripts/ralph/prd.json — упорядоченные user stories (схема → бэкенд → UI), у каждой статус passes: false. Проверь нарезку глазами: если задачу нельзя описать в 2–3 предложениях — она слишком крупная, агент не уложится в один контекст и выдаст битый код. «Добавить аутентификацию» — это не одна задача, а пять; дроби.

Запустить цикл

Одна команда — и дальше можно идти по своим делам.

./scripts/ralph/ralph.sh --tool claude 15

15 — лимит кругов, страховка от бесконечного молотилова. Что происходит на каждом круге:

• запускается новый агент с чистым контекстом;
• читает prd.json → берёт первую невыполненную задачу по приоритету;
• пишет код, прогоняет проверки (typecheck, lint, tests);
• коммитит feat: US-xxx, ставит задаче passes: true;
• дописывает урок в progress.txt для следующего круга;
• когда все задачи закрыты — печатает <promise>COMPLETE</promise> и цикл сам стопается.

Возвращаешься не к простыне текста в чате, а к собранному проекту в git.

Ревью перед merge

Зелёные тесты — это ещё не «готово». Ветка не закрыта, пока её не подписали два независимых слоя.

• L1 — агентский code-reviewer. Сверяет ветку с критериями приёмки ТЗ и стандартами проекта, адверсариально (не «вроде работает»). В Claude Code — /code-review.
• L2 — независимая вторая модель другого провайдера: codex review --base main. Ловит то, что автор-модель в собственном коде не видит by design.

Мёржить только когда оба слоя зелёные — или каждое замечание осознанно закрыто с записью «почему».

Хочешь сразу получить команды гейта после прогона — запускай через обёртку ./review-gate/ralph-review.sh 15: она гоняет цикл и в конце печатает точные команды L1/L2. Авто-мёрджа нет — человек держит гейт.

Ключевые файлы

Четыре файла, по которым видно весь ход работы.

• tasks/prd-*.md — человекочитаемое ТЗ (исходник).
• scripts/ralph/prd.json — машинный статус: у каждой задачи passes: true/false.
• scripts/ralph/progress.txt — лог каждого круга плюс уроки, которые переезжают между итерациями.
• scripts/ralph/archive/ — архивы прошлых prd.json, когда начинаешь новую фичу.

Полезные флаги

Один скрипт, лимит кругов под размер задачи.

./scripts/ralph/ralph.sh --tool claude 10   # короткая задача
./scripts/ralph/ralph.sh --tool claude 25   # крупная фича
tail -f scripts/ralph/progress.txt           # смотреть прогресс вживую

Когда НЕ использовать

Автономный цикл — для инфраструктуры и скаффолда, где ошибка дешёвая и проверяемая.

Никогда не гоняй луп на реальных деньгах, секретах, кредах и необратимых действиях — платежи, прод-миграции, отправка писем, удаление данных. Чистый-контекст автономия там противопоказана: такие потоки идут только под наблюдением, по одному шагу, с человеком на гейте. Это ровно тот класс ошибок, от которого ревью-гейт не спасает.

Цена за принятый результат

Главная метрика — не токены и не число прогонов, а сколько результатов ты реально принял.

Если из десяти кругов ты выкидываешь шесть и доделываешь руками — луп не забрал у тебя работу, а только сделал вид, и обходится дороже, чем приносит. Принимаешь меньше половины — чини upstream: ужимай ТЗ, делай критерии приёмки проверяемыми, дроби задачи мельче, пока каждая не влезает в один чистый контекст.