RALF — Recursive Autonomous Loop Framework

ロールベースの自己改善フレームワーク。Claude Code / Codex 等のコーディングエージェントをオーケストレーションし、Product / Architect / Engineer / Reviewer の4ロール + Director で改善ループを回す CLIツール。

Features

• ロールベース実行 — Product / Architect / Engineer / Reviewer の4ロールがそれぞれ専門的視点で改善を提案・実行
• Director — LLMベースのウォッチドッグがロール実行を評価し、次のアクションを動的に決定
• エージェント抽象化 — IAgentAdapter インターフェースにより Claude Code / Codex / カスタムツールを差し替え可能
• 判断ポイント — <judgment_needed> タグでエージェントが一時停止し、人間に設計判断・リスク確認を委ねる
• エンハンスメントキュー — <enhancement_proposal> タグでループを止めずに改善提案を蓄積・レビュー
• トピックバックログ — フォーカスや探索トピックを park / pick で管理
• 段階的モデルルーティング — ロール別に異なるモデルを使い分け
• 永続化 — JSON Lines 形式で履歴・判断・提案を保存
• リトライ・タイムアウト — エージェント呼び出しの耐障害性

Requirements

• Node.js >= 20
• pnpm
• Claude Code CLI（エージェントとして使用する場合）

Install

pnpm install
pnpm build

Usage

# 基本実行（4ロール全て）
ralf run --codebase ./src

# フォーカスを指定
ralf run --focus "error handling is inconsistent across modules"

# ロール選択・バジェット
ralf run --roles product,architect,engineer,reviewer
ralf run --role-budget 30

# コスト上限付きで実行（SDK アダプタがデフォルト）
ralf run --max-budget-usd 5.00

# モデル指定
ralf run --model claude-sonnet-4-5-20250929

# Director無効化（コスト節約）
ralf run --no-director

# 複数スプリント連続実行
ralf run --sprints 3

# 承認済み提案の一括適用（blitz）
ralf run --blitz 5

# トピックバックログからフォーカスを選択
ralf run --from-backlog

# エンハンスメント提案管理
ralf proposal add --title "改善タイトル" --category performance
ralf proposal list --status approved
ralf proposal review
ralf proposal apply

# 週次レポート生成
ralf report

# プロジェクトヘルスダッシュボード
ralf status

# トピックバックログ管理
ralf topic list
ralf topic park
ralf topic pick

# フレームワーク自己改善（MEP）
ralf self-improve list
ralf self-improve review

# スプリントログの可視化
ralf visualize

ralf run 主要オプション

| オプション | デフォルト | 説明 | | ------------------- | ----------- | -------------------------------------- | | --codebase | ./src | 対象コードベースのパス | | --focus | - | 改善フォーカス指示 | | --roles | 全ロール | 実行するロール（カンマ区切り） | | --role-budget | - | ロール呼び出し上限 | | --model | (default) | 使用するモデル | | --adapter | sdk | エージェント実行方式（sdk / cli） | | --sdk-provider | claude | SDKプロバイダ（claude / codex） | | --max-budget-usd | - | 最大予算USD | | --no-director | - | Director無効化 | | --sprints | 1 | 連続実行スプリント数 | | --blitz | 0 | blitz で適用する提案数 | | --cycles | 1 | sprint+blitz サイクル数 | | --auto-commit | false | スプリント後に自動コミット | | --from-backlog | - | トピックバックログからフォーカスを選択 | | --no-enhancements | - | エンハンスメント検出を無効化 |

設定ファイル配置

設定ファイルは <projectRoot>/.config/ralf/ に集約。

• config.yaml — run コマンド既定値（language など）と models 設定
• project-context.md — プロジェクト文脈の明示指定
• work-guidance.md — 実行時ガイダンス

Config YAML 例

.config/ralf/config.yaml

language: ja
models:
  default: claude-sonnet-4-6
  roles:
    engineer: claude-opus-4-6

Design

詳細な設計思想は docs/DESIGN.md を参照。

実行モデル

基本:   Agent SDK の query() で流す（デフォルト）。--adapter cli で CLI版にフォールバック可。
ロール: Product → Architect → Engineer → Reviewer の順にロールを実行。
        Director が各ロール実行後の結果を評価し、追加ロール呼び出しを判断。
例外1:  エージェントが <judgment_needed> を出力 → 一時停止 → 人間に判断を求める → 回答を注入して再開
例外2:  エージェントが <enhancement_proposal> を出力 → キューに投函 → ループは止めず続行

設計原則

1. エージェントは差し替え可能 — IAgentAdapter を実装すれば何でも繋がる
2. ロールは関心の分離 — 各ロールが専門的視点で改善を提案・実行
3. Director は監視役 — LLMベースのウォッチドッグが次のアクションを動的に決定
4. 人間が最終判断者 — 自動化は提案まで。破壊的変更・設計判断は必ず人間に聞く

Development

# テスト実行
pnpm test

# 型チェック
pnpm lint

# 開発実行
pnpm dev

License

MIT