📂 CLAUDE.MD ✦ CLAUDE.LOCAL.MD ✦ SETTINGS.JSON ✦ SKILLS ✦ AGENTS ✦ @IMPORT ✦ CONTEXT POLLUTION ✦ SCOPE HIERARCHY ✦ MCP SERVER ✦ HOOKS ✦ 📂 CLAUDE.MD ✦ CLAUDE.LOCAL.MD ✦ SETTINGS.JSON ✦ SKILLS ✦ AGENTS ✦
📂 CONTEXT GUIDE
何をどこに書くか
設定ファイル完全整理
CLAUDE.md・settings.json・Skills・Agents — 情報の種類別・最適な置き場所
CLAUDE.md 汚染防止 Skills スコープ設計
🔗 関連ガイド
コンテナでのボリューム永続化・バックグラウンドジョブ運用は コンテナ運用ガイド、サンドボックスの仕組み自体は サンドボックスガイド を参照。
⚡ TL;DR
🕐 常時ロードされるものは短く。 CLAUDE.md は毎セッションのトークンコスト。読まれるだけで消費される
🎯 たまにしか使わないものは Skills へ。 オンデマンドロードで必要なときだけ読まれる
🔒 PJ固有のものは絶対グローバルに書かない。 書く前に「全PJで必要か?」と問う
📝 長い説明は docs/ に書いて @import 参照。 CLAUDE.md 本体は目次として保つ
01 — まずロードタイミングを理解する
⚡ 毎セッション自動ロード
  • ~/.claude/CLAUDE.md
  • ./CLAUDE.md
  • ./CLAUDE.local.md
  • 親ディレクトリの CLAUDE.md

ここに書いたものは 常にトークンを消費する。 短さが正義。

⏳ オンデマンドロード
  • .claude/skills/ (呼び出し時)
  • .claude/agents/ (委譲時)
  • subdir/CLAUDE.md (そのdirを触ったとき)
  • @import 先のファイル (参照時)

必要なときだけ読まれる。使う頻度が低いものはここへ。

02 — 情報の種類 × 最適な置き場所
情報の種類 置き場所 スコープ 理由
返答言語・絶対ルール ~/.claude/CLAUDE.md GLOBAL 本当に全PJで毎回必要なものだけ
ビルド・テストコマンド ./CLAUDE.md PROJECT PJ固有。チームで共有するためgit管理
コーディング規約(短いもの) ./CLAUDE.md PROJECT 常時必要なら直書き。長ければ @import
アーキテクチャ・API仕様(長文) ./docs/xxx.md
→ @import で参照
PROJECT CLAUDE.md を太らせない。docs/ に本体を置く
個人的な癖・好み ./CLAUDE.local.md LOCAL .gitignore に追加。チームに強制しない
たまにしか使わないワークフロー ./.claude/skills/ PROJECT オンデマンドロード。常時読まれない
権限許可・hooks ./.claude/settings.json PROJECT PJスコープで閉じる。グローバルに書かない
MCP サーバー設定(PJ用) claude mcp add -s local PROJECT -s user にするとグローバル汚染する
サブエージェント定義 ./.claude/agents/ PROJECT PJ固有の専門エージェント
サブディレクトリの特殊ルール ./subdir/CLAUDE.md ON-DEMAND そのdirを触ったときだけロード。常時不要
03 — どこに書くか迷ったときの判断ツリー
「この情報、本当に書く必要があるか?」 YES 「全PJで毎回必要か?」 ├─ YES ~/.claude/CLAUDE.md ← ここは最小限に └─ NO 「このPJのチーム全員に必要か?」 ├─ YES ./CLAUDE.md ← git管理 └─ NO(自分だけ) ./CLAUDE.local.md ← .gitignore 「毎セッション必要か、たまにだけか?」 ├─ 毎回 ./CLAUDE.md に短く書く └─ たまに ./.claude/skills/ ← オンデマンド 「長い説明が必要か?」 └─ YES ./docs/ に書いて @import で参照
04 — やりがちな汚染パターン vs 正しい書き方
❌ 悪い例:グローバルに何でも書く
# ~/.claude/CLAUDE.md
- 返答は日本語で
- src/auth/ は JWT を使っている  ← PJ固有
- テストは pytest で実行          ← PJ固有
- Slackはscripts/notify.shで通知 ← すぐ陳腐化
- React のベストプラクティスに従う ← Claude はもう知ってる
- コードは読みやすく書く          ← 自明

PJが増えるほど矛盾が増え、ルールが埋もれて Claude に無視される。

✅ 良い例:スコープを分けて書く
# ~/.claude/CLAUDE.md
- 返答は常に日本語で

# ./CLAUDE.md(PJ固有)
- ビルド: npm run build
- テスト: npm test
- アーキテクチャ: @docs/arch.md

# ./CLAUDE.local.md(個人)
- コミットメッセージは英語で

グローバルは 1 行。PJ固有はPJに。個人設定はローカルに。

05 — 汚染の種類と症状
A CLAUDE.md の汚染 — 命令の競合・肥大化

症状: Claude がルールを無視し始める。矛盾する指示を両方守ろうとして挙動がおかしくなる。

原因: PJ固有のルールがグローバルに混入。「書いた方が安心」という心理で追加し続けた結果、命令が埋もれる。

対処: 1行ごとに「これを消したら Claude が間違えるか?」と問う。NOなら消す。重要なルールには IMPORTANT:YOU MUST を付けて埋もれを防ぐ。

B settings.json の汚染 — 権限・hooks の累積

症状: 別PJの hooks が発火する。関係ないコマンドに権限が付いている。「Always allow」を押し続けた結果、何でも通る状態に。

# 気づかないうちにこうなる
"permissions": {
  "allow": [
    "Bash(make deploy*)",     ← Aプロジェクト用
    "Bash(kubectl apply*)",   ← 前の仕事のやつ
    "Bash(npm run release*)"  ← いつ追加したか不明
  ]
},
"hooks": {
  "PostToolUse": [
    { "command": "notify-slack.sh" }  ← どのPJのSlack?
  ]
}

対処: グローバルの ~/.claude/settings.json は定期的に棚卸し。PJ固有の権限・hooks は ./.claude/settings.json に書く。

C Skills のグローバル化 — 不要スキルの蓄積

症状: 起動コストが重くなる。関係ないスキルが誤発動する。「前の仕事で入れたやつ」が残り続ける。

原因: インストールコマンドが cp -r skills/xxx ~/.claude/skills/ でグローバル前提の設計になっている。バージョン管理・削除の仕組みがない。

対処: PJ固有のスキルは ./.claude/skills/ に置く。グローバルに入れるのは本当に全PJで使うものだけ(changelog-review など)。

D MCP サーバーのグローバル化 — 不要な接続の常時確立

症状: 関係ないDBに繋がろうとする。起動時エラーが増える。別PJのNotionに誤アクセス。

# グローバルに書いてしまった例(避けるべき)
claude mcp add my-db-server postgresql://...

# PJスコープで追加する(推奨)
claude mcp add -s local my-db-server postgresql://...
# → .claude/mcp.json に書かれる(git管理可)

対処: MCP 追加時は必ず -s local(PJスコープ)か -s project を指定。-s user はグローバルになる。

06 — @import で CLAUDE.md を目次にする
📎 @import 構文パターン
# ./CLAUDE.md — 本体は目次として短く保つ

## Project Overview
See @README.md

## Commands
- Build: npm run build
- Test:  npm test
- Lint:  npx eslint .

## Architecture
@docs/architecture.md

## API Conventions
@docs/api-conventions.md

## Git Workflow
@docs/git-workflow.md

# 個人の追加ルール(ローカルのみ)
@~/.claude/my-personal-rules.md
💡 @import のメリット
  • CLAUDE.md 本体が短く保たれる(ルールが埋もれない)
  • 詳細ドキュメントは docs/ で人間も読める形で管理できる
  • Claude が 参照時にだけ読み込む(常時トークン消費しない)
  • ファイルごとにバージョン管理・レビューがしやすい
07 — 既存設定の棚卸しチェック
~/.claude/CLAUDE.md の精査

各行に対して以下の順で問う:

  1. 「これを消したら Claude が間違いを犯すか?」 → NOなら削除
  2. 「これは特定PJにしか関係ないか?」 → YESなら ./CLAUDE.md へ移動
  3. 「Claude はこれをすでに知っているか?」 → YESなら削除(言語仕様・一般的な慣習等)
  4. 「頻繁に変わる情報か?」 → YESなら削除(すぐ陳腐化する)
  5. 「これは自分の個人的な好みか?」 → YESなら CLAUDE.local.md へ移動
~/.claude/settings.json の棚卸し
# 確認コマンド
cat ~/.claude/settings.json

# 確認すべき項目
permissions.allow  ← 各ルールが今も有効か?どのPJ用か?
hooks              ← 各hookがどのPJのものか?今も必要か?
mcpServers         ← PJ固有のサーバーが混入していないか?

PJ固有のものは ./.claude/settings.json に移動し、グローバルから削除する。

~/.claude/skills/ の棚卸し
# インストール済みスキルを確認
ls ~/.claude/skills/

# 各スキルについて問う
 今も使っているか?
 全PJで使うか、特定PJだけか?
 特定PJだけなら ./.claude/skills/ へ移動

グローバルに残すのは changelog-review など本当に横断的なものだけ。

最終更新: 2026-06-13 ✦ 公式 Best Practices (code.claude.com) を参照 ✦ 独自調査・実運用経験を含む