08 設定ファイルプログラムの動作を決める設定値を書いたファイル。コード本体を書き換えずに、設定だけ変えられるようにする — 全設定の解説

設定の3層構造

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

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

CLAUDE.md

<a id="claude-md-globグロブ。ファイル名を「＊（任意の文字列）」等のワイルドカードで指定する書き方。「*.md」＝すべてのmdファイル、のような使い方al"></a>Layer 1: グローバルCLAUDE.md

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

• 場所: ~/.claude/CLAUDE.md
• 内容: 言語設定、LLM利用ポリシー、セキュリティルール、コーディング原則、SSOT参照
• トークンAIにとっての「文字数」のようなもの。AIは文章をトークンという小片に区切って処理する。課金や入力上限（コンテキストウィンドウ）はこの単位で数えられる: ~2.4k（常にロードされる）

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

• 日本語回答ルール
• モデルルーティング（上位モデル → バランス型 → 軽量型）
• 使用モデル表示ルール
• タスク切り替え時の記録ルール
• セキュリティルール（APIApplication Programming Interface（エーピーアイ）の略。あるプログラムの機能を、別のプログラムから呼び出せるようにした「窓口」キー非表示等）
• コーディング原則
• SSOT（共通知識ベース）の参照
• セッションClaude Codeの1回の対話単位。起動から終了までの会話と作業状態のこと。長く使うと内容が混ざるため、トピックの区切りで新セッションに引き継ぐ運用をするタイトルの日本語生成ルール
• 実行環境の注意（Windows + WSL2の2層構造 — Cron等は wsl bash -c 経由必須）

<a id="claude-md-project"></a>Layer 2: プロジェクトCLAUDE.md

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

• 場所: <repo>/CLAUDE.md
• 内容: プロジェクトの構造、使用技術、テスト方法、ビルドソースコードから、実行可能な完成品を組み立てることコマンドターミナルに入力してコンピュータに与える一行の指示。lsやcdのように『プログラム名+補足指定』で構成される
• 作成方法: /init コマンドで自動生成、または手動作成

Layer 3: ディレクトリフォルダのこと。ファイルを階層的に整理する入れ物。Linux系ではフォルダをディレクトリと呼ぶのが普通CLAUDE.md

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

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

settings.json

<a id="settings-json"></a>グローバル設定: ~/.claude/settings.json

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

主要セクション:

{
  "permissions": {
    "allow": ["Bash(npm test)", "Read"],
    "deny": ["Bash(rm -rf)"],
    "ask": ["Bash(git worktree add:*)"]
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "PostToolUseFailure": [...],
    "SessionStart": [...],
    "Stop": [...],
    "Notification": [...]
  },
  "mcpServers": {
    "brave-search": { ... },
    "github": { ... },
    "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 }
}

フックの種類と用途

その他の設定項目

<a id="statusline"></a>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.3 | Ctx 45% (90k/200k) | Req 8.5MB/32 | +100 -50 | 🪟e36d
• 表示例（peak帯フォールバック）: 🟠[peak→minimax] GLM-5.3→MiniMax-M3 | ... | 🪟e36d
• 並び順（2026-08-16改）: LLM名 → Ctx → Req → 作業量 → タブID。コスト（$表示）は削除（claude-costコマンドで確認）。※スマホ表示で末尾が見切れるため、モデル・コンテキストを先頭に変更（旧: タブID先頭・2026-07-23〜）

<a id="env-settings"></a>env（環境変数値を入れておく名前付きの箱。x = 1 のように名前に値を紐付けて、後で使い回すの注入）

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

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

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

<a id="settings-local"></a>プロジェクト設定: <repo>/.claude/settings.json

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

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

<a id="claude-json"></a>~/.claude.json（追加設定ファイル）

2ファイル問題: ~/.claude.json と ~/.claude/settings.json の両方が存在し、マージ分かれていた変更を1つに統合すること。ブランチで進めた作業を本体（main）に取り込む作業されてロードされる。

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

<a id="secrets"></a>シークレット管理

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 セクション）
• Claude Code本体（ANTHROPIC_AUTH_TOKEN 等）はシェルユーザーとOSの間に入って、コマンド入力を受け付けて実行する程序。ターミナルで打つコマンドを実際に処理する部分環境変数でも動作するが、同フックで注入する設計に統一
• Git管理: settings.json は claude-config/.gitignore で除外済み — 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（全環境変数表示）

設定変更の方法

<a id="gitignore-best-practice"></a>.gitignore ベストプラクティス（設定リポジトリ向け）

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

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

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

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

<a id="windows-vs-wsl"></a>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は両方の設定ファイルとも別管理

<a id="windows-git-auth"></a>Windows DesktopのGitHub認証「あなたは誰か」を確認すること。パスワードや鍵で本人であることを確かめる手続き（git push失敗の対処）

WindowsとWSLはSSH鍵の置き場所も独立している。WSL側~/.ssh/id_ed25519で運用しているGitHub鍵は、Windows側C:\Users\<user>\.ssh\には存在しないため、Windows Desktop版のBashツール（Git Bash）からgit pushするとPermission denied (publickey)で失敗する。

対処（HTTPエイチティーティーピー。Webの通信で使われる基本的な約束事（プロトコル）。ブラウザとサーバー、プログラム同士のやり取りの共通言語S + GitHub CLI方式）: SSH鍵をコピー・共有せず、GitHub CLI (gh) の認証情報をWindows側のみで使う。

# 1. インストール
winget install GitHub.cli

# 2. ブラウザ認証（対話操作が必要）
gh auth login --hostname github.com --git-protocol https --web

# 3. gitのcredential helperと連携
gh auth setup-git

# 4. Windows側グローバルgitconfigにURL書き換えルールを追加
git config --global url."https://github.com/".insteadOf "git@github.com:"

• 4番目の設定は C:\Users\<user>\.gitconfig にのみ追加され、WSL側 ~/.gitconfig（実体は別ファイル）には一切影響しない
• リポジトリ本体（.git/configのremote URL）も変更不要。Windows側のgit実行時にだけURL解釈が書き換わる
• WSL側は従来通りSSH鍵で動作し続ける（双方の動作確認済み）

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

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アプリパッケージ内に配置される。

<a id="claude-config-venvブイエンブ。Python標準の仮想環境を作るコマンド/仕組み。プロジェクトごとにライブラリを分けてインストールできるようにする"></a>claude-config配下スクリプトのPython実行環境

claude-config リポジトリ（scripts/api/*.py 等）のPythonスクリプトは 専用仮想環境プロジェクトごとにインストールするライブラリを分ける独立したPython環境。プロジェクト間のバージョン衝突を防ぐ .venv で実行 する。

• 原因: google-genai は .venv にのみ導入。システム python3（~/.local の namespace google）には genai が無い
• 対策: 常に .venv/bin/python を使用。pip install --user でシステム側へ入れるのは誤り（.venvに既存）
• シークレット読込を前置: set -a; source ~/.secrets.env; set +a

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

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

OAuthオーオースと読む。他のサービスの機能を、IDやパスワードを教えずに安全に使わせるための認可の標準規格。「○○でログイン」ボタンの裏側で動いている仕組み認証トークンの蓄積問題

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

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

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

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