ralph-loop-workflow

Ralph Loop ワークフロー

コーディングエージェントを自律的なループで実行し、幅広いプロンプトをタスクに分割して、各タスクの構築、テスト、リリースを行います。

前提条件

まず、次のセットアップ手順を完了してください。

• AI コーディングエージェントの設定
• コードの健全性、リンティング、フォーマット
• テスト

ループ

Ralph は、人間の介入なしにエージェントが動作できる時間を最大化します。目標はファイル形式ではありません。エージェントが自力で計画、構築、検証を続けられる状態にすることです。意図を記録する永続的な情報は、エージェントが生成する成果物、つまりテスト（実行可能な受け入れ基準）、ユーザー向けドキュメント、公開ライブラリの変更履歴に残ります。

input prompt
  -> preflight check (CLIs installed, linked, authenticated)
  -> agent harness managed todo list (first-principles task breakdown)
  -> code + user-facing docs + changelog + tests
  -> verification (typecheck, fmt, fallow, browser, tests, deploy, prod check)
  -> iterate

エージェントには、幅広く成果に焦点を当てたプロンプトを渡し、独自のハーネスで ToDo リストを管理させます。作成や完了確認が必要なユーザーストーリーのファイルは別途ありません。

プロンプトが指定されていない場合は、停止してユーザーに次のように尋ねてください。「Ralph ループでどのような成果を目指しますか？幅広く、成果に焦点を当てたプロンプトをお知らせください。タスクに分割します。」続行する前に、回答を待ってください。

プリフライトチェックを一度実行します。不足しているもの、または認証されていないものがあれば、修正コマンドを正確に報告して停止してください。すべてが問題ない状態になるまで、ループは開始しません。その後、各イテレーションで次の作業を行います。

1. コードベースの現在の状態と、これまでの進捗を確認します。
2. 第一原理思考で、残りの作業をタスクに分割します。
3. 最も優先度の高いタスクを選びます。
4. 開発ワークフローに沿って実装します。テストの作成、ビルド、必要に応じた DB スキーマの生成とマイグレーション、フォーマットを行います。
5. 検証します。http://localhost:3000 で型チェック、ビルド、テスト、ブラウザー操作を行います。
6. 検証に合格するまで、デバッグと修正を行います。
7. 公開する成果物があれば、ユーザー向けドキュメントと変更履歴を更新します。
8. 内容が分かるコミットメッセージでコミットし、次のタスクに進みます。

開発サーバーは起動したままにしてください（bun run dev）。エージェントはテスト用データベースを使用するため、自由にマイグレーションできます。タスクがなくなり、すべての検証に合格するとループは終了します。

エージェントに必要なもの

Ralph 専用にインストールするものはありません。ループを実行するには、次の3つが整っている必要があります。

• コンテキスト — AGENTS.md、設定済みの MCP サーバー、インストール済みのスキルを通じて、このコードベースでの作業方法（パターン、開発ワークフロー、規約）を把握します。
• ツール — プロジェクトの MCP サーバーと CLI を通じて、リソースのプロビジョニング、マイグレーションの実行、ログの取得、デプロイの確認を行います。エージェントにも、あなたが使用するものと同じツールを与えてください。
• 検証 — 自律的な作業を長く続けるための要素です。エージェントはローカル環境と本番環境で、自分の作業を確認する必要があります。
  • コードの健全性 — bun run typecheck、bun run fmt、bun run fallow
  • テスト — 分離されたデータベースブランチに対する bun run test（Playwright、統合テスト、単体テスト）
  • ブラウザー — agent-browser で、実行中のアプリをユーザーのように操作します
  • ログとデプロイ — デプロイとランタイムのログを取得し、変更がリリースされ、本番環境で動作していることを確認します

検証の信頼性が高く、自分で実行できる状態であれば、エージェントは人間が介入しなくても、自ら回帰を検出して修正できます。

事前チェック

最初のイテレーションの途中で認証情報が不足していることに気付くのではなく、開始前にエージェントに必要なものがすべて揃っていることを確認します。固定のリストを想定せず、コードベースから使用中のインフラを推測して、各ツールをチェックします。

1. 使用中のインフラを特定します。 MCP 設定（.cursor/mcp.json）、better-env の configSchema 宣言、package.json のスクリプトを確認します。設定済みのサービスごとに、CLI またはトークンが必要です。Neon（DATABASE_URL）、Vercel、Resend、Sentry、GitHub、Better Auth などが該当します。
2. 各ツールのインストール、連携、認証を、変更を加えないコマンドで確認します。
3. チェックリストを報告し、赤になった項目ごとに修正コマンドを提示します。

チェック例（コードベースで使用しているものだけを実行します）：

agent-browser -v                                      # browser automation
vercel --version && vercel whoami && vercel project ls # installed + linked + auth
neonctl me                                            # Neon CLI authenticated
sentry-cli info                                       # token present and valid
gh auth status                                        # GitHub CLI for PRs, logs
bun run env:validate                                  # env vars match the schema

赤になった項目があれば停止します：

Preflight check
  [ok]   agent-browser            v1.4.2
  [ok]   vercel                   linked to acme/app, logged in as andre
  [fail] neon                     not authenticated
  [fail] DATABASE_URL             not set in .env.local
  [ok]   gh                       authenticated

2 issues block the loop. Run these, then re-run /ralph:

  neonctl auth                      # opens browser for OAuth
  bun run env:pull                  # pull DATABASE_URL from Vercel

インタラクティブな OAuth（Vercel、Neon、GitHub）の場合は、ユーザー自身が実行できる正確なコマンドを提示します。ユーザーに代わってブラウザーでログインしようとしてはいけません。環境変数の取得やトークンの設定など、インタラクティブでなくても修正できるものは、実行することを申し出ます。すべての項目が緑になってからループを開始します。

ループの進め方

プロンプトは広く、成果に焦点を当てたものにし、作業をエージェントに分解させます。手順を細かく指示するのではなく、入力を明確にして方向性を示します。

• より明確なプロンプト — 手順ではなく、成果と制約を伝えます。
• より強力なテスト — 失敗するテストは、作業がまだ残っていることを示す最も信頼できるサインです。
• より優れたツール — エージェントが何度も行き詰まる場合、指示ではなく、ツール（MCP サーバー、CLI、ログへのアクセス）が不足していることがほとんどです。

背景と参考資料

• Ralph - Geoffrey Huntley - 独自のコンセプトと実装
• 長時間稼働するエージェントのための効果的なハーネス - Anthropic - エージェントループのエンジニアリングパターン
• Ralph についての Matt Pocock - 動画による解説