コード補完からコードチームへ：Claude Codeをエンジニアリング部門に変えた方法

私たちは毎日Claude Codeを使用しています。優れています。複雑なリファクタリング、テスト作成、大規模コードベースのナビゲーション、見落としたバグの発見を処理します。しかし、数ヶ月間それを自律型マルチエージェントシステムの一部として実行した後、私たちはあることに気づきました：Claude Codeは強力なツールですが、基本的に受動的です。命令を待って、実行して、停止します。自身を監視しない、事前計画をしない、自分の出力をレビューしない、または前回何が間違ったかを覚えていません。

これは批判ではなく、設計上の選択です。Claude Codeはコーディングアシスタントとして構築されており、自律型エンジニアリングエージェントではありません。私たちが常に抱いていた質問は：それを自律型に変えるにはどうすればよいかということでした。

その答えが、私たちがV2アーキテクチャと呼ぶものになりました：Claude Codeを監視、計画、レビューでラップする3層システムです。このポストでは、何を構築したか、そして各層が存在する理由について説明します。

受動的ツールの問題

Claude Codeを直接実行すると、相互作用モデルは：タスクを与える、それが処理する、完了する（またはスタックする）。進捗を監視するプロセスはなく、実行している構造化された計画もなく、出力が実際に正しいかについての第二の意見もありません。

実際のところ、これは私たちが繰り返し遭遇する3つの失敗モードを作成します。

Permission prompts（許可プロンプト）。 Claude Codeはファイル読み取り、コマンド実行、ディレクトリアクセスの許可を頻繁に要求します。対話的セッションではそれで問題ありません—承認するだけです。しかし自律的に実行する場合、これらのプロンプトはセッション全体を停止させます。承認する人がいないため、タスクは停止するだけです。

最初のパスはめったに十分ではない。 Claude Codeはタスクを完了して技術的には機能しますが、実際にテストしてみると—アプリを実行する、出力をチェックする、エッジケースを確認する—調整が必要です。初期実装はコーナーケースを見落とすかもしれません、または出力形式が正しくないか、ローカルでは機能しますが本番環境で破損します。人間のエンジニアは結果を見て、デバッグして、イテレーションします。Claude Codeはデフォルトでは「完了」と宣言して待機するだけです。これはV2で構築しようとしているものです—Coderエージェントが人間在ループとして機能して、Claude Codeを監視し、出力をテストし、実際の結果を評価し、別のパスのための改良されたプロンプトを提供します。単一ショットツールを反復開発ループに変換します。

クロスレビューなし。 モデルが自分の出力をレビューすることには盲点があります—バグを生成したのと同じ推論がバグが問題ないという根拠を生成することが多いです。異なるトレーニング分布を持つ2番目のモデルが異なる問題をキャッチします。

これらは解決可能です。一緒になるとV2アーキテクチャになります。

V2アーキテクチャ概要

このシステムには、すべてのClaude Codeセッションの周りで動作する3層があります：

Layer 1: Heartbeat (watchdog + supervisor)
  └─ tmux session monitor
  └─ detects stuck/permission prompts → review + 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は実際のコーディングを行います。層はそれを置き換えません—ラップします。

Layer 1: Heartbeat

Claude Codeはtmuxセッションで実行されます。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はこれらをサイレント失敗から処理される例外に変換します。

スタックセッションを検出するだけを超えて別の次元があります：許可監督です。Claude Codeが許可承認を待っているとき、Coderエージェントは盲目的に承認しません—それはClaude Codeが何をしようとしているのかをレビューします。このコマンドは妥当ですか？安全ですか？破壊的である可能性がありますか？Coderはベビーシッターではなく、スーパーバイザーとして機能します。スタックセッションを監視し、人間の代わりに情報に基づいた同意を提供します。これにより、自律型コーディングは信頼性と安全性の両方になります。

Layer 2: Skill-driven development

些細ではないタスクが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に完了時を推測するのではなく、成功基準をチェックするために提供します。

もう1つの利点は再利用です。スキルは時間とともに蓄積します。同様のタスクが再度発生した場合、オーケストレータはスキルライブラリで関連パターンを検索し、最初からではなく既存の計画を適応させることができます。時間とともに、システムが特定のタイプのタスクにアプローチする方法についての制度的知識を構築する方法です。

Layer 3: Dual review

Claude Codeが完了して変更をステージングした後、2つのレビューがコミット前に実行されます。

Claude Code self-review。 最初のレビューはClaude Code自体を使用します—ただし別のセッションで、それが書いたばかりのコードではなくdiffをレビューします。これにより簡単な問題がキャッチされます：デバッグ出力の残骸、不完全な実装、間違ったものをテストするテストファイル。

Gemini CLI cross-review。 2番目のレビューはステージングされた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ツールに適用されます。ツールは仕事をします。システムは仕事が保つ価値があることを保証します。