Impact-Site-Verification: 578d421e-1081-463d-918b-ec5e29c5b9db
<戻る

AIコーディングエージェントの運用基盤

個人プロジェクト

概要

Claude Codeに仕事を任せるための運用の仕組みを自作した.作業を指定モデルのヘッドレスワーカーへ委任するCLI,委任のルールを強制するhooks,差分の規模でレビューのモデルを選ぶ仕組み,Claude Code用のスキルからなる.ファイル検索や要約などの軽い処理は,DGX Spark上でセルフホストしたローカルLLMに回す.

hooksとレビューのモデル選択

  1. 委任の強制: メインのセッションが自分で使ったツールの回数を数え,読み取り60回・編集など8回の予算を超えると拒否する.委任すれば数え直す.
  2. レビューのモデル選択: 差分が300行以上なら最上位のモデル,200〜299行なら次のモデル,200行未満なら標準のモデルにし,文書だけの変更ならレビューを出さない.機微なパス(認証情報・認証・決済・hooks),破壊的な操作(rm -rf,強制push,DROP TABLEなど),依存関係のマニフェストの変更,やり直しの変更は,規模によらず最上位のモデルにする.測れないものは必ず上の段に倒す(フェイルクローズ).
  3. hooks(登録6本): 委任の強制,rmの前のバックアップ,push前の非破壊のマージ確認,計画モードの強制,日本語の件名が化けるメール送信経路の遮断,全角句読点の検査.
  4. スキル: Claude Code用のスキルを17本自作した(外部から取り込んだものを除く).

委任CLI

呼び出し側がモデルを指定し,ヘッドレスのClaude Codeワーカーに作業を任せる.本体はBash 3,669行,集計とレビュー判定の補助はPython 2,634行(標準ライブラリのみ).CLI自体は難易度を判定せず,難易度とモデルの対応はルールとして書いている.

  1. 実行の記録: 1回の実行ごとに,モデル・役割・ターン数・セッションID・証跡のパスを1行のJSONで記録し,プロンプトも保存する.
  2. 実装の排他: 実装役のワーカーはディレクトリごとのロックを取り,2つのワーカーが同じ作業ツリーを同時に編集しないようにした.ロックが埋まっていれば,git worktreeを自動で作って並列に走らせ,終わったら元のブランチへ取り込む.
  3. テストの証跡: 実装役はテストの結果を証跡ファイルに残し,作業ツリーの指紋も記録する.レビュー役は証跡を読み,ツリーが動いていれば証跡が古いことを知らされる.
  4. 暴走の防止: ワーカーは独立したプロセスグループで監視タイマー(既定3,600秒)の下で動き,時間切れならツールの子プロセスごと止める.セッションIDを先に決めるので,止まった実行を再開できる.ワーカーからの再帰呼び出しは終了コードで拒否する.
  5. ターン数の上限は既定で設けない: 上限で止めると編集の途中で終わるため,暴走の防止は監視タイマーに任せた.
  6. MCPサーバーは指定したときだけワーカーに読み込ませ,プロンプトの共通部分を小さく保つ.

ローカルLLM

Qwen3.8-Flash-Next(NVFP4量子化)をDGX Spark上にvLLMでセルフホストし,ファイル検索・コード読解・要約・害のない機械的な編集をOpenCode経由で実行する.実装やレビューはローカルに渡さず,委任CLIとは別の経路にしている.

  1. イメージの固定: 標準のvLLMイメージはこのモデルの量子化済みテーブルを読めず,また手順が1週間に2回壊れたため,動作したイメージのタグに固定した.26.8GiBのテーブルはNVMeに置き,io_uringで読んでメモリに収めた.
  2. 採らなかった案: サブエージェントをヘッダーでローカルへ振り分ける方式は,専用の起動手段が必要でリモート操作の機能を失い,DGX Sparkが止まったときの代替経路もないため採らなかった.
  3. 安全策: シェルは読み取り専用の許可リストに限る.同じ秒に複数の実行が始まるとOpenCodeのSQLiteがロックされるため,ランダムに待って1回だけ再試行する.
  4. 観察: ローカルのモデルは「設定の既定値を変える」指示にも従ったため,任せる範囲は呼び出し側の規律で絞っている.

検証と利用の記録

  1. テスト: 委任CLIは偽のClaude CLIに差し替えたテストスイートで確かめ,2026年10月21日の実行記録では742件成功・0件失敗だった.レビューのモデル選択にも専用のテストがあり,hooksは6本中4本にテストスクリプトがある.
  2. 計測(ローカルLLMの切替時): 起動631秒,1系列で46.3トークン/秒,4系列の並列で計96.1トークン/秒,4本の並列実行はすべて正常終了した.
  3. 計測(2026年11月16日時点の実行ログ): 委任CLIの実行は3,128回(1回 = ログに残った1回の呼び出し.再開と失敗を含む).ローカルLLMの経路は139回で,うちQwen3.8-Flash-Nextでの実行は59回(それ以前は別のモデル).

使用技術

Claude CodeBashPythongit worktreeHooksOpenCodevLLMDGX SparkQwen3.8-Flash-NextDockerchezmoi