Ralph - エージェント非依存の自律ループクリエーター

Ralphは機能を小さなユーザーストーリーに分割し、1つずつ完了させることで機能を実装する自律コーディングループを作成します。各イテレーションでは、きれいなコンテキストを持つ新しいヘッドレスエージェントが起動されます。メモリはgit、progress.txt、prd.jsonを通じて永続化されます。Ralphは単一のAIエージェントに限定されません。ユーザーが各ループを動かすエージェントとモデルを選択します。

ワークフロー

ステップ1: 機能を理解する

ユーザーが@でマークダウンファイルをタグ付けした場合は、それを機能仕様として読み込みます。そうでない場合は、ユーザーに機能を説明するよう依頼します。

必要に応じて明確化の質問をします:

• これはどのような問題を解決しますか?
• 主なユーザーアクションは何ですか?
• スコープ外は何ですか?
• 完了をどのように判断しますか?

ステップ2: ループを設定する

ループを設定するために、ユーザーに4つの質問をします:

2a. どのAIエージェント?

このリストを提示し、ユーザーに選択させます:

1. claude — Claude Code
2. droid — Factory Droid
3. codex — OpenAI Codex
4. opencode — OpenCode
5. gemini — Gemini CLI
6. copilot — GitHub Copilot
7. cc-compatible — Claude Code互換バイナリ(ユーザーがバイナリ名を提供。例: zai、minimax、kimi)
8. custom — 完全カスタムコマンド(ユーザーが$PROMPT_FILEをプレースホルダーとして含む完全なコマンドテンプレートを提供)

エージェントごとのヘッドレスコマンドテンプレート(ループスクリプト生成時に使用):

# claude — Claude Code
claude -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model $MODEL

# droid — Factory Droid
droid exec --skip-permissions-unsafe -f "$PROMPT_FILE" --output-format text -m $MODEL

# codex — OpenAI Codex
codex exec --yolo -m $MODEL "$(cat "$PROMPT_FILE")"

# opencode — OpenCode
opencode run --yolo -m $MODEL "$(cat "$PROMPT_FILE")"

# gemini — Gemini CLI
gemini -p "$(cat "$PROMPT_FILE")" --yolo -m $MODEL

# copilot — GitHub Copilot
copilot -p "$(cat "$PROMPT_FILE")" --yolo --model $MODEL

# cc-compatible — ユーザーが提供したバイナリ名を使用してClaude Codeと同じ
$BINARY -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model $MODEL

# custom — ユーザーが完全なコマンドテンプレートを提供
# ユーザーのテンプレートはプロンプトファイルパスが入るべき場所に$PROMPT_FILEを含む必要があります

ユーザーがcc-compatibleを選択した場合、バイナリ名を尋ねます(例: zai)。ユーザーがcustomを選択した場合、完全なコマンドテンプレートを尋ね、プロンプトファイルパスが入る場所に$PROMPT_FILEを使用するよう指示します。

2b. どのモデル?

ユーザーにモデル識別子を尋ねます(自由なテキスト入力)。例:

• Claude Code: opus、claude-opus-4-6、sonnet、claude-sonnet-4-5-20250929
• Factory Droid: claude-opus-4-6、o3
• OpenAI Codex: o3、o4-mini
• OpenCode: anthropic/claude-opus-4-6、openai/o3(形式: provider/model)
• Gemini CLI: gemini-2.5-pro、gemini-2.0-flash
• GitHub Copilot: claude-sonnet-4-5、gpt-4o

ユーザーが「default」と言うか空白のままの場合、モデルフラグを完全に省略します(エージェントのビルトインデフォルトを使用)。

2c. ループ名?

機能に基づいて名前をケバブケース(例: add-task-priorities)で提案します。ユーザーはそれを受け入れるか別の名前を提供できます。これがファイル名になります: .ralph/<loop-name>.sh

2d. 自動プッシュとPR作成?

ユーザーに尋ねます: 「ループが終了したときにRalphが自動的にブランチをプッシュしてPRを作成すべきですか?」

• はい — ループが終了したとき(すべてのストーリーが完了するか最大イテレーションに達した時)、スクリプトはoriginにブランチをプッシュし、gh pr createでプルリクエストを作成します。ベースブランチ(例: mainまたはmaster)は生成時にリモートに存在するブランチを確認して自動検出されます。
• いいえ — スクリプトはローカルのみで実行されます。すべてのコミットはローカルに留まります。ユーザーが自分でプッシュしてPRを作成します。

ユーザーが「はい」と言った場合、生成時にベースブランチを検出します:

1. refs/remotes/origin/mainが存在しますか? → mainを使用
2. refs/remotes/origin/masterが存在しますか? → masterを使用
3. どちらもない → デフォルトはmain

解決されたベースブランチを生成されたスクリプトに直接ベークします: DEFAULT_BRANCH="main"(または"master")。

ステップ3: prd.jsonを作成する

プロジェクトルートにprd.jsonファイルを生成します:

{
  "project": "[プロジェクト名]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[機能説明]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[ストーリータイトル]",
      "description": "[ユーザー]として、[機能]が欲しいのは[利点]のためです",
      "acceptanceCriteria": [
        "基準1",
        "基準2",
        "型チェックが通る"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

ステップ4: ループを生成して実行する

1. プロジェクトルートに.ralph/ディレクトリがなければ作成します
2. .gitignoreを確認 — .ralph/、.ralph-archive/、.ralph-last-branchがなければ追加します(.gitignoreがなければ作成)
3. scripts/ralph.sh(このスキルのリファレンステンプレート)を読んでループ構造を理解します
4. リファレンステンプレートの構造を使用して.ralph/<loop-name>.shを生成し、選択したエージェントコマンドをベークインします:
   • ステップ2aから正確なコマンドテンプレートを使用し、ステップ2bのユーザーのモデルを置換します
   • モデルが指定されない場合、コマンドからモデルフラグを省略します
   • PROMPT_FILE="$SCRIPT_DIR/<loop-name>-prompt.md"を設定します(スクリプトと同じ場所)
   • AGENT_BINを選択した実行ファイルに設定します(customの場合、コマンドの実行ファイルトークンを使用)
   • すべての既存ロジックを保持: アーカイブ、ブランチ追跡、進捗初期化、完了検出、イテレーション間の2秒スリープ
   • ユーザーがステップ2dで自動プッシュ+PRを選択した場合: DEFAULT_BRANCHを解決されたベースブランチに設定したfinalize()関数を含め、AUTO_PUSH_PR="true"に設定します。そうでない場合、AUTO_PUSH_PR="false"に設定しfinalize()関数を省略します。
5. scripts/prompt.md(このスキルから) → .ralph/<loop-name>-prompt.mdをコピーします
6. スクリプトを実行可能にします: chmod +x .ralph/<loop-name>.sh
7. ユーザーに伝えます: 実行: .ralph/<loop-name>.sh [max_iterations]

ユーザーストーリーの重要なルール

サイズ: 小さいが実質的

各ストーリーは1つのイテレーションで完了できなければいけません。2〜3文で説明できないなら大きすぎます。しかし各ストーリーは実質的な作業を伴う必要があります。単一の検索と置換または1行の編集なら小さすぎて、関連作業と組み合わせるべきです。

小さすぎる(関連作業と組み合わせる):

• 「1つのファイルでnvidia-smiをrocm-smiに置き換える」→ より広い文書正確性ストーリーに組み合わせる
• 「READMEに1つの不足している環境変数を追加」→ 他の文書ギャップと組み合わせる
• 「設定ファイルのタイプを修正」→ 他の設定改善と組み合わせる
• 開発者が5分以内に完了できるストーリー

サイズが適切:

• データベースカラムとマイグレーションを追加
• 既存ページにUIコンポーネントを追加
• 新しいロジックでサーバーアクションを更新
• リストにフィルタードロップダウンを追加
• 検証バグを修正し、修正のテストを追加し、文書を更新
• 複数ファイル間で重複したヘルパー関数を統合

大きすぎる(分割する):

• 「ダッシュボード全体を構築」→ スキーマ、クエリ、UIコンポーネント、フィルタ
• 「認証を追加」→ スキーマ、ミドルウェア、ログインUI、セッション処理

順序: 依存関係が最優先

1. スキーマ/データベース変更(マイグレーション)
2. サーバーアクション/バックエンドロジック
3. バックエンドを使用するUIコンポーネント
4. ダッシュボード/サマリービュー

承認基準: 検証可能

良い例:

• 「statusカラムをデフォルト'pending'で追加」
• 「フィルタドロップダウンはオプション: All、Active、Completed」
• 「型チェックが通る」

悪い例:

• 「正しく動作」
• 「良いUX」

常に含める:

• すべてのストーリーで"型チェックが通る"
• UIストーリーで"ブラウザで検証"

例

ユーザーが言う: 「use ralph to add task priorities」

ステップ1: 機能説明を読み、明確化の質問をする。

ステップ2: 尋ねる: どのエージェント? → claude。どのモデル? → sonnet。ループ名? → add-task-priorities。自動プッシュ+PR? → yes。

ステップ3: prd.jsonを作成:

{
  "project": "TaskApp",
  "branchName": "ralph/task-priority",
  "description": "タスクに優先度レベル(高/中/低)を追加",
  "userStories": [
    {
      "id": "US-001",
      "title": "データベースに優先度フィールドを追加",
      "description": "開発者として、タスク優先度を保存する必要があります。",
      "acceptanceCriteria": [
        "優先度カラムを追加: 'high' | 'medium' | 'low'(デフォルト 'medium')",
        "マイグレーションが正常に実行される",
        "型チェックが通る"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "タスクカードに優先度バッジを表示",
      "description": "ユーザーとして、優先度を一目で確認したいです。",
      "acceptanceCriteria": [
        "カラー付きバッジ: 赤=高、黄=中、灰色=低",
        "ホバーなしで表示される",
        "型チェックが通る",
        "ブラウザで検証"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    }
  ]
}

ステップ4: .ralph/add-task-priorities.shを生成します(claude -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model sonnetをエージェントコマンドとして、ユーザーが自動プッシュ+PRを選択したためAUTO_PUSH_PR="true"とDEFAULT_BRANCH="main"を設定)。プロンプトを.ralph/add-task-priorities-prompt.mdにコピーし、.ralph/、.ralph-archive/、.ralph-last-branchを.gitignoreに追加します。

prd.jsonが2つのユーザーストーリーで作成されました。自律実行を開始するには.ralph/add-task-priorities.shを実行してください。

Ralphの実行方法

各イテレーションで、新しいヘッドレスエージェントが:

1. prd.jsonとprogress.txtを読む
2. passes: falseの最優先ストーリーを選ぶ
3. それを実装
4. 品質チェックを実行(型チェック、リント、テスト)
5. 通れば提出します(詰まっていれば進捗メモを提出 — プロンプトの「詰まった場合」を参照)
6. prd.jsonを更新してpasses: trueにマークします(またはブロックされた場合はnotesを更新)
7. 学習をprogress.txtに追記
8. 終了

すべてのストーリーが通るか最大イテレーションに達するまでループが続きます。

ユーザーが自動プッシュ+PR(ステップ2d)を選択した場合、ループが終了した後(すべてのストーリーが完了するか最大イテレーションに達した時):

1. ループスクリプトはブランチをoriginにプッシュします
2. gh pr createでralphinブランチからデフォルトブランチにPRを作成します
3. gh CLIが利用できないかPR作成に失敗した場合、ループ実行の成功をマスクするのではなく、手動の指示を出力する代わりに中止します
4. プッシュまたはPR失敗は適切に処理されます — 成功したループ実行をマスクすることはありません

ユーザーがローカルのみを選択した場合、スクリプトはループ後に単純に終了します。すべてのコミットはローカルに留まります。

ファイルリファレンス

ファイル	目的
prd.json	合否状態のユーザーストーリー
progress.txt	将来のイテレーション用の学習を追記
.ralph/<name>.sh	エージェントコマンドをベークインした生成されたループスクリプト
.ralph/<name>-prompt.md	ループ用プロンプトファイル(scripts/prompt.mdのコピー)

デコンポーズモード

トリガー: /ralph decompose <input>またはナチュラルランゲージ「reverse ralph this feature」、 「decompose X into a replication plan」、「break this feature down into user stories」。

何をするか

Reverse Ralphは既存機能の説明を受け取り、それを再帰的かつ完全に分解します — フォワードRalphループが実行可能なアトミック化されたprd.jsonにします。

分解は行動と機能に関してです: 機能が何をして外からどのように動作するかをキャプチャします。内部的にどのように構築されているかではなく。フォワードループはすべての実装決定を処理します。

受け入れられる入力

• URL(2ホップまでリンクされたドキュメントを取得)
• ローカルファイルパス(直接読み込み)
• ナチュラルランゲージ説明
• 上記の任意の組み合わせ

エージェントワークフロー

下記のステップ1〜7についてはscripts/decompose-init-prompt.mdの詳細な指示に従います。

1. 入力を収集。 すべての提供ソースを読みます。URLについては、ページを取得してドキュメントリンクを2ホップまで深く追跡します(同じドキュメンテーションドメインのみ)。収集したすべてのコンテンツを機能サーフェスに統合します: 観察可能なすべての動作、状態、入力、出力、設定オプション、機能の統合の構造化説明。

2. ループ名を尋ねる。 このデコンポーズ実行に何という名前を付けるかをユーザーに尋ねます。生成されたスクリプトファイル名に使用: .ralph/decompose-<n>.sh。

3. どの実行エージェントを使用するか をユーザーに尋ねます。フォワードRalphと同じエージェントマトリックス: claude、droid、codex、opencode、gemini、copilot、 cc-compatible、またはcustom。

4. どのモデル(オプション — ブランクのままでCLIデフォルトを使用)。

5. decomp.jsonをシード。 機能サーフェスから抽出されたトップレベルの機能クラスタを含む初期状態ファイルを生成します。各クラスタはステータスneeds_splitを取得します。

6. scripts/decompose.shから.ralph/decompose-<n>.shを生成 し、__AGENT__、__MODEL__、__LOOP_NAME__を置換します。scripts/decompose-prompt.mdを.ralph/decompose-<n>-prompt.mdにコピーします。

7. ユーザーに指示 します:

   .ralph/decompose-<n>.sh [max_iterations]
   

   デフォルトmax_iterationsは50です。ループはdecomp.jsonのすべてのリーフノードがステータスatomicを持つまで自律実行されます(分割された親ノードはステータスsplitを取得)、その後prd.jsonを出力します。

既知の制限

• コンテキストウィンドウ: 完全なdecomp.jsonは各イテレーションのプロンプトに追記されます。非常に大きな機能分解(数百のノード)の場合、エージェントコンテキスト制限に近づく可能性があります。この場合、max_iterationsを増やしてループを再開できるようにします。

デコンポーズファイルリファレンス

ファイル	目的
scripts/decompose-init-prompt.md	オーケストレーティングエージェント用の初期化プロンプト(ステップ1〜7)
decomp.json	ノードとステータスを持つ分解状態ツリー
prd.json	最終出力 — フォワードRalph互換のフラットストーリーリスト
.ralph/decompose-<n>.sh	生成されたデコンポーズループスクリプト
.ralph/decompose-<n>-prompt.md	デコンポーズループ用プロンプトファイル