Smart Ralph｜Claude Code/Codexにspec-driven開発を持ち込む14コマンド・6エージェント基盤

Claude Codeに「ユーザー認証を追加して」と一言投げて任せると、要件確認も設計もすっ飛ばして実装に入り、200行ほど書いた頃にコンテキストが詰まって迷走する——という経験をしたことがある人は多い。Spec-driven開発を求める声が2026年に入ってGitHub spec-kitやSpeckitなどへ集中したのは、そのvibeとプロダクションのギャップが大きすぎたからだ。

tzachbon/smart-ralph（★316、2026年4月最終push）はそのギャップを「最小構成のClaude Code/Codexプラグイン」として埋めにきたOSSだ。/ralph-specum:start user-auth "Add JWT authentication"と打つだけで、研究→要件→設計→タスク→実装の5フェーズを6つの専門エージェントが順に処理し、最終的にタスクを1個ずつフレッシュコンテキストで実行する。Ralph Wiggumの「考えすぎず次のタスクをやる」ループパターンに、structured spec workflowを組み合わせた設計が特徴である。

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

1. Smart Ralphとは——曖昧な要件をspec-driven開発に変換するプラグイン

Smart Ralphは、Claude CodeとCodex CLIに対応したspec-driven開発プラグインだ。tzachbon氏が2026年に公開し、5月時点で★316、forks 15、open issues 9という規模感である。リポジトリのdescriptionは「Spec-driven development with smart compaction. Claude Code plugin combining Ralph Wiggum loop with structured specification workflow.」と簡潔にまとまっている。

「Smart compaction（賢い圧縮）」という単語が示す通り、特徴はコンテキスト管理だ。長時間の自律実行で問題になるトークン消費を、タスクごとにフレッシュコンテキストへ切り替える設計で抑える。これは2026年に入って急速に標準化したパターンで、snarktank/ralphのハーネスエンジニアリングも同じ思想を持つが、Smart Ralphはその上に仕様生成の段階構造を載せている点が違う。

Ralph Wiggumから来た「考えすぎないループ」

プロジェクト名のRalphは、Geoffrey HuntleyのブログPost「Ralph Wiggum as a Software Engineer」で広まったエージェントパターンに由来する。Ralph Wiggumはアニメ『シンプソンズ』の登場人物で、深く考えずに目の前のタスクを淡々とこなすキャラクター。AIエージェントの設計思想として「複雑な計画より、シンプルなループで次のタスクを処理させる方が結果が出る」という考え方を象徴している。

Smart Ralphはその哲学を継承しつつ、「次のタスク」を機械的に決めるためのspec-driven前処理を加えた点が新しい。タスクは事前にtasks.mdへ書き出され、依存関係も明示されているため、ループ側は「次の未完了タスクをフレッシュコンテキストで実行する」という単純動作に専念できる。

v3.0.0で何が変わったか

2026年時点の最新版はv3.0.0で、最大の変更はralph-loop外部プラグインの依存を排除した点だ。v2系では別途ralph-loopをインストールしてタスク実行を任せていたが、v3ではbuilt-in stop-hookでループ制御を内包する。既存の仕様ファイルはそのまま継承できるため、移行コストはゼロに近い。

2. インストール手順——Claude CodeとCodex両対応の段差

Smart RalphはClaude CodeとCodex CLIの両方で動く。インストール体験には差があり、Claude Codeはほぼ1コマンド、Codexは手動コピーが必要だ。

Claude Codeへの導入（推奨）

Claude Codeの場合はプラグインマーケットプレース経由で入る。以下を順に実行する。

# 1. マーケットプレースを追加
/plugin marketplace add tzachbon/smart-ralph

# 2. メインのspec-drivenプラグインをインストール
/plugin install ralph-specum@smart-ralph

# 3. （任意）GitHub spec-kit準拠版も使う場合
/plugin install ralph-speckit@smart-ralph

インストール後、Claude Codeを再起動すると/ralph-specum:startなどのコマンドが使えるようになる。これだけで14コマンドと6エージェントが利用可能になる。プラグイン経由で入るため、Anthropic公式のClaude Skillsの仕組みに沿って自動的にスキルが読み込まれる。

Codexへの導入（手動コピー）

Codexの場合は@openai/codex CLIが先に必要だ。npm install -g @openai/codexで入る。次にSmart RalphのCodex版を手動でコピーする。

# 1. 一時クローン
git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph

# 2. ~/.codex/plugins/ にCodex版プラグインをコピー
mkdir -p ~/.codex/plugins
cp -R /tmp/smart-ralph/plugins/ralph-specum-codex \
      ~/.codex/plugins/ralph-specum-codex

# 3. マーケットプレース定義を作成
mkdir -p ~/.agents/plugins
cat > ~/.agents/plugins/marketplace.json << 'EOF'
{
  "name": "smart-ralph",
  "plugins": [{
    "name": "ralph-specum",
    "source": {"source": "local", "path": "~/.codex/plugins/ralph-specum-codex"},
    "policy": {"installation": "AVAILABLE"},
    "category": "Productivity"
  }]
}
EOF

# 4. クリーンアップ
rm -rf /tmp/smart-ralph

加えて~/.codex/config.tomlに[features] codex_hooks = trueを追記しておくと、Stop hookで自動タスク実行が有効になる。プロジェクト単位でだけ使いたい場合は、コピー先を./plugins/、マーケットプレース定義を./.agents/plugins/marketplace.jsonに置き換える。

動作確認とアップデート

インストール後、/ralph-specum:statusを実行して何も仕様がない旨が表示されれば導入は成功している。アップデートするときは同名フォルダを上書きコピーする運用になる（Claude Code側はマーケットプレース経由で再インストール）。

3. 14コマンドの全体像——/startから/implementまでの流れ

Smart Ralphが提供するコマンドは14個で、用途別に4グループに分かれる。コマンド面では「/ralph-specum:startが万能エントリ」「単発フェーズ実行用に/research〜/implement」「メタ操作用に/status//switch//cancel」「分解用に/triage//index」と覚えると整理しやすい。

最頻出は/ralph-specum:startで、引数なしで打てば既存仕様のresumeを自動検出し、引数を渡せば新規作成に入る。「考えずに打てる1コマンド」を意図的にエントリに置いている設計だ。

標準フロー：段階的に確認しながら進める

落ち着いて1ステップずつ確認したいときは、step-by-stepで進める。各フェーズの後に承認チェックポイントが入るため、出力されたspecを読んでから次へ進める。

# 機能名と目標を渡して新規仕様を作る
/ralph-specum:new user-auth Add JWT authentication

# 各フェーズを順に走らせる
/ralph-specum:research       # 関連ライブラリ・既存実装を調査
/ralph-specum:requirements   # ユーザーストーリー・受け入れ基準を生成
/ralph-specum:design         # 技術設計（アーキテクチャ・パターン）
/ralph-specum:tasks          # 実装タスクをPOC優先で分解
/ralph-specum:implement      # タスクを1個ずつフレッシュコンテキストで実行

各フェーズはMarkdownファイル（./specs/user-auth/research.mdなど）として永続化される。途中で気に入らなければ/ralph-specum:researchを再実行してやり直せる。

Quickモード：とにかく回す

時間がない、または小さなプロトタイプを試すときは--quickを付ける。承認チェックポイントを飛ばし、5フェーズすべてを連続実行する。

/ralph-specum:start "Add user auth" --quick

Quickモードはvibeコーディングを残しつつ、内部では仕様駆動を走らせるという折衷モードだ。生成された仕様ファイルは後から読めるので、自分で書く前のたたき台として使う運用も可能である。

4. 6つの専門エージェントが分業する開発フロー

Smart Ralphの内部は6つの専門サブエージェントに分業されている。Claude Codeのagent skill機能を使って役割を切り分け、フェーズごとに最適化したシステムプロンプトと評価基準で動く設計だ。

エージェントの分業はトークン効率にも効く。各エージェントのコンテキストは独立しているため、研究フェーズの大量Web検索ログがdesignフェーズに混入しない。フレッシュコンテキスト原則を保ったまま、必要な情報だけが受け渡される設計だ。

Triageが必要になる境界

/startは与えられたゴールが単一仕様で扱える規模か、複数仕様（epic）への分解が必要かを判定する。判定が「too big」だった場合は/triageへ自動分岐する。Triageは内部で4ステップ（Exploration Research → Brainstorm → Validation Research → Epic Plan）を踏み、依存関係付きの複数仕様計画を出力する。

たとえば「ECサイトを作る」のような巨大なゴールはTriageに通すと、商品カタログ・カート・決済・ユーザー管理など複数仕様に分割され、各仕様ごとに独立したresearch〜executionサイクルが回る。

research-analystの仕事内容

最初に動くresearch-analystは「使うべきライブラリ」「既存コードベースの該当箇所」「実現可能性」の3点を埋めにいく。Web検索とコードベース走査を組み合わせ、研究結果をresearch.mdに出力する。重要なのはコードを書かない点だ。事実集めだけに徹することで、後段の設計判断に偏りを残さない設計になっている。

5. 4フェーズタスク実行——POCから品質ゲートまで

タスク段階のexecutionは、さらに内部で4フェーズに分かれている。tasks.mdに書かれた各タスクは、すべてこの4フェーズを通って完了とみなされる。ここがSmart Ralphの「品質を担保する仕組み」の核だ。

このフェーズ分けは、AIエージェントが「テストを後回しにすると最初から書けない」「最初から完璧を求めると進まない」という両極端に陥るのを防ぐための工夫だ。最初に動くものを作って一旦Greenにし、その後でリファクタとテストを段階的に積むという人間の熟練エンジニアの順序を再現している。

粒度コントロールと並列マーカー

タスク粒度は--tasks-size fine|coarseで切り替えられる。fineは細かく分割、coarseは大粒度。プロジェクト規模やAI側のミス確率に応じて調整する。fineは進捗が見えやすい代わりにオーバーヘッドが大きく、coarseは速い代わりに失敗時の手戻りが大きい。

並列実行可能なタスクには[P]マーカーが付与され、依存しないタスクは並列で進められる。[VERIFY]マーカーは明示的な検証フェーズを強制し、たとえばDBマイグレーションやスキーマ変更のような不可逆操作の前に挿入される。

# tasks.md の例
- [ ] [P] M1 Add User model in src/models/user.ts
- [ ] [P] M2 Add auth middleware in src/middleware/auth.ts
- [ ] M3 Wire User and middleware in src/app.ts
- [ ] [VERIFY] Run migrations against local DB
- [ ] M4 Add JWT issuance in src/services/auth.ts
- [ ] T1 Add unit tests for auth middleware
- [ ] Q1 Run lint and type check

このタスク表記法はSpec-Kitの規約と互換があり、人間が手で編集しても壊れない。

Spec保存構造

仕様ファイルは./specs/配下にまとまる。アクティブな仕様は.current-specポインタで示され、状態管理は.ralph-state.jsonが担当する。完了時にstate fileは自動削除され、Markdown仕様だけが残る。

./specs/
├── .current-spec
└── user-auth/
    ├── .ralph-state.json
    ├── .progress.md
    ├── research.md
    ├── requirements.md
    ├── design.md
    └── tasks.md

.progress.mdはループ中の進捗ログで、エラーが発生した場合のフォールバック資料になる。タスクが失敗したら.progress.mdを読んで原因を確認し、手で直してから/ralph-specum:implementで再開する運用になる。

6. ralph-specum vs ralph-speckit——軽量とエンタープライズの使い分け

Smart Ralphには似た2つの兄弟プラグインが同梱されている。ralph-specumとralph-speckitだ。両者は仕様駆動という思想は共通するが、ファイル構造とガバナンスモデルが異なる。

ralph-specumを選ぶ場合

ralph-specumは個人開発や数人チームの高速反復向けだ。仕様ファイルはフラットな./specs/feature-name/に置かれ、4ファイル（research/requirements/design/tasks）で完結する。連番がないので機能間の優先順序を意識する必要がなく、軽い気持ちで/startできる。

/ralph-specum:start user-auth Add JWT authentication

ralph-speckitを選ぶ場合

ralph-speckitはGitHub公式のspec-kitに準拠した構成だ。仕様は001-連番付きディレクトリに置かれ、spec.mdでWHAT/WHYを、plan.mdでHOWを分離する。さらに.specify/memory/constitution.mdにプロジェクト原則（命名規約・依存制約・許容アーキテクチャ）を記載でき、Spec-Kitワークフローの全コマンドが使える。

/speckit:start user-auth "Add JWT authentication"
/speckit:specify
/speckit:plan
/speckit:tasks
/speckit:implement

監査ログ・チームレビュー・複数人並行開発のような要件があればspeckit、自分1人で速度を取りたいならspecum。迷ったらまずspecumから始めて、必要になったらspeckitへ移行する運用が現実的だ。

7. snarktank/ralphとの違い——スコープが違う2つのRalph

「Ralph」を冠したOSSは2026年にいくつか登場しており、混同しやすい。代表的なのはsnarktank/ralph（★15,000+）だ。両者の関係を整理する。

snarktank/ralphは「PRDを書き終わった後の長時間ループ」が得意だ。一方Smart Ralphは「PRDを書く段階から自動化したい」場合に向く。両者は競合ではなく補完の関係にあり、Smart Ralphでspecを生成し、その後snarktank/ralphに渡して長時間自走させる運用も理屈上は可能である。

Vibeコーディングとの距離感

Smart Ralphは「vibeコーディングを否定するものではない」。--quickモードがあるのが象徴的で、仕様化の手間が要らない場面では従来通りのvibe実行に戻れる。一方で機能が大きくなったときに「仕様を書け」と強制せずに、フレッシュコンテキストで段階生成する選択肢を提供する点が新しい。

Andrej KarpathyのCLAUDE.md・skillsガイドが示すように、AIコーディングの主流はvibeから「文脈の構造化」へ移っている。Smart Ralphはその構造化をプラグイン1個で受け取れる現実解だ。

＜悪い例＞ 「ユーザー認証を追加して」とClaude Codeに渡すと、いきなり実装に入って中盤でコンテキスト切れし、テストもないコードが残る。

＜改善例＞ /ralph-specum:start user-auth Add JWT authenticationと打つと、研究→要件→設計→タスクが順に生成され、各タスクがフレッシュコンテキストでテスト付きで完了する。

8. まとめ——いつSmart Ralphを採用すべきか

Smart Ralphの本質は「Ralphループに仕様駆動の段階構造を載せた最小プラグイン」だ。インストール2コマンド、コマンド14個、エージェント6つ、フェーズ4段階というシンプルな構成で、Claude Code/Codexの自走能力を一段引き上げる。

2026年5月時点で★316とまだ若いが、v3.0.0でself-containedな実行ループを実現し、ralph-loop依存を排除した点は本番採用に向けた前進だ。エンタープライズでの本格採用にはspeckit側の運用検証が必要だが、個人開発と小規模チームでの「vibeから仕様駆動への移行」には今すぐ使える。/plugin marketplace add tzachbon/smart-ralphの1コマンドから始められる。

参照ソース

• tzachbon/smart-ralph - GitHub
• Ralph Wiggum as a Software Engineer - Geoffrey Huntley
• GitHub spec-kit - GitHub