Codexで調査用サブエージェントを用意し、普段使いもしやすい状態を目指す
過去に実装済みのものに対して仕様を調査する機会が度々ある。最近はこういったものもAI Agentでやるのが楽なのでそうしているのだけど、そろそろやり方の型化をしたいなと思って色々やったので書いておく。
前提
- Codex CLI (Codex 5.4)
探索用エージェントと仕様を調べるエージェント
やりたいことから考えるとスキルでも十分なんだけど、探索という作業自体はさほど推論が必要ないので推論レベルをlowに指定しても問題ないみたい。むしろ推論しないので十分であり、考える時間を省けるのもあってトークン消費を抑えることにもつながるように思った。
作業をするなかで調査をすることになると、推論レベルを medium だったり high のまま探索を依頼する可能性がある。そうなると無駄に考え、無駄に探索し時間を消費するということが起きうる。
更にこれが曖昧なものに対して並列・複数エージェントで実行されるとトークンの消費がたまったもんじゃない。これのおかげで一度5時間制限の枠を大幅に消費してしまうことがあった。
そういう意味でも 推論レベルをlowにしたサブエージェントを飼っておいて適宜使い分ける というのができるのが良いと考えた。
また、仕様を深堀って調査しまとめるということもしたい。この2つを1エージェントにすると常に時間がかかる状態になるし、場合によっては調査が過剰だったりする。
なのでざっくり調べるエージェントと深堀りするエージェントを用意し使い分けられるようにした。
ざっくり調べるエージェント
プロンプトをどうしようかと思っていたのだけれど、組み込みのexplorerというエージェントがあり、それが向いていそうだったのでそれを活用することにした。
Subagents – Codex | OpenAI Developers Use subagents and custom agents in Codex developers.openai.com
深堀するエージェント
調査対象がWebフロントエンド、バックエンド(API, バッチ、DB)など多岐にわたるため、それぞれのレビュー観点とアウトプットのフォーマットをスキル化した。
エージェント側は、依頼内容から調査対象を割り出しスキルを使い分けて調査を行う。
今のところこの構成が結構よくてアウトプットもある程度安定しているように感じる。サブエージェントのプロンプトを一部貼っておく。
目的:
- コードから現行仕様を正確に読み取る
- 推測を避け、根拠ベースで説明する
- 仕様の抜け漏れを最小化する
基本方針:
- 必ず「主となるスキル」を1つ選択する
- 必要に応じて他の観点（API/DBなど）も補助的に確認する
- 最終出力は主スキルのフォーマットに従う
スキル選択ルール:
- 画面・ページ・URL・パス指定 → 画面スキル
- API・endpoint・controller → APIスキル
- job・batch・cron・worker → バッチスキル
- table・schema・migration → DBスキル
AGENTS.mdの整備
これだけでは使い分けられないので、以下のようなプロンプトを追加した
作業開始時に、まず依頼内容を「実装」「一次確認」「仕様調査」「レビュー」のどれに当たるか判定する
- 一次確認に該当する場合
- 最初に explorer 系の low推論サブエージェントを使う
- 仕様調査に該当する場合
- 最初に spec-investigator を使う
## サブエージェント活用の実行原則
- 利用できる場合はサブエージェントを最大限活用する
- 作業を分担し並列で実行できる場合は並列で進める
- サブエージェントに作業を渡す場合は、完全に委譲しメインのエージェントは同様の作業を行わない
これによってやり方の確定と適切に委譲することを狙っている。
追加してからはサブエージェントを適切に使い分けられるようになったり、メインのエージェントが調査しないようになったと感じる。
他にも書いているけれど大まかなハンドリングなどはこの辺り。
あと、地味に制御を入れた部分は以下。
## spec-investigator の出力ルール
- spec-investigator に調査を依頼する場合は、結果が大きくなることを前提として、常に Markdown ファイルへ出力すること。
- 出力ファイル名は 調査タイトル.md 形式とし、調査内容が識別しやすい日本語タイトルを付けること。
調査結果の出力までサブエージェントがやってくれた方がいいんだけど、広範囲に調査する可能性があるのでsandbox的にRead-Onlyにしておきたいというのがあり出力はメインエージェント側に寄せた。
サブエージェントは明示的に指定する必要がある
前回の記事でサブエージェントを作ったりはしている。
しかし、実際は上手く使えなかったりして困っていたが、ようやく状況を理解した。
Codexの場合、ユーザーが明示的に「利用して」と言わない限りサブエージェントを使えないという制御が入っているらしい。これはAGENTS.mdに「サブエージェントを活用して」みたいに書いておいても先述の制御と競合し制御側が優先されるらしい。
skillに入れておいてそのスキルを明示的に呼び出すのは？と思ったけどそれも無効らしく。プロンプトに含め忘れる状態と向き合わないといけなそうだった。
「明示的に使って」と言ったことにする方法が無いかを使い方踏まえて考えたが 確認させる ことに落ち着いた。
## 調査系タスクのサブエージェント確認ルール
- 調査系の依頼だと判断した場合、ユーザーが依頼文でサブエージェント利用を明示していないときに限り、着手前にサブエージェントを活用するかを確認すること。
- ユーザーが依頼文または確認応答でサブエージェント利用を肯定した場合は、サブエージェントを使って進めること。
これにより「サブエージェントを活用して」と言えばそのまま活用するし、プロンプトに付与し忘れていれば、使いますか？と聞いてくれるようになった。yesと答えればいいだけ。
これができたときはなんだかすごく達成感があった。
今後やりたいこと
レビュー時も様々な観点でレビューさせることになるので、このあたりもサブエージェントを活用し、良い感じに時間効率よく解決していきたい