Claude CodeのAgent descriptions警告(15.0kトークン超)の直し方

「Agent descriptions are over the 15.0k-token limit」とは何の警告か

この警告は、自分で用意したサブエージェントの説明文が多すぎるときに、起動時の通知として会話画面に出ます。標準エラー出力ではなく、会話ビューの起動通知として表示される点が特徴です。

Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

括弧内の ~16.2k tokens は、Claude Codeが見積もった現在の合計です。この例なら上限を約1.2k超えています。

数える対象は、組み込みを除くサブエージェントの name と description です。1つのagentにつき、名前と description フロントマターを足した分が加算され、本文(システムプロンプト)は数に入りません。プラグインや管理設定で配られたagent、--agents で渡したagentも組み込みではないので、数える対象です。上限の15,000トークンはClaude Codeの推定値です。

誤解されやすいのは、警告が読み込みの可否を変えない点です。agentは全部読み込まれます。ただ、説明文はClaudeが「どのagentに任せるか」を決めるために毎回見せられる情報なので、増えるほどコンテキストを食います。

まず合計を減らすべきか判断する

警告が出たからといって、すぐ壊れるわけではありません。次の表で、今の状況に近い行を探してください。

説明文が短くなりすぎると、Claudeが適切なagentを選べなくなります。説明文は「いつ委任するか」を伝える欄です。削る対象は手順や背景であって、使う場面の一文ではありません。

手順1: どのagentが重いかを測る

警告は合計しか教えてくれません。どのファイルを直すかは自分で決める必要があります。次のスクリプトは、description の文字数が大きい順にagentを並べます。トークンそのものではなく、削る優先順位を決めるための目安です。

find .claude/agents ~/.claude/agents -name '*.md' 2>/dev/null | while read -r f; do
  n=$(grep -m1 '^description:' "$f" | wc -c)
  echo "$n $f"
done | sort -rn | head -10

注意点が2つあります。

• description: が複数行のYAML(> や | で書いた形)だと、1行目しか数えられません。その場合は目で確認します
• .claude/agents/ はサブフォルダも再帰的に走査されるため、スクリプトも find で階層の下まで見ています(zshでファイルが無いglobが no matches found で止まる問題も避けられます)

プロジェクトの .claude/agents/ と ~/.claude/agents/ は別の場所ですが、どちらも合計に入るので、両方を確認します。プラグインが持つ agents/ ディレクトリのagentも組み込みではないため、合計に入ります。

手順2: descriptionを削る

削り方の基本は、説明文を「いつ使うか」だけにすることです。手順や出力形式は、agentファイルの本文に移します。本文はそのagentが実行されるときにだけ読み込まれます。

---
name: code-reviewer
description: コードを変更した直後に使うレビュー担当。差分を読み、命名・エラー処理・テストの有無・セキュリティ上の懸念を順に確認し、重大度ごとに分けて箇条書きで報告する。指摘は必ずファイル名と行番号を添える。
---

---
name: code-reviewer
description: コード変更の直後に差分をレビューする。品質とセキュリティの指摘が欲しいときに使う。
---
 
確認順:命名、エラー処理、テスト、セキュリティ。
重大度ごとに箇条書きで報告し、ファイル名と行番号を添える。

上の例は一例です。確認順や報告形式は本文に移しても、agentが動くときにはそのまま読まれます。一方で一覧に載る説明文は短くなります。

Claudeに任せる方法もあります。警告の文面自体が「Claudeに説明文を削らせる」ことを案内しているので、次のように頼めます。

.claude/agents/ のdescriptionを、使う場面が分かる1〜2文まで短くして。
手順や出力形式は本文に移して。削った前後の文字数を表にして見せて。

差分は、実行後に git diff で確かめます。削った結果、似た説明文が2つ並んで見分けがつかなくなっていないかも見てください。説明文は、1つのagentだけに振り分けられる程度には具体的に残します。

手順3: 使っていないagentを消す

説明文を削るより早いのは、使っていないagentファイルの削除です。プロジェクト用のagentはGitで管理していることが多いので、消しても履歴から戻せます。

消さずに止めたいだけなら、設定の permissions.deny に Agent(名前) を書く方法があります。これでClaudeが特定のサブエージェントを使えないようにできます。

{
  "permissions": {
    "deny": ["Agent(my-custom-agent)"]
  }
}

ただし、エラー一覧のこの警告の説明にもサブエージェントのページにも、deny が警告の合計に効くかどうかの記述はありません。警告を消すことが目的なら、ファイルを消すか、説明文を削るほうが確実です。

直したあとの確認

.claude/agents/ と ~/.claude/agents/ は変更が数秒で検出され、次の委任から新しい定義が使われます。ただし、監視の対象はセッション開始時に存在していたディレクトリだけです。agentsディレクトリを新しく作った直後は、再起動が必要です。

警告は起動通知なので、消えたかどうかを確かめるには、新しくClaude Codeを起動します。

警告の数字が手元のファイル数と合わないとき

合計が小さく見えるときは、読み込まれていないファイルを疑います。次のファイルは通知なしで読み飛ばされます。

• フロントマターに name がない(ドキュメント扱いになる)
• name はあるが description がない
• YAMLが解釈できない

合計が大きく見えるときは、手元の .claude/agents/ に無いagentが加わっています。

• ~/.claude/agents/ のagent(全プロジェクトで読み込まれる)
• --add-dir で追加したディレクトリの .claude/agents/
• リポジトリルートまでの途中にある .claude/agents/(作業ディレクトリから親へたどって走査される)
• プラグインの agents/ ディレクトリや管理設定で配られたagent
• 起動時に --agents のJSONで渡したagent。ファイルには残らず、そのセッションだけの一覧に入ります

同じ name が別の置き場所にもあると、優先度の高い定義だけが残ります。ファイルが2つあっても一覧では1つなので、ここでも手元のファイル数とは一致しません。同じディレクトリ(サブフォルダを含む)に同じ name が2つあるときは、片方しか読み込まれず、どちらが残るかはファイルシステムの読み込み順で決まります。/doctor はこの重複を報告し、名前の変更か削除を提案します。

読み込まれなかった理由は、--debug を付けて起動したときのデバッグログに出ます。agentsディレクトリのフロントマターだけを先に調べるなら、claude plugin validate .claude/agents が使えます(v2.1.233以降)。ただし name がないだけのファイルは検出されません。

読み込まれているagentの一覧を確認したいときの注意もあります。v2.1.197より後の /agents は対話ウィザードを開かず、Claudeに頼むか .claude/agents/ と ~/.claude/agents/ を直接編集するよう案内を出すだけです。v2.1.197以前では、実行中のagentを見るRunningタブと、作成・編集・削除をするLibraryタブのウィザードが開きました。一覧の確認は、ls や前掲のスクリプトで手元のファイルを見るか、Claudeに「いま使えるサブエージェントを挙げて」と頼む形になります。

スキル側の上限とは別物

似た話に、スキルの説明文の上限があります。こちらは skillListingMaxDescChars というキーで、スキル1つあたりの文字数を制限する仕組みです。経緯と設定はskillListingMaxDescCharsの解説にあります。

サブエージェントの15,000トークンは、合計に対する推定上限で、設定キーで変える形にはなっていません。対処は、説明文を削るか、ファイルを消すかの2つです。

説明文を削ったあとの設計

説明文を短くする作業は、agentの設計を見直す機会にもなります。サブエージェントの全体像はClaude Codeサブエージェント完全ガイドで、権限の組み方はサブエージェントの権限ルール設計で扱っています。

agentが増える背景には、モデルや権限の違いごとに別ファイルを作る運用があります。モデルごとの割り当てを整理したいときは、サブエージェントのモデル配分設計が参考になります。同じ役割のagentを統合できれば、説明文の合計も減ります。

まとめ

警告が出ても機能は止まらず、増えるのはコンテキストの消費だけです。急いで直す必要は薄く、次にagentを足すタイミングで整理すれば足ります。

判断の軸は、そのagentを直近で呼んだかどうかです。呼んでいないagentは説明文を磨くより削除したほうが合計は早く減り、似た役割が複数あるなら統合で説明文そのものを減らせます。説明文の短縮は、残すagentに「いつ使うか」の一文を残して手順を本文へ移す作業です。合計が手元のファイル数と合わないときは、ホーム側・--agents・プラグイン由来のagentを先に疑ってください。