何のためのものか
settings.json による設定。要点はスコープが 4 層あり、優先順位が決まっていること。「書いたのに効かない」のほとんどは、層を間違えているか、反映タイミングを誤解しているかのどちらかである。
触る
- 対話セッションで
/configを開く。v2.1.181 から/config key=valueで UI を開かずに 1 項目を変えられる /statusの Status タブにあるSetting sources行を見る。そのセッションで読み込まれた層が並ぶ
Setting sources はどのソースが読まれたかを示すだけで、各キーをどの層が供給したかは示さない。空の一覧は「設定ソースが見つからなかった」を意味する。
入れる
3 つの層に何を置くかを決める。
| 層 | ファイル | 何を置くか |
|---|---|---|
| User | ~/.claude/settings.json | 自分の全プロジェクトに効かせたい癖 |
| Project | .claude/settings.json | リポジトリの共同作業者に配る規約。git にコミットする |
| Local | .claude/settings.local.json | このリポジトリでの自分だけの事情。Claude Code が保存するとき gitignore される |
- 恒久的な「don't ask again」の permission 承認は
.claude/settings.local.jsonに入る .claude/settings.local.jsonは git リポジトリルートで読み書きされ、1 ファイルでリポジトリ内のどのサブディレクトリ・worktree のセッションもカバーする$schemaにhttps://json.schemastore.org/claude-code-settings.jsonを指定するとエディタの補完と検証が効く
効かせる
優先順位を覚える。 上が強い。
- Managed settings（server-managed、MDM / OS レベルポリシー、managed settings ファイル）
- コマンドライン引数（
--settings） - Local project settings（
.claude/settings.local.json） - Shared project settings（
.claude/settings.json） - User settings（
~/.claude/settings.json）
反映タイミングは 2 種類ある。
- 設定ファイルは監視されており、
permissions、hooks、apiKeyHelperなどは再起動なしに反映される（変更ごとにConfigChangehook が発火する） modelとoutputStyleはセッション開始時に一度だけ読まれる。セッション中に変えるなら/model、outputStyleは/clearか再起動
配列は置き換えではなく連結・重複排除される。 複数スコープに同じ配列設定があるとマージされる。例外は fallbackModel（順序に意味があるため最上位のファイルが全体を供給）と availableModels。
落とし穴
~/.claude.jsonにしか置けないキーがある。autoConnectIde、diffTool、permissionExplainerEnabledなどはsettings.jsonに書くと起動時に黙って無視される- project settings は user settings より強い。
~/.claude/settings.jsonで plugin をfalseにしても、project の.claude/settings.jsonが有効にした plugin は無効にならない。自分のマシンで外すなら.claude/settings.local.json - user / project / local の設定ファイルは厳格。 検証に失敗したファイルは全体が拒否される（managed settings だけが寛容にパースされ、不正エントリを除いて残りを強制する）
- 起動時に Settings Error ダイアログが出たら、
/statusで該当ファイルを見てclaude doctorで詳細を読む - 機微なファイルを除外するには
permissions.denyを使う。非推奨のignorePatternsではない