AIコーディングエージェントの運用基盤
個人プロジェクト
概要
Claude Codeに仕事を任せるための運用の仕組みを自作した.作業を指定モデルのヘッドレスワーカーへ委任するCLI,委任のルールを強制するhooks,差分の規模でレビューのモデルを選ぶ仕組み,Claude Code用のスキルからなる.ファイル検索や要約などの軽い処理は,DGX Spark上でセルフホストしたローカルLLMに回す.
hooksとレビューのモデル選択
- 委任の強制: メインのセッションが自分で使ったツールの回数を数え,読み取り60回・編集など8回の予算を超えると拒否する.委任すれば数え直す.
- レビューのモデル選択: 差分が300行以上なら最上位のモデル,200〜299行なら次のモデル,200行未満なら標準のモデルにし,文書だけの変更ならレビューを出さない.機微なパス(認証情報・認証・決済・hooks),破壊的な操作(rm -rf,強制push,DROP TABLEなど),依存関係のマニフェストの変更,やり直しの変更は,規模によらず最上位のモデルにする.測れないものは必ず上の段に倒す(フェイルクローズ).
- hooks(登録6本): 委任の強制,rmの前のバックアップ,push前の非破壊のマージ確認,計画モードの強制,日本語の件名が化けるメール送信経路の遮断,全角句読点の検査.
- スキル: Claude Code用のスキルを17本自作した(外部から取り込んだものを除く).
委任CLI
呼び出し側がモデルを指定し,ヘッドレスのClaude Codeワーカーに作業を任せる.本体はBash 3,669行,集計とレビュー判定の補助はPython 2,634行(標準ライブラリのみ).CLI自体は難易度を判定せず,難易度とモデルの対応はルールとして書いている.
- 実行の記録: 1回の実行ごとに,モデル・役割・ターン数・セッションID・証跡のパスを1行のJSONで記録し,プロンプトも保存する.
- 実装の排他: 実装役のワーカーはディレクトリごとのロックを取り,2つのワーカーが同じ作業ツリーを同時に編集しないようにした.ロックが埋まっていれば,git worktreeを自動で作って並列に走らせ,終わったら元のブランチへ取り込む.
- テストの証跡: 実装役はテストの結果を証跡ファイルに残し,作業ツリーの指紋も記録する.レビュー役は証跡を読み,ツリーが動いていれば証跡が古いことを知らされる.
- 暴走の防止: ワーカーは独立したプロセスグループで監視タイマー(既定3,600秒)の下で動き,時間切れならツールの子プロセスごと止める.セッションIDを先に決めるので,止まった実行を再開できる.ワーカーからの再帰呼び出しは終了コードで拒否する.
- ターン数の上限は既定で設けない: 上限で止めると編集の途中で終わるため,暴走の防止は監視タイマーに任せた.
- MCPサーバーは指定したときだけワーカーに読み込ませ,プロンプトの共通部分を小さく保つ.
ローカルLLM
Qwen3.8-Flash-Next(NVFP4量子化)をDGX Spark上にvLLMでセルフホストし,ファイル検索・コード読解・要約・害のない機械的な編集をOpenCode経由で実行する.実装やレビューはローカルに渡さず,委任CLIとは別の経路にしている.
- イメージの固定: 標準のvLLMイメージはこのモデルの量子化済みテーブルを読めず,また手順が1週間に2回壊れたため,動作したイメージのタグに固定した.26.8GiBのテーブルはNVMeに置き,io_uringで読んでメモリに収めた.
- 採らなかった案: サブエージェントをヘッダーでローカルへ振り分ける方式は,専用の起動手段が必要でリモート操作の機能を失い,DGX Sparkが止まったときの代替経路もないため採らなかった.
- 安全策: シェルは読み取り専用の許可リストに限る.同じ秒に複数の実行が始まるとOpenCodeのSQLiteがロックされるため,ランダムに待って1回だけ再試行する.
- 観察: ローカルのモデルは「設定の既定値を変える」指示にも従ったため,任せる範囲は呼び出し側の規律で絞っている.
検証と利用の記録
- テスト: 委任CLIは偽のClaude CLIに差し替えたテストスイートで確かめ,2026年10月21日の実行記録では742件成功・0件失敗だった.レビューのモデル選択にも専用のテストがあり,hooksは6本中4本にテストスクリプトがある.
- 計測(ローカルLLMの切替時): 起動631秒,1系列で46.3トークン/秒,4系列の並列で計96.1トークン/秒,4本の並列実行はすべて正常終了した.
- 計測(2026年11月16日時点の実行ログ): 委任CLIの実行は3,128回(1回 = ログに残った1回の呼び出し.再開と失敗を含む).ローカルLLMの経路は139回で,うちQwen3.8-Flash-Nextでの実行は59回(それ以前は別のモデル).
使用技術
Claude CodeBashPythongit worktreeHooksOpenCodevLLMDGX SparkQwen3.8-Flash-NextDockerchezmoi