ralph-loop

⚠️ WARNING：このスキルは、Python オーケストレータースクリプトを使用する新しいコマンド ralph-loop-v2 に置き換えられ、非推奨になりました。
古い /specs:ralph-loop コマンドはまもなく削除されます。新しいコマンドに移行してください。

Ralph Loop — Python オーケストレーター

⚠️ IMPORTANT：このスキルでは Python オーケストレータースクリプトを使用します。任意の bash コマンドは実行しないでください。Bash は ralph_loop.py の実行にのみ使用してください。すべてのタスクコマンド（/developer-kit-specs:specs.task-implementation など）は、ユーザーが手動で実行できるように表示されます。

概要

Ralph Loop は、仕様駆動開発に Geoffrey Huntley の「Ralph Wiggum as a Software Engineer」手法を適用します。状態機械を管理する Python オーケストレータースクリプトを使用します。1 回の呼び出しで 1 ステップを実行し、状態は fix_plan.json に保存されます。

重要な洞察：実装、レビュー、同期を 1 回の呼び出しで行うと、コンテキストウィンドウが大幅に圧迫されます。解決策は、ループの各反復で 1 つのステップだけを実行し、状態を fix_plan.json に保存して停止することです。次の反復では、保存された状態から再開します。

主な改善点：Python スクリプト ralph_loop.py が、すべての状態管理、タスク選択、コマンド生成を処理します。タスクコマンドを直接実行することはありません。代わりに、CLI で実行する正しいコマンドを表示します。

使用する場面

• ユーザーが定期的な自動化のために /loop コマンドを実行する場合
• ユーザーが「実装を自動化する」または「ループでタスクを実行する」と依頼した場合
• ユーザーが「タスクを順番に反復処理する」または「ワークフローの自動化を実行する」と希望する場合
• 複数の SDD コマンドにわたる「コンテキストウィンドウの管理」が必要な場合
• ユーザーが TASK-N から TASK-M までの「タスク範囲を処理する」と希望する場合
• マルチエージェント対応（タスクごとに異なる CLI を使用）が必要な場合

アーキテクチャ

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ralph_loop.py │────▶│   fix_plan.json │────▶│  User executes  │
│   (orchestrator)│     │   (state file)  │     │  command in CLI │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         │                                               ▼
         │                                      ┌─────────────────┐
         └──────────────────────────────────────│   Task result   │
                                                │   (success/     │
                                                │   failure)      │
                                                └─────────────────┘

1 ステップのフロー：

1. ralph_loop.py --action=loop を実行します
2. スクリプトが fix_plan.json を読み込み、現在のステップを判定します
3. スクリプトが実行するコマンド（例：/developer-kit-specs:specs.task-implementation）を表示します
4. ユーザーが CLI でコマンドを実行します
5. ユーザーが再度 ralph_loop.py --action=loop を実行します
6. スクリプトが結果に基づいて状態を更新し、次のコマンドを表示します

状態機械

fix_plan.json state machine:
┌─────────────────────────────────────────────────────────────┐
│  state: "init"                                            │
│    → --action=start: Initialize fix_plan.json              │
│    → Load tasks from tasks/TASK-*.md files                │
│    → Apply task_range filter                              │
│                                                             │
│  state: "choose_task"                                      │
│    → Pick next pending task (within range, deps satisfied)│
│    → No tasks in range → state: "complete"               │
│    → Task found → state: "implementation"                │
│                                                             │
│  state: "implementation"                                  │
│    → Show /developer-kit-specs:specs.task-implementation command             │
│    → User executes, then runs loop again                  │
│    → Next state: "review"                                │
│                                                             │
│  state: "review"                                          ││    → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│},{find:                    │
│    → User reviews results, then runs loop again          │
│    → Issues found → state: "fix" (retry ≤ 3)             │
│    → Clean → state: "cleanup"                            │
│                                                             │
│  state: "fix"                                             │
│    → Show commands to fix issues                         │
│    → User applies fixes, then runs loop again            │
│    → Next state: "review"                                │
│                                                             │
│  state: "cleanup"                                         │
│    → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│
│    → Next state: "sync"                                  │
│                                                             │
│  state: "sync"                                            │
│    → Show /developer-kit-specs:specs.sync command             │
│    → Next state: "update_done"                           │
│                                                             │
│  state: "update_done"                                     │
│    → Mark task done, commit git changes                  │
│    → Re-evaluate dependencies                            │
│    → state: "choose_task"                                │
│                                                             │
│  state: "complete" | "failed"                            │
│    → Print result, stop                                   │
└─────────────────────────────────────────────────────────────┘

ファイルの配置要件

⚠️ CRITICAL：fix_plan.json ファイルは必ず次の場所に配置してください。

docs/specs/[ID-feature]/_ralph_loop/fix_plan.json

LLM が誤った場所にファイルを作成しないよう、スクリプトによってこの配置が強制されます。

移行：仕様フォルダーのルートに古い fix_plan.json がある場合、初回実行時にスクリプトが自動的に _ralph_loop/ へ移行します。

手順

フェーズ 1：初期化

--action=start を指定して Python スクリプトを実行し、タスクファイルをスキャンして、正しい場所に fix_plan.json を作成します。

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041

フェーズ 2：ループの各ステップを実行

--action=loop を指定してスクリプトを実行し、現在の状態と実行するコマンドを確認します。

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

スクリプトは、現在のステップで実行する正確なコマンドを表示します。CLI で実行した後、再度ループコマンドを実行してください。

フェーズ 3：状態を進める（手動）

表示されたコマンドを実行した後、手動で次のステップに進めます。

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=next \
  --spec=docs/specs/001-feature/

これにより、fix_plan.json が次の状態に更新されます（例：implementation → review）。

フェーズ 4：進捗を確認

--action=status を指定すると、いつでも状態を確認できます。

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

クイックスタート

1. 初期化

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041 \
  --agent=claude

2. ループを実行

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

スクリプトが実行するコマンドを表示します。コマンドを実行した後、再度ループを実行してください。

3. 状態を確認

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

引数

引数	説明
--action	start（初期化）、loop（1 ステップ実行）、status、resume、next（ステップを進める）
--spec	仕様フォルダーのパス（例：docs/specs/001-feature/）
--from-task	タスク範囲の開始（例：TASK-036）
--to-task	タスク範囲の終了（例：TASK-041）
--agent	デフォルトのエージェント：claude、codex、copilot、kimi、gemini、glm4、minimax
--no-commit	Git コミットをスキップします（テスト用）

ステップの詳細

ステップ 1：初期化（--action=start）

スクリプトは次の処理を行います。

1. 仕様フォルダー内の tasks/TASK-*.md ファイルをスキャンします
2. YAML フロントマターからメタデータ（id、title、status、lang、dependencies、agent）を抽出します
3. --from-task と --to-task のフィルターを適用します
4. 完全な状態を含む fix_plan.json を作成します

ステップ 2：タスクの選択（choose_task）

スクリプトは次の処理を行います。

1. 範囲内の保留中のタスクを検索します
2. 依存関係が満たされていることを確認します
3. 次のタスクを選択します
4. fix_plan.json の current_task を更新します
5. 実行するコマンドを表示します

ステップ 3：実装（implementation）

スクリプトは次を表示します。

→ Implementation: TASK-037

Execute:
  /developer-kit-specs:specs.task-implementation --task=TASK-037

After execution, update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

ステップ 4：レビュー（review）

スクリプトは次を表示します。

→ Review: TASK-037 | Retry: 0/3

Execute:
  /developer-kit-specs:specs.task-review --task=TASK-037

Review the generated review report, then update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

ステップ 5：修正（fix） - レビューに失敗した場合

問題が見つかった場合、スクリプトは修正手順を表示します。修正後、ユーザーはループを再度実行します。

ステップ 6：クリーンアップ（cleanup）

スクリプトは次を表示します。

→ Cleanup: TASK-037

Execute:
  /developer-kit-specs:specs.task-implementation --task=TASK-037 --action=cleanup

ステップ 7：同期（sync）

スクリプトは次を表示します。

→ Sync: TASK-037

Execute:
  /developer-kit-specs:specs.sync docs/specs/001-feature/ --after-task=TASK-037

ステップ 8：完了状態の更新（update_done）

スクリプトは次の処理を行います。

1. fix_plan.json でタスクを完了済みとしてマークします
2. Git の変更をコミットします（--no-commit が指定されていない場合）
3. イテレーション数を更新します
4. choose_task に戻ります

マルチエージェントのサポート

すべてのタスクに対するデフォルトエージェント

python3 ralph_loop.py --action=start --spec=... --agent=codex

タスクごとのエージェント

タスクファイルの YAML フロントマターでエージェントを指定します。

---
id: TASK-036
title: Refactor user service
status: pending
lang: java
agent: codex
---

対応エージェント：claude、codex、copilot、kimi、gemini、glm4、minimax

/loop との併用（Claude Code）

5 分ごとに自動スケジュールするには：

/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

これによりループが繰り返し実行され、そのたびに次のコマンドが表示されます。

注：Ralph Loop は現在、Python スクリプトから直接管理されます。非推奨の /developer-kit-specs:specs.ralph-loop コマンドは削除されました。

タスクファイルの形式

各タスクは個別のファイルにしてください：tasks/TASK-XXX.md

---
id: TASK-036
title: Implement user authentication
status: pending
lang: java
dependencies: []
complexity: medium
agent: claude
---

## Description

Implement JWT-based authentication for the API.

## Acceptance Criteria

- [ ] Login endpoint returns JWT token
- [ ] Token validation middleware
- [ ] Refresh token mechanism

例

例 1：基本的な使い方

# Initialize
python3 ralph_loop.py --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-001 \
  --to-task=TASK-005

# Loop until complete
while true; do
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/
  # Execute the shown command manually
  # Then continue loop
done

例 2：Claude Code /loop を使用する場合

# Start with specific range
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/002-tdd-command \
  --from-task=TASK-001 \
  --to-task=TASK-010

例 3：マルチエージェントの設定

# Initialize with Claude as default
python3 ralph_loop.py --action=start \
  --spec=docs/specs/001-feature/ \
  --agent=claude

# Some tasks have "agent: codex" in their frontmatter
# Those will show Codex-formatted commands

ベストプラクティス

• 1 回の呼び出しにつき 1 ステップ：ステップを正確に 1 つ実行し、状態を保存して終了します
• 状態を信頼する：fix_plan.json から読み込み、fix_plan.json に書き込みます
• コンテキストを蓄積しない：状態はコンテキストではなくファイルに保存されます
• コマンドは手動で実行する：スクリプトがコマンドを表示するので、CLI で実行します
• レビュー失敗時は再試行する：失敗とする前に最大 3 回再試行します
• 範囲でフィルターする：常に task_range でフィルターします
• 依存関係を先に解決する：すべての依存関係が完了しているタスクのみを選択します
• Git コミット：スクリプトはタスクが完了するたびに自動コミットします

制約と警告

• コンテキストの肥大化：1 回の呼び出しで実装、レビュー、同期をすべて行わないでください。コンテキストがあふれます
• 再試行の上限：レビューに失敗した場合、最大 3 回再試行してから失敗とします
• Git の状態：開始前に Git の状態がクリーンであることを確認してください
• テスト基盤：ループではテストの合格が必要です。テストがないと、バックプレッシャーは効果を発揮しません
• 厳密な状態検証：有効な state.step の値は次のもののみです：init、choose_task、implementation、review、fix、cleanup、sync、update_done、complete、failed
• コマンドの自動実行はありません：スクリプトはコマンドを表示しますが、実行はしません。CLI で実行する必要があります

トラブルシューティング

「fix_plan.json が見つかりません」

まず --action=start を実行してください。

python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/

スクリプトは正しい場所に fix_plan.json を作成します。

docs/specs/001-feature/_ralph_loop/fix_plan.json

「fix_plan.json の場所が正しくありません」

ファイルの場所が正しくないという警告が表示された場合、スクリプトが移行手順を案内します。

# Manual migration if needed
mkdir -p docs/specs/001-feature/_ralph_loop
mv docs/specs/001-feature/fix_plan.json docs/specs/001-feature/_ralph_loop/fix_plan.json

スクリプトは初回実行時に、古いファイルを自動的に移行します。

「仕様フォルダーが無効です」

まず --action=start を実行してください。

python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/

タスクファイルが見つからない

タスクが YAML フロントマターを含む tasks/TASK-XXX.md 形式になっていることを確認してください。

エージェントのコマンドが正しくない

--agent パラメーター、またはタスクのフロントマターにある agent: フィールドを確認してください。

参考資料

• references/state-machine.md - ステートマシンの完全なドキュメント
• references/multi-cli-integration.md - マルチ CLI の設定ガイド
• references/loop-prompt-template.md - シェルループ用のプロンプトテンプレート