2026/03/29Claude Code

AI活用導入・運用

Claude Code settings.jsonの書き方｜settings.local.jsonとの違いと実務設定例

「settings.jsonとsettings.local.jsonはどう違うのか」「~/.claude.jsonという似た名前のファイルは何なのか」——Claude Codeの設定ファイルは名前が紛らわしく、どこに何を書けばいいか迷いがちです。

結論から言うと、settings.jsonは置き場所によって適用範囲が変わる階層構造になっており、「User→Project→Local→Managed」の優先順位さえ押さえれば迷いません。~/.claude.jsonは設定ファイルではなく内部状態ファイルで、手で編集する対象ではありません。

株式会社Fyveは中小企業のAI活用を支援しています。この記事では、私が実際にモノレポ運用で使っている設定を例に、スコープの使い分け・permissions・hooks・環境変数まで、settings.jsonの実務設定を解説します。

settings.jsonのスコープ——4つの置き場所と優先順位

settings.jsonには、適用範囲が異なる置き場所があります。同じファイル名でも、どこに置くかで意味が変わります。

settings.jsonの3スコープのマージ順 — Enterprise、Project、Userの優先順位と階層構造

1. Userスコープ（グローバル）

~/.claude/settings.jsonに配置します。全てのClaude Codeセッションに共通で適用される個人用のデフォルト設定です。自分が常に使うモデルやステータスライン、有効化するプラグインなどをここに書きます。

2. Projectスコープ（チーム共有）

.claude/settings.jsonに配置します。gitでコミットすることで、チーム全員（と、同じリポジトリで動く全セッション）が同じ設定で作業できます。ツールの許可設定やhooksなど、プロジェクト固有のルールを書きます。

3. Localスコープ（個人×プロジェクト）

.claude/settings.local.jsonに配置します。同じプロジェクトの中で、自分だけに適用したい設定の置き場所です。詳しくは次のセクションで説明します。

4. Enterpriseスコープ（組織管理）

組織のIT管理者が展開するManaged Settings（managed-settings.json）です。サーバー配信、MDMプロファイル、レジストリポリシー、ファイルベースなどの方法で展開され、他のスコープで上書きできない最優先の設定です。セキュリティポリシーの強制適用に使われます。

優先順位

設定の優先順位は以下のとおりです（上が強い）。

Managed Settings（最高優先・上書き不可）
コマンドライン引数（そのセッション限り）
.claude/settings.local.json（個人×プロジェクト）
.claude/settings.json（チームプロジェクト）
~/.claude/settings.json（グローバル・最低優先）

重要なのは、denyルールは最高の安全優先度を持つという点です。下位スコープのallowやaskルールで上書きできません。

settings.local.jsonとは——gitに乗らない「自分専用の上書き」

検索で特に迷われるのがこのファイルです。.claude/settings.local.jsonは、プロジェクト設定（.claude/settings.json）を自分のマシンでだけ上書きするためのファイルで、次の性質を持ちます。

gitにコミットしない——Claude Codeがこのファイルに設定を保存するとき、リポジトリで除外されていなければグローバルgit excludeに自動追加してくれます（~/.config/git/ignore 等）。つまり放っておいてもgitに乗りません
Projectスコープより優先——チーム設定を壊さずに、自分だけ挙動を変えられます
権限承認の自動記録先——セッション中に「このコマンドを常に許可」を選ぶと、その承認がここに書き込まれていきます

実際、私のモノレポのsettings.local.jsonには、日々の作業で承認したallowルールが30件以上蓄積されています。自分で書くというより「Claude Codeが育てていくファイル」と捉えるのが実態に近く、たまに開いて不要な許可を削る、という付き合い方をしています。

使い分けの目安は1行で言えます——チームにも効かせたいなら settings.json、自分のマシンだけなら settings.local.json。

読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →

~/.claude.jsonとの違い——編集していいファイルではない

もう1つの混同ポイントが、ホームディレクトリ直下の~/.claude.jsonです。名前は似ていますが、settings.jsonとは別物の「内部状態ファイル」です。

~/.claude/settings.json（settingsフォルダの中）——あなたが書く設定ファイル
~/.claude.json（ホーム直下）——Claude Codeが書く状態ファイル。認証セッション、プロジェクトごとの信頼状態や許可の記録、Userスコープで登録したMCPサーバー、各種キャッシュなどが格納されます

~/.claude.jsonを手で編集するのは、設定変更の正規ルートではありません。MCPサーバーの追加はclaude mcpコマンド、設定変更はsettings.jsonか/configコマンドで行い、このファイル自体は触らないのが安全です。

パーミッション設定の実践

settings.jsonで最も頻繁に設定するのがパーミッション（permissions）です。allow（許可）・deny（拒否）・ask（毎回確認）の3リストで、どのツールをどこまで自動実行させるかを制御します。

ワイルドカードの活用

パーミッション設定ではワイルドカード（*）が使えます。これが実務で非常に便利です。

たとえばMicroCMSのMCP操作を全て許可する場合、個別にmcp__microcms__microcms_get_list、mcp__microcms__microcms_create_content_draftと書く代わりに、mcp__microcms__*と書くだけでまとめて許可できます。

同様に、Bashコマンドもワイルドカードで細かく制御できます。Bash(npm run *)と書けばnpm run系のコマンドだけを許可、Bash(git *)でgitコマンドだけを許可、といった具合です。

denyで機密ファイルを守る

allowだけでなく、denyの設計も実務では重要です。公式ドキュメントが挙げる典型例は、環境変数ファイルと機密ディレクトリの読み取り拒否です。

Read(./.env)・Read(./.env.*)——APIキーの入ったファイルを読ませない
Read(./secrets/**)——機密ディレクトリを丸ごと読ませない
Bash(curl *)——外部への任意送信をさせない

denyルールはどのスコープのallowでも上書きできないため、「絶対に触らせたくないもの」はdenyに書いておけば構造的に守られます。

実務での設定例

私が実際に使っている設定では、以下のようなツールを許可しています。

基本ツール：Read、Write、Edit、Glob、Grep
Bashコマンド：npm run、git、node、python3、ls、mkdirなどを個別に許可
エージェントツール：WebFetch、WebSearch、Agent、Skill
MCP：mcp__microcms__*、mcp__supabase__*をワイルドカードで許可

このように、必要なツールを明示的に許可することで、毎回の許可確認ダイアログを減らし、作業のスピードが大幅に向上します。

hooks——設定ファイルから品質ゲートを仕掛ける

settings.jsonのhooksは、ツール実行の前後などのイベントに自作スクリプトを差し込む仕組みです。これはCLAUDE.mdにはできない、settings.jsonならではの機能です。CLAUDE.mdの指示は「お願い」なので忘れられることがありますが、hooksはハーネス側が機械的に実行するため、必ず動きます。

私のモノレポでは、Projectスコープのsettings.jsonに次のようなhooksを入れて運用しています。

PreToolUse（Bash実行前）——契約書系ファイルの検証スクリプトや、公開文章のトーンチェックスクリプトを実行。問題があればコマンド実行前に止まる
PostToolUse（Write/Edit後）——クライアント案件のfrontmatter更新漏れをリマインドするスクリプトを実行

ポイントは、これをProjectスコープに置いていることです。gitで共有されるため、どのセッションで作業しても同じ品質ゲートが必ず効きます。「ルールをCLAUDE.mdに書いたのに守られない」と感じたら、その一部をhooksに移せないか検討する価値があります。

envとモデル設定

env——セッションに環境変数を渡す

envキーに書いたキーと値は、Claude Codeのセッションに環境変数として渡されます。プロキシ設定やテレメトリ制御など、環境変数で制御する類の設定をチームで揃えたいとき、Projectスコープのsettings.jsonに書いておくと全員に効きます。

model設定

modelフィールドで使用するモデルを指定できます。"opus"、"sonnet"などのエイリアスか、フルモデルIDも使えます。私はUserスコープでモデルを指定し、複雑な業務（記事執筆、大規模実装）にはOpus、単純作業には別のツールという使い分けをしています。

⚠️ 1点だけ実務上の注意があります。エイリアス（"opus"等）の解決先はCLIのバージョンによって変わります。私の環境でも、バージョンの違う2台で同じ"opus"が別世代のモデルに解決されたことがあります。自動実行ジョブなど「モデルが勝手に変わると困る」用途では、エイリアスではなくフルモデルIDで固定するのが安全です。

effortLevel——思考の深さを制御する

推論の深さはeffortLevel（low / medium / high / xhigh / max）で制御できます。深いほど複雑なタスクの精度が上がる一方、応答は遅く、トークン消費も増えます。私はUserスコープでhighを既定にし、セッション単位で変えたいときはCLIの--effortオプションで上書きしています。

その他の主要設定

statusLine

ターミナル下部のステータスラインを自作スクリプトでカスタマイズできます。私は現在のモデル名と利用枠の残量を常時表示させています。長時間の作業で「いま何をどれだけ使っているか」が見えるのは、地味ですが効きます。

language

languageで応答言語を指定できます。日本語で固定したい場合はUserスコープに書いておくと全プロジェクトに効きます。

cleanupPeriodDays

セッションの保持期間を日数で指定します。デフォルトは30日です。長期プロジェクトで過去のセッションを参照したい場合は、より長い期間に設定するとよいでしょう。

autoUpdatesChannel

"stable"または"latest"から選べます。安定性重視ならstable、最新機能をいち早く使いたいならlatestを選びます。

CLAUDE.mdとsettings.jsonの役割分担

CLAUDE.mdとsettings.jsonは混同されやすいですが、役割は明確に異なります。

CLAUDE.mdに書くこと

プロジェクトの概要・コンテキスト
ディレクトリ構成の説明
ワークフローや業務手順
禁止事項・ビジネスルール
データの所在と用途

settings.jsonに書くこと

ツールの許可・拒否設定（permissions）
モデル指定・思考の深さ（model / effortLevel）
イベントフック（hooks）
環境変数（env）
セッションのクリーンアップ期間

一言でまとめると、CLAUDE.mdは「何をするか」の知識、settings.jsonは「どう動くか」の技術設定です。

よくある失敗は、CLAUDE.mdに「このツールを使っていい」「モデルはOpusを使え」といった技術設定を書いてしまうことです。これらはsettings.jsonに書かないと確実には反映されません。逆に言えば、CLAUDE.mdの指示は破られ得るが、settings.jsonのdenyとhooksは破られない——この非対称性を理解すると、どちらに書くべきかで迷わなくなります。

なお、Claude Codeの設定ファイルはsettings.json以外にもCLAUDE.md・スキル・コマンドなど複数あります。全体像はこちらの記事で整理しています。

Claude CodeClaude Codeの設定ファイル5種類｜CLAUDE.md以外に何を置くか

実例——私の3スコープの実際の分担

抽象論で終わらないよう、私がモノレポ（会社の全プロジェクトを1リポジトリで管理）で実際に使っている分担を紹介します。

User（~/.claude/settings.json）——モデル指定・effortLevel（high）・statusLine・有効化プラグイン。「どのプロジェクトでも変わらない自分の好み」だけを置く
Project（.claude/settings.json）——よく使うMCPツールのallow、そしてhooksによる品質ゲート（公開文章のトーンチェック・契約書検証・frontmatter更新リマインド）。gitで共有されるため、全セッションに強制される
Local（.claude/settings.local.json）——日々の承認が自動蓄積されたallowルール約30件。手ではほぼ書かない

この分担にしてから、「設定がどこに書いてあるか分からない」がなくなりました。迷ったら「チームや全セッションに効かせたいか？」だけを考えてスコープを選ぶ——これが運用のコツです。

企業導入での設定戦略

企業でClaude Codeを導入する場合、Managed Settingsを活用することでセキュリティポリシーを強制適用できます。

特定のツールをdenyに設定して、社員が解除できない制限をかける
使用可能なモデルを制限して、コストを管理する
hooksを組織側で固定して、監査ログや品質チェックを全社員に強制する

Managed Settingsはサーバー配信、MDMプロファイル、レジストリポリシー、ファイルベースの4つの方法で展開できます。さらに、drop-inディレクトリ（managed-settings.d/）を使えば、ポリシーを独立したファイルで管理できます。

よくある質問

settings.jsonとsettings.local.json、どちらに書けばいいですか？

チームや他のセッションにも効かせたい設定はsettings.json、自分のマシンだけの設定はsettings.local.jsonです。迷ったらsettings.local.jsonに書いて試し、チームに広げたくなったらsettings.jsonへ移す、という順番が安全です。

~/.claude.jsonは編集していいですか？

推奨しません。認証情報やプロジェクトの状態を保持する内部ファイルで、壊すとセッションや信頼設定に影響します。設定変更はsettings.jsonか/configコマンド、MCP追加はclaude mcpコマンドが正規ルートです。

設定を変えたのに反映されません。

まずclaude doctor（またはセッション内の/doctor）で設定ファイルの読み込み状態を確認してください。よくある原因は、上位スコープ（Localや Managed）に同じキーがあって上書きされているケースと、JSONの構文エラーです。permissionsやhooksの変更は即時反映されますが、modelなど一部の設定は次のセッションから反映されます。