AI Hub

Claude Code settings.json解説｜設定項目と優先順位まとめ

公開:

#設定 #settings.json

Claude Codeのsettings.jsonは、権限・環境変数・hooksなど本体の「動作」を制御する設定ファイルです。設定は「ユーザー」「プロジェクト」「ローカル」「組織管理(managed)」の4階層に分かれ、同じキーを複数箇所で指定すると決まった優先順位で上書きされます。本記事では各階層の配置場所と優先順位、permissions・env・hooks・modelといった主要キーの書き方をサンプルつきで整理します。設定ファイル全体を体系立てて理解したい方は「Claude Code設定完全ガイド」もご覧ください。

前提・対象バージョン

Claude Code CLIがインストール済みであることを前提にします。settings.jsonはJSON形式のプレーンテキストファイルで、エディタ編集のほか/configコマンドから一部項目を変更できます。設定キーは今後のアップデートで変わる可能性があるため、正確な仕様は都度公式ドキュメントで確認してください。

settings.jsonの階層と優先順位

Claude Codeの設定ファイルは、範囲の広いものから狭いものまで次の4階層で管理されています。

スコープファイルパス主な用途Git管理
組織管理(Managed)managed-settings.json(WindowsはC:\Program Files\ClaudeCode\配下)組織全体のポリシー強制IT部門が配布
ユーザー(User)~/.claude/settings.json個人の全プロジェクト共通設定対象外
プロジェクト(Project).claude/settings.jsonチームで共有する設定git管理・共有
ローカル(Local).claude/settings.local.json個人用の一時的な上書き.gitignore対象

優先順位は「Managed > コマンドライン起動オプション > Local > Project > User」の順です。ユーザー設定でautoMemoryEnabled: trueでも、プロジェクト設定にfalseとあればプロジェクト側が優先されます。/configで変更した項目や権限の承認履歴は自動的にローカルへ書き込まれます。

permissionsで実行権限を制御する

permissionsは、どのツール・コマンドを確認なしに実行してよいかを制御するキーです。allow(自動許可)・deny(常に拒否)・ask(実行前に確認)の3リストを指定できます。

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
  }
}

ツール名の後ろに実行内容のパターンを括弧で指定するのが基本の書式です。denyはallowより優先されるため、機密ファイルの読み取りやリスクの高いコマンドはdeny側に明示すると安全です。実践的な設定例は「Claude Codeの権限管理入門」で詳しく解説しています。

env・model・hooksの主要キー

envは環境変数、modelは使用モデルとフォールバック先を指定するキーです。

{
  "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1" },
  "model": "claude-opus-4",
  "fallbackModel": ["claude-sonnet-5"]
}

hooksはツール実行前後などのタイミングで任意のコマンドを差し込む設定です。イベント名(PreToolUse・PostToolUseなど)ごとにmatcherで対象ツールを絞り込み、hooks配列に実行内容を書きます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-check.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

このほか出力スタイルを指定するoutputStyleや、メモリ機能を制御するautoMemoryEnabledなど細かいキーも多数あります。網羅的な一覧は公式ドキュメントの設定リファレンスで確認してください。

サンプルsettings.json全文

ここまでのキーを組み合わせたプロジェクト用のサンプル全文です。実際の値はプロジェクト方針に合わせて調整してください。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
  },
  "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1" },
  "model": "claude-opus-4",
  "fallbackModel": ["claude-sonnet-5"],
  "hooks": { "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-check.sh" }] }] },
  "autoMemoryEnabled": true
}

/configコマンドや環境変数との関係

/configはsettings.jsonの内容をセッション内から確認・変更するコマンドです。引数なしで実行すると設定画面が開き、/config verbose=trueのように書けば特定の項目だけを直接変更できます。/statusで読み込み済みの設定ソースを、/doctorで構文エラーを確認できます。

/config
/config verbose=true

多くのキーは保存時にリアルタイム再読み込みされますが、modelなどはセッション起動時にしか読み込まれず、反映には/modelコマンドか再起動が必要です。OS側の環境変数(ANTHROPIC_MODELなど)を併用している場合はそちらが優先されることもあるため、意図通り反映されないときはどちらで指定しているか確認しましょう。

CLAUDE.mdとの役割の違い

settings.jsonと混同されやすいファイルにCLAUDE.mdがあります。CLAUDE.mdはClaudeに読ませる「指示・前提知識」、settings.jsonは権限やhooksなど「ツール自体の動作」を定義するファイルです。コーディング規約のような文脈情報はCLAUDE.mdに、コマンドを自動実行してよいかという制御ロジックはsettings.jsonに書く、と使い分けます。具体的な書き方は「CLAUDE.mdの書き方」で解説しています。

つまずきポイント

よくある質問

settings.jsonとsettings.local.jsonはどう使い分ければよいですか?

チームで共有したい権限やhooksは.claude/settings.jsonに書いてgit管理し、個人的な上書きや承認履歴は.claude/settings.local.jsonに書いて.gitignoreで除外するのが基本です。

4つの階層の設定が競合した場合、どれが優先されますか?

組織管理(Managed)が最優先で、次にコマンドライン起動オプション、その後はローカル・プロジェクト・ユーザーの順です。ユーザー設定は範囲が広い分、優先度は最も低くなります。

環境変数とsettings.jsonのenvキーはどちらが優先されますか?

基本的にはenvキーの値がセッションに反映されますが、キーによってはOS側の環境変数が優先される場合もあります。挙動が怪しいときは/statusで実際の値を確認しましょう。

まとめ

settings.jsonは、組織管理・ユーザー・プロジェクト・ローカルという4階層で管理され、permissions・env・hooks・modelといったキーでClaude Codeの動作を細かく制御できる設定ファイルです。チーム共有の設定は.claude/settings.jsonに、個人用の上書きは.gitignore対象の.claude/settings.local.jsonに分けて書くのが基本です。権限設定をさらに深掘りしたい方は「Claude Codeの権限管理入門」、指示や前提知識の書き方は「CLAUDE.mdの書き方」もあわせてご覧ください。