KB

Appearance

マルチエージェント委譲構成（Claude Code = PM） ​

Claude Code を PM/オーケストレーター とし、サブタスクを外部CLIエージェント（codex / opencode / 別claude）へ非対話（ヘッドレス）で委譲する構成。

設計判断 ​

  • 異種CLIエージェントを繋ぐため、A2A等の重いプロトコルではなく「ヘッドレス実行 + オーケストレーション」が現実解。
    • MCP = エージェントに能力(ツール)を与える / A2A = エージェント同士でタスク委譲。今回はPMが一方的に呼ぶ非対称構成で、CLIが未対応のためラッパー自作コストに見合わない。
  • PMの責務: ①要件確定 → ②タスク分解 → ③委譲 → ④検証・統合。ワーカー出力は鵜呑みにせずPM側で検証。実装系は /review 前提。

実装: /delegate スキル ​

~/.claude/commands/delegate.md。/delegate <tool> <task> で委譲。

ワーカーの選び方 ​

  • opencode — 生成・調査・要約・ドラフト・定型コード（最軽量）
  • codex — ファイル編集を伴う実装/リファクタ/レビュー（git管理下）
  • claude — 高度推論・複雑な多段作業をサブで
  • ファイル探索のみ → 委譲せず組み込み Explore

委譲の原則 ​

  1. 入出力はファイルで受け渡し、出力はログファイルに逃がしコンテキストには差分・要点だけ
  2. 独立タスクは run_in_background で並列化
  3. 書込を伴う委譲は作業ディレクトリを明示

確認済み 実コマンド（2026-06-22 実機検証 / 全て exit=0） ​

bash
# opencode（生成・調査）※末尾に装飾行が混じる→末尾の実回答を拾う
opencode run "<指示>" > out.md 2>&1
#   -m provider/model / -c 継続 / -f 添付 / --format json

# codex（実装・編集）※ -o に最終メッセージだけ出る→これを読む
codex exec "<指示>" -C <dir> -s workspace-write -o last.md --json > events.jsonl 2>&1
#   読取専用調査 -s read-only / git外 --skip-git-repo-check / 追加書込 --add-dir

# claude（サブ推論）
claude -p "<指示>" --output-format text --permission-mode acceptEdits --add-dir <dir> > out.md 2>&1
#   --allowedTools "Read Edit Bash" / --model / --output-format json

opencode 実装役エージェント (build) ​

opencode を「実装役」として呼びやすくするため、専用 agent を定義（2026-06-22）。

  • 定義: ~/.config/opencode/agent/build.md（frontmatter + body=system prompt）
  • 既定モデル litellm/nim-gpt-oss-120b（実装は精度優先。難問5/5・186tok/s。ベンチは [[litellm-proxmox-opencode]]）
  • permission: edit/bash allow、temperature: 0.2、mode: all
  • 呼び出し: opencode run --agent build "<実装指示>" --dir "<projectルート>"
  • opencode agent list で認識確認可。生成・調査は agent 無し（既定 gemma4-12b）で十分。

ハマりどころ（実機検証 2026-06-22） ​

  • 書込は git 管理下（プロジェクトルート）で実行必須。opencode はプロジェクト境界を git 等で判定し、境界外パスへの書込は external_directory permission が非対話実行では auto-reject されて失敗する。
  • git 未初期化ディレクトリを --dir に渡すと、ルートを / と誤認して Glob/Write が全拒否される。委譲前に対象が git リポジトリか確認（必要なら git init）。
  • /var/folders(TMPDIR) 配下も external 扱いで拒否。テストは home 配下の git リポジトリで。

tmux で進行を人間が目視（2026-06-22 実証） ​

委譲を裏で走らせず人間がリアルタイム監視したいとき、PMが detached tmux セッションにウィンドウを足し、人間は tmux attach -t delegate で覗く。PMは tee ログで結果取得、tmux wait-for で完了同期、tmux capture-pane -p で attach せず途中経過を覗ける。

bash
S=delegate; LOG="${TMPDIR:-/tmp}/delegate-$(date +%s).log"
tmux has-session -t "$S" 2>/dev/null || tmux new-session -d -s "$S"
tmux new-window -t "$S" -n build \
  "cd <proj> && (<cmd> 2>&1 | tee $LOG); echo '--- DONE ---'; tmux wait-for -S build-done; exec \$SHELL"
# PM完了待ち: tmux wait-for build-done を run_in_background で → 完了で自動再開、$LOG から結果取得
  • exec $SHELL でペインを残すこと。付けないと完了時にウィンドウ/セッションが消え、人間が後から attach できない（実証で確認した落とし穴）。
  • 複数委譲は同セッションに別名ウィンドウ＋別トークン（-S <name>-done）で並列監視。
  • 検証済み: tee記録 / wait-for同期 / capture-pane覗き見 / exec $SHELL でのペイン残存。

関連 ​

  • opencode のモデル接続・ベンチは [[litellm-proxmox-opencode]] 参照。