Claude Codeのsettings.json完全ガイド：配置場所・permissions・hooks/MCP・CLI連携

settings.jsonが制御するもの、CLAUDE.mdとの役割の違い

settings.jsonとCLAUDE.mdは、同じ「設定ファイル」という言葉でひとくくりにされがちだが、書く中身はまったく違う。settings.jsonはClaude Codeの動作条件を決める「設定値」を書くファイルであり、CLAUDE.mdはプロジェクトの背景知識や指示文脈を伝える「文章」を書くファイルだ。

具体的には、settings.jsonはどのコマンドを実行してよいかというpermissions、Claude Codeの子プロセスに渡す環境変数のenv、特定のタイミングで外部コマンドを走らせるhooks、外部サーバーへの接続を許可するMCP関連の設定といった、機械が解釈する構造化データを格納する。一方でCLAUDE.mdは、このプロジェクトでは何を優先するか、どんな命名規則を使うか、どんな背景があるかといった、モデルが読んで文脈として理解するための自然文を書く場所だ。両方とも設定ファイルという点は共通しているが、settings.jsonは「何を許可・禁止するか」、CLAUDE.mdは「何を知っておいてほしいか」という役割分担で覚えると混同しにくい。CLAUDE.mdの書き方そのものはclaude-md-writing-guideに、基本的な使い方の全体像はclaude-code-how-to-guideにまとめているので、settings.json以外の部分で迷ったらそちらを参照してほしい。

settings.jsonはどこに置けば、意図した優先順位で反映されるのか？

settings.jsonは一箇所にしか置けないわけではなく、複数の場所に併存できる。範囲が狭く個人的な設定ほど優先順位が高く、同じキーが重複すれば狭い範囲の値が広い範囲の値を上書きする。

置き場所を比較するときは「誰と共有する設定か」「どこに置くか」「どのくらい優先されるか」という3つの軸で見ると判断しやすい。

スコープ	主な置き場所	共有範囲	優先度の傾向
ローカル（個人の一時設定）	`.claude/settings.local.json`	自分の端末だけ、gitには含めない前提	高い
プロジェクト	`.claude/settings.json`	リポジトリを通じてチーム全員	中間
ユーザー	`~/.claude/settings.json`	自分が触るすべてのプロジェクト	低い
エンタープライズ／管理者ポリシー	組織側で配布される設定	組織全体	個々の設定より優先される想定

「設定を書いたのに反映されない」という事象の多くは、この優先順位を取り違えていることが原因になりやすい。たとえばプロジェクト全体で共有したいpermissionsをローカル設定にだけ書いてしまうと、他のメンバーの環境には反映されない。逆に、自分だけの一時的な調整をプロジェクト設定に書いてしまうと、意図せずチーム全体の挙動を変えてしまう。まずは自分が変更しているファイルがどのスコープに属するかを.claude/配下のパスで確認する習慣をつけるとよい。組織単位のポリシー配布については、この記事では踏み込まずclaude-code-enterprise-security-guideに委ねる。

permissions設計の基本：allow・ask・denyで事故を防ぐ考え方

ツールやコマンドの実行可否を制御する仕組みが、permissionsだ。allow・ask・denyの3段階を使い分け、最初から広く許可するのではなく、必要な操作だけを許可リストに足していく設計にすれば事故を防げる。

settings.jsonの中では、次のような形でこの3段階を書き分ける。

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Read(./src/**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "WebFetch"
    ]
  }
}

allowは確認なしで実行してよい操作、askは実行前に確認を挟みたい操作、denyはどんな状況でも実行させたくない操作を書く場所だ。個人利用であれば、まずすべてをask寄りにして、繰り返し使うコマンドだけを少しずつallowへ動かしていくやり方が安全に始めやすい。チームで使う場合は、逆に「誰かが誤って実行すると被害が大きい操作」を先にdenyへ書き出してから、日常的に必要な操作をallowに足していく順番のほうが漏れが出にくい。

権限を絞るという発想は、対話的な利用に限らず自動実行の場面でも同じ考え方が使われる。当メディアのブログ自動生成エンジンでは、Claude Codeを呼び出す際にツールの許可範囲をCLIの--allowedToolsで指定しており、実際に渡せるツール名はWebSearchとWebFetchの2つに限られている。調査を行う段階だけこの2つを渡し、それ以外の段階は許可ツールを空のまま呼び出す実装になっている。settings.jsonのpermissionsとCLIの--allowedToolsは別の仕組みだが、「必要な操作だけを明示的に許可し、それ以外は渡さない」という最小権限の考え方は共通しているので、settings.json内のpermissions設計を考える際の参考になる。権限設計をどこまで厳しくするか、何を外部に出してよいかという判断軸はclaude-code-operation-rulesにまとめてある。事故を防ぐ運用ルールまで詰めたい場合は、目を通しておくとよい。

hooks・env・MCPの設定はsettings.json内でどう書き分ければいいのか？

hooks・env・MCPは名前が並んで語られがちだが、担う役割はまったく別物だ。hooksは特定のイベントが起きたときに外部コマンドを自動実行する仕組み、envはClaude Codeが子プロセスを起動するときにだけ渡す環境変数の上書き設定、MCP関連のキーは外部サーバーへの接続をどこまで許可するかを書く場所である。

envについて補足すると、これはシェルでexportした環境変数とは別物で、settings.jsonのenvに書いた値はClaude Codeが起動するサブプロセスにだけ渡り、OS全体や他のアプリケーションの環境変数を変えるものではない。書き方は次のようになる。

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "DISABLE_TELEMETRY": "1"
  }
}

同じエンジンは、envの発想を逆方向にも使っている。Claude Codeの子プロセスへ渡す環境変数から、プロバイダーの認証情報や接続設定、クラウド切り替え（Bedrock/Vertex/Foundryなど）に関する変数、通知設定に関する変数などをあえて削除して起動している。settings.jsonのenvキーで「何を渡すか」を決められるのと同じように、「何を渡さないか」を明示的にコントロールできることを示す実例といえる。

hooksは、たとえばファイル編集の前後で特定のコマンドを走らせたいときに使う。書式の骨格は次のようになる。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo before-bash" }
        ]
      }
    ]
  }
}

hooksがどのイベントで使え、どんな用途に向くかという設計面の話はclaude-code-hooks-guideで扱っている。settings.json内の書式を押さえたら、次はそちらで理解を広げられる。MCP関連のキーは、有効にするサーバーの一覧や既定の有効化フラグなどを設定する場所で、細かい書式や、どのサーバーをどこまで信頼するかというガバナンスの判断はclaude-code-mcp-guideに委ねる。

【自動化・CI連携を検討している人向け】CLIの`--setting-sources`や`--settings`フラグとsettings.jsonの関係

settings.jsonファイルをそもそも読み込むかどうか、読み込む場合はどの内容で上書きするかは、実行時にCLIから指定することもできる。使うフラグは--setting-sourcesと--settingsで、ファイルの状態に依存しない再現性の高い実行が可能になる。この節は対話的にClaude Codeを使うだけの読者には基本的に関係がなく、GitHub Actionsや無人バッチのように自動化・CI連携でClaude Codeを組み込みたい人向けの内容なので、対話的な利用が中心の人は読み飛ばして構わない。

2026年8月4日時点で実機のClaude Code CLIを確認すると、バージョンは2.1.221で、--helpの出力には--safe-mode、--setting-sources、--strict-mcp-config、--tools、--allowedTools、--no-session-persistenceといったフラグが並んでいた。これらのフラグ名から想定できる大まかな役割はあるものの、細かい挙動はclaude --helpや公式ドキュメントで手元のバージョンに合わせて確認するのが確実だ。

このエンジンでは、Claude Codeを-p、--output-format json、--safe-mode、空の--setting-sources、--settings {}、--strict-mcp-config、--disable-slash-commands、--no-session-persistenceを付けて起動している。空の--setting-sourcesは、User・Project・Localといったファイルベースの設定を読み込まないという指定であり、これによりファイルベースの設定を読み込まない実行になる。そのうえで--settings {}にインラインのJSONを渡すことで、その回の実行だけに適用される設定を明示的に上書きできる。権限を絞る運用については前節で触れた実例と同じ発想で、許可ツールが必要な段階だけ--allowedToolsを追加している。

加えて、このエンジンのClaude Code子プロセスは毎回一時ディレクトリをカレントディレクトリとして起動され、実行が終わるとそのディレクトリごと削除される隔離実行になっている。ファイルの読み込みをCLIフラグで止め、作業ディレクトリも使い捨てにすることで、前回の実行結果や置き忘れた設定ファイルが次の実行に影響しない状態を作っている。CI環境でClaude Codeを組み込む際の設計思想はclaude-code-github-actions-guideに、ブログ生成のような無人実行の全体像はclaude-code-blog-automation-guideに、それぞれまとめてある。settings.jsonとCLIフラグの関係を踏まえて自動化設計を詰めたい場合は、あわせて確認すると理解が深まる。

個人用・チーム用で、最小構成からどう育てていけばいいのか？（段階的ロードマップ）

settings.jsonを事故の原因にしないコツは、育て方の順番にある。最小構成から始めて、必要になった段階で少しずつ設定を足していけばよい。

具体的な順番は次のようになる。

段階	やること	主な置き場所	目的
1. 初期状態	settings.jsonを置かず、既定の挙動のまま使う	なし	挙動に慣れる
2. 最小permissions	危険な操作だけ`deny`に書き、それ以外は`ask`寄りにする	User設定	誤操作を防ぐ土台を作る
3. envで固定	使いたいモデルなど、繰り返し指定したい値をenvに書く	User設定	毎回の指定を省く
4. チーム共有	よく使う`allow`やhooksをプロジェクトへ昇格させる	Project設定	チームで挙動を揃える

この順番のポイントは、最初から完璧な設定を用意しようとしないことにある。まず自分の手元で最小限のpermissionsを試し、使い勝手を確認してから、チームに共有する価値がある部分だけをProjectスコープへ引き上げるという流れなら、途中で設定を見直しても影響範囲が小さく済む。チーム研修などで設定の育て方を教材化したい場合は、claude-code-training-materials-guideにある目次のたたき台も参考になる。

まとめ：今日から始める最初の一歩

settings.jsonを扱う際の判断軸は、次の4点に集約できる。

どのスコープ（User／Project／Local／組織ポリシー）に書くべき設定かを最初に決める
permissionsは広く許可するところから始めず、危険な操作のdenyから固める
env・hooks・MCPはそれぞれ別の役割を持つキーだと理解し、混同しない
自動化やCIで使う場合は、CLIフラグでファイル依存をなくせることを知っておく

まずは自分の利用シーンに合わせて、スコープを1つ決めて最小のpermissionsを書いてみることが最初の一歩になる。settings.jsonを書けるようになったあとは、hooksやMCPとの組み合わせ方、チーム運用のルール化まで、実際に手を動かしながら学び続ける場が役に立つ。月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」（lab.no-wave.jp）では、こうした設定を自分の環境で試しながら、安全に使いこなすための学びを続けられる。