setup-ralph-loop

Ralph Loop のセットアップ

Ralph を安全に実行するために必要なローカルスクリプトとリポジトリ規約を作成します。

呼び出すタイミング

これはインフラストラクチャスキルであり、通常の機能提供ステージではありません。

プロジェクトで /execute を再現可能な HITL から AFK へのループで実行したい場合に、/setup-ralph-loop を使用します。

自動呼び出し： /execute は、複数のスライスにまたがる GitHub issue の作業（PRD、大規模バッチの作業量、または複数のユーザーストーリー）を検出し、リポジトリのルートに ralph-once.sh も ralph.sh も存在しない場合、このスキルを自動的に呼び出します。つまり、ユーザーが明示的に呼び出さなくても、このスキルに進むことがあります。検出と呼び出しは、/execute 内の前提ステップとして実行されます。

デフォルトの機能パイプラインの一部として使用しないでください。後続の /execute 実行が、反復回数を制限し、明示的なフィードバックループと GitHub に裏付けられた永続的な状態のもとで Ralph を実行できるよう、リポジトリを準備します。

ここでセットアップするもの

• ralph-once.sh：1 回のイテレーションを実行する HITL Ralph 用
• ralph.sh：反復回数を制限した AFK Ralph の実行用
• package.json スクリプト（任意）：呼び出しを簡単にするため
• リポジトリ内のループプロンプト：Ralph に、ブロックされていない最もリスクの高いスライスを優先し、フィードバックループを実行し、作業が完了したら停止するよう指示するもの

セットアップ前のルール

• Ralph は /execute の実行モードであり、別個のワークフローではありません。
• まず HITL Ralph から始めます。プロンプト、フィードバックループ、品質基準が適切に機能してから、AFK に移行してください。
• このワークフローにおける Ralph の永続的な進捗状態は、GitHub issue、issue コメント、コミットに保存します。progress.txt やその他のローカルタスク状態ファイルには保存しません。
• 各イテレーションで実装するのは、レビュー可能なスライス 1 つだけにしてください。
• AFK ループには必ず上限を設けてください。無限ループを生成しないでください。

手順

1. タスクのソースと状態モデルを確認する

Ralph がどこから作業を読み取るべきかを尋ねます。

次の順序を優先します。

1. 依存関係が設定された GitHub issue
2. リポジトリで実際に使用している、別の永続的なバックログシステム
3. ユーザーが明示的に希望する場合に限り、一時的な代替ファイル

リポジトリで GitHub issue を使用している場合は、Ralph も GitHub を中心に運用します。

• オープンな PRD issue で最終状態を定義します
• スライス issue で現在の作業キューを定義します
• issue コメントに正確なエラーや途中までの進捗に関する情報を記録します
• コミットを実行ログとして使用します

ユーザーがリポジトリの GitHub 優先モデルから逸脱することを明示的に選ばない限り、永続的な状態として progress.txt を導入しないでください。

2. フィードバックループを確認する

スクリプトを生成する前に、対象リポジトリを調査します。

package.json または同等のツールに、利用可能なコマンドがあるか確認します。

• typecheck
• test
• lint
• build

また、リポジトリに以下がすでにあるか確認します。

• /setup-pre-commit
• コンテナまたはサンドボックスのツール
• 設定済みの GitHub CLI

生成する Ralph プロンプトには、実際に存在するフィードバックループだけを記載してください。

3. 実行環境を確認する

Ralph をどの環境で実行するかを尋ねます。

• 現在のリポジトリのシェル
• サンドボックス化されたシェルまたはコンテナ
• pnpm などの既存のタスクランナー経由

推奨されるデフォルト設定：

• まず現在のリポジトリで HITL を実行
• 可能な場合は、サンドボックス化または隔離された環境で AFK を実行

4. ralph-once.sh を生成する

まずは監督付きで使うための、1 回限りのスクリプトを作成します。

スクリプトでは、次のことを行います。

• Ralph をちょうど 1 回実行する
• Ralph にタスクソースを指定する
• スクリプト内でブロックされていない候補を計算し、その中から最もリスクの高いスライスを選ぶよう Ralph に指示する
• /execute を使うよう Ralph に指示する
• リポジトリの実際のフィードバックループを実行するよう Ralph に指示する
• レビュー可能なスライスを 1 つ完了したら停止するよう Ralph に指示する

推奨される形式：

#!/bin/bash
set -e

# Compute the frontier in bash rather than asking the model to reconstruct it
# by reading `Blocked by` prose out of N issue bodies. Native GitHub issue
# dependencies (wired by /prd-to-issues §7) make this a lookup; filtering to
# OPEN blockers keeps it current with no bookkeeping.
#
# `gh issue list` excludes pull requests by definition, so no filter is
# needed. `state` is the GraphQL enum: uppercase OPEN, not REST's lowercase.
FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
  --jq '[.[]
        | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
        | .number] | join(", ")')

if [ -z "$FRONTIER" ]; then
  echo "No unblocked issues — either all work is done, or the graph has a cycle."
  exit 0
fi

claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

実際のタスクソースと利用可能なコマンドに合わせて、プロンプトを調整してください。

この形式の要点は、「ブロック関係を考慮する」という指示ではなく、計算済みの候補セットをモデルに渡すことです。モデルがまず文章から再構築しなければならないグラフを尊重するよう指示しても、それを裏付ける仕組みはありません。失敗すると、エラーではなく、もっともらしく見える間違ったスライスが選ばれます。AFK は誰も見ていない段階なので、こうした失敗を最も受け止めにくい段階です。決定的な選択は bash に任せ、モデルが実際に得意とする判断（この候補のうちどれが最もリスクが高いか）はプロンプトに任せます。

リポジトリのスライスに関する issue がネイティブな依存関係の設定より前に作成された場合、$FRONTIER にはすべてが含まれます。信用する前に確認してください。オープンな issue のすべてで .blockedBy.totalCount == 0 と報告されている一方、本文に Blocked by #N の行がある場合、エッジは一度も書き込まれていません。まずエッジを設定してください。手順は /prd-to-issues §7 を参照してください。そうしないと、ループは再び推測に頼ることになります。誰も間違ったスライスが選ばれるのを見ていないため、AFK はこうした問題を最も受け止めにくい段階です。

5. ralph.sh を生成する

上限のある AFK ループを作成します。

スクリプトでは、次のことを行う必要があります。

• イテレーション回数の引数を必須にする
• 引数が指定されていない場合は、すぐに失敗する
• ループごとに 1 回のイテレーションを実行する
• while true を使わない
• ralph-once.sh と同じタスク選択ロジックを維持する

推奨される形式：

#!/bin/bash
set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

for ((iteration=1; iteration<=$1; iteration++)); do
  # Recompute each iteration — closing a blocker un-gates its dependents,
  # so the frontier grows as the loop makes progress.
  FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
    --jq '[.[]
          | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
          | .number] | join(", ")')

  if [ -z "$FRONTIER" ]; then
    echo "No unblocked issues — stopping after $((iteration - 1)) iteration(s)."
    break
  fi

  claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

  echo "Ralph iteration $iteration complete."
done

ループ内でフロンティアを再計算することで、イテレーションをまたいでグラフが機能します。イテレーション 1 ではブロックされていたスライスも、ブロッカーがクローズした時点で、issue 本文を編集することなく着手可能になります。

ユーザーが希望する場合は、たとえば次のような便利なスクリプトを package.json に追加しても構いません。

{
  "scripts": {
    "ralph:once": "./ralph-once.sh",
    "ralph": "./ralph.sh 5"
  }
}

package スクリプトを追加する場合は、デフォルトのイテレーション回数を少なめにしてください。

6. 品質基準を明示する

生成されるループのプロンプトに、リポジトリの品質要件が明確に記載されていることを確認してください。

プロンプトでは、Ralph に次のことを求めてください。

• 一度に 1 つずつ、レビュー可能なスライスを実装する
• 各イテレーションでフィードバックループを実行する
• スコープを黙って変更しない
• ブロックが解除されたら、早い段階でリスクの高いスライスを優先する
• ブロックされた場合は、エラーの正確な出力を issue コメントに残す
• 失敗が繰り返されたら、無限に再試行せず停止してエスカレーションする
• 失敗の繰り返しだけでなく、進捗が繰り返しない場合（停滞）も停止してエスカレーションする。進捗がないとは、同じスライスに対する 2 回連続のイテレーションで、未達の受け入れ基準、失敗しているチェック、未解決の不明点のいずれも解決済みに移行しなかったことを指します。回復したイテレーションが 1 回あれば、カウンターをリセットします。完全なルールについては、/execute の「AFK progress and plateau detection」と、このスキルに同梱されている references/SYSTEM-OVERVIEW.md を参照してください。
• 実装後、/pre-merge の loop-mode でレビューを実行する。AFK のイテレーションが完了するのは、コードがコミットされた時点ではなく、すべてのレビュー指摘事項が PR の処置記録に記載された時点である
• 指摘事項を記録し、対応はしない。loop-mode ではコミットも決着も行いません。修正、起票、受け入れ、取り下げはオペレーターが朝に処置記録を見て判断します
• 「レビューで問題がなかった」ことを停止理由にしない。クリーンなレビューで終了するループは、より良いコードではなく、クリーンなレビューを生み出します

まだ ralph.sh にレビュー段階を追加しないでください。 loop-mode は /execute の Step 6 における AFK 終了処理から開始されます。それで十分に機能を検証できます。実装後の段階としてスクリプトに明示的に組み込むのは、まずループを HITL で実行してからにしてください。これは Ralph 自身にも適用される「AFK の前に HITL」というルールと同じです（以下の Step 8）。

リポジトリが明らかに長期間運用されている本番コードである場合は、プロンプトにその旨を明記してください。

7. 生成されたセットアップを検証する

確認項目：

• ralph-once.sh が存在し、実行可能であること
• ralph.sh が存在し、実行可能であること
• 要求されている場合、package.json のスクリプトが正しく追加されていること
• 生成されたプロンプトが実際のタスクソースを参照していること
• 生成されたプロンプトが実際に存在するフィードバックループのみを参照していること
• ユーザーから明示的に求められていない限り、progress.txt が導入されていないこと

完了時： セットアップが完了したことを強制適用フックに知らせるため、Ralph マーカーを作成します。

mkdir -p "$CLAUDE_PROJECT_DIR/.claude" && touch "$CLAUDE_PROJECT_DIR/.claude/.ralph-checked"

8. 最初の使用方法を案内する

ユーザーに次の手順を案内します。

1. 最初に ./ralph-once.sh を実行する
2. 結果を確認する
3. タスクの選択や品質に問題がある場合は、プロンプトを調整する
4. その後に限り、./ralph.sh 5 のように回数を制限して AFK Ralph を実行する

検証

セットアップの完了と見なす前に、次の項目を確認します。

• Ralph に HITL のエントリーポイントがある
• Ralph に回数を制限した AFK のエントリーポイントがある
• AFK ループが無限に実行されない
• タスクの選択が単なるリスト順ではなく、リスクを優先している
• プロンプトで /execute を使用している
• プロンプトでリポジトリに実在するフィードバックループを指定している
• ユーザーが明示的に別の方法を選択していない限り、永続状態が GitHub ネイティブのままである

引き継ぎ

• 想定される入力： /execute を中心に Ralph を繰り返し実行したいリポジトリ
• 生成物： 動作する Ralph ループスクリプトと、HITL を優先した回数制限付き AFK 実行のためのリポジトリローカルな規約
• 後続の作業をサポート： /execute、/pre-merge、GitHub Issue ベースの実行をサポートし、AFK 作業の安全性と再現性を高めます
• 次のステップ： 通常の機能開発に戻ります。まず ralph-once.sh を試し、セットアップの信頼性が確認できたら、回数を制限した AFK Ralph を使用します