Claude Codeのsettings.jsonとsettings.local.jsonを使い分ける方法

「.claude/settings.jsonにAPIキーを書いてgit pushしたら、チーム全員に個人の設定がばらまかれた」——こういう事故、実は結構起きています。Claude Codeの設定ファイルはチーム共有用と個人用で分けるのが基本なんですが、どこに何を書くかの判断が最初は迷います。この記事では、settings.jsonとsettings.local.jsonの使い分けを、具体的な設定例を見ながら整理していきます。

ざっくり3本の内容

ざっくり次の3本を整理します。

settings.jsonとsettings.local.jsonの違いと使い分け
チームで設定をGit共有する仕組み
読後に自分のプロジェクトで設定ファイルを整理できる状態にする

設定ファイルが2つある理由はシンプルです。チーム全員で共有したいものと、自分だけが使うものを分けるため。これさえ押さえておけば、どちらに何を書くかの迷いがかなり減ります。

ざっくり一覧：どこに何を書くか

まずは判断基準を一覧で見てしまいましょう。

設定内容	`settings.json`（チーム共有）	`settings.local.json`（個人用）
permissions（許可・拒否のルール）	〇	—
hooks（ツール実行前後の自動処理）	〇	—
チーム共通のMCPサーバー	別ファイル（`.mcp.json`）	—
個人のAPIキー・トークン	—	〇
試しに入れてみたMCPサーバー	—	〇
個人の環境変数（ローカルパス等）	—	〇

ざっくり言うと、「git pushしても問題ないもの」がsettings.json、「自分のPCにだけ残したいもの」がsettings.local.jsonです。

事前に必要なもの

この記事の手順を進める前に、次の環境が整っていることを確認してください。

Claude Codeがインストール済みであること
Gitの基本操作（commit / push / pull）ができること
プロジェクトフォルダに.gitフォルダがあること（= Git管理されていること）
Windows環境であること

Git管理されていないプロジェクトでは、settings.jsonをチーム共有する仕組みが使えません。まずはgit init済みのプロジェクトで試してください。

Claude Codeの設定スコープ全体像

Claude Codeには設定を保存する場所が4つあります。名前と場所をまとめると次の通りです。

スコープ名	ファイルの場所（Windows）	役割
Managed	組織の管理者が設定（詳細は割愛）	組織全体のポリシー
User	`~/.claude/settings.json`（Windowsは `C:\Users\<ユーザー名>\.claude\settings.json`）	そのPCでの個人設定
Project	`.claude/settings.json`	プロジェクトごとのチーム共有設定
Local	`.claude/settings.local.json`	プロジェクトごとの個人設定

この記事で扱うのは、下の2つ（ProjectとLocal）だけです。初心者なら、まずはこの2つだけ意識すれば大丈夫。残り2つ（UserとManaged）は後から知っても問題ない。

settings.json（チーム共有用）の仕組み

場所はプロジェクトフォルダ内の.claude/settings.jsonです。

このファイルはプロジェクトフォルダの中にあるため、git commitしてgit pushすれば、チームの他のメンバーにも共有されます。pullすれば他のメンバーが追加した設定を自分の手元に取り込めます。

チーム共通で設定したい代表的なものを挙げると、だいたい次のあたりになります。

permissions — どのツールの実行を許可・拒否するかのルール
hooks — ツール実行の前後に自動で走る処理
MCPサーバー — チーム全員が使う外部ツール連携の設定（別ファイル.mcp.jsonに設定する）

具体的な設定例を見てみましょう。

{
  "permissions": {
    "allow": [
      "Bash(git log:*)",
      "Bash(npm test:*)",
      "Read"
    ],
    "deny": [
      "Bash(rm -rf:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Bash実行中]'"
          }
        ]
      }
    ]
  }
}

MCPサーバーを追加する場合は、プロジェクトフォルダのルートに別ファイル.mcp.jsonを作成する。

{
  "mcpServers": {
    "shared-tools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"]
    }
  }
}

このファイルもgit commit & git pushでチームに共有される。

後から変えられるので、まずは最小限の設定（permissionsだけ等）で始めて、チームの運用に合わせて足していけばよい。

よくある失敗：全部settings.jsonに書いてしまった

個人用のAPIキーや実験的な設定までsettings.jsonに書いてgit pushすると、チーム全員に個人の設定が共有されてしまいます。後で消すのも手間なので、最初から分けておくのが安全です。

個人のAPIキーや実験的な設定はどこに書けばいいか——それがsettings.local.jsonの役割だ。

settings.local.json（個人用）の仕組み

場所は同じく.claude/settings.local.jsonです。

このファイルはClaude Codeが自動で.gitignoreに追加する仕様になっています。そのため、git addしてもステージングされず、git pushしてもリモートに上がりません。

ここに書くべきなのは、自分のPCだけで使いたいものです。

APIキーやトークン — 個人のアカウント情報
試しに入れたMCPサーバー — まだチームに提案していない実験的なもの
個人の環境変数 — 自分のPC固有のパス設定など

設定例を見てみます。

{
  "env": {
    "MY_API_KEY": "sk-xxxxxxxxxxxxxxxx",
    "LOCAL_DB_PATH": "C:\\Users\\yourname\\data\\local.db"
  }
}

ここで迷いやすいポイント

「MCPサーバーの設定はどこに保存されるの？」→ チーム全員で共有するMCPサーバーは、プロジェクトルートの.mcp.jsonに保存します。自分だけが試すMCPサーバーは、Claude CodeのMCP追加コマンドでlocal scopeとして追加します。この場合、settings.local.jsonに直接書く前提ではなく、Claude Code側のMCP設定として管理します。

.gitignoreで個人設定が混入するのを防ぐ

Claude Codeはsettings.local.jsonを自動で.claude/.gitignoreに追加します。ですが、念のため自分で確認しておくと安心です。

確認手順：

エクスプローラーまたはテキストエディタで.claude/.gitignoreを開く
settings.local.jsonという行があるかを確認する

# .claude/.gitignore の中身（例）
settings.local.json

この行があれば、settings.local.jsonはGit管理から外れています。

もし.gitignoreに含まれていなかった場合：

手動で追加してください。

# .claude/.gitignore に追加
settings.local.json

すでにGitにコミットしてしまった場合：

git rm --cachedでインデックスからのみ削除すれば、ファイル自体は残ります。

git rm --cached .claude/settings.local.json
git commit -m "remove local settings from git tracking"

APIキーが含まれている場合は、コミット履歴にも残る点に注意が必要です。本格的な対応にはgit filter-branchや専用ツール（BFG等）が必要になりますが、まずはgit rm --cachedで追加コミット以降の漏れを防ぐのが現実的な第一歩です。

設定が競合したときの優先順位

複数のスコープに同じ設定項目がある場合、次の順で強い設定が使われます。

Managed > コマンドライン引数 > Local > Project > User

具体例で考えましょう。User設定とProject設定で同じpermissionsが違う値だった場合、Project設定が優先されます（Projectの方がUserより上位だから）。

同じように、Project設定とLocal設定で同じ項目が違う値だった場合、基本的にはLocal設定の方が優先されます。ただし、permissions.allowのような配列形式の設定は、単純に丸ごと上書きされるのではなく、複数スコープの内容がマージされることがあります。

そのため、「Localに書けば必ずProject設定を完全に置き換えられる」と考えるより、まずは/configで実際に有効になっている設定を確認するのが安全です。

実際に何が効いているかは、Claude Code内で/configコマンドを実行すると確認できます。

> /config

# 現在の有効な設定が一覧で表示される

ここは先に/configで確認しておくと、トラブル時の原因特定が楽です。「設定が反映されない」という場合、大抵は上位スコープの設定で上書きされていることが原因です。

自分のプロジェクトで設定を整理してみる

それでは実際に設定ファイルを整理してみましょう。

Step 1：現在の設定ファイルを確認する

プロジェクトフォルダの.claude/の中身を見ます。

dir .claude

# 期待される出力例
...
.claude\settings.json
.claude\settings.local.json
.claude\.gitignore
...

Step 2：チーム共有設定をsettings.jsonにまとめる

.claude/settings.jsonをテキストエディタで開いて、チーム共通の設定を記述します。

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm test:*)"
    ],
    "deny": []
  }
}

個人用のAPIキーや実験的なMCPサーバーはここに書かないようにします。

Step 3：個人設定をsettings.local.jsonに分離する

.claude/settings.local.jsonを開いて、個人用の設定を記述します。

{
  "env": {
    "MY_API_KEY": "sk-your-key-here"
  }
}

Step 4：.gitignoreを確認する

.claude/.gitignoreにsettings.local.jsonが含まれているか確認します。

type .claude\.gitignore

# 期待される出力
settings.local.json

含まれていなければ手動で追加してください。

Step 5：チームに共有する

settings.jsonをコミットしてプッシュします。

git add .claude/settings.json .claude/.gitignore
git commit -m "add project settings for team"
git push

チームメンバーはgit pullするだけで、プロジェクトの設定が反映されます。

うまくいかない時だけ見る代替手順

環境によっては、いくつかつまずきやすいポイントがあります。

settings.local.jsonが.gitignoreに自動追加されない

Claude Codeのバージョンによっては自動追加されないケースがあります。その場合はStep 4のように手動で.claude/.gitignoreに追加してください。

設定ファイルが反映されない

Claude Code内で/configを実行して、現在の有効な設定を確認してください。上位スコープで上書きされている可能性があります。

チームメンバーが設定をpullしても反映されない

Claude Codeを再起動する必要がある場合があります。VS Codeの拡張機能として使っている場合は、VS Codeごと再起動してみてください。

設定ファイルの整理ができたら

最後に動作確認のチェックリストをざっくり確認しておきます。

settings.jsonがGit管理されているか（git statusで表示されるか）
settings.local.jsonが.gitignoreされているか（git statusで表示されないか）
/configで意図通りの設定が表示されるか

ここまでできれば、チームでの設定共有の基礎は完了です。

次にやることの目安：

次に読む — CLAUDE.mdの書き方を知りたい場合は、プロジェクトのルールファイルの書き方解説記事を参照してください
次に試す — hooksの設定をカスタマイズして、ツール実行前の自動チェックなどを導入してみてください
高度な設定 — User scopeやManaged scopeを活用すると、PC全体や組織全体での設定管理もできます。チームの規模が大きくなってから検討する程度で問題ありません

Claude Codeでどこまでできる？