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

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

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

omitClaudeMdは、サブエージェントのfrontmatterに書く真偽値フィールドです。trueを設定すると、そのサブエージェントはユーザー・プロジェクト・ローカルのCLAUDE.mdを受け取らずに起動します。

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

設定の有無でサブエージェントの初期コンテキストはどう変わるか

フォークでない通常のサブエージェントは、新しい空のコンテキストから始まります。そこへ入るCLAUDE.md関連の内容が、omitClaudeMdの有無で次のように変わります。

CLAUDE.mdのないリポジトリではAGENTS.mdがプロジェクト指示として読まれますが、プロジェクト指示を読まないサブエージェントはこれも読みません。組み込みのExploreとPlanは、omitClaudeMdと無関係にCLAUDE.mdとgit statusのスナップショットを読みません。それ以外の組み込みサブエージェントとカスタムサブエージェントは、omitClaudeMdを設定しない限りCLAUDE.mdを受け取ります。ExploreとPlanそのものを外す環境変数はCLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTSの記事にあります。

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

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

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

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

claude -p --agents '{"portable-reviewer":{"description":"共通レビュアー","prompt":"移植性を重視してレビューする","omitClaudeMd":true}}' "変更をレビューして"

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

--agentsのヘルプとエラーの実物(v2.1.289)

v2.1.289では、claude --helpが--agentsを次のように説明します。

--agents <json-or-file>   JSON object defining custom agents, or
                          with --print the path to a file that
                          holds one (e.g. '{"reviewer":
                          {"description": "Reviews code",
                          "prompt": "You are a code reviewer"}}')

omitClaudeMdに真偽値でない値を渡すと、モデルを呼ぶ前にスキーマ検査で止まります。v2.1.289の出力は次のとおりです。

$ claude -p --agents '{"portable-reviewer":{"description":"x","prompt":"y","omitClaudeMd":"yes"}}' "hi"
Error: Invalid --agents configuration:
portable-reviewer.omitClaudeMd: Invalid input: expected boolean, received string
 
$ claude -p --agents '{"portable-reviewer":' "hi"
Error: Invalid --agents configuration:
invalid JSON: JSON Parse error: Unexpected EOF
 
$ claude -p --agents ./nofile.json "hi"
Error: --agents file not found: <作業ディレクトリ>/nofile.json (a value that is not a JSON object is read as a file path)

trueを引用符で囲んで文字列にすると、1つ目のエラーになります。{で始まらず、JSONとしても有効でない値はファイルパスとして読まれるため、JSONの書き出しを誤ると3つ目のようなファイル探索のエラーが出ます。

なおclaude agentsコマンドの説明は「Manage background agents」で、サブエージェントの定義とは別物です。サブエージェントの定義は、.claude/agents/や~/.claude/agents/のファイルを直接編集します。/agentsも現行版では、Claudeに頼むかファイルを直接編集するよう促す案内を出すだけです。

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

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

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

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

claudeMdExcludesは絶対パスに対するグロブで、モノレポで他チームのCLAUDE.mdを避けたいときなど、リポジトリの構造に応じた調整に向きます。配列は各層をまたいで結合されます。一方omitClaudeMdはサブエージェントの定義そのものに書くので、別のリポジトリへ持っていっても設定が付いてきます。利用先のsettings.jsonを書き換える必要はありません。

両者に共通する点もあります。managed policyのCLAUDE.mdはclaudeMdExcludesでも除外できず、omitClaudeMdでも(managed subagentsを除いて)残ります。組織の指示は個人側の設定では外せない設計です。

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

omitClaudeMdが向くのは、サブエージェント自身が委任プロンプトだけで完結するように設計されている場面です。プラグインとして配布するサブエージェントは典型例で、プラグインのagents/に置いたMarkdownでもomitClaudeMdはサポート対象のフィールドです。

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

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

CLAUDE.mdを外した代わりに必要な手順は、skillsフィールドでプリロードできます。skillsに列挙したスキルは全文がサブエージェントの初期コンテキストに注入されます。ただし、これは「プリロードするスキル」を決めるだけで、列挙しなかったスキルもSkillツールから呼び出せます。

プラグインサブエージェントで一緒に使えないフィールド

プラグインのagents/に置いたサブエージェントでは、name・description・model・tools・disallowedTools・skills・omitClaudeMdなどが有効です。一方、hooks・mcpServers・permissionMode・initialPromptはfrontmatterに書いても無視されます。

ツール制限はtoolsとdisallowedToolsで足ります。フックやMCPサーバーが必要なら、プラグイン側のhooks.jsonやMCPサーバー定義として別に持たせます。

よくあるつまずき

omitClaudeMdを設定しても意図どおりに動かないときは、次の2点を見ます。

Claude Codeがv2.1.271より古いと、omitClaudeMdは認識されず、CLAUDE.mdは従来どおり読み込まれ続けます。まずclaude --versionで確かめます。v2.1.289では次のように表示されます。

$ claude --version
2.1.289 (Claude Code)

nameが無いサブエージェントのファイルは、定義ではなくドキュメントとして扱われ、セッションには何も報告されません。nameがあってdescriptionが無いファイルや、YAMLとして読めないファイルも、読み込みをスキップしてデバッグログにだけ理由を書きます。omitClaudeMdを書いたのに効かないときは、claude --debugでそのファイルが読み込まれているかを確かめます。

まとめ

trueにする前に、CLAUDE.mdのルールを一つずつ「親会話が結果を読む段階で効けば足りるか」「サブエージェントの作業そのものを縛る必要があるか」で分けます。後者だけが委任プロンプトの書き直し対象で、手順の類はskillsのプリロードでも渡せます。