Ralph — автономный цикл AI-агента для выполнения PRD

Ralph — это автономный AI-агент, который запускает инструменты AI-кодирования (Amp или Claude Code) в цикле, пока все задачи из Product Requirements Document не будут выполнены. Каждая итерация создаёт свежий инстанс с чистым контекстом, а память между запусками сохраняется через git-историю, progress.txt и prd.json. Проект основан на паттерне Ральфа от Geoffrey Huntley.

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

Ralph представляет собой bash-скрипт (ralph.sh), который в цикле порождает новые экземпляры AI-инструмента. На каждой итерации происходит следующее:

1. Создаётся feature-ветка (имя берётся из prd.json)
2. Выбирается задача с наивысшим приоритетом, где passes: false
3. AI-инструмент реализует эту задачу
4. Запускаются проверки качества (typecheck, тесты)
5. При успешных проверках — коммит
6. prd.json обновляется: passes: true
7. Накопленный опыт дописывается в progress.txt
8. Цикл повторяется, пока все задачи не будут выполнены или не достигнут лимит итераций

Когда все user stories получают статус passes: true, Ralph выводит <promise>COMPLETE</promise> и завершает работу.

Установка

Есть три способа интеграции в проект. Первый — скопировать ralph.sh и шаблон промпта (prompt.md для Amp или CLAUDE.md для Claude Code) в scripts/ralph/ вашего проекта. Второй — установить skills глобально в ~/.config/amp/skills/ или ~/.claude/skills/. Третий — подключить через Claude Code Marketplace:

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Для работы нужен один из AI-инструментов (Amp CLI или Claude Code), утилита jq и git-репозиторий проекта. Рекомендуется включить auto-handoff в настройках Amp — это позволяет обрабатывать задачи, превышающие размер одного контекстного окна.

Рабочий процесс

Работа с Ralph состоит из трёх шагов. Сначала с помощью skill /prd генерируется документ с требованиями — PRD. Затем skill /ralph конвертирует его в формат prd.json, где каждая user story имеет поля id, title, priority, passes и критерии приёмки. После этого запускается Ralph:

./scripts/ralph/ralph.sh              # Amp, 10 итераций по умолчанию
./scripts/ralph/ralph.sh --tool claude # Claude Code

Ключевые принципы

Чистый контекст на каждой итерации. Каждый запуск — это новый AI-инстанс без истории предыдущих диалогов. Единственная память между итерациями — git-коммиты, progress.txt и prd.json. Это предотвращает накопление ошибок и галлюцинаций.

Маленькие задачи. Каждая story в PRD должна быть достаточно мала, чтобы уложиться в одно контекстное окно. Правильный размер: добавить колонку в базу данных, добавить UI-компонент на существующую страницу, обновить server action. Слишком большое: «построить весь дашборд» или «добавить аутентификацию» — такие задачи нужно разбивать.

Обновление AGENTS.md. После каждой итерации Ralph записывает найденные паттерны и подводные камни в AGENTS.md. Поскольку AI-инструменты автоматически читают этот файл, будущие итерации и разработчики получают выгоду от накопленного опыта.

Обратные связи обязательны. Ralph работает только при наличии feedback loops: typecheck ловит ошибки типов, тесты проверяют поведение, CI должен оставаться зелёным. Сломанный код накапливается от итерации к итерации.

Архивация

При запуске нового feature (с другим branchName) Ralph автоматически архивирует предыдущий запуск в archive/YYYY-MM-DD-feature-name/.

Отладка

Проверить текущее состояние можно командами:

cat prd.json | jq '.userStories[] | {id, title, passes}'
cat progress.txt
git log --oneline -10

Файлы проекта

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