🔗 関連ガイド
コンテナでのボリューム永続化・バックグラウンドジョブ運用は コンテナ運用ガイド、サンドボックスの仕組み自体は サンドボックスガイド を参照。
⚡ TL;DR
🕐 常時ロードされるものは短く。 CLAUDE.md は毎セッションのトークンコスト。読まれるだけで消費される
🎯 たまにしか使わないものは Skills へ。 オンデマンドロードで必要なときだけ読まれる
🔒 PJ固有のものは絶対グローバルに書かない。 書く前に「全PJで必要か?」と問う
📝 一部のファイルにだけ関係するルールは .claude/rules/ に paths 付きで。 @import は起動時に全文が読み込まれるのでトークンは減らない
01 — まずロードタイミングを理解する
⚡ 毎セッション自動ロード
  • ~/.claude/CLAUDE.md
  • ./CLAUDE.md
  • ./CLAUDE.local.md
  • 親ディレクトリの CLAUDE.md
  • 上記から @import したファイル(一緒に展開される)
  • .claude/rules/*.md(paths 指定がないもの)
  • Skills・サブエージェントの name / description

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

⏳ オンデマンドロード
  • .claude/skills/ の本文(呼び出し時)
  • .claude/agents/ の本文(委譲時)
  • subdir/CLAUDE.md (そのdirのファイルを読み書きしたとき)
  • .claude/rules/*.md で paths を指定したもの(一致するファイルを扱うとき)

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

02 — 情報の種類 × 最適な置き場所
情報の種類 置き場所 スコープ 理由
返答言語・絶対ルール ~/.claude/CLAUDE.md GLOBAL 本当に全PJで毎回必要なものだけ
ビルド・テストコマンド ./CLAUDE.md PROJECT PJ固有。チームで共有するためgit管理
コーディング規約(短いもの) ./CLAUDE.md PROJECT 常時必要なら直書き。一部のファイルにだけ関係するなら .claude/rules/ に paths 付きで
アーキテクチャ・API仕様(長文) ./docs/xxx.md
(必要なら .claude/rules/ や Skills から参照)
PROJECT リポジトリを読めばわかる構成は書かない。@import すると毎回全文が読み込まれるので、長文は取り込まない
個人的な癖・好み ./CLAUDE.local.md LOCAL .gitignore に追加。チームに強制しない
たまにしか使わないワークフロー ./.claude/skills/ PROJECT オンデマンドロード。常時読まれない
権限許可・hooks ./.claude/settings.json PROJECT PJスコープで閉じる。グローバルに書かない
MCP サーバー設定(チーム共有) claude mcp add -s project
→ ./.mcp.json
PROJECT git で共有する。-s user にすると全PJに効く
MCP サーバー設定(自分だけ・このPJ) claude mcp add -s local(既定)
→ ~/.claude.json
LOCAL このPJでだけ自分が使う。共有されない
サブエージェント定義 ./.claude/agents/ PROJECT PJ固有の専門エージェント
一部のファイルにだけ関係するルール ./.claude/rules/*.md
(frontmatter に paths)
ON-DEMAND 一致するファイルを扱うときだけロード。公式が推奨する置き場
サブディレクトリの特殊ルール ./subdir/CLAUDE.md ON-DEMAND そのdirのファイルを読み書きしたときだけロード
03 — どこに書くか迷ったときの判断ツリー
「この情報、本当に書く必要があるか?」 ↓ YES 「全PJで毎回必要か?」 ├─ YES → ~/.claude/CLAUDE.md ← ここは最小限に └─ NO ↓ 「このPJのチーム全員に必要か?」 ├─ NO(自分だけ) → ./CLAUDE.local.md ← .gitignore └─ YES ↓ 「毎セッション必要か?」 ├─ 毎回 → ./CLAUDE.md に短く書く ← git管理 ├─ 特定のファイルを扱うときだけ → ./.claude/rules/(paths 指定) └─ 特定の作業のときだけ → ./.claude/skills/ ← 呼び出し時に本文を読む
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
- API の規約: .claude/rules/api.md(paths 指定)

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

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

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

症状: Claude がルールを無視し始める。矛盾する指示があると、どちらか一方が任意に選ばれる。

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

対処: 1行ごとに「これを消したら Claude が間違えるか?」と問う。NOなら消す。IMPORTANT: などの強調語に頼るのではなく、ファイルを短くする(公式の目安は1ファイル200行未満)。例外のないルールは hook か permissions の deny ルールにする。/doctor prompt-audit で矛盾や古い指示を点検できる。

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

症状: 別PJの hooks が発火する。関係ないコマンドに権限が付いている。権限の確認で「Yes, and don't ask again」を選び続けた結果、allow ルールが溜まって何でも通る状態に(この承認はリポジトリの .claude/settings.local.json に保存される)。

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

対処: グローバルの ~/.claude/settings.json と、各PJの .claude/settings.local.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に誤アクセス。

# 全PJに効いてしまう例(PJ固有のサーバーでは避ける)
claude mcp add -s user my-db-server -- npx -y @example/db-mcp

# チームで共有する(./.mcp.json に書かれ、git管理できる)
claude mcp add -s project my-db-server -- npx -y @example/db-mcp

# 自分だけ・このPJだけ(既定。~/.claude.json に保存され共有されない)
claude mcp add my-db-server -- npx -y @example/db-mcp

対処: スコープを指定しない既定は local(自分だけ・このPJ)。チームで共有するなら -s project、全PJで使うものだけ -s user。HTTP のサーバーは claude mcp add --transport http <name> <url> の形で追加する。

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

## Project Overview
See @README.md

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

## Git Workflow
@docs/git-workflow.md   ← 毎回必要な短いものだけ import

# ./CLAUDE.local.md(個人用。共有の CLAUDE.md には書かない)
@~/.claude/my-personal-rules.md

# ./.claude/rules/api.md — src/api を扱うときだけ読み込まれる
---
paths:
  - "src/api/**"
---
- API レスポンスは zod で検証する
💡 @import と rules の違い
  • @import: 取り込んだファイルは CLAUDE.md と一緒に起動時に読み込まれる。ファイルの整理には役立つが、トークンは減らない(入れ子は最大4段)
  • .claude/rules/: paths を指定すると、一致するファイルを扱うときだけ読み込まれる。必要なときだけ読ませたいルールはこちら
  • Skills: 起動時は name と description だけ読み込まれ、本文は呼び出したときに読まれる
  • 共有の CLAUDE.md からホームディレクトリなど外部のファイルを import すると、初回に承認を求められ、チームメイトの環境には存在しない。個人用の import は CLAUDE.local.md に書く
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
claude mcp list   # MCP サーバーは settings.json ではなく ~/.claude.json に保存される

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

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

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

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

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

最終更新: 2026-11-02 公式ドキュメント(code.claude.com の memory・mcp・settings・best-practices)と照合 · 独自調査・実運用経験を含む