何をどこに書くか 設定ファイル完全整理
CLAUDE.md・settings.json・Skills・Agents — 情報の種類別・最適な置き場所
- ~/.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 を指定したもの(一致するファイルを扱うとき)
必要なときだけ読まれる。使う頻度が低いものはここへ。
| 情報の種類 | 置き場所 | スコープ | 理由 |
|---|---|---|---|
| 返答言語・絶対ルール | ~/.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のファイルを読み書きしたときだけロード |
# ~/.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に。個人設定はローカルに。
症状: Claude がルールを無視し始める。矛盾する指示があると、どちらか一方が任意に選ばれる。
原因: PJ固有のルールがグローバルに混入。「書いた方が安心」という心理で追加し続けた結果、命令が埋もれる。
対処: 1行ごとに「これを消したら Claude が間違えるか?」と問う。NOなら消す。IMPORTANT: などの強調語に頼るのではなく、ファイルを短くする(公式の目安は1ファイル200行未満)。例外のないルールは hook か permissions の deny ルールにする。/doctor prompt-audit で矛盾や古い指示を点検できる。
症状: 別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 に書く。
症状: 起動コストが重くなる。関係ないスキルが誤発動する。「前の仕事で入れたやつ」が残り続ける。
原因: インストールコマンドが cp -r skills/xxx ~/.claude/skills/ でグローバル前提の設計になっている。バージョン管理・削除の仕組みがない。
対処: PJ固有のスキルは ./.claude/skills/ に置く。グローバルに入れるのは本当に全PJで使うものだけ(changelog-review など)。
症状: 関係ない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> の形で追加する。
# ./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: 取り込んだファイルは CLAUDE.md と一緒に起動時に読み込まれる。ファイルの整理には役立つが、トークンは減らない(入れ子は最大4段)
- .claude/rules/:
pathsを指定すると、一致するファイルを扱うときだけ読み込まれる。必要なときだけ読ませたいルールはこちら - Skills: 起動時は name と description だけ読み込まれ、本文は呼び出したときに読まれる
- 共有の CLAUDE.md からホームディレクトリなど外部のファイルを import すると、初回に承認を求められ、チームメイトの環境には存在しない。個人用の import は CLAUDE.local.md に書く
各行に対して以下の順で問う:
- 「これを消したら Claude が間違いを犯すか?」 → NOなら削除
- 「これは特定PJにしか関係ないか?」 → YESなら ./CLAUDE.md へ移動
- 「Claude はこれをすでに知っているか?」 → YESなら削除(言語仕様・一般的な慣習等)
- 「頻繁に変わる情報か?」 → YESなら削除(すぐ陳腐化する)
- 「これは自分の個人的な好みか?」 → YESなら CLAUDE.local.md へ移動
# 確認コマンド 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 に移動し、グローバルから削除する。
# インストール済みスキルを確認 ls ~/.claude/skills/ # 各スキルについて問う □ 今も使っているか? □ 全PJで使うか、特定PJだけか? □ 特定PJだけなら ./.claude/skills/ へ移動
グローバルに残すのは changelog-review など本当に横断的なものだけ。
最終更新: 2026-11-02 公式ドキュメント(code.claude.com の memory・mcp・settings・best-practices)と照合 · 独自調査・実運用経験を含む