背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

公式ドキュメント：https://code.claude.com/docs/ja/settings

1. 一言でいうと

Claude Code の設定がどのファイルに書かれ、それぞれ誰に効くのか、同じキーが複数の場所にあるときはどれが勝つのかを説明するページです。優先順位は上から「管理設定 → コマンドラインの --settings → プロジェクトローカル → 共有プロジェクト → ユーザー」の5段で、上の段が下の段を上書きします。ただし、配列はマージされること、環境変数はこの段には入らないこと、セキュリティに関わる一部のキーでは下の段の「より厳しい値」が管理設定にも勝つこと、という3つの例外があります。

前回の「すべての設定」は、245 個のキーそれぞれについて「何を書けるか」を引く辞書でした。その辞書が冒頭で「ファイルの選び方と優先順位はこちらから」と送り出していた先が、今回のページです。辞書と合わせて読むと、「書いたのに効かない」の原因の大半を切り分けられるようになります。

---

2. どういう場面で役立つか

シーン1：チームの設定と自分の好みがぶつかる

チームがコミットした .claude/settings.json ではモデルが Sonnet になっているが、自分は Opus を使いたい。こういうときに、チームのファイルを書き換えずに自分だけ変える方法（プロジェクトローカルのファイル）がわかります。

シーン2：設定したはずなのに効かない

~/.claude/settings.json でオフにしたはずの機能が、あるプロジェクトでだけ戻ってくる。チームメイトにはコミットした許可ルールが効いていない。こうした症状ごとに、原因の候補と確かめ方が原文にまとまっています。

シーン3：クラウドセッションで手元と違う動きをする

Claude Code on the web のクラウドセッションは、手元のマシンとは別の場所で、リポジトリの新しいクローンの上で動きます。どの設定ファイルがそこまで届き、どれが届かないのかを確かめられます。

不要・向かないケース

• 特定のキーの意味や既定値を知りたい：それは前回の「すべての設定」の担当です。原文も冒頭でそちらへ案内しています。
• 権限ルールの書き方を知りたい：allow・ask・deny の構文は「権限を構成する」のページの担当です。
• 組織の管理設定をどう配るか知りたい：配信の仕組みは「管理設定をデプロイする」や、第48回で取り上げたサーバー管理設定のページが担当です。今回のページは、利用者の側から「組織に何を強制されているか」を確かめる方法に絞っています。

---

3. コードと仕組みの解説

原文の fenced コードブロックは 2本（設定ファイルの例と、1回だけ設定を変えるコマンド）で、どちらも引用します。原文の冒頭には優先順位とスコープの図を描くための React コンポーネントのコードがありますが、これはページの表示用なので引用せず、図が表している中身を表に起こします。

3-0. バージョン要件

バージョン	内容
v2.1.211 より前	プロジェクトローカルのファイルを、リポジトリのルートではなく開始したディレクトリに置いていた
v2.1.242 以降	modelPicker の独自の組み合わせ規則、enableArtifact の「より厳しい値が勝つ」例外
v2.1.246 以降	/cd で移動した先のディレクトリからプロジェクトのファイルを読み直す
v2.1.257 以降	permissions.blockReadsOutsideWorkingDirectories の例外。これより前は bypassPermissions がどのファイルからでも有効になっていた
v2.1.267 以降	maxEffortLevel の例外（いちばん低い上限が勝つ）

3-1. 4つのファイルと、5つ目のファイル

Claude Code は4つのファイルから設定を読み込み、組織は claude.ai のコンソールからも管理設定を配れます。原文の表を要約します。

スコープ	ファイル	誰に効くか	主な用途
ユーザー	~/.claude/settings.json	自分。このマシンのすべてのプロジェクト	テーマ、エディターモード、既定のモデル、自分の権限ルール
共有プロジェクト	.claude/settings.json	そのフォルダで作業する全員（コミットすればチームメイトにも届く）	チームの権限、フック、プラグイン、プロジェクトに要る環境変数
プロジェクトローカル	.claude/settings.local.json	自分。このプロジェクトだけ	1つのプロジェクトでの個人的な上書き、共有する前の試し
管理	managed-settings.json などの管理ソース	組織が配った全員	セキュリティポリシー、コンプライアンス要件

~/.claude はホームディレクトリの .claude フォルダ、パスのない .claude はプロジェクトの中の .claude フォルダです。Windows では ~/.claude は %USERPROFILE%\.claude を指します。

Claude Code をインストールしても、設定ファイルは作られません。 手元にあるとすれば、組織が配ったもの、プロジェクトにコミットされていたもの、あるいは Claude Code が自動で書いたものです。自動で書かれるタイミングは原文に書かれています。/config でテーマなどを初めて変えたときに ~/.claude/settings.json が、権限の確認で「はい、今後は聞かないでください」を初めて選んだときに .claude/settings.local.json が作られます。

これとは別に、5つ目のファイル ~/.claude.json があります。サインインの状態、MCP サーバーの設定、フォルダの信頼の判断といったプロジェクトごとの状態と、/config が書くグローバル設定のキーを持つファイルで、Claude Code 自身が書き込みます。原文は「編集する必要はありません」と書いています。前回見たとおり、グローバル設定のキーはこのファイルにしか効きません。

どこまで届くか

原文は、website/・api/・acme-app/ の3つのプロジェクトを持つ人を例に、各ファイルの届く範囲を説明しています。

• ~/.claude/settings.json は自分のマシンのすべてのプロジェクトに届くが、チームメイトのクローンやクラウドセッションには届かない。
• acme-app/.claude/settings.json は、コミットして初めてチームメイトのクローンとクラウドセッションに届く。それまではただのファイル。
• acme-app/.claude/settings.local.json は自分の acme-app/ だけ。
• 管理設定は組織が配ったマシンのすべてのプロジェクトに届くが、クラウドセッションまで届くのはサーバー管理設定だけ。

3-2. プロジェクトローカルのファイルの細かい振る舞い

.claude/settings.local.json は、共有ファイルの上に重ねる「自分用の上書き」です。原文は、チームのファイルが "model": "claude-sonnet-5" を設定していても、ローカルファイルに "model": "claude-opus-5-5" を入れれば自分のセッションだけが変わる、という例を挙げています。このファイルには3つの特徴があります。

1. Claude Code もここに書き込む。 権限の確認で「はい、今後は聞かないでください」を選ぶと、その承認が allow ルールとして保存されます。
2. 自分で作った場合を除き、gitignore は不要。 Claude Code がこのファイルを初めて書くとき、グローバルな git の除外ファイルに **/.claude/settings.local.json を追加します。除外ファイルは、core.excludesFile が絶対パスか ~ で始まるパスならそのファイル、そうでなければ $XDG_CONFIG_HOME/git/ignore、XDG_CONFIG_HOME がなければ ~/.config/git/ignore です。手で作ったファイルは自分で .gitignore に追加する必要があります。
3. git で追跡されていない間は、allow ルールが信頼の確認を待たない。 リポジトリのものではなく自分のものだからです。逆に、git で追跡されているなら、共有ファイルと同じく信頼の確認が要ります。

置き場所にも注意が要ります。git リポジトリのサブディレクトリで Claude Code を始めても、ローカルファイルはリポジトリのルートに置かれ、承認はリポジトリ全体に効きます（worktree ではメインのチェックアウトのルート）。ただし、git リポジトリの外、リポジトリのルートがホームディレクトリ、Windows、ルートや .git・.claude の所有者が自分でない、のいずれかに当たるときは、共有ファイルと同じ場所に置かれます。また、ファイルがルートにあっても、/ で始まる権限ルールや相対パスのサンドボックスのパスは、リポジトリのルートではなくセッションのプライマリ作業ディレクトリを基準にします。

一方、共有の .claude/settings.json はセッションのプライマリ作業ディレクトリから読み込まれます。 ルートにコミットしたファイルを使うには、ルートで Claude Code を始める必要があります。サブディレクトリで始めると、ローカルファイルはルートのものが効くのに共有ファイルは効かない、という食い違いが起こりうる、ということです（筆者の解釈）。

3-3. 設定を変える3つの方法

/config メニュー

/config の Config タブには、テーマ、エディターモード、詳細出力などの短い個人向けのオプションだけが並びます。すべてのキーではありません。保存先は、ほとんどが ~/.claude/settings.json、「ヒントを表示」など一部は .claude/settings.local.json、グローバル設定のオプションは ~/.claude.json です。/config verbose=true のように key=value を渡せば、メニューを開かずに設定できます。なお /config はターミナルの機能で、VS Code のチャットパネルやデスクトップアプリでは開きません。

設定ファイルを直接編集する

設定ファイルは厳密な JSON です。// のコメントや末尾のカンマは構文エラーになり、次の起動時に設定エラーとして報告されます。原文の例は、lint とテストのコマンドを確認なしで実行させ、.env を読ませないようにするものです。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

1行目の $schema は、Claude Code の設定の公開 JSON スキーマを指します。VS Code や Cursor など JSON スキーマに対応したエディターで、補完とその場での検証が効くようになります。ただし原文は、スキーマは最新の CLI のリリースより遅れることがあるので、最近ドキュメントに載ったキーで検証の警告が出ても、設定が無効とは限らない、と注意しています。

1つのセッションだけ変える

値を保存せずに試すには、起動時に指定します。方法は3つで、--settings に JSON（インラインかファイルのパス）を渡す、キー専用のフラグ（model の --model、effortLevel と modelSettings の --effort など）を使う、対になる環境変数（model なら ANTHROPIC_MODEL）を設定する、のいずれかです。

claude --settings '{"model": "claude-opus-5-5"}'

--settings はユーザー設定のファイルに書けるキーなら設定できますが、Managed と Global config のキーは設定できません。

反対に、セッションの中で使うコマンドはたいてい選択を保存します。 /config は設定ファイルに書き、/model は新しいセッションの既定として保存します。保存せずにモデルを切り替えたいときは、/model のピッカーで s を押します。

いつ効くか

Claude Code は設定ファイルを監視しているので、permissions、hooks、apiKeyHelper などの編集は、ほとんど再起動なしで実行中のセッションに反映されます。ファイルの変更を検知するたびに ConfigChange フックも動きます。ただし、MDM や claude.ai のコンソールから届く管理設定は、保存時ではなく決まったスケジュールで届きます。また、model、effortLevel、modelSettings のようにセッション開始時に一度だけ読むキーは、編集しても実行中のセッションには届きません。セッションの途中で変えるなら /model や /effort を使います。

3-4. 優先順位の5段

原文の図を表に起こすと次のとおりです。上ほど優先されます。

順位	レベル	ファイルなど	誰の設定か
1	管理設定	managed-settings.json、MDM、claude.ai コンソール	組織
2	コマンドライン	claude --settings	自分、このセッションだけ
3	プロジェクトローカル	.claude/settings.local.json	自分、このプロジェクトだけ
4	共有プロジェクト	.claude/settings.json	プロジェクトの全員
5	ユーザー	~/.claude/settings.json	自分、すべてのプロジェクト

注意したい点がいくつかあります。

• 共有プロジェクトはユーザーより上です。 個人のファイルで何かをオフにしても、チームのファイルがオンにしていればそのプロジェクトではオンになります。前回、プラグインの enabledPlugins で「プロジェクトの有効は個人の無効に勝つ」と見たのは、この順位の一例です。
• 管理設定の model はロックではなく、開始時の既定値です。 モデルを縛るのは availableModels と deniedModels です。--model などのフラグは、組織が許可したモデルの中からしか選べません。
• --model のような個別のフラグは、この段に含まれません。 段に入るのは --settings で渡した JSON だけです。
• 環境変数も段に入りません。 シェルの変数と設定のキーのどちらが勝つかは、ペアごとに決まります。たとえばシェルの ANTHROPIC_MODEL はどのファイルの model よりも優先されますが、ANTHROPIC_DEFAULT_MODEL はどのファイルも model を設定していないときにしか使われません。一方、設定ファイルの中の env ブロックはふつうのキーとして、この段に従います。

配列は上書きではなくマージ

permissions.allow のような配列のキーは、複数のファイルにあるとき1つを選ぶのではなく、結合されます。各ファイルは、ほかのファイルのエントリを消さずに追加できます。ただし、モデルに関わる4つのキーは独自の規則に従います。

キー	規則
fallbackModel	順番に意味がある連鎖なので、最も優先度の高いファイルの値をまるごと使う
modelPicker	管理設定・--settings・ユーザー設定のうち最も高いものの値をまるごと使い、プロジェクトとローカルの値は無視する
availableModels	管理設定が定義していれば、それをそのまま使い、ユーザー・プロジェクト・ローカルで足したエントリは無視する（Claude Code を埋め込むアプリが独自のリストを渡す場合を除く）
modelSettings	effortLevel と合わせて、モデルごとに1つずつ決める

3-5. より厳しい値が管理設定に勝つ例外

ここがこのページでいちばん特徴的なところです。セッションを制限する方向の値を持つ少数のキーでは、ふつうは管理設定を上書きできないはずの段の値でも、より厳しいものが優先されます。原文の表を要約します。

キー	優先される値	どこからでもよいか
disableClaudeAiConnectors	true	どのスコープからでも
enableArtifact	false（または disableArtifact: true）	どのスコープからでも。何をしてもオンに戻らない
isolatePeerMachines	true	どのスコープからでも
permissions.blockReadsOutsideWorkingDirectories	true	どのスコープからでも
autoMode.classifyAllShell	true	~/.claude/settings.json か --settings から
remoteControlAtStartup	false	共有プロジェクトかローカルから（プロジェクトの true は無視）
crossSessionInbound	より厳しい値（accept < hold < refuse）	共有プロジェクトかローカルから（緩い値は無視）
useAutoModeDuringPlan・syncClaudeAiSkills・syncClaudeAiPlugins	false	管理・--settings・ユーザー・ローカルから（共有プロジェクトの false は無視）
maxEffortLevel	より低い上限	--settings を含むどのスコープからでも

キーによって「どこからの厳しい値なら認めるか」が違うのが読みどころです。remoteControlAtStartup と crossSessionInbound は、リポジトリが自分を守る方向に締めることを認めています。一方、useAutoModeDuringPlan や同期の2つのキーは、共有プロジェクトの false を無視します。チームのファイルが個々の利用者の同期や auto モードの使い方を決めるのは筋が違う、という線引きだと読めます（筆者の解釈）。

これとは別の例外として、Claude Code を内部で動かし、CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定するアプリのモデル設定は、管理ソースの model・fallbackModel・modelPicker・modelOverrides より優先されます。

3-6. 効かないときの切り分け

原文は、まず /status で読み込まれたファイルを確かめ、次に症状から原因を探すよう勧めています。症状ごとに整理します。

症状	主な原因	対処
設定した値が無視される	上の段が同じキーを設定している／セキュリティキーの厳しい値が残っている／そのファイルからは設定できない値（auto・bypassPermissions の開始モード、テレメトリを有効にする env 変数）／ファイルが壊れている	/status で読み込み元を見て、上の段か前回の辞書のスコープの行を確認
Claude Code の中で変えた値が次のセッションで消える	~/.claude/settings.json に書けない（別のツールが生成している、読み取り専用のコピーへのリンク）	生成元のツールでキーを設定するか、書き込めるファイルに置き換える
管理設定の変更が届かない	届くのはスケジュールどおり／より優先度の高い管理ソースがある	セッションを再開し、/status のソース名を確認
コミットしたキーがチームメイトに効かない	リポジトリのファイルからは効かないスコープのキー／信頼待ち	辞書のスコープの列を確認。各自がフォルダを信頼する
権限ルールの組み合わせが想定と違う	ローカルに保存した allow は、プロジェクトや管理設定の ask に勝たない／管理設定の allow は自分のものとマージされる	権限ルールの結合順を確認

信頼待ちになるものは具体的に挙げられています。permissions.allow、permissions.additionalDirectories、extraKnownMarketplaces、そして env のほとんどの値は、各チームメイトがフォルダを信頼するまで効きません。一方で deny と ask はすぐに効きます。 許可を広げる設定だけが信頼を待つ、という非対称な作りです。

筆者の指摘：権限の行の補足として、原文は VS Code 拡張機能の承認カードが、共有プロジェクトのファイルも含めて保存先を選べると書いています。そこを選ぶとチーム全員のルールが変わります。CLI ではローカルのファイルにしか書かれないので、同じ「今後は聞かない」でも、どこで押したかで影響範囲が変わります。

壊れた設定ファイル

壊れ方によって表示が変わります。

種類	何が起きるか
設定エラー	ユーザー・プロジェクト・ローカルのファイルが不正な JSON か、スキーマが拒否する値を含む。対話セッションの開始時にダイアログが出て、Claude の助けで直す・終了する・壊れた設定なしで続ける、を選べる
設定警告	個々のエントリだけが失敗（不正な権限ルール、不明なフックのイベント名など）。その値だけを飛ばし、残りは有効
管理設定	残りの部分は強制され続ける
構成エラー	~/.claude.json が解析できない。壊れたファイルを ~/.claude/backups/ に退避し、手で直すか既定に戻すかを尋ねる

~/.claude.json は、書き込む前に ~/.claude/backups/ にバックアップが保存されていて、最新の5つから戻せます。

ここで見落としやすいのが -p の実行です。-p ではダイアログが出ず、管理設定のドキュメントが解析できない場合を除いて、壊れたファイルや値を黙って飛ばして続行します。原文は、設定を飛ばした -p の実行のあとは claude doctor で何が捨てられたか確認するよう書いています。CI などで -p を使っているなら、設定ファイルの編集のあとに一度確かめておくと安全です（筆者の指摘）。

3-7. クラウドセッションに届く設定

クラウドセッションは、手元のマシンではなくリポジトリの新しいクローンで動くので、届く設定が限られます。

設定	クラウドセッションでは
共有プロジェクト（.claude/settings.json）	リポジトリが1つのセッションなら読み込まれる。Anthropic がホストする環境で複数のリポジトリを扱うセッションでは、各リポジトリから enabledPlugins と extraKnownMarketplaces だけを読み、権限ルール・フック・env などは読まない
ユーザー・プロジェクトローカル	読み込まれない（どちらも手元のマシンにある）
管理設定	デバイスの managed-settings.json や MDM プロファイルは届かない。サーバー管理設定は届く
/config	ブラウザの claude.ai/code では値を変えず、claude.ai の設定画面を開く

クラウドセッションの設定を変えるには、環境に環境変数を設定するか、リポジトリが1つのセッションなら .claude/settings.json にコミットします。

---

4. まとめ

• 設定ファイルは ユーザー・共有プロジェクト・プロジェクトローカル・管理 の4つ。これとは別に、Claude Code 自身が書く ~/.claude.json がある。インストールしただけではどのファイルも作られない。
• 優先順位は 管理 → --settings → ローカル → 共有プロジェクト → ユーザー。共有プロジェクトはユーザーより上なので、チームの設定を自分だけ変えるならローカルのファイルを使う。
• 配列はマージ、環境変数と個別のフラグは段の外でキーごとに決まる、一部のセキュリティキーは下の段の厳しい値が管理設定にも勝つ。
• 共有ファイルでは、許可を広げる設定（allow、追加ディレクトリ、マーケットプレイス、ほとんどの env）は信頼を待つが、deny と ask はすぐ効く。
• 効かないときはまず /status、何が捨てられたかは claude doctor。-p では壊れた設定が黙って飛ばされるので特に注意。
• クラウドセッションに届くのは、コミットした共有ファイルとサーバー管理設定だけ。

次回予告

次回は 「設定ファイルの例」（settings-example） を取り上げる予定です。

前回の「すべての設定」でキーの一覧を、今回は設定ファイルの置き場所と優先順位を見てきました。どちらのページも、完成した設定ファイルの見本として「設定ファイルの例」を案内しています。次回は、個人用のファイル、チームで共有するファイル、組織が配る管理設定のファイルという3つの見本を読み、ここまでの2回で見たキーとスコープが実際のファイルの中でどう組み合わさるのかを確かめていきます。

---