第8章設定システムリファレンス

はじめに

ここまでの章で登場したパーミッション・フック・MCP などの設定は、すべて settings.json を中心とした設定システムに集約されます。
本章では、設定ファイルの階層と優先順位、主要項目を体系的に整理します。

8.1 設定ファイルの階層と優先順位

settings.json は複数の場所に置くことができ、上位（より具体的・より管理的）が下位を上書き します。

flowchart TD
    A["1. エンタープライズ管理設定<br/>managed-settings.json（管理者が配布・最優先）"]
    B["2. CLI オプション<br/>（そのセッション限り）"]
    C["3. プロジェクトローカル設定<br/>.claude/settings.local.json（git 管理外・個人用）"]
    D["4. プロジェクト共有設定<br/>.claude/settings.json（git 共有・チーム用）"]
    E["5. ユーザー設定<br/>~/.claude/settings.json（全プロジェクト共通）"]
    A -->|上書き| B -->|上書き| C -->|上書き| D -->|上書き| E

ファイル	対象	git 管理	典型的な内容
`managed-settings.json`	組織全体（強制）	—	セキュリティポリシー、禁止事項
`.claude/settings.local.json`	自分×このリポジトリ	しない	個人的な許可ルール、ローカル環境変数
`.claude/settings.json`	チーム×このリポジトリ	する	共通の許可ルール、フック、環境変数
`~/.claude/settings.json`	自分×全リポジトリ	—	個人の既定モデル、共通フック

8.2 settings.json の全体像

主要な設定項目を1つのサンプルにまとめると次のようになります。

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(pnpm test:*)", "Bash(git diff:*)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Bash(rm -rf:*)"],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "pnpm biome check --write ." }]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 30
}

キー	役割	関連章
`model`	既定モデルの指定	—
`permissions`	allow / ask / deny ルールと既定モード	第4章
`env`	セッションに適用する環境変数	—
`hooks`	フック定義	第5章
`statusLine`	ステータスライン表示のカスタマイズ	—
`cleanupPeriodDays`	セッション履歴の保持期間	第2章

このほか、.mcp.json（MCP サーバー定義・第6章）、.claude/commands/・.claude/skills/・.claude/agents/（第6・7章）も設定システムの一部です。

8.3 環境変数による制御

ハーネスの挙動は環境変数でも制御できます。
代表的なもの：

環境変数	役割
`ANTHROPIC_API_KEY`	API キー（API 経由で利用する場合）
`ANTHROPIC_MODEL`	既定モデルの上書き
`CLAUDE_CODE_USE_BEDROCK`	Amazon Bedrock 経由で接続
`CLAUDE_CODE_USE_VERTEX`	Google Vertex AI 経由で接続
`HTTP_PROXY` / `HTTPS_PROXY`	プロキシ設定
`MAX_THINKING_TOKENS`	拡張思考のトークン上限

settings.json の env に書けば、チームで統一した環境変数をセッションに適用できます。

8.4 CLI オプション（セッション単位の上書き）

一時的な挙動変更は CLI オプションが便利です。

# モデルを指定して起動
claude --model claude-opus-4-8

# 読み取り専用ツールだけ許可して起動
claude --allowedTools "Read" "Glob" "Grep"

# 非対話モード（ワンショット実行、CI 向け）
claude -p "テストを実行して失敗があれば要約して"

# システムプロンプトへの追記
claude --append-system-prompt "回答は必ず日本語で行うこと"

# パーミッションモードを指定
claude --permission-mode plan

8.5 設定のデバッグ

設定が意図どおり効いているかを確認する手段：

コマンド	確認できること
`/config`	現在の設定の確認・変更
`/permissions`	有効なパーミッションルールの一覧
`/hooks`	登録されているフックの一覧
`/mcp`	MCP サーバーの接続状態
`/status`	セッション情報（モデル、アカウントなど）
`claude doctor`	インストール状態の診断

複数階層の設定がマージされるため、「効かない」と思ったら上位層（managed settings や local settings）による上書きを疑うのが定石です。

まとめ

設定は「管理設定 > CLI > プロジェクトローカル > プロジェクト共有 > ユーザー」の優先順位でマージされる
チームに効かせたいものは .claude/settings.json にコミット、個人用は local / ユーザー設定へ
permissions・hooks・env・model が settings.json の中核。
MCP・スキル・エージェント定義も含めて .claude/ ディレクトリが設定の中心地
/permissions /hooks /mcp などのスラッシュコマンドで現在の状態を確認しながら調整する