ralph-loop-kiro-specs

Kiro Specs 用 Ralph Loop

Kiro で仕様に基づく開発を進める、自動化された反復型エージェントランナーです。kiro-cli を Bash のループで実行し、綿密に設計されたプロンプトを与えることで、Kiro を規律ある自己修正型の実装エージェントとして機能させます。仕様からタスクを選び、実装し、自身の作業を検証し、反復を重ねながら失敗から学習します。

クレジット： Apache License 2.0 の下でライセンスされている、mreferre による ralph-loop-kiro-specs に基づいています。

使用する場面

• エージェントの反復を繰り返して、Kiro の仕様タスクの実装を自動化する
• プロンプトを手動で一つずつ入力することなく、仕様の開始から完了まで進める
• 新しいプロジェクトで Ralph Loop をセットアップする
• 停止または失敗した Ralph Loop の実行をトラブルシューティングする
• 進捗の追跡、修正、コードベースのパターンの仕組みを理解する
• 完了後にサマリーダッシュボードを生成または解釈する

前提条件

要件	詳細
Kiro CLI	kiro-cli がインストールされ、PATH に設定されていること（kiro.dev/cli）
Kiro IDE	kiro.dev がインストールされていること
Bash	標準の Bash シェル
Kiro Specs	.kiro/specs/<specs_name>/ に仕様があり、少なくとも requirements.md、design.md、tasks.md を含むプロジェクト

仕組み

Ralph はループを実行し、各反復でプロンプトを kiro-cli に送ります。このプロンプトは、エージェントに次の厳格な 6 段階のサイクルに従うよう指示します。

6 つのフェーズ

1. コンテキストの読み込み — ステアリングファイル（product.md、structure.md、tech.md）と対象の仕様（requirements.md、design.md、tasks.md、progress.md）を読み込みます。利用可能なツールを確認します。
2. タスクを 1 つ選ぶ — 未完了のトップレベルタスクのうち、番号が最も小さいものを見つけます。開始時刻を記録します。1 回の反復で 2 つ以上のタスクを選んではいけません。
3. 実装前に理解する — 関連するソースファイルを読み、既存のパターンを調べ、progress.md の「Corrections」セクションと「Codebase Patterns」セクションを読み直し、該当する修正をすべて事前に適用します。
4. 実装する — タスクとすべてのサブタスクを順番に実装します。型チェックとテストを実行します。失敗した場合は修正し、今後の反復でも同じ問題が起こり得るならすぐに修正内容を記録してから、先へ進みます。5 回試行しても失敗する場合は、タスクに [F] を付け、未解決のブロッカーを記録します。
5. 終了条件を確認する — requirements.md の終了条件と design.md の設計上の制約を読み直します。完了とマークする前に、それぞれの条件が満たされていることを確認します。
6. 追跡情報を更新する — tasks.md でタスクに [X] を付け、progress.md に進捗を追記し、新たなコードベースのパターンを追加し、最後に修正内容を見直して、所要時間を specs_time.md に記録します。

自己修正システム

progress.md の先頭にある「Corrections」セクションは、間違いとその修正をまとめたフラットなルックアップテーブルです。各反復では作業を始める前に必ずこのセクションを読み、記載された間違いを決して繰り返してはいけません。エラーが発生したら、タスクの最後ではなく、その場ですぐに修正内容を記録します。

形式：

- ❌ `python manage.py migrate` → ✅ `python3 manage.py migrate` (system has no `python` alias)
- ❌ Running tests with `npm test` → ✅ `npm run test:unit` (project uses separate test scripts)
- ❌ UNRESOLVED: [description of issue that couldn't be fixed after 5 attempts]

コードベースのパターン

Ralph は実装中に見つけた規約（ファイルの命名、インポートのパターン、エラー処理、テストコマンドなど）を蓄積します。記録するのは実際に遭遇したパターンのみで、推測に基づくものは記録しません。

完了とサマリーダッシュボード

すべてのタスクに [X] が付くと、Ralph は仕様ディレクトリに自己完結型の summary.html を生成します。内容は次のとおりです。

• 上部ペイン：仕様名、ステータス表示（緑／赤）、合計経過時間、タスク数、期間
• 左ペイン：ホバー時に進捗の詳細を表示するツールチップ付きの、折りたたみ可能なタスクツリー
• 右ペイン：タスクごとの開始時刻、終了時刻、所要時間を示す時間テーブル

プロジェクト構成

Ralph を実行する前のユーザーのプロジェクトは、次のような構成である必要があります。

your-project/
├── ralph-loop-kiro-specs-prompt.md    # The Ralph agent prompt template
├── ralph-loop-kiro-specs-script.sh    # The loop runner script
└── .kiro/
    ├── steering/
    │   ├── product.md                 # What the product is
    │   ├── structure.md               # Project structure conventions
    │   └── tech.md                    # Tech stack and tooling
    └── specs/
        └── <specs_name>/
            ├── requirements.md        # Requirements and exit criteria
            ├── design.md              # Architecture and design decisions
            ├── tasks.md               # Task checklist
            ├── progress.md            # Auto-created: corrections, patterns, progress log
            ├── specs_time.md          # Auto-created: per-task timing
            └── summary.html           # Auto-generated on completion: visual dashboard

セットアップ手順

プロジェクトで Ralph Loop をセットアップするには：

1. スクリプトとプロンプトテンプレートをプロジェクトのルートにコピーします：
   • ralph-loop-kiro-specs-script.sh — ループ実行スクリプト（このスキルの scripts/ に同梱）
   • ralph-loop-kiro-specs-prompt.md — エージェントのプロンプトテンプレート（references/ に同梱）
2. スクリプトを実行可能にします：chmod +x ralph-loop-kiro-specs-script.sh
3. プロジェクトに .kiro/specs/<specs_name>/ の下で Kiro の仕様が設定されており、少なくとも requirements.md、design.md、tasks.md があることを確認します
4. .kiro/steering/ の下にステアリングファイル（product.md、structure.md、tech.md）があることを確認します。これらがあると出力品質が大幅に向上します

使用方法

./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>

引数	説明
max_iterations	ループの最大反復回数（正の整数）。各反復で 1 つのタスクを実装します。タスク数にリトライ分を加えた値以上に設定してください。
specs_name	.kiro/specs/ の下にある仕様ディレクトリの名前です。必要なファイルがそろった状態で、あらかじめ存在している必要があります。

例

# Run up to 15 iterations on the "auth-feature" spec
./ralph-loop-kiro-specs-script.sh 15 auth-feature

反復モード

スクリプトの起動時に、自動または手動で実行するかを選択します：

• 自動 — 一時停止せずにタスクを続けて実行します。仕様が明確な場合に適しています。
• 手動 — 各反復の後にレビューのため一時停止します。新しい仕様や不慣れな仕様に適しています。

トラブルシューティング

Ralph がタスクで行き詰まる（[F] と表示される）

問題を手動で修正し、tasks.md のタスクのマークを外してから再実行します。失敗した試行での修正内容は progress.md に残るため、次の反復で学習に活用されます。

完了前に最大反復回数に達する

max_iterations を増やして再実行します。Ralph は tasks.md を読み込んで次の未完了タスクを見つけるため、前回の続きから再開します。

エージェントが 1 回の反復で複数のタスクを実装する

これは中核となる制約に違反しています。変更されていないプロンプトテンプレートを使用していることを確認してください。テンプレートの先頭にある重要な制約セクションで、1 回の反復につき 1 タスクのみ実装するよう定めています。

ステアリングファイルがない

なくても Ralph は動作しますが、コンテキストがあるほうがより良い結果が得られます。製品、プロジェクト構造、技術スタックについて説明する .kiro/steering/product.md、structure.md、tech.md を作成してください。

品質チェックリスト

Ralph Loop を実行する前に、次の項目を確認してください：

• kiro-cli がインストールされ、PATH から利用できる
• .kiro/specs/<specs_name>/ の下に仕様ディレクトリがある
• requirements.md に終了条件を含む要件が番号付きで記載されている
• design.md にアーキテクチャと設計上の決定事項が記載されている
• tasks.md にサブタスクを含む番号付きタスクリストがある
• .kiro/steering/ の下にステアリングファイルがある（推奨）
• max_iterations がタスク数にバッファを加えた値以上に設定されている
• プロンプトテンプレート（ralph-loop-kiro-specs-prompt.md）がプロジェクトのルートにある
• スクリプト（ralph-loop-kiro-specs-script.sh）が実行可能になっている

同梱リソース

リソース	パス	説明
実行スクリプト	scripts/ralph-loop-kiro-specs-script.sh	反復を実行する Bash ループです。プロジェクトのルートにコピーしてください。
プロンプトテンプレート	references/ralph-loop-kiro-specs-prompt.md	エージェントのプロンプトテンプレートです。プロジェクトのルートにコピーしてください。

フェーズの詳細な指示、修正形式、コードベースパターンのカテゴリ、またはサマリーダッシュボードの仕様を確認する必要がある場合は、プロンプトテンプレートを読んでください。

ライセンス

このスキルは、mreferre による ralph-loop-kiro-specs をベースとしており、Apache License 2.0 の下でライセンスされています。

Copyright [mreferre]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.