Claude Media
omitClaudeMdでサブエージェントにCLAUDE.mdを渡さない設定
Claude CodeTips

omitClaudeMdでサブエージェントにCLAUDE.mdを渡さない設定

omitClaudeMdはサブエージェントの起動時にCLAUDE.mdを読ませないfrontmatterフィールドです。効果範囲とclaudeMdExcludesとの違いを扱います。

読了目安 約9分

Claude Codeのサブエージェントは、起動時に既定でユーザー・プロジェクト・ローカルのCLAUDE.mdをすべて受け取ります。v2.1.271で追加されたomitClaudeMdフロントマターフィールドを使うと、特定のサブエージェントだけこの読み込みを止められます。他のリポジトリへ配るプラグインや汎用サブエージェントで、配布先のCLAUDE.mdに動作を左右されたくないときに使う設定です。

omitClaudeMdとは — サブエージェント起動時にCLAUDE.mdを外すフィールド

omitClaudeMdは、サブエージェントのfrontmatterに書く真偽値フィールドです。trueを設定すると、そのサブエージェントはユーザー・プロジェクト・ローカルのCLAUDE.mdを一切受け取らずに起動します。管理者が配布するmanaged policyのCLAUDE.mdだけは、このフィールドを設定していても読み込まれます。

対象になるのはカスタムサブエージェントとプラグイン提供のサブエージェントです。frontmatterのフィールドとしても、CLIの--agentsに渡すJSON定義としても書け、どちらの経路でもClaude Code v2.1.271以降が必要です。frontmatterで必須なのはnameとdescriptionだけで、omitClaudeMdを含む他のフィールドはすべて省略できます。

サブエージェントは既定でCLAUDE.mdをまるごと受け取る

omitClaudeMdを理解するには、それを設定しないときの既定動作を先に押さえておく必要があります。フォークでない通常のサブエージェントが起動すると、初期コンテキストには次の階層すべてのCLAUDE.mdが含まれます。

  • ~/.claude/CLAUDE.md(ユーザー)
  • プロジェクトのCLAUDE.mdとCLAUDE.local.md
  • managed policyのCLAUDE.md
  • プロジェクト指示として読み込まれたAGENTS.md

組み込みのExploreとPlanだけは、omitClaudeMdの有無に関わらず常にこれらを読みません。それ以外のすべてのカスタムサブエージェントとプラグインサブエージェントは、omitClaudeMdを設定しない限りこの一式を受け取ります。数百パッケージのモノレポで動くサブエージェントほど、無関係なCLAUDE.mdまで読み込んでコンテキストを消費しがちです。

frontmatterと--agents JSONでの設定方法

もっとも単純な設定は、サブエージェントのMarkdownファイルにフィールドを1行足すだけです。

---
name: portable-reviewer
description: リポジトリ間で共通のレビュー規約を適用するレビュアー
omitClaudeMd: true
---
 
あなたは移植性を重視したコードレビュアーです。このプロンプトに書かれた規約だけに従い、
呼び出し元リポジトリのCLAUDE.mdの指示は参照しません。

非対話モードで--agentsにJSON定義を渡す場合も、同じフィールド名で指定します。

claude -p --agents '{"portable-reviewer":{"description":"共通レビュアー","omitClaudeMd":true}}' "変更をレビューして"

定義が大きい場合は、同じ形のJSONをファイルに保存して--agents ./agents.jsonのようにパスで渡せます。ファイルパスで渡す形はv2.1.281以降が必要で、対話セッションではファイルパスの指定自体が拒否されます。

omitClaudeMdを設定してもなお読み込まれるもの

omitClaudeMdが止めるのはユーザー・プロジェクト・ローカルのCLAUDE.mdだけです。次の3つは範囲外なので、動作を検証するときに混同しないようにします。

ケースomitClaudeMd設定後の挙動
managed policyのCLAUDE.mdomitClaudeMd設定後の挙動通常どおり読み込まれる
managed subagents(管理者設定由来のサブエージェント)omitClaudeMd設定後の挙動managed policyも含めて何も読み込まない
--agentでセッション全体をそのエージェントにする場合omitClaudeMd設定後の挙動フィールドは無視され、通常フローでCLAUDE.mdが読み込まれる

managed subagentsは、組織の管理者がmanaged settingsディレクトリの.claude/agents/に配置するサブエージェントで、同名のプロジェクト・ユーザーサブエージェントより優先して読み込まれます。この管理者配布のサブエージェント定義にomitClaudeMdを設定した場合だけ、managed policyのCLAUDE.mdも含めて何も読み込まれません。個人やプロジェクトの権限で書ける通常のサブエージェント定義では、omitClaudeMdを設定してもmanaged policyだけは常に残ります。

最後の行は見落としやすい挙動です。omitClaudeMdはサブエージェントとして委任されたとき(Agentツール経由や@メンションでの起動)にだけ働き、同じ定義を--agentフラグやsettingsのagentキーでセッション全体のエージェントとして使う場合は効きません。この場合、CLAUDE.mdとプロジェクトメモリは通常の会話フローでいつもどおり読み込まれます。

claudeMdExcludesとの違い — 除外の単位が別

CLAUDE.mdを読ませない設定はomitClaudeMdだけではありません。claudeMdExcludesの設定手順で扱ったclaudeMdExcludesも同じ目的で使われますが、除外の単位が違います。

設定除外の単位書く場所対象
claudeMdExcludes除外の単位ファイルパス(グロブ)書く場所settings.json(4層)対象セッションのメモリー読み込み時に該当するCLAUDE.mdファイル
omitClaudeMd除外の単位サブエージェント単位書く場所サブエージェントのfrontmatterまたは--agents JSON対象そのサブエージェント1体だけ

claudeMdExcludesはどのファイルを除外するかを利用者側のsettings.jsonで指定します。モノレポの特定パッケージなど、リポジトリの構造に応じて調整する用途に向きます。一方omitClaudeMdはサブエージェントの定義そのものに書くので、そのサブエージェントを別のリポジトリへ持っていっても設定が付いてきます。利用先のsettings.jsonを書き換える必要がありません。サブエージェントの初期コンテキストにもclaudeMdExcludesの除外が及ぶかどうかは、公式docsに明記が見当たらず確認できていません。

こんな場面で使う — 配布用サブエージェントとプラグイン

omitClaudeMdが向くのは、サブエージェント自身が委任プロンプトだけで完結するように設計されている場面です。プラグインとして配布するサブエージェントは典型例です。プラグインのagentsディレクトリに置いたMarkdownファイルはomitClaudeMdをサポートするフィールドの一つで、name・description・modelなどと同じ扱いで動きます。

社内で複数リポジトリに配るレビュー用サブエージェントも同じ理由で候補になります。リポジトリごとにCLAUDE.mdの流儀が違っていても、レビュー観点を委任プロンプト側に書き切っておけば、omitClaudeMd: trueでどの利用先でも同じ基準のまま動かせます。反対に、プロジェクト固有の規約をサブエージェントにも守らせたい場合は、omitClaudeMdを設定せず既定のままにしておきます。

サブエージェントのモデル選定や役割設計そのものはClaude Codeサブエージェントのモデル配分設計で扱っています。ストール検知や起動・終了タイミングの監視など、サブエージェントのライフサイクルに関わる他の設定はCLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSとはやSubagentStart/SubagentStop hookでサブエージェントの起動と終了を監視するにまとめています。

CLAUDE.mdを外す代わりに、サブエージェントが必要とする手順はskillsフィールドで明示的にプリロードしておくのが安全です。skillsに列挙したスキルは全文がサブエージェントの初期コンテキストに注入されるため、CLAUDE.mdの断片的な指示に頼らず、そのサブエージェント専用の手順として持ち運べます。

プラグインサブエージェントとの相性 — 一緒に使えないフィールドがある

配布用サブエージェントをプラグインのagents/ディレクトリに置く場合、omitClaudeMd自体は問題なくサポート対象のフィールドですが、同時に使いたくなる他のフィールドの一部はプラグインでは無視されます。プラグインのサブエージェントではhooks・mcpServers・permissionMode・initialPromptが無効になり、frontmatterに書いても読み込まれません。ツール制限を掛けたいサブエージェントならtoolsとdisallowedToolsは引き続き効くので、権限周りの制御はこの2つで完結させ、フックやMCPサーバーが必要な場合はプラグイン側のhooks.jsonやMCPサーバー定義で別途持たせる設計になります。

よくあるつまずき

omitClaudeMdを設定しても意図通りに動かないときは、次の3点を確認します。

Claude Codeのバージョンがv2.1.271より古いと、omitClaudeMdは認識されず、CLAUDE.mdは従来どおり読み込まれ続けます。まずclaude --versionでバージョンを確認します。

managed policyのCLAUDE.mdまで消えたと誤解するケースもあります。omitClaudeMdが止めるのはユーザー・プロジェクト・ローカルの3層で、組織が配布するmanaged policyは対象外です。個人やプロジェクトの権限で書くサブエージェント定義からは、managed policyを止める手段はありません(管理者が配布するmanaged subagentsだけが例外です)。

--agentフラグでそのサブエージェント定義をセッション全体に使ったときに、CLAUDE.mdが相変わらず読み込まれて戸惑うこともあります。これは不具合ではなく、omitClaudeMdがAgentツール経由の委任にだけ効く仕様どおりの挙動です。

CLAUDE.mdに書いていた「vendor配下は触らない」のような個別の注意事項も、omitClaudeMdを設定した瞬間にサブエージェントへは届かなくなります。委任元の会話は自分のCLAUDE.mdを保ったままなので気づきにくく、サブエージェントが規約を破ってから発覚しがちです。守らせたい規約があるなら、委任プロンプトに直接書き添えておきます。

まとめ

omitClaudeMdは、サブエージェントの定義に付けておくだけで、そのサブエージェントがどのリポジトリで動いてもユーザー・プロジェクト・ローカルのCLAUDE.mdを読まなくなる設定です。managed policyは常に読み込まれ、--agentでセッション全体のエージェントとして使うときは効かない点を押さえておけば、プラグインや配布用サブエージェントの設計に組み込みやすくなります。ファイル単位で除外したいだけならclaudeMdExcludes、サブエージェント単位で切り離したいならomitClaudeMdという使い分けです。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →