Claude Codeの設定ファイルを場所と形式の2軸で整理する

CLAUDE.mdは知っているけど.claude/settings.jsonは触ったことがない、という人はここで止まるケースが多いです。Claude Codeの設定ファイルは、「場所」と「形式」の2つの軸で見ると一気に分かりやすくなります。この記事では、その2軸を使って設定ファイル全体を整理し、「自分の場合はどこに何を書けばいいか」が判断できる状態を目指します。

設定ファイルが多くて混乱する理由

Claude Codeの設定ファイル、思ったより数があります。CLAUDE.md、.claude/settings.json、~/.claude/settings.json、settings.local.json――名前は似ているし、拡張子もバラバラ。果たしてどこに何を書けばいいのか。

混乱の元は大きく2つあります。「置き場所」が3階層に分かれていることと、「書き方」が2種類あることです。この2つの軸を掛け合わせると、全体像がすっきり見えてきます。

前提として、この記事ではWindows環境を想定して説明します。パスの区切りは\、ホームディレクトリはC:\Users\ユーザー名です。

まず押さえる2軸——「場所」と「形式」

Claude Codeの設定は、次の2つの軸で整理できます。

軸1: 場所（3階層）

~/.claude/（ユーザーのホームディレクトリ）――全プロジェクトに共通するグローバル設定
.claude/（プロジェクトのルートディレクトリ）――そのプロジェクト固有のプロジェクト設定
.claude/settings.local.json（同じくプロジェクト内）――自分だけのローカル設定

軸2: 形式（2種類）

CLAUDE.md――Markdownで書く自然言語の指示・ガイダンス
settings.json / settings.local.json――JSONで書く技術的な動作設定

これを掛け合わせた一覧表がこちらです。

ファイル	場所	形式	適用範囲	Git管理
`~/.claude/settings.json`	ホーム	JSON	全プロジェクト	されない
`~/.claude/CLAUDE.md`	ホーム	Markdown	全プロジェクト	されない
`.claude/settings.json`	プロジェクト	JSON	そのプロジェクト	される
`.claude/settings.local.json`	プロジェクト	JSON	自分だけ	されない（推奨）
`CLAUDE.md`（プロジェクトルート）	プロジェクト	Markdown	そのプロジェクト	される

ざっくり言うと、場所の列が「どこに置くか」、形式の列が「何を書くか」です。この表を頭に入れておけば、残りの説明も読みやすくなります。

場所の違い——グローバル/プロジェクト/ローカル

3つの置き場所を、もう少し具体的に見ていきます。

グローバル（~/.claude/）

Windowsなら C:\Users\ユーザー名\.claude\ に当たります。ここに置いた設定は、PC上のすべてのClaude Codeプロジェクトに反映されます。「どのプロジェクトでもPythonを使う」「すべてのプロジェクトでこの文体ルールを適用する」といった共通設定を書く場所です。

Git管理の対象外なので、他の人には共有されません。自分専用の設定として安心して使えます。

プロジェクト（.claude/）

プロジェクトのルートディレクトリ（git initした場所やリポジトリの一番上）に.claudeフォルダを作って置きます。そのプロジェクトだけで有効な設定です。

.claude/settings.jsonはGitでコミットされるため、チームメンバーと設定を共有できます。「このプロジェクトではこのコーディング規約を使う」「このプロジェクトで許可するツール一覧」などを置くのに向いています。

ローカル（.claude/settings.local.json）

同じプロジェクト内でも、「自分だけの設定」を書きたい場合があります。たとえば自分の環境にだけあるツールのパスや、試験的に使いたいMCPサーバーの設定などです。

settings.local.jsonは.gitignoreに追加してGit管理から外すのが推奨されています。チームに影響を与えずに、自分だけの設定を持てます。

各場所には、次のようなファイルを置けます。

グローバル（~/.claude/）: settings.json、CLAUDE.md、commands/
プロジェクト（.claude/）: settings.json、settings.local.json、CLAUDE.md（ルートにも可）、commands/、rules/、skills/、agents/

同じキーの設定がグローバルとプロジェクトの両方にある場合、プロジェクト側が優先されます（詳しくは後の「読み込みタイミングと優先順位」で解説）。

形式の違い——CLAUDE.mdとsettings.json

置き場所が分かったところで、次は「何を書くか」です。CLAUDE.mdとsettings.jsonは、役割が明確に分かれています。

CLAUDE.md（自然言語の指示）

CLAUDE.mdはMarkdown形式で、Claude Codeに「こうしてほしい」という方針やガイダンスを自然言語で伝えるファイルです。

例えば次のような内容を書きます。

# CLAUDE.md

## コーディング規約
- インデントはスペース2つ
- 関数には必ずdocstringを付ける

## プロジェクトの前提
- Python 3.11を使用
- テストフレームワークはpytest

「どう書くか」「何を前提にしているか」「何を避けるか」といった、人間が読んでも分かる方針を書くのがCLAUDE.mdの役割です。

settings.json（JSON技術設定）

settings.jsonは、Claude Codeの動作を技術的に制御するファイルです。JSON形式で書く必要があります。

主な設定項目は次のとおり。

allowedTools: 確認なしで自動実行を許可するツールのリスト
env: 環境変数の定義

（MCPサーバーの接続設定は、settings.jsonとは別のファイル（.mcp.jsonなど）で管理するのが公式の標準的な方法です）

具体例を見てみましょう。

{
  "permissions": {
    "allowedTools": [
      "Bash(python:*)",
      "Read",
      "Write"
    ]
  },
  "env": {
    "PYTHONPATH": "./src"
  }
}

「確認プロンプトを出さずに実行してよいツール」をallowedToolsに書くと、毎回「これ実行していい？」と聞かれなくなります。よく使うコマンドをここに登録しておくと、作業がスムーズになります。

なぜ2つの形式が存在するのかというと、Claudeが読む対象が違うからです。CLAUDE.mdはClaudeがコンテキストとして読み込む「指示書」で、settings.jsonはClaude Codeのシステムが機械的に読み込む「設定ファイル」。人間向けの説明と機械向けの設定を分けることで、どちらも管理しやすくなります。

読み込みタイミングと優先順位

各ファイルがいつ読み込まれるのかを知っておくと、「設定を変えたのに反映されない」という事態を減らせます。

CLAUDE.mdの読み込み

プロジェクトルートのCLAUDE.mdは、Claude Codeのセッション開始時に読み込まれます。いわば「最初に読む指示書」です。

サブディレクトリに置いたCLAUDE.mdは、そのディレクトリ内のファイルを操作するタイミングでオンデマンドに読み込まれます。たとえばsrc/CLAUDE.mdを置いておくと、src/以下のファイルを触るときだけ追加の指示が反映される仕組みです。

settings.jsonの読み込み

グローバルもプロジェクトも、どちらもセッション開始時に読み込まれます。セッションの途中でファイルを編集しても、基本的には次回のセッション開始時に反映されます。

commands/、rules/、skills/の読み込み

commands/内のファイルは、スラッシュコマンドを実行したタイミングで読み込まれます
rules/内のファイルは、条件に合致したタイミングで読み込まれます
skills/内のファイルは、スキルが呼び出されたタイミングで読み込まれます

優先順位

グローバルとプロジェクトで同じ設定キーがあった場合の優先順位は、プロジェクト側が優先されるのが基本です。具体的には次の順でマージされます。

グローバルの~/.claude/settings.json（ベース）
プロジェクトの.claude/settings.json（上書き・追加）
プロジェクトの.claude/settings.local.json（さらに上書き・追加）

つまり、グローバルで広く設定しておき、プロジェクトで必要な分だけ上書きする形が取りやすい構造になっています。

初心者がつまずきやすい3つのポイント

設定ファイル周りで初心者がよく引っかかるポイントをまとめました。

「CLAUDE.mdとsettings.json、どっちに書けばいいか分からない」

判断の目安はシンプルです。人間が読んで分かる方針・ルールならCLAUDE.md、機械的な動作設定ならsettings.jsonと考えておけば大きくは外れません。

「Pythonで書く」「テストを必ず通す」→ CLAUDE.md
「Bash(python:*)を確認なしで許可する」→ settings.json
「このMCPサーバーを使う」→ .mcp.json（または専用設定ファイル）
「エラーが出たら日本語で説明する」→ CLAUDE.md

「グローバルとプロジェクト、どちらに書くべきか」

全部のプロジェクトで共通する設定はグローバル、特定のプロジェクトだけで使う設定はプロジェクトに書くのが基本です。ただ、最初は全部プロジェクト側に書いてしまっても構いません。後から「これ他のプロジェクトでも使い回すな」と思ったものをグローバルに移動すればよいです。

「設定が反映されない」

設定を書いたのに動かない場合、まずは次の点を確認してみてください。

JSONの構文エラー: カンマの忘れ、閉じ括弧の不足、文字列のクォート忘れ。JSONは1文字でも間違えるとファイル全体が読み込まれません。VS Codeなどのエディタで開くと、エラー箇所に赤い波線が出るので確認しやすいです
ファイルの場所の間違い: ~/.claude/（グローバル）と.claude/（プロジェクト）を間違えていないか。特にホームディレクトリ側にプロジェクトの設定を置いてしまっているケースが目立つ印象です
セッションの再起動: 設定ファイルはセッション開始時に読み込まれるため、すでに起動中のセッションには反映されません。一度Claude Codeを終了して再起動してみてください

JSONの編集に慣れていない場合、VS Codeの「JSON Language Features」拡張を有効にしておくと構文チェックが効くので安心です。

ユースケース別——どこに何を書くか

具体的な状況に合わせて、どこに何を書くかの例を見ていきます。架空のプロジェクト「my-app」で考えます。

ケース1: 全プロジェクトで共通設定を使いたい

グローバルの~/.claude/settings.jsonに書きます。

// C:\Users\ユーザー名\.claude\settings.json
{
  "permissions": {
    "allowedTools": [
      "Bash(python:*)",
      "Read",
      "Write",
      "Glob"
    ]
  }
}

これで、どのプロジェクトを開いても共通のツール許可が適用されます。

ケース2: チームと設定を共有したい

プロジェクトの.claude/settings.jsonに書きます。Gitでコミットされるので、チームメンバー全員に同じ設定が届きます。

// my-app\.claude\settings.json
{
  "permissions": {
    "allowedTools": [
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

CLAUDE.mdにもプロジェクトの前提を書いておくと、チーム全体でClaudeの動きを揃えられます。

ケース3: 自分だけの設定を隠したい

.claude/settings.local.jsonに書きます。たとえば自分の環境にだけインストールしているツールや、試験中のMCPサーバー設定などです。

// my-app\.mcp.json
{
  "mcpServers": {
    "my-test-server": {
      "command": "node",
      "args": ["C:\\tools\\test-mcp\\index.js"]
    }
  }
}

MCPサーバーの設定は、プロジェクトなら.mcp.json、ユーザー共通なら~/.claude.jsonに書くのが公式の標準的な方法です（settings.jsonやsettings.local.jsonとは別ファイルになります）。

ケース4: 初心者の最小構成

まずはこれだけで始められます。

プロジェクトルートにCLAUDE.mdを作り、基本方針を3〜5行書く
.claude/settings.jsonに、よく使うツールの許可だけ書く

<!-- CLAUDE.md（プロジェクトルート） -->
# CLAUDE.md

## 前提
- Windows 11環境
- Pythonでスクリプトを書く

## ルール
- コードにはコメントを付ける
- エラーが出たら原因を日本語で説明する

// .claude/settings.json
{
  "permissions": {
    "allowedTools": [
      "Bash(python:*)",
      "Read",
      "Write"
    ]
  }
}

グローバル設定やローカル設定は、必要になってから追加すれば構いません。最初から全部用意しようとすると、かえって混乱の元になります。

まとめ——2軸で整理すれば迷わない

Claude Codeの設定ファイルは、「場所（グローバル/プロジェクト/ローカル）」と「形式（CLAUDE.md/settings.json）」の2軸で整理できます。

場所で決まるのは「どこまで反映するか」。全プロジェクトか、そのプロジェクトだけか、自分だけか
形式で決まるのは「何を書くか」。人間向けの方針か、機械向けの動作設定か

初心者は、まずプロジェクトルートのCLAUDE.mdに基本方針を書き、必要な許可設定だけ.claude/settings.jsonに追加する形から始めるのがおすすめです。グローバル設定やローカル設定は、使っていく中で「これは共通化したい」「これは隠しておきたい」と感じたタイミングで追加していけば大丈夫です。

次に読むなら:

CLAUDE.mdの具体的な書き方を知りたい → 別記事「CLAUDE.mdの書き方」
MCPサーバーの設定について知りたい → 別記事「MCPサーバー設定の基礎」
スキルやコマンドの作り方を知りたい → 別記事「カスタムコマンドとスキルの作り方」

Claude Codeでどこまでできる？