⚠️ 警告: このスキルは、Pythonオーケストレータースクリプトを使用する新しいコマンド ralph-loop-v2 に廃止されました。 古い /specs:ralph-loop コマンドはまもなく削除されます。新しいコマンドへの移行をお願いします。

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

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

概要

Ralph Loop は Geoffrey Huntley の「Software Engineer としての Ralph Wiggum」テクニックを仕様駆動開発に適用します。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: "init"                                            │
│    → --action=start: fix_plan.json を初期化              │
│    → tasks/TASK-*.md ファイルからタスクをロード          │
│    → task_range フィルターを適用                         │
│                                                             │
│  state: "choose_task"                                      │
│    → 次の保留中タスクを選択 (範囲内、依存関係を満たす)  │
│    → 範囲内にタスクなし → state: "complete"            │
│    → タスク見つかった → state: "implementation"          │
│                                                             │
│  state: "implementation"                                  │
│    → /developer-kit-specs:specs.task-implementation コマンドを表示       │
│    → ユーザーが実行してからループを再度実行             │
│    → 次のステート: "review"                             │
│                                                             │
│  state: "review"                                          │
│    → /developer-kit-specs:specs.task-review コマンドを表示              │
│    → ユーザーが結果をレビューしてからループを再度実行  │
│    → 問題が見つかった → state: "fix" (リトライ ≤ 3)   │
│    → クリーン → state: "cleanup"                        │
│                                                             │
│  state: "fix"                                             │
│    → 問題を修正するコマンドを表示                        │
│    → ユーザーが修正を適用してからループを再度実行      │
│    → 次のステート: "review"                             │
│                                                             │
│  state: "cleanup"                                         │
│    → /developer-kit-specs:specs-code-cleanup コマンドを表示  │
│    → 次のステート: "sync"                               │
│                                                             │
│  state: "sync"                                            │
│    → /developer-kit-specs:specs.spec-sync-with-code コマンドを表示      │
│    → 次のステート: "update_done"                        │
│                                                             │
│  state: "update_done"                                     │
│    → タスクを完了としてマーク、git 変更をコミット      │
│    → 依存関係を再評価                                    │
│    → state: "choose_task"                                │
│                                                             │
│  state: "complete" | "failed"                            │
│    → 結果を出力、停止                                    │
└─────────────────────────────────────────────────────────────┘

ファイルロケーション要件

⚠️ 重要: 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. current_task で fix_plan.json を更新
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-code-cleanup --task=TASK-037

ステップ 7: 同期 (sync)

スクリプトが表示:

→ Sync: TASK-037

Execute:
  /developer-kit-specs:specs.spec-sync-with-code 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: 基本的な使用方法

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

# 完了するまでループ
while true; do
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/
  # 表示されたコマンドを手動で実行
  # その後ループを継続
done

例 2: Claude Code /loop での使用

# 特定の範囲で開始
/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: マルチエージェント設定

# Claude をデフォルトで初期化
python3 ralph_loop.py --action=start \
  --spec=docs/specs/001-feature/ \
  --agent=claude

# 一部のタスクは frontmatter に "agent: codex" を持つ
# これらは Codex 形式のコマンドを表示します

ベストプラクティス

• 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 が間違ったロケーションにあります"

ファイルが間違ったロケーションにあるというコメントが表示される場合、スクリプトがマイグレーションをガイドします:

# 必要に応じて手動マイグレーション
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/

タスクファイルが見つかりません

tasks/TASK-XXX.md 形式の YAML frontmatter を持つタスクを確認してください。

エージェントコマンドが間違っています

--agent パラメーターまたはタスク agent: frontmatter フィールドを確認してください。

参考資料

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