Codexのサブエージェントを「育てる」ための小技2つ

AI駆動開発していますか？ みらい翻訳のプラットフォーム開発部で VPoE 兼アーキテクトをしている Satie です。

私は Codex をよく使っています。ソースコードが GitHub で公開されているため、内部実装を確認しながら進められます。ドキュメントや Web 上の説明が多少古かったり、説明が不足していたりしても、最終的にはソースを読めば「何をしているのか」を確かめられる。この安心感が、マルチエージェント前提の AI 駆動開発ライフサイクルを改善していく上で大きな助けになっています。

今回は、Codex のサブエージェント運用で役立った Tips を 2 つ紹介します。なお、確認した Codex のバージョンは v0.116.0 です。

Tips1: サブエージェントにニックネームを付けられる

プロジェクトディレクトリの .codex/config.toml で、agents.<エージェント名> テーブルに nickname_candidates を配列で指定できます。

[agents.planner]
description = "相談内容を整理し、論点整理、方針案、実行プラン、タスク化を行う。"
config_file = "agents/planner/config.toml"
nickname_candidates = ["Pikachu", "Charmander", "Eevee"]

これを設定しておくと、サブエージェントが spawn されたときに候補の 1 つ（例: Charmander）がニックネームとして表示されます。

ちょっとしたことですが、ログを見るときの愛着が増し、「このエージェントをもっと良く育てよう」という気持ちになりやすいのでおすすめです。

なお、codex-rs/core/src/config/agent_roles.rs 426行目付近にあるように使える文字は ASCII 英数字、空白、- 、_ に制限されているようです。

    if !normalized_nickname
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || matches!(c, ' ' | '-' | '_'))

Tips2: サブエージェントが思うように spawn されないとき

メインエージェントに「こういうときはサブエージェントを作って」とオーケストレーションの指示（AGENTS.md など）を書いていても、期待したほどサブエージェントが生成されず、メインエージェントがそのまま処理してしまうことがあります。

もちろん「この入力はサブエージェントを作るほどの複雑さではない」と判断される場合もあります。しかし、それだけでは釈然としないケースもあります。

Codex の実装を追うと、次のような趣旨の指示が codex-rs/core/src/tools/spec.rs の該当箇所（1093 行目付近）にハードコードされているようでした。

• ユーザーが明確に「サブエージェントを使って」「委譲して」「並列でやって」と依頼した場合に限り、spawn_agent を使う

この挙動は公式ドキュメントにも記載があります。

Subagents – Codex | OpenAI Developers

では、毎回「サブエージェントを使って」と言葉で明示すればよいのでしょうか。流石に面倒です。実装を変えずに対処するなら、大きく 2 つの方向性が考えられます。

1. 設定でハードコード相当の指示を上書きする
2. こちらの運用ルールで「サブエージェント利用を明示しやすく」する

1) 設定でハードコード相当の指示を上書きする

codex-rs/core/src/config/mod.rs の実装を見る限り、developer_instructions が設定ファイル経由で上書きできそうです。たとえば、プロジェクトの .codex/config.toml のトップレベルに次のように書くイメージです（※未検証）。

developer_instructions = """
サブエージェントは必要に応じて生成してよい。
"""

ただし、Codex がデフォルトで「明示的に依頼されたときだけサブエージェントを使う」制約を置いている理由も理解しておく必要があります。

公式ドキュメントにもある通り、サブエージェントはトークン消費（≒コスト）が増えやすいです。

Subagents – Codex | OpenAI Developers

加えて（これは主観ですが）、サブエージェントに任せたときの品質ブレや、原因切り分けの難しさを避ける意図もあるのだと思います。デフォルト値として agents.max_threads=6 や agents.max_depth=1 のように、並列数や再帰的生成を抑える設定が用意されているのも、その延長線上に見えます。

私は今のところこの「上書き」は試していません。

2) 運用ルールで「サブエージェント利用を明示しやすく」する

個人的にはこちらがおすすめです。毎回長文で明示するのではなく、入力の先頭に短い合図を付けるだけで「明示したことにする」ルールを決めます。

たとえば、プロジェクトの AGENTS.md に次のような一文を追加します。

## サブエージェント利用の明示許可

ユーザーが `/subagent` で始まる依頼をした場合、その依頼は既存サブエージェントの利用を明示的に許可したものとして扱う。

このルールを入れておくと、「今回は並列に分けて考えてほしい」「レビューや調査を分担してほしい」といった場面で、依頼の先頭に /subagent を付けるだけで意図が伝わりやすくなります。

また、サブエージェントの挙動が期待通りだったかどうかを見て、期待と違えば各サブエージェントの指示文（役割）を改善する、というフィードバックサイクルも回しやすくなります。