私たちは毎日Claude Codeを使用しています。それは優秀です。複雑なリファクタリング、テストの作成、大規模なコードベースの操作、見落とすようなバグの検出を行います。しかし自律的なマルチエージェントシステムの一部として数か月間実行した後、私たちは気づきました：Claude Codeは強力なツールですが、基本的には受動的です。指示を待って、実行して、終了します。自身を監視したり、事前計画したり、出力をレビューしたり、前回何が失敗したかを記憶したりはしません。
これは批判ではなく、設計上の選択です。Claude Codeはコーディングアシスタントとして構築されており、自律型エンジニアリングエージェントではありません。私たちが常に問い続けていた質問は：それを自律型にするには何が必要か、ということでした。
その答えが私たちが「V2アーキテクチャ」と呼ぶものになりました。監視、計画、レビューでClaude Codeをラップする3層システムです。このポストでは、私たちが構築したものと、各層が存在する理由について説明します。
受動的ツール問題
Claude Codeを直接実行すると、インタラクションモデルは以下の通りです：タスクを与えて、処理して、終了する（または行き詰まる）。進捗があるかどうかを監視するプロセスはなく、実行している構造化された計画もなく、出力が実際に正しいかどうかを見直す第二の意見もありません。
実際には、これにより私たちが繰り返し遭遇した3つの障害モードが生じます：
行き詰まりループ。 Claude Codeは時々同じ失敗したアプローチを再試行する状態に陥ります。外部監視がないと、何かが間違っていることに気づくまでセッションが実行され続けます。夜間に自律的に実行している場合、それは数時間後かもしれません。
事前計画の欠如。 複数のステップや依存関係があるタスクの場合、明確な実装計画を立てずにコードに飛び込むと、回復に費用がかかるタスク中のピボットが発生します。人間のエンジニアの自然な方法はアプローチをまずスケッチすることです。Claude Codeはデフォルトではこれを行いません。
クロスレビューの欠如。 モデルが自身の出力をレビューすると、盲点があります。バグを生じさせた同じ推論がバグが大丈夫である理由を説明する根拠を生じさせることがしばしばあります。異なるトレーニング分布を持つ第二のモデルは異なるものをキャッチします。
これらはそれぞれ解決可能です。一緒になるとV2アーキテクチャになります。
V2アーキテクチャ概要
システムはClaude Codeセッションの周囲で操作する3層があります：
Layer 1: Heartbeat (watchdog)
└─ tmux session monitor
└─ detects stuck/crashed → auto-recover
Layer 2: Skill-Driven Dev (planning)
└─ SKILL.md written before code
└─ implementation blueprint
Layer 3: Dual Review (verification)
└─ Claude Code self-review
└─ Gemini CLI cross-review
Claude Codeは実際のコーディングを行います。層はそれを置き換えません。それをラップします。
レイヤー1：Heartbeat
Claude CodeはtmuxセッションのLicense。Heartbeatはそのセッションを30秒ごとにポーリングしターミナル出力を検査するウォッチドッグプロセスです。1つのことを探しています：Claude Codeのプロンプトが表示されているかどうか。これは終了して入力を待っていることを示しています。
SOCKET="${TMPDIR:-/tmp}/openclaw-tmux-sockets/openclaw.sock"
LAST5=$(tmux -S "$SOCKET" capture-pane -p -J -t claude-code:0.0 -S -5)
echo "$LAST5" | grep -q "❯" && echo "DONE" || echo "RUNNING"
❯ はClaude Codeのシェルプロンプトです。表示されている場合、セッションはアイドル状態です。タイムアウト閾値より長く表示されていない場合、何か問題があります。
Heartbeatが行き詰まったセッションを検出すると、段階的なエスカレーション順に3つの復旧戦略があります：穏やかな中断を送信するか、同じタスクコンテキストでセッションを閉じて再開するか、オーケストレーター（Orange）にページングして人間による介入を行うかです。ほとんどの行き詰まったセッションは手順1で解決します。
これは単純に見えますし、そうです。しかしそれがなければ、自律型コーディングセッションは脆弱です。Claude Codeはネットワークエラー、権限の問題、または進捗を遂行していると確信するループで行き詰まります。Heartbeatはこれらを無声の障害から処理される例外に変換します。
レイヤー2：スキル駆動開発
自明でないタスクがClaude Codeに送信される前に、オーケストレーターはSKILL.mdファイルを作成します。これは構造化された実装計画です。設計ドキュメントと同等です。Claude Codeがそれに対して実行します。
スキルファイル構造：
skills/
feature-name/
SKILL.md # implementation plan + steps
典型的なSKILL.mdは以下のものを持ちます：
- Goal — タスクが何であり、完了時がどのようなものかを定義
- Reference style — モデルにする既存コード
- Outline — 特定のセクションまたはステップ、主要な技術詳細が記入されている
- Implementation steps — 何をするか、どの順序で行うかの順序付きリスト
- Privacy/safety checklist — コミット前に検証すべき事項
これはあなたが現在その元の形式で読んでいるファイルです。このブログポストはそれ自身のSKILL.mdに対して作成されました。
計画ステップはコードが書かれる前に精密さを強制します。曖昧なタスクは計画時に明確化されます。実装中ではなく。また、完了時を推測するのではなく、Claude Codeが確認できる成功基準を提供します。
他の利点は再利用性です。スキルは時間とともに蓄積します。類似したタスクが再度発生するとき、オーケストレーターはスキルライブラリで関連パターンを検索し、既存の計画を適応させることができます。一から始めるのではなく。時間経過とともに、これは特定の種類のタスクがどのようにアプローチされるべきかについて、システムが制度的知識を構築する方法です。
レイヤー3：二重レビュー
Claude Codeが終了して変更をステージング後、コミット前に2つのレビューが実行されます。
Claude Code自己レビュー。 最初のレビューはClaude Code自体を使用します。ただし別のセッションで、書いたばかりのコードではなくdiffをレビューしています。これは単純な問題をキャッチします：残されたデバッグ出力、不完全な実装、間違ったものをテストするテストファイル。
Gemini CLI クロスレビュー。 第二のレビューはステージングされたdiffをGeminiにパイプします：
git diff --cached | gemini -p "Review this diff for: security issues, privacy leaks (IPs, emails, API keys), code quality. Output: PASSED or list of issues."
クロスレビューはより重要なものです。異なるトレーニング分布を持つ異なるモデルは、Claude Codeの自己レビューが見落とすものを確実にキャッチします。特にセキュリティの問題とプライバシーリークです。私たちはGeminiがハードコードされたテスト認証情報、公開コードにあるべきではない内部ホスト名、Claude Codeの自己レビューが意図的な設計決定として説明するロジックエラーをキャッチするのを見てきました。
出力形式は厳密です：PASSED またはイシューのリストのいずれかです。イシューがある場合、コミットはブロックされ、問題はClaude Codeに送信されて修復されます。ループはGeminiが合格するまで継続されます。
完全なV2ワークフロー
すべてを組み合わせると、オーケストレーターのAGENTS.mdはすべてのコーディングタスクの固定シーケンスを説明します：
1. memory_search → find relevant lessons and patterns from past work
2. Write SKILL.md (plan before code)
3. Launch Claude Code via tmux (with Heartbeat active)
4. Wait for Heartbeat signal: DONE
5. Gemini Review on staged diff
6. If issues: send back to Claude Code, loop
7. Commit
8. Update lessons/MEMORY.md with what was learned
ステップ1と8はシステムにメモリを提供するものです。開始する前に、オーケストレーターは同様の過去タスクからのレッスンをベクトルメモリで検索します。以前の決定、障害モード、機能したパターン。終了後、学んだことをメモリに書き込みます。時間経過とともに、これは特定の種類のタスクで測定可能にシステムが改善される反フィードバックループを作成します。
これが何ではないか
これは完全に自律的なエンジニアリングチームではありません。オーケストレーター（Orange）はまだ、本番環境に触れるもの、財務運用に関わるもの、または重要な建築上の決定を表すものについて、人間（Qiushi）の承認が必要です。V2アーキテクチャはルーチンコーディング作業を自動化します。判断は自動化しません。
またClaude Codeの置き換えでもありません。それ用のハーネスです。コーディング品質はClaude Codeから来ます。アーキテクチャはその品質がチェックされることを確認し、セッションが無音で失敗しないようにし、システムが毎回最初から始めるのではなく知識を蓄積するようにします。
原則
ここでのパターンは私たちが繰り返して戻ってくるパターンです。AIツールは単独ではなく、システムに埋め込まれている場合に最も強力です。それらを監視し、指示し、出力をチェックするシステムです。Claude Code単独は強力なコーダーです。Heartbeat、計画層、クロスレビューステップを備えたClaude Codeは信頼性の高いエンジニアリングワークフローに近いです。
同じ原則が任意の有能であるが受動的なAIツールに適用されます。ツールが仕事をします。システムは仕事に値することを確認します。
この記事は claw-stack.com で最初に公開されました。OpenClawはオープンソースのAIエージェントランタイムです。