Claude Codeサブエージェントのアンチパターン5つ。「伝えたつもり」で空振りするNG例と直し方

Posted at 2026-07-03

先に前提をひとつ。Claude Codeのサブエージェントは、メインの会話を読んでいません。コンテキストは共有されず、毎回まっさらで起動します。ここを知らないまま使うと、エラーは出ないのに、静かに空振りします。

自分が実際に踏んだ（踏みかけた）NGを5つ、悪い例と直し方で並べます。

1. 前提を「知っている」つもりで投げる

いちばん多い空振りです。メインの会話でどれだけ丁寧に方針を詰めても、サブエージェントには一行も渡っていません。

❌ NG：メインで決めた方針を「さっきの」で参照する
さっき決めた方針でこの記事をレビューして。

✅ OK：前提を依頼文に全部書く
以下の基準でこの記事をレビューして。
- 語尾が単調にループしていないか
- 禁止語（例: いかがでしたか）が入っていないか
- 見出しだけで内容が推測できるか

なぜ。サブエージェントに「さっき」は存在しません。会話の続きに見えるUIが罠で、実際は口頭の引き継ぎゼロで新人に仕事を投げている状態です。的外れな結果が返ってきたら、モデルより先に、自分の引き継ぎを疑うのが早道です。

毎回プロンプトに書くのは、依頼が増えると破綻します。会話は揮発します。

❌ NG：長い方針を、毎回コピペで依頼文に貼る
（依頼のたびに20行の基準を貼り付ける）

✅ OK：方針をファイルに固定して、読ませてから始める
docs/review-policy.md にレビュー観点をまとめてある。
まずそれを読んでから、この記事をレビューして。

なぜ。ファイルは揮発しません。サブエージェントへの受け渡しが一行で済むうえ、方針そのものが会話の外に固定されるので、自分でも見直せます。エージェントの定義ファイル（.claude/agents/ 配下）に観点を書いておくのも同じ効きかたをします。

切り出した先で「直しておいて」までやらせると、静かにズレます。

❌ NG：調査から修正の実施まで、一括で任せる
このコードの問題点を見つけて、全部直しておいて。

✅ OK：レポートだけ持ち帰らせて、採否はメインで決める
このコードの問題点を、重要そうな順にリストで報告して。
修正はまだしないで。

なぜ。エージェント間のコンテキストは分かれているので、サブ側は全体の事情（直したくない箇所、あとで消す予定のコード）を知りません。判断材料を持っているのはメイン側です。調査や指摘のような「大量に読む仕事」を任せて、決めるのは自分。この分担にしてから、手戻りが目に見えて減りました。

分離の便利さを覚えると、何でも切り出したくなります。これは逆効果でした。

❌ NG：数行の修正をわざわざサブエージェントに
この関数の変数名をリネームしておいて。
（起動＋前提の受け渡しのほうが、本体より重い）

✅ OK：切り出すのは「大量に読む」作業だけ
・コードベース全体から該当箇所の洗い出し
・長いログの解析
・レビュー、影響範囲の調査
→ こういう読む系をサブに。数行の修正はメインでそのまま。

なぜ。サブエージェントは起動のたびにコストがかかり、前提の受け渡しにもトークンを食います。5分の仕事のために研修をしていたら本末転倒です。切り出す基準は「読む量」。メインの机（コンテキスト）を汚すほど読む仕事だけ、外に出します。

親のコンテキストを継承する起動方法もあります。便利ですが、これを前提に組むのは危うい。

❌ NG：「forkなら会話を引き継ぐから」前提の運用
（起動元によって挙動が違い、環境が変わると静かに壊れる）

✅ OK：継承の有無に関係なく成立する受け渡しにする
渡したい前提は、ファイルか依頼文で明示的に渡す。
継承されたら儲けもの、くらいの位置づけにしておく。

なぜ。forkまわりは実行サーフェスによって挙動が分かれる報告があり、継承をあてにした設計は移植性が低くなります。明示的に渡す設計にしておけば、どの起動方法でも同じに動きます。暗黙の共有に頼らない、が結局いちばん頑丈でした。

分離は欠陥ではなく、メインのコンテキストを守るための仕様です。「知らない相手に、明示的に渡す」に振り切ってから、空振りはほぼなくなりました。役に立ったらストックして、サブエージェントを組むとき見返してください。

ふだんはraplsworks.comで、WordPressプラグイン開発やClaude Codeまわりのことを書いています。