Ralphとは：AIコーディングエージェントの自律ループを実現するOSS
AIコーディングエージェントに長時間のタスクを任せると、コンテキストウィンドウの限界で途中で精度が落ちる。Ralphはこの問題を「イテレーションごとに新しいAIインスタンスを起動し、外部ファイルで記憶を引き継ぐ」というアプローチで解決する。GitHub 15,300+スターを獲得し、今注目のハーネスエンジニアリングを実践するOSSプロジェクトだ。
ハーネスエンジニアリングとは「Agent = Model + Harness」という考え方で、AIモデル以外の全てのインフラ（制約、状態管理、品質チェック、回復機構）を設計する手法。Ralphはこの概念を「自律開発ループ」として具現化している。
基本的な流れは、PRD（製品要件定義書）をJSON形式で構造化し、各ユーザーストーリーに対してAIが実装→検証→コミット→次のストーリーへ、というサイクルを人間の介入なしで繰り返す。
# 最もシンプルな起動方法
./scripts/ralph/ralph.sh 10 # 最大10イテレーション
# Claude Codeプラグインとしてインストール
/plugin marketplace add snarktank/ralph
ハーネスエンジニアリングにおけるRalphのアーキテクチャ設計
Ralphの設計思想はHarnessフレームワークと共通するが、フォーカスが異なる。Harnessがエージェントチームの構築パターンを提供するのに対し、Ralphは「単一エージェントの長時間自律実行」に特化している。
アーキテクチャの核心は分散コンテキストモデルだ。従来の長時間セッションでは1つのコンテキストウィンドウが肥大化するが、Ralphは各イテレーションで完全にクリーンなAIインスタンスを起動する。記憶は3つのファイルで外部化される。
| ファイル | 役割 | 更新タイミング |
|---|---|---|
prd.json |
タスク定義・完了フラグ・ブランチ情報 | ストーリー完了時 |
progress.txt |
累積学習ログ・コードベースパターン | 各イテレーション終了時 |
AGENTS.md |
プロジェクト固有のパターンと規約 | パターン発見時に自動更新 |
prd.json生成"] --> B["ストーリー選択
未完了の最小単位を取得"] B --> C["AIインスタンス起動
クリーンなコンテキスト"] C --> D["コンテキスト注入
Git履歴 + progress.txt + prd.json"] D --> E["実装
コード変更"] E --> F["品質チェック
typecheck + lint + test"] F -->|失敗| G["自己修正
エラーを修正して再実行"] G --> F F -->|成功| H["コミット
feat: [Story ID] - Title"] H --> I["progress.txt更新
学習ログ追記"] I --> J{"全ストーリー
完了？"} J -->|No| B J -->|Yes| K["完了
全PRD項目クリア"]
この設計には明確な利点がある。各イテレーションが独立しているため、途中で失敗しても前回のコミットまでロールバックできる。Martin Fowlerが提唱するハーネスエンジニアリングの「フィードフォワード制御（予防）」と「フィードバック制御（自己修正）」の両方を組み込んでいる。
PRD駆動開発：AIエージェントのタスク分解と状態管理
Ralphの実行単位は「ユーザーストーリー」だ。PRDをJSON形式に変換し、各ストーリーが1つのコンテキストウィンドウに収まるサイズに分割する。これがハーネスエンジニアリングにおける「フィードフォワード制御」に相当する。
{
"title": "ECサイトのカート機能",
"stories": [
{
"id": "S1",
"title": "商品をカートに追加",
"acceptance_criteria": [
"商品詳細ページに「カートに追加」ボタンがある",
"ボタンクリックでカートアイテム数が増加する",
"同じ商品を複数回追加すると数量が増える"
],
"completed": false,
"branch": ""
},
{
"id": "S2",
"title": "カート内商品の数量変更",
"acceptance_criteria": [
"カートページで各商品の数量を変更できる",
"数量0で商品がカートから削除される",
"合計金額がリアルタイムで更新される"
],
"completed": false,
"branch": ""
}
]
}
PRDからprd.jsonへの変換にはRalph付属のスキルを使う。
# PRDをprd.jsonに変換（Claude Codeスキル）
/ralph:convert-prd
# 既存のマークダウンPRDからの変換も可能
/ralph:generate-prd
重要なのは、各ストーリーの受け入れ条件（acceptance_criteria）がAIの検証基準になる点だ。Ralphは実装後にテストを実行し、受け入れ条件を満たしているかを確認する。満たしていなければ自己修正ループに入る。
progress.txtの設計：イテレーション間の記憶継承メカニズム
Ralphのハーネスエンジニアリングで最も独自性が高いのがprogress.txtの設計だ。このファイルはAIの「長期記憶」として機能し、2つのセクションで構成される。
Codebase Patterns（先頭セクション）: プロジェクト固有の再利用可能なパターン。「sql<number>テンプレートで集計クエリを書く」「テスト用DBはtest_プレフィックス」といった汎用知識が蓄積される。
イテレーションログ（時系列セクション）: 各サイクルの実装内容、変更ファイル、学習事項の記録。日時、ストーリーID、スレッドURL、具体的な変更点を含む。
# Codebase Patterns
- Use `sql<number>` template tag for database aggregations
- Test database uses `test_` prefix with seed data in fixtures/
- API responses follow { data, error, meta } envelope format
- Component tests use `@testing-library/react` with `screen` queries
# Progress Log
## 2026-04-12 09:15 — S1: 商品をカートに追加
- Thread: https://...
- Changed: src/components/ProductDetail.tsx, src/store/cart.ts
- Added: src/store/__tests__/cart.test.ts
- Learnings: CartContextはuseReducerパターンで実装。
既存のProductContextと同じパターンに合わせた。
## 2026-04-12 09:32 — S2: カート内商品の数量変更
- Thread: https://...
- Changed: src/pages/Cart.tsx, src/store/cart.ts
- Learnings: 数量0の削除はreducerのREMOVE_ITEMアクションに統合。
この設計により、新しいAIインスタンスはプロジェクトの「文化」を理解した状態で開発を開始できる。OpenHandsのようなAIコーディングエージェントが単一セッション内でコンテキストを管理するのに対し、Ralphは明示的なファイルベースの状態管理でセッション間の連続性を保証する。
品質チェック機構：フィードバック制御によるコード品質の維持
ハーネスエンジニアリングの「フィードバック制御」をRalphは実用的に実装している。各イテレーションの間に統合チェックが実行され、コード品質の劣化を防ぐ。
| チェック種別 | 実行内容 | 失敗時の動作 |
|---|---|---|
| 型チェック | TypeScript tsc --noEmit |
自己修正ループ |
| リンター | ESLint / Prettier | 自動修正 → 再チェック |
| テスト | Jest / Vitest 実行 | 修正 → 再実行（最大3回） |
| ブラウザ検証 | dev-browserスキルでUI確認 | 手動判断ポイント |
ブラウザ検証は特に興味深い設計だ。UI変更を含むストーリーでは、Ralphがdev-browserスキルを使って実際にブラウザを起動し、視覚的に動作を確認する。自動テストだけでは検出できないレイアウト崩れやインタラクションの問題を捕捉する仕組みだ。
コミットのフォーマットも厳密に管理される。
# Ralphが生成するコミットメッセージの形式
git commit -m "feat: [S1] - 商品をカートに追加"
git commit -m "feat: [S2] - カート内商品の数量変更"
全てのコミットが品質チェックを通過した状態でのみ記録される。これにより、Git履歴自体が「検証済みの実装ステップ」のログとして機能する。
他のAIコーディングツールとの比較：Ralphの位置づけ
Ralphは単体のAIコーディングツールではなく、既存ツールの上位レイヤーとして動作する。以下の比較表で位置づけを整理する。
| 項目 | Claude Code単体 | OpenHands | Ralph |
|---|---|---|---|
| 実行形態 | 単一セッション | コンテナ内エージェント | ループオーケストレーター |
| コンテキスト管理 | ウィンドウ内 | サンドボックス状態 | 外部ファイル（progress.txt） |
| タスク分解 | 手動 | 自動（単一セッション内） | PRD駆動（事前分解） |
| 品質チェック | ユーザー依存 | 組み込みテスト | イテレーション間の統合チェック |
| 記憶の永続性 | セッション終了で消失 | セッション終了で消失 | Git + progress.txt で永続 |
| 最大タスク規模 | コンテキスト長に依存 | 中規模 | PRD全体（数十ストーリー） |
重要なのは、RalphはClaude CodeやAmpを置き換えるものではなく、ハーネスとして包むものだという点。モデルの能力を最大限引き出すための「馬具」として機能する。
セットアップ手順：5分でRalphを導入する方法
Ralphの導入は3つの方法がある。プロジェクトローカル、グローバル設定、Claude Codeプラグインのいずれかを選択する。
ローカルインストール（推奨）
# 1. リポジトリをクローン
git clone https://github.com/snarktank/ralph.git
# 2. スクリプトをプロジェクトにコピー
cp -r ralph/scripts/ralph/ your-project/scripts/ralph/
# 3. PRDを作成してループ開始
cd your-project
./scripts/ralph/ralph.sh 20 # 最大20イテレーション
Claude Codeプラグインとしてインストール
# マーケットプレイスから
/plugin marketplace add snarktank/ralph
# または直接インストール
/plugin install snarktank/ralph
必要な依存関係は以下の通り。
| 依存ツール | 用途 | インストール |
|---|---|---|
| Claude Code or Amp | AIコーディングエンジン | npm install -g @anthropic-ai/claude-code |
| jq | JSONパース・操作 | brew install jq (macOS) |
| Git | バージョン管理・記憶保持 | 標準搭載 |
| Node.js | TypeScriptスキル実行 | brew install node |
セットアップ後は/ralph:generate-prdでPRDを作成し、ralph.shを実行するだけでAIが自律的に開発を進める。イテレーション数の上限を設定しておけば、無限ループを防げる。
まとめ：ハーネスエンジニアリング時代のAI開発ワークフロー
Ralphが示しているのは、「AIの性能を上げる」のではなく「AIが動く環境を整える」というハーネスエンジニアリングの実践だ。LangChainのコーディングエージェントがハーネスの改善だけでTerminal Bench 2.0のスコアを52.8%→66.5%に引き上げた事例が象徴するように、モデルを変えずに成果を改善する時代が来ている。
Ralphの設計原則（PRD駆動のタスク分解、外部ファイルベースの記憶、イテレーション間の品質チェック）は、自社のAI開発ワークフローにも応用できる。まずは小さなプロジェクトで試し、progress.txtの蓄積効果を体感してみてほしい。
