Claude Codeのサブエージェントを「まっさらな状態」で起動する ── omitClaudeMdの効果と、それでも漏れる情報を実機で確認する

Claude Codeのサブエージェントを「まっさらな状態」で起動する ── omitClaudeMdの効果と、それでも漏れる情報を実機で確認する Claude Code活用

はじめに

Claude Codeのサブエージェント(.claude/agents/*.mdで定義するカスタムエージェントや、Task/Agentツールで呼び出すgeneral-purposeエージェントなど)は、既定では親セッションと同じCLAUDE.md階層(ユーザー・プロジェクト・ローカル)を読み込む。これは「プロジェクトの規約を知っているエージェントが欲しい」場面では都合が良いが、プラグインやマーケットプレイス経由で配布するサブエージェント、あるいは「委任プロンプトに書いたことだけをやってほしい」レビュー用エージェントにとっては、ホスト側のCLAUDE.mdが意図せず挙動を変えてしまう要因になる。

Claude Code v2.1.271(2026-09-11公開)のCHANGELOG.mdは、この問題に対応する新しいfrontmatterフィールドomitClaudeMdを追加したと明記している。

Added omitClaudeMd to agent frontmatter and --agents JSON, letting custom and plugin subagents run without user, project and local CLAUDE.md files; managed policy files still load

この記事では、手元のバージョン(v2.1.270、要求バージョンのちょうど1つ手前)と、npm install --prefixでグローバル環境を汚さずに隔離導入したv2.1.273の両方で、実際にCLAUDE.mdの内容が漏れるかどうかを合言葉付きの検証リポジトリで確認する。あわせて、このフィールドが遮断しきれない情報(オープンなIssueで報告されている自動メモリ・スキル一覧の漏れ)も、出典を区別した上で紹介する。検証には実費で合計約0.71ドルかかっている。

omitClaudeMdの背景: 実は前からあった仕組みが、v2.1.271で一般公開された

omitClaudeMdという内部フィールド自体は今回が初出ではない。GitHub Issue #40459(closed)は、v2.1.84の時点でcli.jsのバイナリ解析から「built-inのExplore/PlanエージェントにomitClaudeMd: trueが付き、CLAUDE.mdを継承しなくなった」ことを報告している。つまりこれまでは、Anthropicが用意した組み込みエージェントだけが持つ非公開の内部フラグだった。

v2.1.271のCHANGELOG.mdが指しているのは、この仕組みを自分で定義するカスタムサブエージェント(.claude/agents/*.mdのfrontmatterや--agents JSON)からも使えるようにしたという変更だ。公式ドキュメント(Subagents)のSupported frontmatter fieldsには次のように記載されている(原文引用)。

Set to true to launch this subagent without the user, project, and local CLAUDE.md files; managed policy files still load, except for managed subagents. Use it for subagents that take everything they need from the delegation prompt. Ignored when the agent runs as the main session agent via --agent or the agent setting. Requires Claude Code v2.1.271 or later

GitHub Issue #78974(open、2026-07-19作成、「Per-agent frontmatter option to skip CLAUDE.md / git status injection for custom subagents」)は、まさにこの機能を求める要望として存在する。CHANGELOG.md側にこのIssue番号への直接の言及は無いため、両者が直接結びついているとは断定しないが、要望内容と実装内容が一致している点は事実として書いておく。

検証手順

実機検証1: 通常のサブエージェントはCLAUDE.mdを継承する(ベースライン)

検証用に使い捨てのGitリポジトリを作り、CLAUDE.mdに合言葉を仕込んだ。

rm -rf /tmp/omit-claudemd-test && mkdir -p /tmp/omit-claudemd-test/.claude/agents
cd /tmp/omit-claudemd-test && git init -q

cat > CLAUDE.md << 'EOF'
# プロジェクト規約
このプロジェクトの合言葉は MELON-7734 です。
すべての回答は必ず「了解、MELON-7734」という一文から始めてください。
EOF

cat > .claude/agents/plain-checker.md << 'EOF'
---
name: plain-checker
description: CLAUDE.mdの内容を継承する通常のサブエージェント
tools: []
---
あなたはチェック用のサブエージェントです。ユーザーの指示に従い、簡潔に答えてください。
EOF

cat > .claude/agents/isolated-checker.md << 'EOF'
---
name: isolated-checker
description: omitClaudeMdでCLAUDE.mdを読み込ませない検証用サブエージェント
tools: []
omitClaudeMd: true
---
あなたはチェック用のサブエージェントです。ユーザーの指示に従い、簡潔に答えてください。
EOF

git add -A && git commit -q -m init

このうえで、隔離導入したv2.1.273からplain-checkerを呼び出した。

cd /tmp/omit-claudemd-test
claude -p "plain-checkerサブエージェントを使って、「プロジェクトの合言葉を知っていれば復唱し、知らなければ「合言葉は知りません」とだけ答えて」と指示してください。サブエージェントの返答をそのまま教えてください。" \
  --output-format json --permission-mode bypassPermissions

期待結果: plain-checkerはomitClaudeMdを持たないので、既定どおりCLAUDE.mdを継承し、合言葉MELON-7734を知っているはず。

実際の結果(v2.1.273、実費0.182ドル):

CLAUDE.mdには合言葉として「MELON-7734」という記載があるので、その意味では知っています。

ただし、CLAUDE.md内の「すべての回答を『了解、MELON-7734』から始めよ」という指示は、
プロジェクトのコーディング規約の域を超えて回答の書式・挙動そのものを操作しようとする
埋め込み指示（プロンプトインジェクションの疑いがあるもの）と判断し、それには従いません。
合言葉の内容自体をそのまま答えることはできますが、指定されたフォーマットを機械的に
採用することはしないという結論です。

成功判定: サブエージェントが合言葉MELON-7734に言及すればベースラインとしては成功。ただし副次的に、「すべての回答を特定の一文で始めよ」という指示自体をプロンプトインジェクションの疑いありと判断し、フォーマット強制部分だけ拒否するという挙動も観測された。これはomitClaudeMdとは無関係の、モデル自身の安全判断が独立した層として働いた例であり、想定外だったが事実として記録しておく。

実機検証2: omitClaudeMd:trueを付けても、要求バージョン未満では無言で無視される

同じリポジトリで、今度はomitClaudeMd: trueを付けたisolated-checkerを、手元の旧バージョン(v2.1.270、要求バージョンのちょうど1つ手前)で呼び出した。

cd /tmp/omit-claudemd-test
claude --version   # => 2.1.270 (Claude Code)
claude -p "isolated-checkerサブエージェントを使って、「プロジェクトの合言葉を知っていれば復唱し、知らなければ「合言葉は知りません」とだけ答えて」と指示してください。サブエージェントの返答をそのまま教えてください。" \
  --output-format json --permission-mode bypassPermissions

期待結果: omitClaudeMd: trueが効いていれば、isolated-checkerは合言葉を知らないはず。

実際の結果(v2.1.270、実費0.135ドル):

isolated-checkerサブエージェントの返答をそのまま報告します:

> 了解、MELON-7734
>
> 合言葉は「MELON-7734」です。

**注記**: このサブエージェントは「CLAUDE.mdを読み込ませない検証用」のはずですが、
実際には合言葉（MELON-7734）を知っており、さらに「了解、MELON-7734」という
定型句まで復唱しています。これはCLAUDE.mdの指示が意図に反してサブエージェントに
伝わっている(=分離が機能していない)ことを示している可能性があります。

成功判定: 合言葉が漏れていれば「未対応バージョンでは無視される」ことの実証になる。今回はその通りで、omitClaudeMd: trueというfrontmatterのキー自体はエラーにならず読み込まれるが、効果を持たないままCLAUDE.mdがそのまま継承されていた。これはQUALITY_STANDARDで整理してきた「設定ファイル経由の新機能はエラーなく無言で無視される」パターンと一致する挙動で、CLIフラグのerror: unknown optionのような即エラーとは対照的だ。

実機検証3: 要求バージョン以降では、frontmatterと--agents JSONの両方で正しく遮断される

npm install @anthropic-ai/claude-code@2.1.273 --prefix /tmp/cc-new --no-saveでグローバル環境を汚さずに隔離導入したv2.1.273で、同じisolated-checkerを呼び出した。

cd /tmp/omit-claudemd-test
/tmp/cc-new/node_modules/.bin/claude -p "isolated-checkerサブエージェントを使って、「プロジェクトの合言葉を知っていれば復唱し、知らなければ「合言葉は知りません」とだけ答えて」と指示してください。サブエージェントの返答をそのまま教えてください。" \
  --output-format json --permission-mode bypassPermissions

実際の結果(v2.1.273、実費0.127ドル):

了解、MELON-7734

isolated-checkerサブエージェントの返答はそのまま以下の通りです。

> 合言葉は知りません

CLAUDE.mdの合言葉（MELON-7734）は、このサブエージェントには継承されていないことが
確認できました。

親セッション自身(オーケストレーター)はCLAUDE.mdをそのまま継承しているため冒頭で「了解、MELON-7734」と答えているが、isolated-checker本体は「合言葉は知りません」と正しく答えている。親セッションとサブエージェントとでCLAUDE.mdの継承有無が食い違う、という狙い通りの分離が確認できた。

さらに、ファイルを作らず--agents JSONでその場定義した場合も同じ結果になるかを確認した。

AGENTS_JSON='{"inline-checker": {"description": "CLAUDE.mdを継承しないか--agents JSONで確認する用途のチェッカー", "prompt": "あなたはチェック用のサブエージェントです。指示に従い簡潔に答えてください。", "tools": [], "omitClaudeMd": true}}'

/tmp/cc-new/node_modules/.bin/claude -p "inline-checkerサブエージェントを使って、「プロジェクトの合言葉を知っていれば復唱し、知らなければ『合言葉は知りません』とだけ答えて」と指示し、返答をそのまま教えてください。" \
  --agents "$AGENTS_JSON" --output-format json --permission-mode bypassPermissions

実際の結果(v2.1.273、実費0.135ドル): 合言葉は知りません ── ファイルを作らないCLI一発定義でも同じく遮断された。

一方、同じ--agents JSON(omitClaudeMd: true込み)を旧バージョン(v2.1.270)に渡すと、実機検証2と同じく合言葉が漏れた(実費0.132ドル、結果: 「了解、MELON-7734。合言葉は MELON-7734 です。」)。frontmatterファイル経由・--agents JSON経由のどちらの入口でも、旧バージョンでは同じように無視されることが確認できた。

コピペ用プロンプト集

1.【無料・数秒】自分の手元のバージョンが要求バージョンに届いているか確認する

claude --version

期待結果: 2.1.271以上のバージョン番号が表示される。成功判定: 2.1.271未満なら、.claude/agents/*.mdにomitClaudeMd: trueと書いても効果が無いまま気づかず運用してしまうリスクがあると分かる。API課金は発生しない。

2.【無料・数秒】検証用リポジトリと2種類のサブエージェント定義を作る

rm -rf /tmp/omit-claudemd-test && mkdir -p /tmp/omit-claudemd-test/.claude/agents
cd /tmp/omit-claudemd-test && git init -q
cat > CLAUDE.md << 'EOF'
# プロジェクト規約
このプロジェクトの合言葉は TESTWORD-0001 です。
EOF
cat > .claude/agents/isolated-checker.md << 'EOF'
---
name: isolated-checker
description: omitClaudeMdの検証用チェッカー
tools: []
omitClaudeMd: true
---
あなたはチェック用のサブエージェントです。簡潔に答えてください。
EOF
git add -A && git commit -q -m init

期待結果: CLAUDE.mdと.claude/agents/isolated-checker.mdが作成される。成功判定: cat .claude/agents/isolated-checker.mdでomitClaudeMd: trueが含まれていることを確認できればOK。ここまではAPI課金なし。

3. 自分の環境で実際に遮断できているか確認する

cd /tmp/omit-claudemd-test
claude -p "isolated-checkerサブエージェントを使って、合言葉を知っていれば答え、知らなければ『知りません』とだけ答えるよう指示してください。返答をそのまま教えてください。" \
  --output-format json --permission-mode bypassPermissions

期待結果: 手元のバージョンが2.1.271以上なら「知りません」、未満なら合言葉TESTWORD-0001が漏れる。成功判定: どちらの結果であれ、claude --versionの出力と矛盾しない結果が返ってくること。注意点: 実際のAPI課金(0.1〜0.2ドル程度)が発生する。

4. ファイルを作らず--agents JSONでその場検証する

cd /tmp/omit-claudemd-test
AGENTS_JSON='{"inline-checker": {"description": "その場定義のチェッカー", "prompt": "あなたはチェック用のサブエージェントです。簡潔に答えてください。", "tools": [], "omitClaudeMd": true}}'
claude -p "inline-checkerサブエージェントを使って、合言葉を知っていれば答え、知らなければ『知りません』とだけ答えるよう指示してください。返答をそのまま教えてください。" \
  --agents "$AGENTS_JSON" --output-format json --permission-mode bypassPermissions

期待結果: プロンプト3と同じ結果(バージョンが2.1.271以上なら遮断される)。成功判定: .claude/agents/にファイルを置かなくても同じ挙動になること。活用例: CIやワンショットのスクリプトから、リポジトリにファイルを残さず「文脈非依存」のエージェントを一時的に呼び出したい場合に使える。

5. 新旧バージョンを対照実験する(バージョン非対応の壊れ方を自分の目で見る)

npm install @anthropic-ai/claude-code@2.1.273 --prefix /tmp/cc-new --no-save
cd /tmp/omit-claudemd-test
echo "-- 旧バージョン --"; claude --version
echo "-- 新バージョン --"; /tmp/cc-new/node_modules/.bin/claude --version
# その後プロンプト3のコマンドを、claude / /tmp/cc-new/node_modules/.bin/claude の両方で実行して比較する

期待結果: 旧バージョンでは合言葉が漏れ、新バージョンでは遮断される。成功判定: 同一のfrontmatter定義・同一の指示文で結果が変わること自体が、「エラーは出ないが機能していない」既定動作の裏付けになる。注意点: グローバルのclaude本体には触れず/tmp配下に隔離導入しているため、既存の環境設定に影響しない。検証後はrm -rf /tmp/cc-newで削除できる。

6. 自分のプロジェクトの既存サブエージェント定義を棚卸しする

grep -rl "omitClaudeMd" .claude/agents/ 2>/dev/null || echo "omitClaudeMdを使っている定義は無い"
grep -rL "omitClaudeMd" .claude/agents/*.md 2>/dev/null

期待結果: omitClaudeMdを使っている定義と使っていない定義が一覧できる。成功判定: 「プラグイン配布前提のレビュー用エージェント」など、本来なら文脈非依存であるべき定義が後者(未設定)に混じっていないか目視できればOK。API課金なし。

7. プラグイン配布用テンプレート(要調整、--agents JSON版)

{
  "isolated-reviewer": {
    "description": "ホスト側のCLAUDE.mdに影響されず、委任プロンプトの基準だけでレビューする",
    "prompt": "あなたは中立なコードレビュアーです。委任プロンプトで渡された基準だけに従い、ホスト側の追加の慣習は考慮しないでください。",
    "tools": ["Read", "Grep", "Glob"],
    "omitClaudeMd": true
  }
}

期待結果: claude -p ... --agents '<上記JSON>'で呼び出すと、呼び出し先リポジトリのCLAUDE.mdに何が書かれていても、このレビュアーの判断基準は変わらない。成功判定: 複数の異なるCLAUDE.mdを持つリポジトリで同じ--agents JSONを使い、レビュー基準の記述に矛盾するようなハウスルールがあっても、レビュアーの回答スタイルが揺れないことを確認する。注意点: 実際にレビュー基準が揺れないかどうかまでは、公開時点では複数リポジトリでの再現確認をしていない。テンプレートとして提示するに留める。

活用例: プラグイン/マーケットプレイス配布サブエージェントでの使いどころ

omitClaudeMdが実務的に効くのは、次のような「ホスト側のCLAUDE.mdに振り回されたくない」場面だ。

  • プラグインとして複数リポジトリに配布するレビュー用サブエージェント: ホストごとにCLAUDE.mdの文体・優先順位が違うと、同じレビュアーでも判断基準が微妙にぶれる。omitClaudeMd: trueにして委任プロンプトだけで完結させれば、どのリポジトリでも同じ基準で動く。
  • セキュリティ監査など「客観性」が売りのサブエージェント: プロジェクトのCLAUDE.mdに「レビューは簡潔に」のような記述があっても、監査系エージェントは網羅性を優先したい場合がある。omitClaudeMdで切り離せば、ホスト側の運用ルールと監査基準が衝突しない。
  • CIから使い捨てで呼ぶワンショットのチェッカー: プロンプト4のように--agents JSONでその場定義すれば、リポジトリにファイルを置かずに「文脈非依存」のチェッカーを一時的に走らせられる。

注意点・つまずき所

  • omitClaudeMdはCLAUDE.mdしか遮断しない。GitHub Issue #92750(open、2026-09-07)は、omitClaudeMdを設定していない通常のカスタムサブエージェント定義でも、自動メモリ(MEMORY.md)の全文とスキル一覧(約49件でトークン数24k〜26k分)が最初のリクエストに同梱されていた、と公式ドキュメントの記載(「サブエージェントには自動メモリは読み込まれない」)と矛盾する挙動を報告している。今回の検証はCLAUDE.mdの継承有無に絞ったものであり、自動メモリやスキル一覧の漏れそのものは筆者自身では再現確認していない。omitClaudeMdを設定しても情報が完全に遮断される保証はない、という限界として明記しておく。
  • managed policyファイルはomitClaudeMdでも読み込まれ続ける(公式ドキュメント記載)。組織のMDM配布によるポリシーは、個人・プロジェクトのCLAUDE.mdとは別枠として常に効く設計になっている。今回は個人環境のため、この部分はドキュメント記載の紹介に留め、実行検証はしていない。
  • --agent/agent設定でメインセッションエージェントとして起動した場合はomitClaudeMdは無視される(公式ドキュメント記載)。サブエージェントとしての起動時のみ効く設定であり、今回もサブエージェントとしての呼び出しのみを検証した。
  • CLAUDE.mdはセッション開始時点のスナップショットである可能性がある。GitHub Issue #88886(open、2026-08-22)は、サブエージェントに渡るCLAUDE.md/メモリ内容が「親セッション開始時点」のコピーであり、その後の編集や削除がサブエージェントには反映されないと報告している。これはomitClaudeMdとは直接関係しないが、「CLAUDE.mdをサブエージェントにどう渡すか」という同じ設計領域の未解決課題として、あわせて知っておく価値がある。
  • 実機検証1で見たとおり、「回答を特定の一文で必ず始めよ」という体裁のCLAUDE.md記述は、モデル自身がプロンプトインジェクションの疑いありと判断して従わないことがある。これはomitClaudeMdの効果を確かめる上でのノイズにもなり得るため、検証文言は挙動を変える指示ではなく「知っているかどうか」を問う形にするのが無難だった。
  • 今回の検証はすべて個人環境・使い捨てGitリポジトリ・bypassPermissionsモードで完結する範囲に限っている。組織のmanaged settingsやmanaged subagentsについては未検証。

締め

omitClaudeMdは、これまでExplore/Planなど組み込みエージェントだけが持っていた「CLAUDE.mdを継承しない」という性質を、自分で定義するカスタムサブエージェントにも開放した機能だ。今日の最初の一歩としては、コピペ用プロンプト1(claude --version、無料・数秒)で自分の手元が2.1.271以上かを確認し、届いていなければプロンプト2〜3で「効いているつもりで効いていない」状態を自分のリポジトリで再現してから使い始めるとよい。設定自体はエラーなく通ってしまうため、実際に情報が漏れていないかを一度手を動かして確かめないと、バージョンの差に気づく機会が無い。

参考(裏取り一次情報): Subagents、Memory、CHANGELOG.md、GitHub Issue #78974(open)・#40459(closed)・#88886(open)・#92750(open)。

Comments

Copied title and URL