Claude Code settings.json 全設定リファレンス──「いつ・なぜ変えるか」の判断基準付き

Claude Code を使い始めて数週間。基本操作には慣れたが、

settings.json

公式ドキュメントは英語で項目が羅列されているだけで、「この設定を、いつ、なぜ変えるのか」 の判断基準がない。この記事では、

settings.json

前提：設定ファイルの 5 層構造

設定項目の解説に入る前に、Claude Code の設定がどこに配置され、どの順序で評価されるかを押さえておく。

優先度: Managed（最高） > CLI フラグ > Local > Project > User（最低）

~/.claude/settings.json          ← User：全プロジェクト共通の個人設定
.claude/settings.json            ← Project：チーム共有（git 管理）
.claude/settings.local.json      ← Local：個人実験用（gitignore）
claude --model opus              ← CLI フラグ：セッション単位の一時的な上書き
/Library/Application Support/    ← Managed：IT 管理者がデプロイ
  ClaudeCode/managed-settings.json

--model

--add-dir

重要: 配列設定（

allow

deny

チーム規模別のスコープ活用目安:

• 個人開発: User スコープのみで十分。Project に設定を置く必要はない
• 小チーム（3〜5人）: Project スコープを git 管理し、チームの deny ルールと Hook を共有する
• 中規模（20人以上）: Managed スコープによる IT ポリシー配布を検討する
• エンタープライズ（50人以上）: Managed + MDM 配布の自動化が現実的な選択肢になる

設定ファイルの先頭に書くべき 1 行

すべての

settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

VS Code・Cursor で自動補完とバリデーションが有効になる。設定キーのタイポを防ぎ、利用可能な値の候補が表示される。この 1 行で設定ミスの大半が未然に防止できる。

カテゴリ 1：コア設定

日常的に最も触る機会が多い基本設定。

model

{
  "model": "claude-sonnet-4-6"
}

string

判断基準: 個人で使うなら

~/.claude/settings.json

.claude/settings.json

availableModels

availableModels

{
  "availableModels": ["sonnet", "haiku"]
}

string[]

判断基準: Managed スコープで設定すると組織全体でモデルを制限できる。Project スコープに入れると、そのプロジェクトのコスト上限を暗黙的に設定する効果がある。

language

{
  "language": "japanese"
}

string

判断基準: 日本語チームなら User スコープに入れておくと快適。英語ドキュメントのプロジェクトでは Project で

"english"

outputStyle

{
  "outputStyle": "Explanatory"
}

string

判断基準: 個人の好みの範囲なので User スコープに置く。プロジェクトで統一する必要はほぼない。

env

{
  "env": {
    "NODE_ENV": "development",
    "BASH_DEFAULT_TIMEOUT_MS": "180000"
  }
}

object

判断基準: シェルの

.zshrc

.bashrc

apiKeyHelper

apiKeyHelper

{
  "apiKeyHelper": "/usr/local/bin/get-claude-api-key.sh"
}

string

判断基準:

ANTHROPIC_API_KEY

.env

cleanupPeriodDays

{
  "cleanupPeriodDays": 14
}

number

30

判断基準: デフォルトの 30 日で問題ないことがほとんど。ディスクが逼迫する CI 環境では短く設定する。

カテゴリ 2：パーミッション設定

最もインパクトが大きく、最初に設計すべきカテゴリ。セキュリティと開発効率のバランスを決める。

permissions.deny

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl * | bash)",
      "Bash(rm -rf *)"
    ]
  }
}

string[]

[]

判断基準: deny ルールは 最優先で評価 される。他のスコープの allow で上書きできない。まず「何を絶対に許可してはいけないか」を書き出し、そこから設計する。

permissions.ask

{
  "permissions": {
    "ask": [
      "Bash(git push *)",
      "Bash(docker *)"
    ]
  }
}

string[]

[]

判断基準:

ask

git push

docker

permissions.allow

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx prettier *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)"
    ]
  }
}

string[]

[]

判断基準: 「Claude が毎回聞いてくるのが煩わしいが、安全なコマンド」を入れる。

npm run lint

git diff

git push

パーミッションルールの構文

パターン構文を理解しておかないと、意図しないルールを書いてしまう。

# 基本形式
ToolName                    # 全操作を対象
ToolName(specifier)         # 条件付き

# Bash のパターン
Bash(npm run *)             # npm run で始まるコマンド（* は単語境界で分割）
Bash(git * main)            # git の後に何かがあり main で終わるコマンド
Bash(ls*)                   # ls で始まる（単語境界なし、lsof もマッチする）

# Read/Edit のパスパターン
Read(./.env)                # カレントディレクトリの .env（./ はカレントから相対）
Read(/src/**/*.ts)          # プロジェクトルートからの相対パス（/ で始める）
Read(./secrets/**)          # secrets 以下を再帰的に
Read(~/.zshrc)              # ホームディレクトリ（~ で始める）
Read(//etc/passwd)          # ファイルシステムルートの絶対パス（// で始める）

# WebFetch のドメインパターン
WebFetch(domain:github.com)       # 特定ドメイン
WebFetch(domain:*.npmjs.org)      # ワイルドカードサブドメイン

# MCP ツール
mcp__github                        # GitHub MCP の全ツール
mcp__puppeteer                     # Puppeteer MCP の全ツール（同上）
mcp__puppeteer__puppeteer_navigate # Puppeteer の特定ツールのみ

permissions.additionalDirectories

{
  "permissions": {
    "additionalDirectories": ["../shared-libs/", "../docs/"]
  }
}

string[]

[]

判断基準: Claude Code はデフォルトでカレントディレクトリのみを作業対象とする。マルチパッケージ構成では、ここに参照先を追加する。

permissions.defaultMode

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

"default"

"acceptEdits"

"plan"

"dontAsk"

/permissions

allow

"bypassPermissions"

判断基準: 個人開発なら

"acceptEdits"

"dontAsk"

permissions.disableBypassPermissionsMode

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

"disable"

--dangerously-skip-permissions

判断基準: Managed スコープ専用と考えてよい。セキュリティポリシーが厳しい組織では必須。個人開発では不要。

カテゴリ 3：サンドボックス設定

パーミッションの deny ルールが 10 個を超えたら、サンドボックスの方が管理しやすい。

sandbox.enabled

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

boolean

false

判断基準: macOS では Apple Seatbelt、Linux では Landlock を使う OS レベルのサンドボックス。有効にすると、Claude のコマンド実行がサンドボックス内に制限される。

autoAllowBashIfSandboxed: true

sandbox.filesystem

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["//tmp/build", "~/.kube"],
      "denyWrite": ["//etc"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

パスプレフィックスの意味:

//

//tmp/build

/tmp/build

~/

~/.kube

/

/build

sandbox.network

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowLocalBinding": true
    }
  }
}

allowedDomains

allowLocalBinding

判断基準: ネットワーク制限は強力だが、設定漏れで

npm install

git clone

allowedDomains

カテゴリ 4：Hooks 設定

ツール実行の前後にカスタム処理を挟む仕組み。自動化のキーポイント。

基本構造

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "ツール名パターン",
        "hooks": [
          {
            "type": "command",
            "command": "実行するコマンド"
          }
        ]
      }
    ]
  }
}

主要イベント一覧

SessionStart

startup

resume

clear

compact

PreToolUse

PostToolUse

Notification

permission_prompt

idle_prompt

auth_success

Stop

UserPromptSubmit

ConfigChange

user_settings

project_settings

Hook の type

command

http

prompt

agent

実践例：自動フォーマット

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

判断基準: PostToolUse で Prettier を走らせると、Claude が編集するたびに自動フォーマットされる。レビュー時のフォーマット差分が解消される。ただし、大量のファイルを連続編集するタスクではフック実行のレイテンシが加算されるため、体感で遅く感じることがある。

実践例：デスクトップ通知（macOS）

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

実践例：コンテキスト圧縮後のリマインダー

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: Use Bun, not npm. Run bun test before committing.'"
          }
        ]
      }
    ]
  }
}

判断基準: 長時間作業でコンテキスト圧縮が発生すると、初期の指示が失われることがある。

compact

終了コードの意味

Hook スクリプトの終了コードで Claude の動作を制御できる。ただし イベントによってブロック可否が異なる 点に注意。

0

UserPromptSubmit

SessionStart

2

exit 2 でブロックできるイベント:

PreToolUse

PermissionRequest

UserPromptSubmit

Stop

SubagentStop

ConfigChange

exit 2 でもブロックできないイベント:

PostToolUse

Notification

SessionStart

SessionEnd

#!/bin/bash
# PreToolUse フックの例：危険なコマンドをブロック
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE "drop table|truncate|rm -rf /"; then
  echo "Blocked: destructive command detected" >&2
  exit 2  # ブロック
fi

exit 0  # 許可

disableAllHooks / allowManagedHooksOnly

{
  "disableAllHooks": false,
  "allowManagedHooksOnly": false
}

判断基準:

disableAllHooks

allowManagedHooksOnly

カテゴリ 5：MCP サーバー設定

MCP（Model Context Protocol）サーバーの管理に関する設定。

enableAllProjectMcpServers

{
  "enableAllProjectMcpServers": true
}

boolean

false

.mcp.json

判断基準: 信頼できるリポジトリでのみ

true

true

allowedMcpServers / deniedMcpServers

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

3 つのマッチ方法がある。

serverName

"github"

serverUrl

"https://*.company.com/*"

serverCommand

["npx", "-y", "package"]

判断基準: Managed スコープに入れると、組織で許可された MCP サーバーのみ使用可能になる。

serverCommand

カテゴリ 6：UI・表示設定

使い勝手の微調整。優先度は低いが、長時間使うなら設定する価値がある。

showTurnDuration

boolean

true

spinnerTipsEnabled

boolean

true

terminalProgressBarEnabled

boolean

true

prefersReducedMotion

boolean

false

respectGitignore

boolean

true

@

.gitignore

{
  "showTurnDuration": true,
  "prefersReducedMotion": false,
  "respectGitignore": true
}

判断基準: 大半のケースでデフォルト値のまま十分に機能する。

respectGitignore: false

node_modules

@

statusLine

{
  "statusLine": {
    "type": "command",
    "command": "echo \"branch: $(git branch --show-current) | cost: $CLAUDE_SESSION_COST\""
  }
}

判断基準: ステータスラインに Git ブランチやセッションコストを表示できる。長時間セッションでコスト管理したいなら設定する価値がある。

カテゴリ 7：認証・クラウドプロバイダー設定

{
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

forceLoginMethod

"claudeai"

"console"

forceLoginOrgUUID

awsAuthRefresh

判断基準: 組織で API Console を使う場合は

"console"

カテゴリ 8：高度な設定

attribution

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

判断基準: コミットメッセージや PR に

Co-Authored-By: Claude

alwaysThinkingEnabled

{
  "alwaysThinkingEnabled": true
}

判断基準: 拡張思考（Extended Thinking）をデフォルトで有効化する。複雑なタスクでは推論品質が上がるが、簡単なタスクではレイテンシが増える。Option+T でトグルもできるので、デフォルト有効にしておいて問題ない。

plansDirectory

{
  "plansDirectory": "./plans"
}

判断基準: Plan モードで生成される計画ファイルの保存先。デフォルトは

./plans

teammateMode

{
  "teammateMode": "auto"
}

"auto"

"in-process"

"tmux"

判断基準: エージェントチーム（

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

"tmux"

主要な環境変数クイックリファレンス

settings.json

env

モデル・出力制御

ANTHROPIC_MODEL

CLAUDE_CODE_MAX_OUTPUT_TOKENS

32000

64000

CLAUDE_CODE_EFFORT_LEVEL

"high"

"low"

"medium"

"high"

CLAUDE_CODE_SUBAGENT_MODEL

Bash 制御

BASH_DEFAULT_TIMEOUT_MS

120000

BASH_MAX_TIMEOUT_MS

600000

BASH_MAX_OUTPUT_LENGTH

機能フラグ

CLAUDE_CODE_DISABLE_AUTO_MEMORY

0

CLAUDE_CODE_DISABLE_FAST_MODE

CLAUDE_CODE_SIMPLE

0

ENABLE_TOOL_SEARCH

"auto"

"auto:5"

プライバシー

DISABLE_TELEMETRY

0

DISABLE_ERROR_REPORTING

0

CLAUDE_CODE_HIDE_ACCOUNT_INFO

0

DISABLE_COST_WARNINGS

0

クラウドプロバイダー

CLAUDE_CODE_USE_BEDROCK

CLAUDE_CODE_USE_VERTEX

CLAUDE_CODE_USE_FOUNDRY

ANTHROPIC_API_KEY

判断基準: 環境変数と

settings.json

一時的に切り替えたい項目はシェルで設定する。

現場でハマる罠と対策

罠 1：deny ルールが「効かない」

症状:

deny

Read(./.env)

.env

原因: Claude が絶対パスでアクセスしている。

./.env

//Users/me/project/.env

対策: 両方のパターンを deny に入れる。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(//.env)",
      "Read(//.env.*)"
    ]
  }
}

罠 2：Hook が発火しない

症状:

PostToolUse

原因: 以下のいずれか。

• matcher

  のツール名が間違っている（大文字小文字は区別される）
• Hook スクリプトに実行権限がない

• disableAllHooks: true

  が上位スコープで設定されている

対策:

claude --debug

claude --debug
# Hook の実行ログが出力される

罠 3：スコープの優先順位を誤解する

症状: User スコープの

allow

deny

原因: これは正しい動作。deny は最優先で評価される。

対策: 設定の意図を理解する。deny はどのスコープに書いても最優先。「Project で deny しているが自分だけ allow したい」場合は、Local スコープ（

.claude/settings.local.json

罠 4：MCP サーバーが起動しない

症状:

.mcp.json

原因:

enableAllProjectMcpServers

false

対策: Claude Code 内で

/mcp

enableAllProjectMcpServers: true

インタラクティブコマンドで設定を管理する

settings.json

/config

/permissions

/hooks

/mcp

/allowed-tools add Edit

判断基準: 初回の設計は

settings.json

/config

/permissions

チーム導入：最初の 3 ステップ

チームに Claude Code の設定を導入する場合、以下のステップで段階的に進める。

• Project スコープの— deny ルール（

  settings.json

  をリポジトリに入れる

  .env

  保護）と PostToolUse Hook（フォーマッター）を最低限設定し、

  git commit

  する
• User スコープの推奨テンプレートを共有する— Wiki やオンボーディングドキュメントに

  ~/.claude/settings.json

  のサンプルを載せる。強制ではなく推奨として配布する
• 20 人を超えたら Managed スコープを検討する—

  disableBypassPermissionsMode

  や

  allowedMcpServers

  など、個人で解除できない組織ポリシーが必要になるタイミングが来る

まとめ：最初に設定する 5 つの項目

設定項目は多いが、最初に触るべきはこの 5 つに絞れる。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "language": "japanese",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ],
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)"
    ]
  }
}

• — エディタ補完を有効化。設定ミスの半分を防ぐ

  $schema

• — 応答言語を固定

  language

• — 秘密情報の保護。最優先で設定する

  deny

• — 安全なコマンドの確認スキップ。日常の摩擦を減らす

  allow

• Hook（PostToolUse → フォーマッター）— 自動フォーマットでレビュー品質を上げる

残りは「痛みが出てから追加する」で十分。設定は増やすより減らす方が難しい。

参考リンク

GitHubで編集を提案