「CLAUDE.mdにしっかり書いたのに、新しいセッションを開いたら無視されていた」——Claude Codeを複数プロジェクトで運用していると、このパターンに必ず遭遇します。
CLAUDE.mdは「読んだけど優先されなかった」か「そのセッションの文脈では届いていなかった」状態になることがある。これは設定ミスではなく、CLAUDE.mdというファイルが持つ構造的な特性です。
結論
CLAUDE.mdだけに頼らず、3層で確実性を担保します。
| 層 | 仕組み | 読まれるタイミング |
|---|---|---|
| 1層: @import | CLAUDE.mdから別ファイルを参照 | セッション開始時・コンテキスト読み込み時 |
| 2層: UserPromptSubmit Hook | settings.jsonのhookで最初のプロンプト時に実行 | 必ずセッション開始時（LLM判断と独立） |
| 3層: グローバルメモリ | ~/.claude/CLAUDE.md | すべてのプロジェクトで参照 |
前提・環境
- Claude Code（2026-10現在）
- 確認環境: masatoman.net（Next.js 16 + MDX、記事200本規模）
- hook実装: UserPromptSubmit / Stop / PreCompact の3種を運用中
なぜCLAUDE.mdだけでは不十分か
CLAUDE.mdは「LLMがコンテキストとして読む」ものです。これは確率的な動作を意味します：
- 読む確率：高い（ほぼ毎回）
- 優先される確率：コンテキスト量・プロンプト内容によって変動
- セッション開始直後：文脈が薄い段階では優先されにくいケースがある
一方、hookは「Claude Codeハーネスが実行する」ものです：
- 実行確率：定義されたタイミングで必ず実行（LLMの判断と独立）
この違いが3層設計の根拠になります。
1層: @import でファイルを分割する
CLAUDE.mdが長くなってくると後半の指示が「薄く」読まれる問題が起きます。@ファイル名形式で別ファイルを参照することで、役割を分けて管理できます。
# CLAUDE.md の冒頭例
@AGENTS.md ← フレームワーク固有の注意（Next.js等）
@docs/style-guide.md ← スタイルガイドが長い場合は分割
分割の判断基準：
- 更新頻度が違うなら分ける（プロジェクトルールは月1更新、フレームワーク注意は年1更新）
- CLAUDE.md単体が60行を超えてきたら分割を検討
- 「これだけ読めばこのタスクはできる」という単位で分ける
2層: UserPromptSubmit hook でセッション開始時に確実に情報を注入する
Claude Codeには「SessionStart」という専用hookはありません。代わりにUserPromptSubmit（最初のプロンプト受信時）を使います。
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'echo \"[Session] Project: $(basename $(pwd)) | Branch: $(git branch --show-current 2>/dev/null || echo none)\"'"
}
]
}
]
}
}
この設定は.claude/settings.json（プロジェクトレベル）または~/.claude/settings.json（グローバル）に書きます。
重要な挙動: hookはsettings.jsonを保存した瞬間から有効になります（2026-05-14の実測で確認。セッション再起動は不要）。
3層: グローバルメモリ（全プロジェクト共通）
~/.claude/CLAUDE.mdに書けば、すべてのプロジェクトのセッションで参照されます。
## 全プロジェクト共通ルール
- ファイル削除の前は必ずgit statusを確認する
- コミットメッセージは日本語で書く
ここには「どのプロジェクトでも絶対に守りたいこと」を書き、プロジェクト固有のルールはプロジェクトのCLAUDE.mdに書きます。
3層を使い分ける判断基準まとめ
| 書くもの | 置き場所 |
|---|---|
| プロジェクト固有の戦略・ルール・禁止事項 | プロジェクトの CLAUDE.md |
| フレームワーク固有の注意（長い） | @importで別ファイル |
| セッション開始時に必ず確認したいこと | UserPromptSubmit hook |
| 全プロジェクト共通ルール | ~/.claude/CLAUDE.md |
よくある詰まりパターン
- CLAUDE.mdが読まれる前に別の指示が勝っている — システムプロンプトや他のファイルの優先順位
- CLAUDE.mdが長くなりすぎて後半が薄く読まれている — @importで分割する
- セッション開始直後はまだ文脈が薄い — hookで明示的に注入する
- @importで参照しているファイルが実際には読まれていない — ファイルパスの確認
まとめ
- CLAUDE.mdは確率的に読まれる（ほぼ毎回だが100%ではない）
- hookはハーネスが実行するため確実（LLMの判断と独立）
- 3層（@import + UserPromptSubmit hook + グローバルメモリ）で役割を分けると確実性が上がる
- まず「CLAUDE.mdが60行超え」なら@import分割、「必ず確認させたいことがある」ならhookを入れる
元記事では各層の実際の設定ファイル全文と、masatoman.netプロジェクトでの適用例も載せています → https://www.masatoman.net/articles/claude-code-claude-md-skip-structure-2026?utm_source=qiita&utm_medium=referral&utm_campaign=dist-syndication&utm_content=claude-code-claude-md-skip-structure-2026