Claude Code 設定ファイル完全ガイド — CLAUDE.md・スキル・settings.jsonの全てを解説

Claude Codeの「設定マップ」

Claude Codeを使い始めると、設定ファイルの種類の多さに驚くかもしれません。CLAUDE.md、スキル、settings.json、フック、MCP、キーバインド…これらはそれぞれ異なる役割を持ち、適切に使い分けることでClaude Codeの能力を最大限に引き出すことができます。

このガイドでは、まず全体像を把握してから各論に入ることで、「どの設定をどこに書けばいいのか」が明確にわかるようになります。

CLAUDE.md — プロジェクトの「ルールブック」

CLAUDE.mdは、Claude Codeが毎セッション自動的に読み込むMarkdown形式の指示書です。プロジェクトのルール、コーディング規約、ワークフロー、セキュリティポリシーなど、「常にClaudeに意識してほしいこと」を記述します。

配置場所の優先順位

CLAUDE.mdは4つの階層で配置でき、すべて結合されて読み込まれます（上書きではありません）。

1. ~/.claude/CLAUDE.md — ユーザー全体の設定（全プロジェクト共通）
2. プロジェクトルートのCLAUDE.md または .claude/CLAUDE.md — チーム全体で共有
3. CLAUDE.local.md — 個人専用のローカル設定（.gitignore対象）
4. 親ディレクトリのCLAUDE.md — モノレポ構成で活用

書くべき内容

• コーディング規約（インデント、命名規則、言語等）
• ワークフロー（テスト手順、コミット前の確認事項等）
• セキュリティルール（APIキーの扱い、禁止事項等）
• プロジェクト概要（目的、構成、デプロイ先等）
• よく使うコマンド（ビルド、テスト、デプロイ等）

書くべきでない内容

• 長大なAPIリファレンス（→ スキルに分離）
• 一時的なタスク指示（→ 会話で指示するか、.claude/rules/に分離）
• 秘密情報（APIキー、パスワード等）

典型的なCLAUDE.mdの構成例

# プロジェクト名

## コーディング規約
- インデント: スペース2つ（JS/TS/HTML/CSS）
- 変数名・関数名は英語で記述

## ワークフロー
- テスト: `npm test` を実行してから commit
- コミットメッセージは日本語OK

## セキュリティ
- .env ファイルの中身をコード内にハードコードしない
- commit 前に `git diff --staged` で秘密情報がないか確認

## 参照ドキュメント
@README.md
@docs/architecture.md

@path/to/file 構文を使うことで、他のファイルをCLAUDE.mdにインポートできます。長大な仕様書を外部ファイルに分離し、必要に応じて読み込ませることが可能です。

CLAUDE.local.md と .claude/rules/ — 個人設定とルール分割

CLAUDE.local.md — 個人専用の設定ファイル

チームでプロジェクトを共有する際、自分だけのローカル開発環境の設定や個人的な好みを記述したい場合があります。そのような情報をCLAUDE.mdに書いてしまうと、チーム全員に共有されてしまいます。

CLAUDE.local.md は、.gitignoreに追加して個人専用の設定ファイルとして使います。ローカル開発サーバーのポート番号、テスト用データベースのパス、個人的なメモなどを記述しましょう。

# 個人設定（このファイルはgitに含めない）

## ローカル開発
- 開発サーバー: localhost:1314
- テスト DB: ~/tmp/test.db

## 個人的な好み
- 日本語でコミュニケーションする

.claude/rules/ — パス固有のルール分割

.claude/rules/ ディレクトリを使うと、特定のファイルパスに対してのみ適用されるルールを定義できます。YAMLフロントマターのpathsフィールドでglobパターンを指定すると、該当ファイルを編集する時だけそのルールが自動的に読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール
- すべての API エンドポイントは入力検証を含める
- エラーレスポンスは標準フォーマットを使用
- OpenAPI ドキュメントコメント必須

この例では、src/api/ 配下のTypeScriptファイルを編集する時だけ、API開発ルールが読み込まれます。フロントエンドのコードを触っている時にはこのルールは適用されません。

Skills（スキル） — 専門家のマニュアル

スキルは、SKILL.mdファイルで定義する「専門知識パッケージ」です。CLAUDE.mdが「常に意識するルール」であるのに対し、スキルは「必要な時だけ読み込まれるマニュアル」として機能します。

スキルの特徴

• /skill-name のようなスラッシュコマンドとして実行可能
• Claudeが文脈に応じて自動で使うことも可能
• コンテキストウィンドウの節約に直結（必要時のみ読み込み）
• 動的コンテキスト（シェルコマンド結果の埋め込み）に対応

配置場所

• ~/.claude/skills/<name>/SKILL.md — ユーザー全体で使えるスキル
• .claude/skills/<name>/SKILL.md — プロジェクト固有のスキル

YAMLフロントマター

SKILL.mdの先頭にYAMLフロントマターを記述することで、スキルの動作を詳細に制御できます。

フィールド	説明
name	（必須）スラッシュコマンド名（/name で呼び出し）
description	（推奨）Claudeが自動起動を判断する説明。250文字以内が推奨
disable-model-invocation	true でClaude自動実行を禁止（手動呼び出しのみ）
paths	対象ファイルパターン（globで指定、マッチ時のみ自動起動）
allowed-tools	このスキルが使えるツールを制限
model	使用するモデルを指定
context	fork でサブエージェントとして分離実行

基本的なSKILL.mdの例

---
name: deploy-checker
description: デプロイ前のチェックリストを実行するスキル
---

# デプロイ前チェック

以下の項目を順番に確認してください:

1. テストが全件パスしているか確認
2. lint エラーがないか確認
3. 環境変数が正しく設定されているか
4. マイグレーションが最新か
5. git stash で未コミット変更がないか確認

動的コンテキストの活用

!`command` 構文を使うと、シェルコマンドの実行結果をスキル内に埋め込むことができます。

---
name: pr-review
description: PRの差分を読んで改善点を提案
---

## PRコンテキスト
- 差分: !`gh pr diff`
- コメント: !`gh pr view --comments`

## タスク
上記のPR差分をレビューして改善点を提案してください。

スキルが実行されるタイミングで、gh pr diff と gh pr view --comments の結果が自動的に埋め込まれ、Claudeに渡されます。

引数置換

スキルを/skill-name arg1 arg2のように引数付きで呼び出した場合、$ARGUMENTS（全引数）や $0, $1（個別引数）で展開できます。

settings.json — 権限・環境・ツールの制御盤

settings.jsonは、Claude Codeアプリケーションの動作をJSONで定義する設定ファイルです。CLAUDE.mdとは役割が異なります。CLAUDE.mdが「Claudeへの自然言語の指示」であるのに対し、settings.jsonは「アプリケーションの動作制御」を担当します。

配置場所とスコープ

1. ~/.claude/settings.json — ユーザー全体に適用される設定
2. .claude/settings.json — プロジェクト共有設定（git管理）
3. .claude/settings.local.json — プロジェクト個人設定（gitignore推奨）
4. マネージド設定 — 組織全体に適用される設定（IT管理）

主要設定項目

permissions — ツールの許可・禁止

permissionsでは、Claudeが実行できるツール操作を制御します。パターンマッチで柔軟に指定できます。

• allow: 自動許可するツール操作（例: Bash(npm run *)）
• deny: 禁止する操作（allowより常に優先、例: Read(./.env)）

permissions.defaultMode — 権限モード

• auto: 許可リストのツールは自動実行、未指定は確認
• plan: すべての操作を計画モードで実行（確認必須）
• bypassPermissions: すべてのツールを自動実行（開発用、本番非推奨）

コード例: プロジェクトの設定

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(**/*.ts)",
      "Read(**/*.js)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)"
    ]
  },
  "model": "claude-sonnet-4-5-20250929",
  "env": {
    "NODE_ENV": "development"
  }
}

コード例: ユーザーの設定

{
  "permissions": {
    "defaultMode": "auto"
  },
  "model": "claude-opus-4-6",
  "autoMemoryEnabled": true
}

Hooks（フック） — イベント駆動の自動化

フックは、Claude Codeの特定のイベント発生時に自動実行される処理です。settings.jsonのhooksキーで定義します。ファイル保存後の自動フォーマットや、タスク完了時の通知など、手動では面倒な作業を自動化できます。

イベントタイプ一覧

• PreToolUse — ツール実行前（検証・ブロック用）
• PostToolUse — ツール実行後（フォーマット・通知等）
• Notification — 通知送信時
• Stop — Claude応答完了時
• SessionStart — セッション開始時

matcherによるフィルタリング

matcherを使うと、対象ツールを正規表現でフィルタリングできます。例えば"Edit|Write"とすれば、EditまたはWriteツール使用時のみフックが発火します。

コード例: ファイル保存後に自動Prettierフォーマット

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  }
}

コード例: デスクトップ通知（Windows）

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('Claudeが入力を待っています')\""
          }
        ]
      }
    ]
  }
}

MCPサーバー — 外部ツールとの接続

MCP（Model Context Protocol）は、Claude Codeに外部ツールの操作能力を追加する規格です。プラグインのような仕組みで、GitHub、Notion、Sentryなどのサービスと直接連携できます。

設定場所

• .mcp.json — プロジェクト共有設定
• ~/.claude.json — ユーザー個人設定

接続方式

http/sse（Webサービス型）: 外部APIサーバーに接続。GitHub MCP、Notion MCPなど。

stdio（ローカルプロセス型）: ローカルでプロセスを起動して通信。ファイルシステムMCPやカスタムツールなど。

コード例: .mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    }
  }
}

CLIで追加

claude mcp add --transport http github <URL>
claude mcp add --transport stdio filesystem -- npx -y @mcp/server-fs

設定の優先順位 — すべてが組み合わさるとき

Claude Codeの設定は多層的で、複数の場所に同じ種類の設定が存在できます。設定が衝突したとき、どれが優先されるのかを理解しておくことが重要です。

優先順位（上が高い）

1. マネージド設定 — 組織IT管理（最高優先度）
2. コマンドライン引数 — --model, --permission-mode（セッション限定）
3. ローカル設定 — settings.local.json, CLAUDE.local.md
4. プロジェクト設定 — settings.json, CLAUDE.md, .mcp.json
5. ユーザー設定 — ~/.claude/settings.json, ~/.claude/CLAUDE.md

重要な注意点

• permissions.deny は permissions.allow より常に優先
• CLAUDE.mdは結合方式 — 複数のCLAUDE.mdは上書きではなく結合されます。矛盾する指示を書くとClaudeが任意に選択するため注意

推奨構成例

プロジェクトルート/
├── CLAUDE.md                    # チーム共有ルール
├── CLAUDE.local.md              # 個人メモ（.gitignore）
├── .claude/
│   ├── settings.json            # チーム共有の権限設定
│   ├── settings.local.json      # 個人の権限設定
│   ├── skills/
│   │   ├── deploy/SKILL.md      # デプロイスキル
│   │   └── review/SKILL.md      # レビュースキル
│   └── rules/
│       ├── frontend.md          # フロントエンドルール
│       └── api.md               # APIルール
└── .mcp.json                    # MCP接続設定

まとめ

ここまで、Claude Codeの設定ファイル体系を詳しく見てきました。それぞれが異なる役割を持ち、組み合わさることで強力な開発環境を構築できます。

ファイル	役割	いつ読まれるか
CLAUDE.md	プロジェクトの指示書	毎セッション自動
CLAUDE.local.md	個人設定	毎セッション自動
.claude/rules/*.md	パス別ルール	対象ファイル操作時
SKILL.md	専門知識パッケージ	必要時 or 手動
settings.json	アプリ動作設定	常時
hooks	イベント自動処理	イベント発生時
.mcp.json	外部ツール接続	セッション開始時

段階的な導入のすすめ

すべてを一度に導入する必要はありません。以下の順序で段階的に拡張していくことをおすすめします。

1. まずCLAUDE.md — プロジェクトの基本ルールを定義
2. 繰り返し使う手順をスキル化 — デプロイ、テスト、レビューなど
3. 権限制御が必要ならsettings.json — セキュリティ重視のプロジェクト向け
4. 自動化したくなったらHooks — フォーマット、通知、検証など