08 設定ファイル — 全設定の解説

設定の3層構造

Claude Codeの設定は 3つのレイヤー で構成される。上のレイヤーほど優先度が高い。

Layer 3: ディレクトリ固有
  <repo>/<dir>/CLAUDE.md
    ↓ （上書き）
Layer 2: プロジェクト固有
  <repo>/CLAUDE.md
    ↓ （上書き）
Layer 1: グローバル（全プロジェクト共通）
  ~/.claude/CLAUDE.md

CLAUDE.md

Layer 1: グローバルCLAUDE.md

全プロジェクトで共通するルールを記述。

• 場所: ~/.claude/CLAUDE.md
• 内容: 言語設定、LLM利用ポリシー、セキュリティルール、コーディング原則、SSOT参照
• トークン: ~2.4k（常にロードされる）

グローバルCLAUDE.mdに含まれるもの:

• 日本語回答ルール
• モデルルーティング（上位モデル → バランス型 → 軽量型）
• 使用モデル表示ルール
• タスク切り替え時の記録ルール
• セキュリティルール（APIキー非表示等）
• コーディング原則
• SSOT（共通知識ベース）の参照
• セッションタイトルの日本語生成ルール
• 実行環境の注意（Windows + WSL2の2層構造 — Cron等は wsl bash -c 経由必須）

Layer 2: プロジェクトCLAUDE.md

プロジェクト固有のルールを記述。

• 場所: <repo>/CLAUDE.md
• 内容: プロジェクトの構造、使用技術、テスト方法、ビルドコマンド
• 作成方法: /init コマンドで自動生成、または手動作成

Layer 3: ディレクトリCLAUDE.md

特定ディレクトリのルール。必要な場合のみ使用。

• 場所: <repo>/<dir>/CLAUDE.md
• 内容: そのディレクトリ特有の規約

settings.json

グローバル設定: ~/.claude/settings.json

Claude Codeの動作を制御するメイン設定ファイル。

主要セクション:

{
  "permissions": {
    "allow": ["Bash(npm test)", "Read"],
    "deny": ["Bash(rm -rf)"]
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "PostToolUseFailure": [...],
    "SessionStart": [...],
    "Stop": [...],
    "Notification": [...]
  },
  "mcpServers": {
    "brave-search": { ... },
    "playwright": { ... },
    "context7": { ... },
    "discord": { ... },
    "mermaid": { ... }
  },
  "env": {
    "ANTHROPIC_API_KEY": "（直接書かない — ~/.secrets.envから注入）"
  },
  "model": "opus",
  "effortLevel": "medium",
  "worktree": { "baseRef": "fresh" },
  "statusLine": { "type": "command", "command": "..." },
  "autoDream": { "enabled": true, "intervalHours": 24 }
}

フックの種類と用途

SessionStartフックの構成（起動シーケンス）

SessionStart で複数のフックが決まった順序で連鎖する：

{
  "SessionStart": [
    { "command": "sync-secrets-to-settings.sh" },   // 1. ~/.secrets.env → settings.json 注入
    { "command": "load-obsidian-log.sh" },          // 2. SSOT日記・バックログをコンテキストへ
    { "command": "sync-settings-to-example.sh" },   // 3. settings.json → settings.example.json（マスク）
    { "command": "skill-guard.sh" },                // 4. プラグインSKILL.md と skills-custom/ 復元
    { "command": "startup-banner.sh" }              // 5. ターミナルにバナー表示（GLMモデル等）
  ]
}

• load-obsidian-log.sh（軽量版）: 今日=直近3セッション / 昨日=1行サマリー / バックログ=P0+P1のみ。/dev/tty でターミナルにも同時表示
• セッション数カウント: 今日の 10_DAILY/YYYY-MM-DD.md 内 ## セッションログ の出現回数を集計しバナーに表示
• バックログ自動確認: 7日以上更新のないタスクは バックログ7日経過 警告を表示（鮮度管理）
• プロキシ互換性自動チェック（check-proxy-compat.sh）: CC版変化時にプロキシ（glm-rate-proxy）が tool_use に応答するか自動検証。致命的即死のみ防止（表面チェックはすり抜ける前提・常にexit 0・ブロックしない）。同版かつ前回okなら省略。プロキシ停止中（proxy_down）/ token未設定（skipped）/ 検証失敗（fail）時は黄色バナーで警告+ダウングレードコマンドを表示。state保存先 ~/.claude/state/proxy-compat.json（cc_version/status/checked_at/detail/last_ok_version）。依存コマンド事前チェック（claude/python3/curl/systemctl）不在時は静かにskip

詳細: 01_基礎概念.md#セッション管理

check-proxy-compat.sh の状態遷移:

状態         条件                                    動作
─────────────────────────────────────────────────────────────────
ok           HTTP 200 かつ tool_use 応答あり          exit 0（次回から同版なら省略）
fail         HTTP 200 だが tool_use 不在              黄色バナー表示・exit 0
fail         HTTP 200以外                            黄色バナー表示・exit 0
proxy_down   プロキシ systemctl active でない          黄色バナー表示・exit 0
skipped      token未設定                              exit 0（無音・推奨A反映）
skip         依存コマンド不在                         exit 0（無音）

• spec: docs/superpowers/specs/2026-07-08-proxy-compat-check-hook-design.md (v2)
• Phase1: settings.json 未登録・手動 bash ~/.claude/scripts/session/check-proxy-compat.sh で検証
• ダウングレード例: npm install -g @anthropic-ai/claude-code@<last_ok_version>

その他の設定項目

statusLine の詳細

画面下部にLLM名・コスト・作業量・コンテキスト残量・会話サイズを表示する。glm-rate-proxy の実動作状態を反映し、peak時間帯のフォールバックもバッジで示す。

• 設定: {"type": "command", "command": "bash ~/.claude/scripts/llm/llm-status.sh"}
• スクリプト: ~/.claude/scripts/llm/llm-status.sh
• 表示例（通常）: 🟡[GLM] GLM-5.2 | $0.12 | +100 -50 | Ctx 45% (90k/200k) | Req 8.5MB/32
• 表示例（peak帯フォールバック）: 🟠[peak→minimax] GLM-5.2→MiniMax-M3 | ...

env（環境変数の注入）

env セクションで Claude Code プロセスに環境変数を追加できる。APIキーは ~/.secrets.env で管理するため、ここには非機密の制御変数のみ記載する（シークレットは SessionStart フックで自動注入）。

代表的な制御変数（非機密）:

glm-rate-proxy経由のルーティング変数（ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL / ANTHROPIC_DEFAULT_OPUS_MODEL 等）→ 13_glm-rate-proxy で詳述。

プロジェクト設定: <repo>/.claude/settings.json

プロジェクト固有の設定。

• 場所: <repo>/.claude/settings.json
• 内容: そのプロジェクトでのみ有効な権限・MCP・フック
• 用途: チーム共有可能な設定（.gitignoreに含めない場合）

~/.claude.json（追加設定ファイル）

2ファイル問題: ~/.claude.json と ~/.claude/settings.json の両方が存在し、マージされてロードされる。

• どちらに書いても効果は同じ
• しかし削除する際は両方から削除する必要がある
• claude mcp remove CLIコマンドを使うと両方に反映される

シークレット管理

APIキー等の機密情報は ~/.secrets.env に一元管理。

# ~/.secrets.env の例
MINIMAX_API_KEY=sk-xxx...
BRAVE_API_KEY=BSExxx...
GITHUB_TOKEN=ghp_xxx...

セキュリティルール

settings.jsonとの関係

SessionStartフック sync-secrets-to-settings.sh が起動のたびに ~/.secrets.env の値を settings.json へ自動注入する。

• 目的: MCPサーバーへ環境変数を渡すため（mcpServers.xxx.env セクション・現在は brave-search/glm/minimax 等）
• Claude Code本体（ANTHROPIC_AUTH_TOKEN 等）はシェル環境変数でも動作するが、同フックで注入する設計に統一
• Git管理: settings.json は claude-config/.gitignore で除外済み — GitHubには上がらない
• ⚠️ github MCP は廃止（2026-06-22）: 32MB問題（settings.json肥大化）のため plugin 経由で無効化済。GitHub操作は gh CLI（SSH認証）に統一。GITHUB_TOKEN（~/.secrets.env）は gh CLI 用として残存するが settings.json には注入しない（注入スクリプトから github 行を削除済・復活経路を完全閉塞）

settings.example.json の自動同期

SessionStartフック sync-settings-to-example.sh が settings.json からシークレット値をマスクして settings.example.json を生成する。

• jq優先: jq で env 内のキー名に KEY|TOKEN|SECRET|PASSWORD|AUTH（大文字小文字区別なし）を含む値を "" に置換
• python3フォールバック: jq が利用不可の場合、python3 で同等のマスク処理を実行
• TOKENマスク: permissions.allow 内の TOKEN=<値> 形式の項目（Discord Bot Token等）も汎用文字列に置換
• mcpServers: 全MCPサーバーの env 値を "" にマスク

# バックアップ運用
settings.example.json  ← 値マスク済み。SSOTへのバックアップはこちらのみ
settings.json          ← 実体。バックアップ・出力・表示は禁止

危険コマンドのブロック

PreToolUseフック（check-command-safety.py）が以下を自動ブロック:

• bash -x（デバッグ出力で露出の恐れ）
• cat -A（特殊文字表示で露出の恐れ）
• マスクなしの grep（APIキー検索）
• フィルタなしの env（全環境変数表示）

settings.json を安全に編集するには（python構造操作）

settings.json 等の機密ファイルは Read がブロックされるため、値を見ずに構造だけ操作して書き戻すのが安全な編集方法。Edit ツールは Read 前提で動かないため、Python で構造のみ触る:

import json, shutil
p = "/home/<USER>/.claude/settings.json"
shutil.copy(p, p + ".tmp-bak")          # バックアップ
d = json.load(open(p))
d["hooks"]["SessionStart"][0]["hooks"].append(
    {"type": "command", "command": "/home/<USER>/.claude/scripts/session/foo.sh"}
)
with open(p, "w") as f:
    json.dump(d, f, indent=2, ensure_ascii=False)  # 元フォーマット(indent=2)保持

• 値（envのAPIキー等）には触れない（構造のみ変更）→ 差分 diff bak new | grep '^>' に secret は出ない
• indent=2 + ensure_ascii=False で元フォーマット保持（最小差分・surgical）
• Bash 経由の変更は PostToolUse の auto-sync が発火しない（Edit/Write トリガーのみ）→ SSOT の設定ファイルコピー(01_DECISIONS/claude-code/設定ファイル/)は手動同期が必要
• ブロック時の guard メッセージにもこの手順が表示される（check-command-safety.py の check_read）

設定変更の方法

.gitignore ベストプラクティス（設定リポジトリ向け）

claude-config のような設定・hook・スクリプト類を管理するリポジトリでは、Auto sync / PostToolUse hook が編集系のバックアップファイルを巻き込んで commit する事故が過去に発生している（*.bak 129行混入の事例あり）。

最低限入れておく除外パターン:

# バックアップファイル（エディタ・merge・rebase 由来）
*.bak
*.orig
*~

# 既存パターン
backups/
backup-*/

Windows Desktop vs WSL CLI — 設定の違い

WSL2環境では Windows Desktopアプリ と WSL CLI の2つのClaude Codeが共存する。設定ファイル・管理系統・ツール定義のシリアライズに重要な違いがある。

設定の独立性

WSL側とWindows側の設定は独立している:

• WSL側でMCP serverを削除しても、Windows Desktopアプリには反映されない
• Windows側でMCP serverを変更しても、WSL CLIには反映されない
• Desktop Extensionsは両方の設定ファイルとも別管理

ツール定義のシリアライズ差異（重要）

Windows Desktopアプリは、同一のMCP構成でもCLIより6倍以上のトークンを消費する。2026年5月時点では、6回の異なる設定変更（MCP server削除・profiles無効化・plugin cache削除・marketplace削除・plugin個別無効化・Extensions削除）で検証済み。Desktop Extensionsの削除のみ-10.6kの効果があったが、残り213kはアプリ内部で固定。

Desktop Extensions

Desktopアプリ専用の拡張機能。Windows Storeアプリパッケージ内に配置される。

Claude Extensions/
  ├── ant.dir.ant.anthropic.filesystem/  (11ツール)
  ├── grafana/                           (71ツール) ※不要なら削除
  ├── pdf-filler/                        (37ツール) ※不要なら削除
  ├── desktopcommander/                  (26ツール) ※不要なら削除
  ├── growthbook/                        (18ツール) ※不要なら削除
  ├── figma/                             (7ツール)  ※不要なら削除
  └── apify/                             (?ツール)  ※不要なら削除

• 管理方法: フォルダを直接削除（設定ファイルからの参照なし）
• WSL CLIからはアクセス不可
• ** filesystemのみ残す推奨**（ファイル操作に有用）

OAuth認証トークンの蓄積問題

Desktopアプリはセッション開始のたびに新しいOAuth認証トークンを作成し、旧トークンを削除しない。長期間使用すると100+個のトークンが蓄積される。

推奨運用（2026年5月時点）

💡 やさしい補足（初心者向け）

• 設定は3層: 全体共通・プロジェクト固有・ローカル（自分だけ）。細かいほど優先される
• CLAUDE.md = ルールブック: 毎回読む。何をどう扱うかの決まりを書く
• settings.json = 機能設定: 追加機能・権限・自動動作を書く
• 秘密は別管理: APIキー等の重要な値は .secrets.env に一つにまとめて、設定ファイルには書かない（漏洩防止）