autonomous-loop

自律ループ

概要

自律ループは、Ralph の反復型開発手法を実装します。各イテレーションでは同一のコンテキスト（PROMPT + AGENTS ファイル）を読み込み、焦点を絞ったタスクを 1 つ実行し、構造化されたステータスを報告して、次のイテレーションに向けて状態をディスクに保存します。二重条件の終了ゲートが満たされるまで、ループは続行されます。中核となる革新は、決定論的な条件により、Claude がループ内で人間の介入を受けずに、自律的に計画、構築、反復を行って品質を高められることです。

開始時に通知: 「自律ループを開始します。コンテキストを読み込み、PLANNING モードを開始します。」

トリガー条件

• /ralph または /loop コマンドが実行された
• プロジェクトに仕様書があり、自律的な反復開発を開始できる状態である
• 自律的な反復が有効な複数タスクの実装である
• ユーザーがタスクごとの承認なしでの自律実行を求めている

---

アーキテクチャ

+--------------------------------------------------+
|                 AUTONOMOUS LOOP                    |
|                                                    |
|  +----------+    +----------+    +-----------+    |
|  | PLANNING |---→| BUILDING |---→|  STATUS   |    |
|  |   MODE   |    |   MODE   |    |  CHECK    |    |
|  +----------+    +----------+    +-----+-----+    |
|       ^                               |           |
|       |            +-----------+      |           |
|       +------------|  EXIT GATE|←-----+           |
|                    |  (dual)   |                   |
|                    +-----+-----+                   |
|                          |                         |
|                    PASS: EXIT                      |
|                    FAIL: LOOP                      |
+--------------------------------------------------+

---

フェーズ 1：PLANNING モード（ギャップ分析）

目標： 仕様書と実装を分析し、残作業を特定して優先順位を付けます。

計画モードでは実装コードを一切生成しません。分析と計画のみを行います。

手順

1. 知識の収集 — Agent ツールを使って（subagent_type="Explore" および model="sonnet" を指定）、仕様書、既存の実装計画、ユーティリティライブラリを調査する並列サブエージェントを最大 250 個起動します
2. コード分析 — Agent ツールを使って（subagent_type="Explore" を指定）、src/* と specs/* を調査し、仕様と実装のギャップを特定する並列サブエージェントを最大 500 個起動します
3. 統合 — Agent ツールを使って（model="opus" を指定）、調査結果を統合し、未完了の作業に優先順位を付ける統合サブエージェントを起動します
4. 計画の更新 — IMPLEMENTATION_PLAN.md を、整理され優先順位が付けられた箇条書きリストとして更新します

計画モードの制約

制約	理由
すべての前提をコード検索で検証する	存在しないと決めつけない
src/lib を信頼できる標準ライブラリとして扱う	重複させず、統合する
出力は優先順位付きのタスクリスト	コードでも設計でもなく、タスクのみ
不足している仕様書を特定する	仕様書の不足は推測で補うものではなく、ブロッカーである

計画モードの出力

IMPLEMENTATION_PLAN.md updated:
- [x] Completed tasks (checked off)
- [ ] Remaining task 1 (highest priority)
- [ ] Remaining task 2
- [ ] Remaining task 3
...
Missing specs identified: [list or "none"]

停止 — 次の条件を満たすまでフェーズ 2 に進まないでください：

• すべての仕様書を読み、分析した
• コードを仕様書と照合した
• IMPLEMENTATION_PLAN.md を優先順位付きタスクで更新した
• 不足している仕様書を特定した（該当する場合）

---

フェーズ 2：BUILDING モード（実装）

目標： 各イテレーションでタスクをちょうど 1 つ選択して完了します。

「1 ループにつき 1 タスク」の原則

各イテレーションでは、IMPLEMENTATION_PLAN.md からタスクをちょうど 1 つ選択して完了します。これによりコンテキストの切り替えが減り、進捗を明確に測定でき、デバッグも容易になります。

手順

1. 調査 — 仕様書と現在の IMPLEMENTATION_PLAN.md を読む
2. 選択 — 残っているタスクの中から最も重要なものを選ぶ
3. 検索 — 既存のコードパターンを探す（実装が存在しないと決めつけない）
4. 実装 — 本番品質の完全なコードを書く（プレースホルダーやスタブは使用しない）
5. テスト — 実装の直後にテストを実行する
6. 更新 — 調査結果と進捗を反映して IMPLEMENTATION_PLAN.md を更新する
7. コミット — 理由を含めた、内容が明確な Conventional Commit メッセージを作成する

タスク選択の判断表

条件	選択するタスク
他のタスクのブロッカーがある	ブロッカーのタスクを選択する
テストが失敗している	失敗を修正するタスクを選択する
すべてのタスクが独立している	優先順位が最も高いタスクを選択する
同じ優先順位のタスクが複数ある	仕様が最も明確なタスクを選択する
最優先タスクの仕様書がない	PLANNING モードを実行して不足を特定する

ビルド中のサブエージェントルール

リソース	上限	理由
読み取り／検索サブエージェント	Sonnet を最大 500 並列	コンテキストをすばやく収集
ビルドサブエージェント	一度に Sonnet を 1 つだけ	ビルドを順番に実行し、失敗を検出
メインコンテキスト	使用率 40～60%	「思考に適した領域」 — 十分に考える余裕を確保

ビルドモードの制約

制約	理由
プレースホルダーやスタブを作らない	すべてのコード行を本番品質にする
実装前に検索する	コードが別の場所にすでに存在する可能性がある
すぐにテストを実行する	フィードバックによりエラーを早期に検出
タスクごとに計画を更新する	計画を実状に合わせて保つ
タスクごとにコミットする	小さなアトミックコミットにして、簡単に元に戻せるようにする

STOP — Phase 3 に進む前に、以下を完了してください：

• タスクが完全に実装されている（スタブがない）
• テストが実行されている
• IMPLEMENTATION_PLAN.md が更新されている
• 変更がコミットされている

---

Phase 3: ステータス確認

目標： RALPH_STATUS ブロックを生成し、終了条件を評価します。

各 BUILD イテレーションの後、ralph-status スキルを呼び出して、構造化されたステータスブロックを生成します。

終了評価

確認項目	条件	結果
残りタスクがあるか？	IMPLEMENTATION_PLAN.md に未チェック項目がある	ループを続ける
テストに合格しているか？	テストスイート全体に合格している	終了に必須
イテレーション中にエラーがあったか？	未解決の例外がなく、正常に実行された	終了に必須
意味のある作業が残っているか？	TODO や未完成の機能がない	終了に必須

ループの判断

ステータス	残りタスク	テスト	アクション
IN_PROGRESS	あり	任意	Phase 1 または 2 に戻る
IN_PROGRESS	なし	FAILING	ループ — まず失敗を修正する
BLOCKED	任意	任意	ブロッカーを報告して、入力を待つ
COMPLETE	なし	PASSING	終了ゲートを評価する

---

終了条件 — 二重条件ゲート

ループを終了するには、両方の条件が同時に真でなければなりません：

条件	しきい値	検証
完了を示す表現	「done」を示す表現が直近に 2 回以上ある	出力をヒューリスティックに検出
明示的な EXIT_SIGNAL	ステータスブロックに EXIT_SIGNAL: true がある	意図的な宣言

EXIT_SIGNAL を true にできるのは、以下のすべてを満たす場合のみです：

• IMPLEMENTATION_PLAN.md に残りのタスクがない
• すべてのテストに合格している
• 最新のイテレーションでエラーがない
• 意味のある作業が残っていない

これにより、作業を継続しているのに完了を示す表現が出た場合の誤検知を防ぎます。

終了判断表

完了を示す表現	EXIT_SIGNAL	アクション
2 回未満	false	ループを続ける
2 回以上	false	続行 — 気軽な表現の可能性がある
2 回未満	true	続行 — 根拠のないシグナル
2 回以上	true	ループを終了する

---

コンテキスト効率

リソース	上限	戦略
メインコンテキスト	ウィンドウの 40～60%	集中を維持し、負荷の高い作業を委任する
読み取りサブエージェント	最大 500 並列	検索、ファイル読み取り、パターンマッチング
ビルドサブエージェント	一度に 1 つ	実装、テスト実行
トークン形式	JSON より Markdown	約 30% 効率的

---

誘導の仕組み

上流の誘導（入力の形成）

仕組み	目的
詳細な仕様に最初の約 5,000 トークンを使う	仕様のコンテキストを最初に与える
各イテレーションで同一のファイルを使う	決定論的なコンテキスト読み込み
既存のコードパターンを手本にする	一貫性のあるコードを生成する

下流の誘導（検証ゲート）

ゲート	検出するもの
テスト	無効な実装
ビルド	コンパイルエラー
リンター	スタイルの不整合
型チェッカー	コントラクト違反
LLM-as-judge	主観的な品質上の問題

---

状態の永続化

イテレーション間で永続化される状態は、ファイルシステムだけです。

ファイル	目的	管理者
IMPLEMENTATION_PLAN.md	タスクリストと進捗	計画モードと構築モード
specs/*.md	仕様ファイル	spec-writing スキル
AGENTS.md	運用メモと学習内容	構築モード
ソースコード + テスト	実際の実装	構築モード

IMPLEMENTATION_PLAN.md は破棄可能です — 計画イテレーションを実行すれば、いつでも仕様から再生成できます。

---

アンチパターン / よくある間違い

アンチパターン	失敗する理由	正しいアプローチ
1 回のイテレーションで複数のタスクを行う	コンテキストの切り替えが発生し、進捗が不明確になります	ループごとにタスクは 1 つだけ
コードが存在しないと思い込む	別の場所に存在する可能性があり、重複につながります	必ず最初に検索します
実装後にテストを省略する	バグが蓄積し、後戻りの機会がなくなります	すぐにテストを実行します
計画中にしか計画を変更しない	計画が現実から乖離します	計画中と構築中の両方で更新します
古い計画を使い続ける	古い前提に基づくタスクになります	ためらわずに再生成します — 計画は低コストです
コンテキストを手動で管理する	メインコンテキストがあふれます	サブエージェントへの委任を信頼します
2 つの条件を満たさずに終了する	早すぎる終了となり、作業が未完了になります	両方の条件を満たす必要があります
各タスク後にコミットしない	変更セットが大きくなり、元に戻しにくくなります	イテレーションごとにコミットします
プレースホルダーやスタブコードを使う	不完全な実装が蓄積します	本番品質のコードのみを作成します
STATUS CHECK を省略する	終了判定が行われず、ループが永久に続きます	すべてのイテレーションをステータス確認で終えます

---

自己正当化を防ぐためのガード

2 つの条件を満たすゲートを通過せずにループを終了してはいけません。1 回のイテレーションで複数のタスクを実装してはいけません。プレースホルダーやスタブコードを書いてはいけません。STATUS CHECK を省略してはいけません。

次のように考えていることに気づいたら：

• 「このイテレーションで簡単なタスクを 2 つこなせる……」 — いいえ。ループごとにタスクは 1 つだけです。
• 「計画はおそらく問題ないから、計画モードは飛ばそう……」 — 確認してください。計画は乖離します。
• 「テストは次のイテレーションまで待てる……」 — 今すぐテストを実行してください。後戻りできる機会が不可欠です。
• 「すべて終わったので終了できる……」 — 2 つの条件を満たすゲートを確認してください。両方を満たす必要があります。

---

サブエージェントへの委任機会

タスクのパターン	委任先	タイミング
コードベース全体にわたる独立したファイルの読み取り	subagent_type="Explore" を指定した Agent ツール	ループのイテレーションで複数の領域からコンテキストが必要な場合
構築フェーズ中のテスト実行	run_in_background=true を指定した Bash ツール	進捗を妨げずにテストで作業を検証できる場合
イテレーション間のコードレビュー	code-reviewer エージェントをディスパッチする Agent ツール	構築イテレーションの完了後、次の計画の前

ディスパッチする際は、dispatching-parallel-agents スキルのプロトコルに従ってください。

---

統合ポイント

スキル	関係	タイミング
ralph-status	イテレーションごと — ステータスブロックを生成	フェーズ 3：STATUS CHECK
circuit-breaker	セーフティネット — ループの健全性を監視	停滞時に停止
spec-writing	上流 — 計画で使用する仕様を作成	ループ開始前
acceptance-testing	検証 — 動作結果を検証	構築モード中
resilient-execution	タスクごと — 失敗時に再試行	タスクの実装に失敗した場合
task-management	追跡 — 個々のタスクを追跡	イテレーション内
llm-as-judge	品質 — 主観的な基準を評価	下流の調整
verification-before-completion	最終ゲート — 完了の主張を検証	EXIT_SIGNAL: true の前

---

具体例

例：計画モードの出力

IMPLEMENTATION_PLAN.md:
- [x] Set up project structure
- [x] Implement core data types
- [ ] Implement user authentication (P0 — blocks 3 other tasks)
- [ ] Add API rate limiting (P1)
- [ ] Implement webhook handlers (P1)
- [ ] Add monitoring and logging (P2)

Missing specs: Rate limiting spec needs error response format defined.

例：構築モードのイテレーション

Task selected: Implement user authentication
Searched: Found existing password hashing in src/lib/crypto.ts
Implemented: src/auth/service.ts, src/auth/middleware.ts
Tests: 8 passing, 0 failing
Committed: feat(auth): implement JWT-based user authentication

Updated IMPLEMENTATION_PLAN.md:
- [x] Implement user authentication

例：ステータスブロック

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 4
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Next: implement API rate limiting (P1)
---END_RALPH_STATUS---

---

スキルタイプ

RIGID — このプロセスに厳密に従ってください。ループの決定性は、一貫した実行に依存します。1 ループにつきタスクは 1 つです。毎回、ステータスブロックを表示してください。終了ゲートには 2 つの条件があります。例外はありません。