Settings JSON 設計 — 権限・環境変数・フック設定

Claude Code の動作は .claude/settings.json で細かく制御できます。権限・環境変数・フックを正しく設定することで、チームで安全にハーネスを運用できます。このページでは設定ファイルの構造から実践的な設計指針まで順を追って解説します。

---

仕組み

settings.json と settings.local.json の違い

Claude Code の設定は 2 つのファイルに分けて管理します。

ファイル	用途	Git 管理
.claude/settings.json	チーム共有の設定	コミットする
.claude/settings.local.json	個人専用の設定・上書き	.gitignore で除外する

settings.json はリポジトリにコミットし、チームメンバー全員が同じ権限・フック設定で動作させます。一方 settings.local.json は個人の API キーや実験的な設定を置く場所で、Git には含めません。

主要な設定項目

settings.json は以下の構造を持ちます。

{
  "permissions": {
    "allow": [
      "Bash(npm run dev)",
      "Bash(npm run harness:*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(npm run build)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Stop": []
  },
  "mcpServers": {
    "github": {}
  }
}

各セクションの役割は次のとおりです。

• permissions: Claude が実行できるツール・コマンドの許可リスト（allow）と禁止リスト（deny）
• env: Claude のセッション中に有効になる環境変数
• hooks: ツール実行の前後・停止時に走るスクリプト
• mcpServers: Model Context Protocol（MCP）サーバーの接続設定

permissions の allow/deny パターン

パターンは 3 種類の形式で書けます。

形式	例	意味
ツール名のみ	"Read"	Read ツール全体を許可
コマンド指定	"Bash(npm run dev)"	特定のコマンドだけを許可
glob パターン	"Bash(npm run harness:*)"	harness: で始まるコマンドすべてを許可

allow に登録したコマンドは、Claude が実行する際に権限プロンプト（確認ダイアログ）が表示されずに自動で実行されます。deny に登録したコマンドは、Claude が実行しようとしても常にブロックされます。

---

ベストプラクティス

最小権限の原則を守る

allow リストは「必要なものだけ」に絞ります。"Bash" 全体を許可すると、Claude がどんなシェルコマンドでも実行できてしまいます。プロジェクトで使う具体的なコマンドだけを列挙することで、意図しない操作を防げます。

// 避けるべき設定: Bash 全体を許可してしまう
"allow": ["Bash", "Read", "Write"]

// 推奨: 使うコマンドだけを明示する
"allow": ["Bash(npm run dev)", "Bash(npm run harness:*)", "Read", "Write", "Edit"]

npm run build は必ず deny に含める

npm run build はホスティングパイプラインと連携している場合、本番デプロイを発火させます。明示的に deny に登録することで、Claude が誤って実行することを防ぎます。

"deny": ["Bash(npm run build)"]

settings.local.json を .gitignore に追加する

個人の ANTHROPIC_API_KEY や実験的な設定が settings.json に混入しないよう、プロジェクトの .gitignore に以下を追記します。

.claude/settings.local.json

環境変数は env セクションに集約する

コードや設定ファイルに環境変数の値をハードコードするのではなく、env セクションに一元管理します。

"env": {
  "NODE_ENV": "development",
  "LOG_LEVEL": "info"
}

---

実践演習

Step 1: 現在の settings.json を確認する

プロジェクトルートで次のコマンドを実行し、現在の設定内容を確認します。

cat .claude/settings.json

permissions の allow と deny に何が登録されているかを読み取ります。

✅ 確認: deny に "Bash(npm run build)" が含まれていることを確認します。含まれていない場合は次のステップで追加します。

---

Step 2: npm run harness:check を allow に追加する

allow に "Bash(npm run harness:check)" が含まれていない場合は追加します。settings.json の permissions.allow 配列に次の行を加えます。

"allow": [
  "Bash(npm run dev)",
  "Bash(npm run harness:check)",
  "Bash(npm run harness:*)",
  "Read",
  "Write",
  "Edit"
]

✅ 確認: JSON の構文エラーがないことを確認します。配列の最後の要素にカンマが付いていないかチェックします。

---

Step 3: settings.local.json を作成する

個人用の設定ファイルをプロジェクトルートに作成します。実際の API キーは書かず、プレースホルダーで構造を確認します。

touch .claude/settings.local.json

ファイルの内容として次の構造を参考にします。

{
  "env": {
    "ANTHROPIC_API_KEY": "YOUR_API_KEY_HERE"
  }
}

次に .gitignore に除外設定が追加されているかを確認します。

grep "settings.local.json" .gitignore

✅ 確認: .gitignore に .claude/settings.local.json が記載されていることを確認します。記載がない場合は追記します。

---

Step 4: 設定の反映を確認する

settings.json を変更した後は Claude Code を再起動して設定を反映します。Claude Code を一度終了し、再度起動してから次のコマンドを実行します。

npm run harness:check

✅ 確認: Claude が権限プロンプトなしに npm run harness:check を実行できることを確認します。

---

まとめ

このページで学んだ内容を整理します。

• settings.json はチーム共有、settings.local.json は個人専用として分割管理する
• allow は使うコマンドだけを具体的に指定し、npm run build は必ず deny に含める
• 環境変数は env セクションに集約し、実際の値は settings.local.json に書く
• settings.local.json は .gitignore で Git 管理から除外する

次のステップ

• Rules ファイル設計 — 安全ルールを宣言的に書く — 設定で制御できない「ルール」を宣言的に管理する方法
• CLAUDE.md 設計 — Claude へのコンテキスト設計を深掘りする

---

よくある質問

Q: allow に登録していないコマンドは実行できませんか？

A: 実行はできますが、Claude が実行しようとするたびに権限プロンプトが表示されます。allow はプロンプトを表示せず自動実行させるコマンドのリストです。deny に登録したコマンドはプロンプトが表示されず、常にブロックされます。

Q: settings.local.json が存在しない場合はどうなりますか？

A: settings.json の設定だけが適用されます。settings.local.json はオプションのファイルです。

Q: glob パターンはどの程度柔軟に書けますか？

A: * は単一のパス区切りを含まない任意の文字列にマッチします。"Bash(npm run harness:*)" は npm run harness:check や npm run harness:sync に一致します。ただし "Bash(*)" のように過度に広いパターンは避けてください。

Q: hooks セクションで何ができますか？

A: PreToolUse はツール実行直前、PostToolUse は実行直後、Stop はセッション終了時に任意のスクリプトを走らせられます。例えばファイル更新後に自動でフォーマッターを走らせる、といった用途に使います。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation