ai-docs

個人スコープの設定（~/.claude）

13 min read

~/.claude に何を置くか — 結局どうすればいいか

14本を統合する。**設定キーの一覧ではなく、「個人スコープに置いたときだけ起きること」**を書く。 キーそのものは settings、ルール構文は permissions にある。

1. 前提: 最も弱い層で、かつ自分にしか存在しない層

~/.claude/settings.json は5層のうち最下位である（settings）。

managed → CLI 引数 → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json

ただし「弱い」のは許可を与える向きだけで、禁止する向きには階層を貫く。

If a tool is denied at any level, no other level can allow it. The same holds across scopes: a user-level deny blocks a project-level allow. **いずれかの階層でツールが拒否されていれば、他のどの階層もそれを許可できない。**これはスコープをまたいでも成り立つ。user 階層の deny は project 階層の allow をブロックする。 — permissions

→ ~/.claude は「自分のマシンで絶対に踏みたくない線」を引く場所として使うのが最も確実。 allow を書いてもプロジェクト側の事情に負けるが、deny は誰も外せない。

もうひとつの性質は他人の環境に存在しないこと。CI、cloud セッション、Cowork、--bare はここを読まない。

A hook in a teammate’s ~/.claude or an MCP server in the project’s .mcp.json won’t run, because bare mode never reads them. teammate の ~/.claude にある hook や、プロジェクトの .mcp.json にある MCP サーバは動かない。bare モードはそれらを一切読まないからである。 — headless

置く基準は3つ。

問いNo なら
全プロジェクトで真かプロジェクトの .claude/ へ
自分だけのものかリポジトリにコミットして共有する
これが無くても他人の同じ作業が成立するか成立しないなら個人スコープに置いてはいけない（再現しない手順になる）

2. 何がどこに置かれるか

パス中身覚えておくこと
~/.claude/settings.json設定・permissions・hooks・env優先度は最下位。hook はマシンローカルで共有できない（hooks-guide）
~/.claude/CLAUDE.md全プロジェクト共通の指示常時 約320トークン（context-window）。さらに全 subagent にもロードされる（sub-agents、Explore / Plan を除く）
~/.claude/rules/マシン全体に効く ruleuser rule が先に読まれ、project rule のほうが優先度が高い（memory）
~/.claude/skills/<name>/SKILL.md個人 skillコマンド名はディレクトリ名から来る。name frontmatter は表示名にしか効かない（skills）
~/.claude/agents/**/*.md個人 subagent再帰的に走査され、同一性は name frontmatter だけで決まる（sub-agents）
~/.claude/workflows/保存した workflow同名ならプロジェクト側が走る（workflows）
~/.claude.jsonMCP の local / user スコープ**~/.claude/ の中ではない。**別ファイル（mcp）
~/.claude/projects/<project>/memory/auto memory<project> は git リポジトリから導出。全 worktree が1つを共有（memory）
~/.claude/projects/**/*.jsonltranscriptcleanupPeriodDays（既定30日）で削除される（settings、how-claude-code-works）
~/.claude/teams/ ~/.claude/tasks/agent teams の実行時状態手で編集しない（agent-teams）

3. 個人スコープ特有の落とし穴

3.1 パスパターンの / は「設定ファイルの場所」を基準にする

user settings に書いた /path は、ファイルシステムのルートでもプロジェクトルートでもなく ~/.claude/path を指す（permissions）。

A deny rule such as Read(/secrets/**) in user settings blocks ~/.claude/secrets/**, not a secrets directory in your project. user 設定にある Read(/secrets/**) のような deny ルールがブロックするのは ~/.claude/secrets/** であって、プロジェクト内の secrets ディレクトリではない。 — permissions

user settings では // か ~/ を使う。

{
  "permissions": {
    "deny": [
      "Read(//Users/alice/secrets/**)",
      "Read(~/.ssh/**)"
    ]
  }
}

**この誤りは沈黙する。**ルールは受理され、ただ何もブロックしない。

3.2 defaultMode: auto は ~/.claude/settings.json にしか書けない

プロジェクトの .claude/settings.json に書いても無視される。リポジトリが自分に auto mode を付与できないようにするための仕様（permission-modes）。

{ "permissions": { "defaultMode": "auto" } }

→ auto mode を常用するなら、置き場所はここ以外にない。

3.3 skill と subagent で、個人と project の強さが逆

**横断して初めて見えるもの。**同名で衝突したとき、勝つ側が逆になる。

優先順位同名のとき勝つのは
skillenterprise > personal > project（skills）~/.claude/skills/ 側
subagentmanaged > --agents > project > user > plugin（sub-agents）.claude/agents/ 側

→ 個人 skill に汎用的な名前（deploy、commit、review）を付けると、行った先のリポジトリの同名 skill を黙って上書きする。 個人 skill ほど名前を尖らせる。

なお skill は同名の bundled skill も上書きする（skills）。~/.claude/skills/code-review/ を作れば /code-review は自作のものに置き換わる。

3.4 ~/.claude/agents/ の同一性はパスではなく name

サブフォルダで整理してよいが、識別に効くのは name frontmatter だけ。ツリー全体で一意に保つ。重複するとファイルシステムの読み取り順という文書化されていない順序で片方だけがロードされる（sub-agents）。/doctor が重複を報告する。

3.5 MCP の user スコープは settings.json ではない

~/.claude.json に保存される。一般の local settings（.claude/settings.local.json）とも別物（mcp）。settings.json を眺めても MCP サーバは見えないので、claude mcp list で確認する。

3.6 個人 CLAUDE.md は subagent の数だけ複製される

~/.claude/CLAUDE.md はメイン会話がロードする階層として、すべての subagent の起動時 context にも入る（Explore と Plan だけがスキップする、sub-agents）。20並列なら20回分の常時コストになる。

そして CLAUDE.md は設定ではない。

Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead. Claude はそれらを、強制される設定ではなく context として扱う。Claude の判断によらず動作をブロックしたいなら、代わりに PreToolUse hook を使え。 — memory

→ 「絶対にやるな」を ~/.claude/CLAUDE.md に書くのは、全プロジェクト・全 subagent に常時課金しながら、保証は何も得ていない状態。 permissions.deny か hook にする。

3.7 個人設定に依存した手順は、他人と自分の CI で壊れる

headless の --bare は個人設定を一切読まない。cloud / Cowork セッションは ~/.claude/skills/ を読まないので、routine から個人 skill を呼ぶと「見つからない」と報告される（skills）。

→ 他人にも回す手順は、個人 skill ではなくリポジトリの .claude/skills/ にコミットする。

3.8 .claude 自体が保護ディレクトリで、allow では開かない

保護ディレクトリには .claude が含まれる（.claude/worktrees を除く）。

permissions.allow rules in settings files do not pre-approve protected-path writes. The safety check runs before Claude Code evaluates allow rules. 設定ファイル内の permissions.allow ルールは、保護されたパスへの書き込みを事前承認しない。安全性のチェックは、Claude Code が allow ルールを評価する前に走る。 — permission-modes

→ 設定ファイル自体を Claude に書き換えさせる運用は、allow を積んでも確認が出る。~/.claude/projects/ 配下の .jsonl transcript への書き込みも auto mode がブロックする（読み取りはブロックされない）。

4. user に置くか、project に置くか

置きたいもの置き場所理由
絶対に触らせたくないパス（~/.ssh など）~/.claude/settings.json の denyuser の deny は誰も外せない
auto mode を既定にする~/.claude/settings.jsonここにしか書けない
自分の好みのモデル・effort・theme~/.claude/settings.json他人には関係がない
全プロジェクトで使う個人的な作業手順~/.claude/skills/（名前は尖らせる）どのリポジトリでも呼べる
チームで守らせたい規約リポジトリの CLAUDE.md / .claude/個人スコープでは他人に届かない
CI でも効いてほしいことリポジトリ + 明示的なフラグ--bare は個人設定を読まない
環境固有のパスや秘密env か外部の仕組みリポジトリにコミットできない
全プロジェクト共通の指示~/.claude/CLAUDE.md（短く）常時コストと subagent 複製がある

5. 常時コストを見る

個人スコープに置いたものはすべてのセッションの起動時コストになる。

もの常時かコスト
~/.claude/CLAUDE.md常時代表 320トークン（context-window）+ subagent ごとに再ロード
~/.claude/rules/（paths なし）常時起動時にロードされる。project rule のほうが優先度が高い（memory）
~/.claude/rules/（paths あり）該当ファイルを読んだとき0
個人 skill の description常時skill 一覧の予算は context window の 1%。溢れると呼ぶ頻度が低いものから description が落とされる（skills）
個人 skill の本体呼んだとき呼んだ後はセッションの残りずっと居座る
disable-model-invocation: true の skill—description も context に載らない（skills）
個人 subagent の定義呼んだときメイン会話には載らない

→ 常時ロードを増やしたくないなら、~/.claude/CLAUDE.md ではなく ~/.claude/skills/ に置く。 手で呼ぶだけでよいものは disable-model-invocation: true を付けると常時コストがゼロになる。

6. 点検

/doctor      # 解決後の設定、strip されたエントリ、subagent 名の重複、skill 一覧のコスト
/status      # 設定がロードされているか
/context     # Memory files に自分のファイルが載っているか
/usage       # skill / subagent / plugin / MCP 別の内訳
/hooks       # 発火する hook の一覧（読み取り専用）
claude mcp list   # MCP は settings.json に出ないので別途

設定が効かないときの順序: /doctor でどの層の値が勝っているかを見る → user settings のパスパターンが / 始まりでないか（3.1）→ そのキーが user スコープで無効でないか（3.2 の逆）。

ほとんどの設定は再起動なしに反映される（settings）。例外は model（/model を使う）と outputStyle（/clear で再構築）。skill ディレクトリも監視されているが、セッション開始時に存在しなかったトップレベルの skills ディレクトリを作った場合は再起動が要る（skills）。

7. チェックリスト

新しく ~/.claude に何か置くとき
  □ 全プロジェクトで真か                        → 違うなら .claude/ へ
  □ 他人の同じ作業がこれ無しで成立するか          → しないならリポジトリへ
  □ パスパターンを書いたか                      → / ではなく // か ~/
  □ skill / subagent の名前は尖っているか        → 汎用名は他リポジトリを上書きする
  □ 常時ロードになるか                          → CLAUDE.md ではなく skill に置けないか
 
ときどき
  □ ~/.claude/CLAUDE.md が育っていないか        → 全 subagent に乗っている
  □ /doctor で重複した subagent 名がないか
  □ /usage で個人 skill の description コスト
  □ 「絶対にさせない」を CLAUDE.md で書いていないか → deny か hook へ

グラフビュー

バックリンク