Claude Code の小さな公式ドキュメントを読み進めたら、使っていないレバーが3つ出てきた——エージェント編成・要約への指示・MCPの隠れた注入経路

はじめに

公式ドキュメントには、機能ごとにまとまった大きなページの他に、数百字から数千字程度の小さなページが大量にある。個別の設定項目やエッジケースだけを説明する、単体では地味なファイルだ。読み飛ばしたくなるが、実際に8本区切りのバッチで最後まで読み切ってみると、単体では気づけない発見が3つ出てきた。

読み方には条件を1つ課した。バッチを読み終えるたびに、自分の既存の記録（設計文書や過去の検討ログ）を機械的に検索し、既に知っていたことを「新発見」と誤認しないようにする。この条件のおかげで、3つ目の発見は「新発見」から「思い出した記録」に着地が変わった。

小さな公式ドキュメント群（8本ずつのバッチ）
  │
  ├─▶ 既出確認（バッチ読了ごとに、自分の記録を機械検索）
  │       └─ 一致すれば「既出」として着地 ── 戻りエッジ ──┐
  │                                                          │
  ├─▶ 発見① 要約処理に「何を残すか」を書けるレバー          │
  │       └─ 常時読み込まれる規律ファイルに専用の記述が0件 ─▶ 未使用と確定
  │
  ├─▶ 発見② 外部連携ツールの説明文がシステムプロンプトに足される
  │       └─ 自作の連携ツールは未設定 ──▶ 他社製の分は見えない（観測の限界）
  │
  └─▶ 発見③ 複数AIを編成する実験的機能は、1か月前から記録済みだった
          └─ 既出確認が発火 ◀───────────────────────────────┘
                （この日のバッチ読みで4回連続で発火。誤って「新発見」と
                 書いていたら、同じ内容が二重に記録され、後で矛盾を疑って
                 読み返す余計な手間が発生していたはずだった）

発見① 要約処理に「何を残すか」を書ける

長い会話を続けていると、途中で「要約による圧縮（コンパクション。直近のやり取りは残したまま、古い部分をAI自身が書いた要約に置き換える処理）」が入る。ここで見落としがちな情報が消えることがある——長時間の作業の冒頭で確認したはずの前提や、途中で決めた判断が、要約を境に会話から抜け落ちる形だ。

公式ドキュメントには、この要約処理そのものに指示を書けるレバーが明記されていた。

“The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent.”

要約を行う内部処理は、常時読み込まれる設定ファイルを他の文脈と同じように読んでおり、そこに「要約するときに何を残すべきか」を書いたセクションを含められる、という意味だ。見出しの文言は固定されておらず、内容の意図で判定されるという注記も付いている。

自分の環境で、常時読み込まれる規律ファイル群を確認したところ、この専用セクションは0件だった。長時間のセッションで要約が入ると、着手前に確認すべき手順や、破壊的操作の前にバックアップを取る規律が要約で薄れる可能性がある——ということ自体は把握していたが、対策としてこのレバーは使っていなかった。

発見② 外部連携ツールの説明文がシステムプロンプトに足される

AIアシスタントに外部のツールやデータソースを接続するための標準規格（自作の独自仕様ではなく、複数のAIアシスタントで共通に使われている連携規格）には、instructions という項目を設定できる。公式ドキュメントは、この項目の扱いを次のように明記していた。

“instructions … Added to Claude’s system prompt.”

つまり、連携ツール側が instructions に文章を書けば、それがAIの土台となる指示（システムプロンプト）にそのまま足される。これは特定の拡張機能専用の仕組みではなく、標準規格そのものの機能だった。

自作している個人用の連携ツール（過去の記録を検索する用途で運用している）の初期化コードを確認すると、ツール名だけを渡していて instructions は未設定だった。つまり自分が書いたツールからシステムプロンプトへの書き込みは起きていない。一方で、他者が公開している連携ツール（ブラウザ操作用のものなど）が同じ項目を使っているかどうかは、こちらから見えない。会話の記録にその内訳が残らない経路があり、そこを覗く手段が無いためだ。

⚠️ この限界は正直に書いておく。「載っていないと確認した」と言えるのは自作の分だけで、他者製の分は「見えていない」というのが正確な状態になる。

発見③ 「新発見」のはずが、1か月前の自分が既に記録していた

複数のAIに役割を分けて並行作業させる実験的な機能について読んだ。既定では無効で、専用の設定を立てないと動かない。読み終えて「新発見」として書こうとしたところ、バッチ読了時の既出確認の手順が発火した。

自分の記録を機械検索すると、次の2件がヒットした。

~/.claude/teams/{team-name}/config.json(session 終了で削除)・mailbox inboxes/{agent}.json・task list ~/.claude/tasks/{team-name}/(永続・cleanupPeriodDays)。team-name=session-+session ID 先頭8字。config は手編集禁止。

experimental・既定 off: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。… token は teammate 数に線形・plan mode で約7x。

日付を確認すると、約1か月前にほぼ同じ内容を自分で記録していた。今回の熟読はその再確認にすぎなかった。しかもこの「既出確認をしてから新発見と書く」という手順自体、この日のバッチ読みで4回連続で発火していた。もし発火していなければ、同じ内容を「新発見」として重ねて書き、後から読み返した自分が「これは前と矛盾しているのか、それとも同じことか」を確認するために余計な時間を使っていたはずだ。

読んでいるものが多いほど、確認する側の手順が重くなる

この読み進めで実際に効いたのは、公式ドキュメントの中身そのものより、「読んだ内容を新発見と呼ぶ前に、自分の記録を検索する」という手順を、バッチのたびに機械的に回したことだった。3つの発見のうち1つは、公式の記述を裏付けとして使う前に、その裏付けが要らないと分かった。読む量を増やすほど、読んだ内容そのものより、その内容をどう既存の理解と突き合わせるかの手順の方が、成果を左右するようになっていく。

Claude Code のオーケストレーター用サブエージェントを廃止した理由——公式harness仕様に基づく構造的な3つの制約

Claude Code に設定ファイルを直接いじらせない——差分案から本人承認に行き着くまでの事故史

3つのレバーは、探しに行って見つけたものではなく、小さくて後回しにしていた資料の中に、ずっと置かれていたものだった。分量が少ない資料ほど「読まなくても分かる」と扱われる——今回、その扱いが3件分の見落としになっていた。