Article

AIエージェントを増やしすぎたときの整理方法

Claude Codeのカスタムサブエージェントを増やしすぎて、どれを使えばよいか分からない・コストが膨らむ・誰も保守していない状態を整理する手順をまとめます。役割の棚卸し、統合と廃止、`/agents`での確認、運用ルールの再設計までを公式仕様に沿って解説する、エージェント運用が混乱したチーム向けの実務ガイドです。

This article is not published in this language yet, so the Japanese version is shown instead.

Claude Codeのカスタムサブエージェントを「便利そうだから」と作り続けると、半年もすればreviewer／code-reviewer／pr-reviewのような重複が並び、誰も保守しない状態になります。本記事は、増えすぎたエージェントを棚卸しして再設計するための手順を、公式仕様に沿って整理します。

結論：エージェントは「使われ続けているか」で再評価する

Anthropic公式のサブエージェント仕様では、カスタムサブエージェントは.claude/agents/配下や~/.claude/agents/にYAMLフロントマター付きMarkdownで保存されます（Sub-agents）。仕組みが軽い分、増やすのも簡単で、消すきっかけがないまま残り続けます。

整理の判断軸は3つで十分です。

使用頻度：直近1〜3か月で実際に呼ばれたか
責務の重複：別名で同じ仕事をしているエージェントがいないか
保守者：誰が中身を更新するか決まっているか

ひとつでも欠けたら、統合・廃止・保守者の再割り当てのいずれかを選びます。

増えすぎているサイン

整理に着手すべきかどうかは、次の症状で判断できます。

症状	何が起きているか
`/agents`の一覧が画面に収まらない	数が多すぎて呼び分けの基準が記憶できない
似た名前が複数ある（`reviewer`／`pr-reviewer`／`code-review`）	責務が分かれていない
メンバーごとに自作エージェントが`~/.claude/agents/`に増殖	個人スコープの可視化がない
サブエージェント呼び出しの体感コストが上がった	各エージェントがCLAUDE.md・MCP・Skillsを独立ロードしている
半年触っていない定義がある	description／中身が現状と乖離している

ひとつでも当てはまるなら、本記事の手順を回す時期です。

ステップ1：棚卸しする

最初にやるのは「いま何があるか」の確認です。場所と数を機械的に列挙します。

ls -1 .claude/agents/ 2>/dev/null && ls -1 ~/.claude/agents/ 2>/dev/null

Claude Codeの中からは/agentsで一覧と説明を確認できます。CLIから一覧だけ取りたい場合は次のとおりです。

claude agents list

棚卸しの出力は、人間が読める表に整えます。表計算でもMarkdownでも構いません。最低限の列は次のとおりです。

列	内容
name	エージェント名
scope	`project` / `user` / `managed` / `plugin`
description	frontmatterの説明（30字以内に要約）
tools	許可しているツール
model	`haiku` / `sonnet` / `opus` / `inherit`
last_updated	`git log -1 --format=%cs` の結果
owner	保守者（決まっていなければ「未定」）
usage_30d	直近30日で呼んだ記憶／ログ

last_updatedとownerが空のものは、それだけで廃止候補に上がります。

ステップ2：重複を統合する

棚卸し表ができたら、まず重複を潰します。重複の見抜き方は単純で、descriptionの30字要約を読み比べて、同じ仕事に見えるものを束ねます。

統合の典型パターンは次の3つです。

同義名の集約：reviewer／code-reviewer／pr-reviewの3つをcode-reviewerに統一。残り2つは削除し、よく使われていた呼び方はdescriptionに「コードレビュー（旧reviewer）」と書いておく
入出力が同じものの集約：bug-investigatorとerror-analyzerが両方「スタックトレースから原因仮説を出す」なら統合
モデル違いの統合：reviewer-haikuとreviewer-opusを1つにまとめ、依頼文側で「軽くチェック」「詳しく見て」を使い分ける。frontmatterのmodel: inheritにすると親の判断に従う

統合のときに注意するのは、tools／permissionMode／mcpServersの設定です。これらは依存関係が暗黙のうちに広がっているので、統合先のエージェントには「両方の和集合」ではなくより厳しい最小集合を採用します。広げてしまうと、消した側の権限がいつの間にか残ります。

ステップ3：廃止する

統合のあとは廃止候補を機械的に消します。基準は3つ全部に当てはまる場合です。

直近90日呼んだ記憶がない
同じ仕事を別のエージェントまたは標準機能（Plan Mode、Skills、組み込みのExplore／general-purpose）で代替できる
保守者が決まっていない

削除はファイル削除で完結します。エージェント定義は.claude/agents/<name>.mdまたは~/.claude/agents/<name>.mdのテキストファイルです。

git rm .claude/agents/old-reviewer.md

個人スコープ（~/.claude/agents/）はgit管理されていないことが多いので、削除する前にチームのSlackやNOTES/に「この名前は廃止」と告知してから消します。あとから「誰かのローカルでは生きている」状態にしないためです。

ステップ4：作る基準を再設計する

整理しただけでは半年後に同じことになります。次に作る人向けの基準を、チームのCLAUDE.mdまたは.claude/rules/agents.mdに短く書きます。

書く項目は次の5つで足ります。

1責務：1つのエージェントは1つの仕事だけ。複数仕事を持つなら依頼文で分ける
命名規則：<動詞>-<対象>に揃える（review-pr、investigate-error）。reviewerのような体言止めは禁止
モデル選択：探索＝haiku、品質チェック＝sonnet、複雑推論＝opus、迷ったらinherit
scope：チーム共有は.claude/agents/へ。試作は~/.claude/agents/、本採用したらprojectに移す
保守者：frontmatterに# Owner: <name>のコメント行を必須にする（公式fieldにはないが運用ルールとして）

判断軸の根拠は「Claude Codeのサブエージェントはいつ使うべき？判断基準を整理」、コスト面の根拠は「Claude Codeのトークン消費を抑えるサブエージェント運用」にまとめています。

ステップ5：定期見直しを仕込む

「作る基準」と「消す基準」が決まったら、見直しの周期も決めておきます。月1回・PRレビューの一環で十分です。

見直しチェックリストは次の3項目で回します。

直近30日で1度も呼ばれていないエージェントの保守者が説明できるか
似た名前が新しく増えていないか（/agentsを画面に出して目視）
frontmatterのdescriptionが、いま実際にやっている仕事と合っているか

3つともクリアできない月が続くなら、整理の頻度を上げます。チームでの導入と運用ルール全体は「チームでClaude Codeを導入するときに最初に決めるルール」に寄せています。

やってはいけないこと

「念のため残す」：呼ばれていないエージェントはdescriptionも更新されないので、いざ呼ばれると別物として動く
権限の和集合で統合：統合のときは最小権限に寄せる
~/.claude/agents/の個人エージェントを暗黙の前提にする：他のメンバーには存在しない。共有が必要なら.claude/agents/へ移す
MCPサーバーを「エージェント専用」と思い込む：MCPはセッション単位の設定で、エージェント側で参照を絞っても親セッションの定義は残り続ける（「Claude CodeとMCPサーバーの基本」参照）