Claude Codeのsettings.json完全ガイド：権限・Hooks・MCP・チーム設定を安全に使う方法

settings.jsonとは？Claude Codeの動作を決める設定ファイル

settings.jsonは、Claude Codeの挙動をJSONで管理する設定ファイルです。たとえば、どのコマンドを自動許可するか、どのファイルを読ませないか、編集後にテストを走らせるか、標準モデルを何にするか、といった設定を書けます。

混同しやすいのがCLAUDE.mdとの違いです。CLAUDE.mdは「プロジェクトの説明や作業ルールをClaudeに読ませるメモリ」、settings.jsonは「Claude Code本体の権限・ツール・環境を制御する設定」です。

settings.jsonを置く場所と優先順位

Claude Codeの設定は、1つのファイルだけで決まるわけではありません。ユーザー全体、プロジェクト共有、個人用ローカル、組織管理ポリシーなど複数の階層があります。

優先順位は、上から「管理ポリシー」「コマンドライン引数」「ローカルプロジェクト設定」「共有プロジェクト設定」「ユーザー設定」です。つまり、~/.claude/settings.jsonで許可していても、プロジェクト側や管理ポリシーで制限されていれば、そちらが優先されます。

まず入れたい基本形：スキーマ、権限、機密ファイル保護

最初におすすめなのは、JSON Schema、最小限の許可、機密ファイルの読み取り拒否です。特に.env、認証JSON、秘密鍵、ビルド成果物は読ませない設定にしておくと事故を減らせます。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

$schemaを入れておくと、VS CodeやCursorなどのエディタで補完やバリデーションが効きやすくなります。ただし、公式ドキュメントに追加されたばかりの設定は、スキーマ側の更新が追いつかない場合もあります。

権限設定では、便利さを優先して広く許可しすぎないことが重要です。最初はnpm run lint、npm run test、git status、git diffのような安全な確認系から始め、必要に応じて追加していくのが現実的です。

permissionsの考え方：allow・deny・defaultMode

permissionsは、Claude Codeに何を許可し、何を止めるかを決める中心設定です。開発効率を上げるために自動許可を増やしたくなりますが、ここは「読む・書く・実行する」の3つを分けて考えると整理しやすくなります。

defaultModeは、Claude Codeを起動したときの権限モードを指定します。たとえば、編集は許可しやすくしつつコマンド実行は確認したい場合はacceptEditsが候補になります。作業前に設計だけさせたい場合はplanも有効です。

env設定：環境変数は便利だが秘密情報の扱いに注意

envには、Claude Codeのセッションで使う環境変数を設定できます。たとえば、テレメトリ、言語、内部ツール用のフラグなどです。

{
  "language": "japanese",
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

一方で、APIキーや長期トークンをそのまま.claude/settings.jsonに書くのは避けた方が安全です。チーム共有ファイルに秘密情報が混ざると、リポジトリ経由で漏えいする可能性があります。

個人環境の値は.claude/settings.local.jsonやOS側のシークレット管理、必要に応じてapiKeyHelperのようなヘルパー方式を検討します。特にGoogle、AWS、GitHub、社内APIとつなぐ場合は、Claudeに認証情報の中身を読ませず、必要なコマンドだけ実行させる設計が安全です。

Hooks設定：編集後のテストや危険コマンドブロックを自動化する

Hooksは、Claude Codeのライフサイクルに合わせてシェルコマンド、HTTPエンドポイント、MCPツール、プロンプトなどを実行する仕組みです。代表的には、ツール実行前のPreToolUse、実行後のPostToolUse、ユーザー入力前後、セッション開始時などに使えます。

たとえば、Claudeがファイルを編集した後にlintを走らせる設定は次のように書けます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/run-lint.sh"
          }
        ]
      }
    ]
  }
}

また、危険なコマンドを実行前に検査するならPreToolUseが向いています。公式ドキュメントでも、Bashツールに対してrm -rfのような破壊的コマンドをブロックする例が紹介されています。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Hooksは非常に強力ですが、設定ファイルに書いたコマンドが自動実行される点に注意が必要です。プロジェクト共有のHooksを導入する場合は、スクリプトの中身をレビューし、外部通信や削除処理がないか確認しましょう。

MCP・プラグイン・マーケットプレイス設定

Claude Codeでは、MCPサーバーやプラグインを使って外部ツール連携を広げられます。ただし、すべてをsettings.jsonに書くわけではありません。公式ドキュメントでは、プロジェクトスコープのMCPサーバーは.mcp.json、ユーザーやローカルのMCP情報は~/.claude.json側に保存されると説明されています。

settings.jsonで扱う代表例は、プラグインの有効化や追加マーケットプレイスです。

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true
  },
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

チームで使うプラグインを標準化したい場合は、.claude/settings.jsonにマーケットプレイスを登録し、必要なプラグインを有効化します。企業利用では、管理ポリシー側でstrictKnownMarketplacesを使い、許可されたマーケットプレイス以外をブロックする運用も可能です。

チーム開発でおすすめのsettings.json構成

チームでClaude Codeを使うなら、共有ファイルと個人ファイルを明確に分けることが重要です。特に、個人のパス、APIキー、ローカルだけのコマンド、実験的なHooksは共有設定に入れないようにします。

設定が効かないときの確認ポイント

Claude Codeの設定が効かないときは、まず配置場所と優先順位を確認します。ユーザー設定に書いた内容がプロジェクト設定で上書きされている、settings.local.jsonが存在している、管理ポリシーが効いている、というケースはよくあります。

• /statusで読み込まれている設定ソースを確認する
• JSONの構文エラーがないか確認する
• プロジェクト設定とローカル設定で同じキーを書いていないか確認する
• 配列系の設定は置き換えではなくマージされる点を理解する
• modelなど一部の設定はセッション再起動が必要な場合がある

公式ドキュメントでは、permissions.allowやsandbox.filesystem.allowWriteのような配列設定は、スコープ間で連結・重複排除されると説明されています。単純に「上位が下位を完全に置き換える」と考えると、意図しない許可が残ることがあります。

実用テンプレート：個人開発向けとチーム向け

個人開発向け

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

チーム共有向け

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/check-after-edit.sh"
          }
        ]
      }
    ]
  }
}

チーム共有向けでは、全員に強制したい最低限の安全設定だけを入れるのがポイントです。プロジェクトごとにテストコマンドが違う場合は、package.jsonやMakefile側に共通コマンドを用意しておくと、Claude Codeからも人間からも同じ手順で実行できます。

まとめ：settings.jsonは「便利設定」ではなく安全な運用設計

Claude Codeのsettings.jsonは、単なる好みの設定ファイルではありません。AIエージェントにどこまで作業を任せるか、何を絶対に読ませないか、編集後に何を確認するかを決める運用設計の中心です。

まずは、.envや秘密情報の読み取り拒否、lint・test・差分確認の許可、必要最小限のHooksから始めましょう。チームで使う場合は、共有設定と個人設定を分け、便利さよりも再現性と安全性を優先すると失敗しにくくなります。

Claude Codeを本格的に使うなら、CLAUDE.mdで作業方針を伝え、settings.jsonで権限と自動化を管理し、必要に応じてMCPやプラグインで外部ツール連携を広げる。この3点セットで整えるのがおすすめです。

参考リンク

• Claude Code Docs: Claude Code settings
• Claude Code Docs: Hooks reference
• Claude Code Docs: Automate workflows with hooks
• Claude Code Docs: Connect Claude Code to tools via MCP

本記事の内容は2026年6月9日時点の公式情報をもとにしています。Claude Codeの設定キー、権限モード、Hooks、プラグイン仕様は更新される可能性があります。