Как настроить технику Ralph Wiggum для автономной разработки с ИИ

КРАТКАЯ СПРАВКА

Сложность	Средняя
Время	45–90 минут на первичную настройку
Что нужно знать	Командная строка, основы Git, идея для проекта
Инструменты	Claude Code CLI (свежая версия), Git, Bash/Zsh, Docker (желательно)

Чему научитесь:

• Настраивать автономный цикл Ralph Wiggum с нуля
• Писать спецификации и промпты, которые направляют ИИ в нужное русло
• Запускать Claude Code в песочнице без постоянных запросов на подтверждение
• Находить причины сбоев цикла и подкручивать промпты по ходу дела

---

Техника Ralph Wiggum — это bash-цикл, который скармливает Claude Code один и тот же промпт снова и снова, пока проект не будет готов. Названа в честь персонажа «Симпсонов», который продолжает пытаться несмотря ни на что. Работает это потому, что каждая итерация получает чистое контекстное окно, а состояние сохраняется в файлах и git. Здесь разберём полную настройку: от установки Claude Code до запуска первого автономного цикла.

Что такое Ральф на самом деле

В основе — пять строк на bash:

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

Это самая чистая форма. Claude читает файл с промптом, делает работу, коммитит прогресс, завершается. Bash-цикл тут же перезапускает его с чистым контекстом. Файл IMPLEMENTATION_PLAN.md на диске подсказывает каждому новому экземпляру Claude, что делать дальше.

Техника решает реальную проблему: языковые модели деградируют по мере заполнения контекстного окна неудачными попытками и мусорным кодом. Принудительно обновляя контекст на каждой задаче, Ральф избегает «загрязнения контекста», когда модель продолжает ссылаться на плохую информацию. Состояние живёт в файлах и git, а не в памяти Claude.

Проверка требований

Прежде чем начать, убедитесь, что у вас есть:

Обязательно:

• Unix-подобная среда (macOS, Linux или WSL на Windows)
• Установленный и настроенный Git
• Аккаунт Anthropic с подпиской Claude Pro, Claude Max или доступом к API

Очень желательно:

• Docker для песочницы (об этом ниже)
• Проект с существующими тестами или проверкой типов (это станет вашим «противодавлением»)

Если вы на Windows без WSL — сначала установите его. Нативная командная строка Windows здесь не подойдёт.

Установка Claude Code

Рекомендуемый способ — нативный установщик. Откройте терминал:

curl -fsSL https://claude.ai/install.sh | bash

После установки перезапустите терминал или выполните source ~/.bashrc (или ~/.zshrc на macOS). Проверьте, что всё работает:

claude --version

Должен появиться номер версии. Если видите «command not found», добавьте директорию с бинарником Claude в PATH:

echo 'export PATH="$HOME/.claude/bin:$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Аутентификация: Запустите claude один раз в любой директории. Откроется браузер для OAuth-аутентификации с вашим аккаунтом Anthropic. Завершите этот шаг, прежде чем продолжать.

Структура проекта

Ральфу нужны определённые файлы. Создайте такую структуру:

your-project/
├── loop.sh                    # Bash-скрипт, запускающий Ральфа
├── PROMPT_build.md            # Инструкции для сборки/реализации
├── PROMPT_plan.md             # Инструкции для планирования/анализа пробелов
├── AGENTS.md                  # Как собирать/тестировать проект
├── IMPLEMENTATION_PLAN.md     # Список задач (генерируется Ральфом)
├── specs/                     # По одному файлу на фичу/тему
│   └── [feature-name].md
└── src/                       # Исходный код

Файл IMPLEMENTATION_PLAN.md изначально не существует. Ральф создаёт его на этапе планирования.

AGENTS.md

Этот файл объясняет Claude, как собирать и тестировать проект. Держите его коротким и операционным. Максимум 60 строк. Не используйте как дневник прогресса.

## Сборка и запуск

- Установка: `npm install`
- Dev-сервер: `npm run dev`
- Сборка: `npm run build`

## Валидация

Запускайте после внесения изменений:

- Тесты: `npm test`
- Проверка типов: `npx tsc --noEmit`
- Линтер: `npm run lint`

## Паттерны кодовой базы

- Компоненты в `src/components/`
- Утилиты в `src/lib/`
- Тесты рядом с файлами: `Button.tsx` → `Button.test.tsx`

Команды валидации критически важны. Они создают «противодавление», не позволяющее Claude коммитить сломанный код. Если тесты падают, Claude должен их починить, прежде чем двигаться дальше.

Директория specs/

Каждый файл спецификации описывает одну фичу или «зону ответственности». Пишите их совместно с ИИ перед запуском цикла или пишите сами. Главное — одна концепция на файл.

Спецификация может выглядеть так:

# Аутентификация пользователей

## Обзор
Пользователи могут регистрироваться, входить и выходить. Сессии сохраняются между перезапусками браузера.

## Требования
- Регистрация по email/паролю с валидацией
- JWT-сессии в httpOnly-куках
- Сброс пароля через email-ссылку
- Ограничение попыток входа (5 в минуту)

## Критерии приёмки
- Пользователь может создать аккаунт с валидным email
- На невалидный email показывается понятное сообщение об ошибке
- Сессия сохраняется после перезапуска браузера
- Выход полностью очищает сессию

Не заморачивайтесь форматом. Эти спецификации для чтения Claude, а он хорошо справляется с неструктурированным текстом.

Файлы промптов

Нужны два файла: один для планирования, один для сборки.

PROMPT_plan.md (создаёт план реализации):

0a. Study `specs/*` with up to 250 parallel Sonnet subagents to learn the application specifications.
0b. Study @IMPLEMENTATION_PLAN.md (if present) to understand the plan so far.
0c. Study `src/lib/*` with up to 250 parallel Sonnet subagents to understand shared utilities & components.
0d. For reference, the application source code is in `src/*`.

1. Study @IMPLEMENTATION_PLAN.md (if present; it may be incorrect) and use up to 500 Sonnet subagents to study existing source code in `src/*` and compare it against `specs/*`. Use an Opus subagent to analyze findings, prioritize tasks, and create/update @IMPLEMENTATION_PLAN.md as a bullet point list sorted in priority of items yet to be implemented. Ultrathink. Consider searching for TODO, minimal implementations, placeholders, skipped/flaky tests, and inconsistent patterns. Study @IMPLEMENTATION_PLAN.md to determine starting point for research and keep it up to date with items considered complete/incomplete using subagents.

IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first. Treat `src/lib` as the project's standard library for shared utilities and components. Prefer consolidated, idiomatic implementations there over ad-hoc copies.

ULTIMATE GOAL: We want to achieve [ВАША ЦЕЛЬ ПРОЕКТА]. Consider missing elements and plan accordingly. If an element is missing, search first to confirm it doesn't exist, then if needed author the specification at specs/FILENAME.md. If you create a new element then document the plan to implement it in @IMPLEMENTATION_PLAN.md using a subagent.

Замените [ВАША ЦЕЛЬ ПРОЕКТА] на реальную цель.

PROMPT_build.md (реализует по плану):

0a. Study `specs/*` with up to 500 parallel Sonnet subagents to learn the application specifications.
0b. Study @IMPLEMENTATION_PLAN.md.
0c. For reference, the application source code is in `src/*`.

1. Your task is to implement functionality per the specifications using parallel subagents. Follow @IMPLEMENTATION_PLAN.md and choose the most important item to address. Before making changes, search the codebase (don't assume not implemented) using Sonnet subagents. You may use up to 500 parallel Sonnet subagents for searches/reads and only 1 Sonnet subagent for build/tests. Use Opus subagents when complex reasoning is needed (debugging, architectural decisions).
2. After implementing functionality or resolving problems, run the tests for that unit of code that was improved. If functionality is missing then it's your job to add it as per the application specifications. Ultrathink.
3. When you discover issues, immediately update @IMPLEMENTATION_PLAN.md with your findings using a subagent. When resolved, update and remove the item.
4. When the tests pass, update @IMPLEMENTATION_PLAN.md, then `git add -A` then `git commit` with a message describing the changes. After the commit, `git push`.

99999. Important: When authoring documentation, capture the why — tests and implementation importance.
999999. Important: Single sources of truth, no migrations/adapters. If tests unrelated to your work fail, resolve them as part of the increment.
9999999. As soon as there are no build or test errors create a git tag. If there are no git tags start at 0.0.0 and increment patch by 1 for example 0.0.1 if 0.0.0 does not exist.
99999999. You may add extra logging if required to debug issues.
999999999. Keep @IMPLEMENTATION_PLAN.md current with learnings using a subagent — future work depends on this to avoid duplicating efforts. Update especially after finishing your turn.
9999999999. When you learn something new about how to run the application, update @AGENTS.md using a subagent but keep it brief.
99999999999. For any bugs you notice, resolve them or document them in @IMPLEMENTATION_PLAN.md using a subagent even if it is unrelated to the current piece of work.
999999999999. Implement functionality completely. Placeholders and stubs waste efforts and time redoing the same work.
9999999999999. When @IMPLEMENTATION_PLAN.md becomes large periodically clean out the items that are completed from the file using a subagent.
99999999999999. If you find inconsistencies in the specs/* then use an Opus 4.5 subagent with 'ultrathink' requested to update the specs.
999999999999999. IMPORTANT: Keep @AGENTS.md operational only — status updates and progress notes belong in IMPLEMENTATION_PLAN.md. A bloated AGENTS.md pollutes every future loop's context.

Нумерованные «ограждения» (99999, 999999 и т. д.) — не случайность. Чем больше число, тем выше приоритет для модели. Они накапливаются со временем, когда вы замечаете паттерны сбоев и добавляете «знаки» для их предотвращения.

loop.sh

Этот скрипт оборачивает ядро цикла с выбором режима и лимитом итераций:

#!/bin/bash
# Использование: ./loop.sh [plan] [max_iterations]
# Примеры:
#   ./loop.sh              # Режим сборки, без ограничения итераций
#   ./loop.sh 20           # Режим сборки, максимум 20 итераций
#   ./loop.sh plan         # Режим планирования, без ограничения
#   ./loop.sh plan 5       # Режим планирования, максимум 5 итераций

if [ "$1" = "plan" ]; then
    MODE="plan"
    PROMPT_FILE="PROMPT_plan.md"
    MAX_ITERATIONS=${2:-0}
elif [[ "$1" =~ ^[0-9]+$ ]]; then
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIONS=$1
else
    MODE="build"
    PROMPT_FILE="PROMPT_build.md"
    MAX_ITERATIONS=0
fi

ITERATION=0
CURRENT_BRANCH=$(git branch --show-current)

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Mode:   $MODE"
echo "Prompt: $PROMPT_FILE"
echo "Branch: $CURRENT_BRANCH"
[ $MAX_ITERATIONS -gt 0 ] && echo "Max:    $MAX_ITERATIONS iterations"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

if [ ! -f "$PROMPT_FILE" ]; then
    echo "Error: $PROMPT_FILE not found"
    exit 1
fi

while true; do
    if [ $MAX_ITERATIONS -gt 0 ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then
        echo "Reached max iterations: $MAX_ITERATIONS"
        break
    fi

    cat "$PROMPT_FILE" | claude -p \
        --dangerously-skip-permissions \
        --output-format=stream-json \
        --model opus \
        --verbose

    git push origin "$CURRENT_BRANCH" || {
        echo "Failed to push. Creating remote branch..."
        git push -u origin "$CURRENT_BRANCH"
    }

    ITERATION=$((ITERATION + 1))
    echo -e "\n\n======================== LOOP $ITERATION ========================\n"
done

Сделайте его исполняемым:

chmod +x loop.sh

Флаг -p запускает Claude в headless-режиме. --dangerously-skip-permissions нужен для автономной работы, что подводит нас к следующей важной теме.

Песочница (обязательно для автономных запусков)

Флаг --dangerously-skip-permissions делает ровно то, что написано в названии. Он отключает все запросы безопасности. Без песочницы атака через внедрение промпта может получить доступ к вашим SSH-ключам, кукам браузера и всему остальному на машине.

Философия Джеффри Хантли: «Вопрос не в том, взломают ли. Вопрос — когда. И каков радиус поражения?»

Варианты, примерно в порядке сложности:

Вариант 1: Docker (локально)

Создайте Dockerfile:

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y \
    curl git nodejs npm python3 \
    && rm -rf /var/lib/apt/lists/*

RUN curl -fsSL https://claude.ai/install.sh | bash

WORKDIR /workspace
CMD ["bash"]

Запустите Claude внутри:

docker build -t ralph-sandbox .
docker run -it --rm \
    -v $(pwd):/workspace \
    -v ~/.claude:/root/.claude \
    ralph-sandbox bash

Затем запустите ./loop.sh изнутри контейнера.

Вариант 2: DevContainer (VS Code/Cursor)

Anthropic предоставляет официальную спецификацию devcontainer. Создайте .devcontainer/devcontainer.json:

{
  "name": "Ralph Sandbox",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  },
  "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash",
  "remoteUser": "vscode"
}

VS Code предложит переоткрыть проект в контейнере.

Вариант 3: Нативная песочница (macOS)

В Claude Code есть встроенная песочница для macOS. Создайте .claude/settings.json в проекте:

{
  "sandbox": {
    "enabled": true,
    "allowedPaths": ["./"],
    "networkAccess": true
  }
}

Это обеспечивает изоляцию файловой системы без Docker. Сетевой доступ остаётся открытым для установки пакетов.

Вариант 4: Удалённые песочницы

Для продакшн-нагрузок рассмотрите Fly Sprites, E2B, Modal или Google Cloud Run. Они обеспечивают изоляцию на уровне VM с сохранением состояния между запусками. Я не тестировал их детально, поэтому конкретных инструкций дать не могу.

Что бы вы ни выбрали, не запускайте --dangerously-skip-permissions на хост-машине с доступом к чувствительным данным. Тот единственный раз, когда вы забудете — будет тем разом, когда что-то пойдёт не так.

Запуск первого цикла

Когда всё готово:

Шаг 1: Инициализация Git

git init
git add .
git commit -m "Initial setup"

Ральфу нужен git для сохранения состояния между итерациями.

Шаг 2: Режим планирования

./loop.sh plan 5

Это запустит до 5 итераций планирования. Claude прочитает спецификации, проанализирует существующий код и создаст IMPLEMENTATION_PLAN.md. Следите за выводом. Если он закончит раньше (план готов), процесс завершится и цикл перезапустится, но вторая итерация должна быстро обнаружить, что делать нечего, и выйти.

Шаг 3: Проверка плана

Откройте IMPLEMENTATION_PLAN.md. Имеет смысл? Приоритеты разумные? Если нет, удалите его, подправьте спецификации или PROMPT_plan.md и запустите планирование заново. План — расходный материал.

Шаг 4: Режим сборки

./loop.sh 20

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

Внимательно наблюдайте за первыми несколькими итерациями. Где Ральф буксует? Какие неверные предположения делает?

Наблюдение и настройка

Первые запуски редко проходят гладко. Типичные паттерны сбоев:

Ральф реализует то, что уже существует

Добавьте в промпт сборки: «Before making changes, search the codebase (don't assume not implemented).» Это уже есть в шаблоне выше, но возможно придётся усилить.

Ральф застревает в цикле исправления одного теста

Либо противодавление слишком строгое, либо есть реальный баг, который он не может решить. Нажмите Ctrl+C, изучите код и либо исправьте вручную, либо добавьте подсказку в AGENTS.md о том, как обрабатывать этот случай.

Ральф игнорирует инструкции

Контекстное окно может быть переполнено. С циклическим подходом это случается реже, поскольку каждая итерация начинается с чистого листа, но если спецификации и AGENTS.md огромные, подумайте о сокращении.

Ральф коммитит сломанный код

Противодавление не работает. Убедитесь, что команды валидации в AGENTS.md действительно запускаются и падают когда должны. Claude узнаёт о провале тестов только если команда возвращает ненулевой код выхода.

Каждый сбой — это информация. Когда видите паттерн, добавляйте ограждение. Если Ральф постоянно удаляет файлы, которые не должен, добавьте «Never delete files without explicit user confirmation» в промпт. Если он создаёт дублирующиеся реализации, добавьте «Search before implementing.» Промпты эволюционируют через наблюдаемые сбои.

Устранение неполадок

«command not found: claude»

PATH не настроен. Добавьте директорию bin Claude в конфиг шелла и перезапустите терминал.

Ошибки аутентификации

Запустите claude интерактивно один раз для завершения OAuth. Токен сохраняется в ~/.claude/.

«Rate limit exceeded»

Вы упёрлись в лимит API. Подождите и попробуйте снова. С Claude Max лимиты щедрые, но не бесконечные.

Цикл крутится вечно без прогресса

Условие завершения не выполняется. Добавьте лимит итераций (./loop.sh 20) как предохранитель.

Permission denied при запуске loop.sh

Выполните chmod +x loop.sh чтобы сделать скрипт исполняемым.

Docker-контейнер не может пушить в git

Примонтируйте SSH-ключи или настройте кеширование учётных данных внутри контейнера. Или пушьте вручную после завершения цикла.

Альтернатива: официальный плагин

Anthropic выпустила официальный плагин Ральфа Виггама для Claude Code. Установите его командой:

/install-github-plugin anthropics/claude-code plugins/ralph-wiggum

Затем используйте:

/ralph-loop "Your task" --max-iterations 20 --completion-promise "DONE"

Плагин обрабатывает цикл внутренне вместо bash. С ним проще начать, но есть нюансы: он не сбрасывает контекст по-настоящему так, как это делает bash-цикл, и использует stop hooks, которые могут оставлять состояние в неожиданных местах. Джеффри Хантли (создатель техники) рекомендует bash-подход для полноценного обновления контекста. У меня результаты с плагином смешанные, поэтому я по умолчанию использую bash-цикл.

Что дальше

Когда первый проект заработает, захочется изучить рабочие ветки (запуск отдельных планов на feature-ветках), противодавление на основе критериев приёмки (вывод требований к тестам из спецификаций) и, возможно, LLM-as-judge для субъективных критериев вроде UI-дизайна. Репозиторий github.com/ghuntley/how-to-ralph-wiggum подробно разбирает эти улучшения.

Ключевой инсайт остаётся простым: скармливайте Claude один и тот же промпт снова и снова, пусть состояние сохраняется в файлах, настраивайте по результатам наблюдений. Всё остальное — уточнения.

---

УСТРАНЕНИЕ НЕПОЛАДОК

Симптом: Claude завершается сразу, ничего не делая Решение: Проверьте, что PROMPT_plan.md или PROMPT_build.md существует и содержит валидный контент. Убедитесь, что путь в loop.sh совпадает с реальными именами файлов.

Симптом: «Error: Cannot find module 'claude'» на некоторых системах Решение: Если устанавливали через npm, убедитесь, что глобальная bin-директория npm в PATH. Запустите npm bin -g чтобы найти путь, затем добавьте в конфиг шелла.

Симптом: Цикл продолжается, но ничего не коммитится Решение: Тесты падают тихо. Запустите команды валидации из AGENTS.md вручную, чтобы увидеть реальные ошибки. Исправьте их или скорректируйте тесты.

Симптом: IMPLEMENTATION_PLAN.md постоянно растёт с завершёнными пунктами Решение: Ограждение для очистки не срабатывает. Вручную уберите завершённые пункты или сделайте инструкцию по очистке более заметной в промпте сборки.

Симптом: Claude создаёт один и тот же файл несколько раз Решение: Добавьте в промпт: «Search the codebase before creating new files. If a similar file exists, modify it instead of creating a duplicate.»

---

ШАБЛОНЫ ПРОМПТОВ

Для начала новой фичи

Read IMPLEMENTATION_PLAN.md and begin work on the highest priority incomplete item. Before implementing, search the codebase to understand existing patterns. Implement the minimal solution that passes tests. Commit when tests pass.

Для отладки застрявшего цикла

Review the last 3 commits in git log. Identify what went wrong. Document the issue in IMPLEMENTATION_PLAN.md. Then fix it.

Пример результата: Claude изучает недавние коммиты, находит циклическую зависимость, которую сам создал, добавляет заметку о паттерне в AGENTS.md и реструктурирует код.

---

FAQ

Сколько стоит запускать это на ночь? С Claude Max включённого лимита обычно хватает. При почасовой оплате API 8-часовая сессия может обойтись в $20–100 в зависимости от сложности задач и выбора модели. Проверяйте реальное потребление в личном кабинете Anthropic.

Можно использовать с GPT-4 или другими моделями? Техника работает с любым CLI для кодирования с ИИ, который не ограничивает вызовы инструментов. Синтаксис промптов придётся адаптировать. У Cursor, Codex и других есть свои реализации Ральфа.

Что если Ральф удалит важные файлы? Для этого и нужны песочница и git. Если что-то пойдёт не так, git reset --hard откатит к последнему хорошему коммиту. Не запускайте без контроля версий.

Нужно постоянно следить? Сначала да. Наблюдайте за первыми 10–20 итерациями, чтобы понять паттерны сбоев. После настройки многие запускают на ночь и проверяют утром.

Как понять, что «готово»? Когда IMPLEMENTATION_PLAN.md пуст и все тесты проходят. Или когда достигнут лимит итераций. Магического определения завершения нет, хотя некоторые реализации добавляют маркер «DONE», который цикл отслеживает.

---

РЕСУРСЫ

• Оригинальный пост о Ralph Wiggum: Базовая статья Джеффри Хантли (требуется подписка на рассылку)
• Репозиторий how-to-ralph-wiggum: Подробный плейбук с шаблонами промптов и улучшениями
• Документация Claude Code: Официальная документация по установке и песочнице
• Руководство по песочнице Claude Code: Детальная настройка безопасности