AIコーディングツールを無限ループで回して、要件を全自動で実装させる仕組み — ralph

アーキテクチャ・仕組み

Ralphの核心は「各イテレーション = 新しいAIインスタンス」という設計にあります。ループのたびに新しいAIプロセス（AmpまたはClaude Code）を起動し、クリーンなコンテキストで作業を開始します。イテレーション間の記憶は以下の3つで保持されます:

• git履歴: 前回のイテレーションでのコミット内容
• progress.txt: 追記専用の学習・知見ファイル
• prd.json: 各ユーザーストーリーの完了状態（passes: true/false）

1回のイテレーションの流れ

1. PRDのbranchNameからフィーチャーブランチを作成
2. passes: falseのストーリーの中から最も優先度が高いものを選択
3. そのストーリーを1つだけ実装
4. 品質チェック（型チェック、テスト）を実行
5. チェックが通ればコミット
6. prd.jsonのステータスをpasses: trueに更新
7. 学んだことをprogress.txtに追記
8. 全ストーリーが完了するか最大イテレーション数に達するまで繰り返し

対応AIツール

主要ファイル構成

• ralph.sh — メインのBashループスクリプト
• prompt.md — Amp用のプロンプトテンプレート
• CLAUDE.md — Claude Code用のプロンプトテンプレート
• prd.json — タスクリスト（JSON形式、ユーザーストーリーと完了状態）
• progress.txt — 追記専用の学習ログ
• skills/prd/ — PRD生成スキル
• skills/ralph/ — PRDからJSON変換スキル
• .claude-plugin/ — Claude Codeマーケットプレイス用プラグインマニフェスト

タスク設計の重要な制約

各PRDアイテムは1つのコンテキストウィンドウで完了できるサイズにする必要があります。大きすぎるとAIがコンテキスト上限に達し、品質の低いコードを生成します。

適切なサイズの例:

• データベースカラムとマイグレーションの追加
• 既存ページへのUIコンポーネント追加
• サーバーアクションのロジック更新

大きすぎる例（分割が必要）:

• 「ダッシュボード全体を構築」
• 「認証機能を追加」

AGENTS.md による知識の蓄積

各イテレーション後、RalphはAGENTS.mdファイルに学びを追記します。AIコーディングツールはこのファイルを自動的に読み込むため、後続のイテレーションや人間の開発者が発見されたパターンや注意点を活用できます。

フィードバックループの必要性

自律動作のためには以下が不可欠:

• 型チェック（型エラーの検出）
• テスト（振る舞いの検証）
• CI（壊れたコードがイテレーションをまたいで蓄積するのを防止）

UI検証

フロントエンドのストーリーでは、受け入れ基準に「dev-browserスキルでブラウザ検証」を含めることで、Ralphが実際にブラウザでUIを操作して変更を確認します。

停止条件

全ストーリーがpasses: trueになると、<promise>COMPLETE</promise>を出力してループが終了します。

アーカイブ機能

新しいフィーチャー（異なるbranchName）を開始すると、前回の実行結果がarchive/YYYY-MM-DD-feature-name/に自動アーカイブされます。

Amp設定の推奨

AmpのautoHandoffを有効にすると、コンテキストが90%に達した際に自動でハンドオフが行われ、大きなストーリーにも対応できます。

元ネタ

Geoffrey Huntley氏のRalphパターンに基づいた実装です。

セットアップ手順

前提条件:

• AIコーディングツール（Amp CLI または Claude Code）がインストール済み
• jq がインストール済み（macOSなら brew install jq）
• gitリポジトリが存在すること

方法1: プロジェクトにコピー

mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
# Amp用
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md
# Claude Code用
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh

方法2: スキルをグローバルにインストール（Amp向け）

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

実行方法:

# Amp（デフォルト）
./scripts/ralph/ralph.sh [max_iterations]
# Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

デフォルトは10回のイテレーションです。