Claude Codeを使い始めると、プロジェクトのルートやホームディレクトリに .claude/ というフォルダが作られることに気づくと思います。このディレクトリには、Claude Codeの動作を細かくコントロールするための設定ファイルや拡張機能がすべて収められています。
本記事では .claude/ ディレクトリの全体構造を俯瞰したうえで、settings.json・Hooks・Agents・Skills・CLAUDE.md それぞれの役割と具体的な設定方法を丁寧に解説します。「なんとなく使っているけれど、正確な役割がわからない」という方や、「チーム開発でClaude Codeをもっと活用したい」という方にぴったりの内容です。
.claude/ディレクトリとは何か
.claude/ ディレクトリには グローバル（ユーザー全体） と プロジェクトローカル の2種類があります。
- ~/.claude/：ホームディレクトリに置かれ、すべてのプロジェクトに共通して適用されるグローバル設定
- ./.claude/：プロジェクトルートに置かれ、そのプロジェクト専用の設定。git で管理してチームと共有できる
主なファイル・フォルダは以下のとおりです。
| ファイル/フォルダ | 役割 | スコープ |
|---|---|---|
| CLAUDE.md | セッション全体に反映される指示・規約 | グローバル / プロジェクト |
| settings.json | 権限・ツール許可・Hooks・環境変数 | グローバル / プロジェクト |
| settings.local.json | 個人用ローカル設定（gitignore推奨） | プロジェクトのみ |
| agents/*.md | カスタムサブエージェントの定義 | グローバル / プロジェクト |
| skills/SKILL.md | スラッシュコマンドとして呼び出せるワークフロー | グローバル / プロジェクト |
| commands/*.md | シンプルなスラッシュコマンド定義 | グローバル / プロジェクト |
設定の優先度は「プロジェクト設定 > グローバル設定」であり、プロジェクト側の設定がグローバルを上書きします。さらに細かい優先順位は次のとおりです。
- managed（管理者デプロイ設定）
- コマンドライン引数（–allowedTools 等）
- .claude/settings.local.json（プロジェクト個人設定）
- .claude/settings.json（プロジェクト共有設定）
- ~/.claude/settings.json（グローバル設定）
CLAUDE.md：セッションを支配するルールファイル
CLAUDE.md はClaude Codeの設定ファイルのなかで最も重要なファイルです。セッション開始時にシステムプロンプトとして自動読み込みされ、記述した内容がセッション全体に渡って守られます。
CLAUDE.md に書くべき内容の例を示します。
# プロジェクト規約
## ビルド・テストコマンド
- ビルド: `npm run build`
- テスト: `npm test`
- リント: `npm run lint`
## コーディング規約
- インデント: スペース2つ
- 変数名: camelCase
- コンポーネント名: PascalCase
- コメントは日本語で記述する
## 禁止事項
- `console.log` をコミットに含めない
- `main` ブランチへの直接プッシュ禁止
## アーキテクチャのポイント
- 状態管理は Zustand を使用
- API通信は src/api/ ディレクトリに集約
- 型定義は src/types/ に置くCLAUDE.md は200行以内に収めることが推奨されています。それ以上長くなるとコンテキストを大量消費し、指示の遵守率が下がる傾向があります。常時適用が不要な内容はSkillsやAgentsに移しましょう。
CLAUDE.md は 複数階層 に配置できます。読み込み順序は以下のとおりです。
- ~/.claude/CLAUDE.md（グローバル・個人設定）
- ./CLAUDE.md（プロジェクトルート）
- ./src/CLAUDE.md など（サブディレクトリごとの上書き）
settings.jsonの設定とHooksのライフサイクル
settings.json はClaude Codeの動作を 構造的に制御 するための設定ファイルです。権限管理・環境変数・Hooksの定義など、幅広い設定を記述できます。
settings.jsonの権限設定（allowedTools / blockedTools）
ツールの使用可否はパーミッションルールで制御します。ルールは deny → ask → allow の順に評価され、deny が最優先です。
{
"permissions": {
"allow": [
"Bash(git:*)",
"Bash(npm run *)",
"Read(*)",
"Write(src/**)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl:*)"
]
},
"env": {
"NODE_ENV": "development",
"PROJECT_NAME": "my-app"
}
}権限ルールの種類は3種類あります。
| ルール | 動作 |
|---|---|
| allow | 確認なしでツールを自動実行 |
| ask | 実行前にユーザーへの確認プロンプトを表示 |
| deny | そのツールの使用を完全にブロック |
Hooksの設定方法と主要イベント
Hooks は セッションのライフサイクルイベントに連動してシェルスクリプトを自動実行 する仕組みです。AIの判断ではなく、確定的・決定論的に動作する点が特徴です。
主要なHookイベントを以下に示します。
| イベント | 発火タイミング | 用途例 |
|---|---|---|
| SessionStart | セッション開始時 | コンテキスト読み込み・環境変数設定 |
| UserPromptSubmit | プロンプト送信時 | 入力バリデーション・前処理 |
| PreToolUse | ツール実行前 | 危険操作のブロック・検証 |
| PermissionRequest | 権限リクエスト時 | 動的な権限評価 |
| PostToolUse | ツール実行成功後 | 自動テスト・コード整形 |
| PostToolUseFailure | ツール実行失敗後 | エラーログ・通知 |
| SessionEnd | セッション終了時 | 後処理・レポート生成 |
settings.json へのHooks設定例を示します。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash /home/user/.claude/hooks/validate-bash.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npm run lint --silent"
}
]
}
],
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session started at '$(date)"
}
]
}
]
}
}HookスクリプトからClaude Codeへの制御は 終了コード で行います。
- 終了コード 0：正常終了。ツール実行を続行
- 終了コード 2：ツール実行をブロック。stderrの内容がClaudeへのメッセージとして渡される
- その他：エラーとして扱われ、ユーザーへの警告が表示される
#!/bin/bash
# validate-bash.sh: rm -rf を含むコマンドをブロックする例
COMMAND=$(cat) # JSONからコマンドを読み取る
if echo "$COMMAND" | grep -q 'rm -rf'; then
echo "危険なコマンドが検出されました: rm -rf は禁止されています" >&2
exit 2 # コード2でブロック
fi
exit 0 # 問題なければ続行Agents（サブエージェント）の定義と呼び出し方
Agentsは 特定のタスクに特化したカスタムAIエージェント を定義する仕組みです。.claude/agents/ 配下にMarkdownファイルを置くだけで作成でき、@エージェント名 でメンション呼び出しができます。
エージェントファイルはYAML frontmatterとシステムプロンプト本文で構成されています。
---
name: security-reviewer
description: セキュリティレビューの専門エージェント。コードの脆弱性や認証の問題を検出するときに使用する。
tools:
- Read
- Bash
model: claude-opus-4-5
permissionMode: default
---
あなたはセキュリティの専門家です。提示されたコードに対して以下の観点でレビューを行ってください。
- SQLインジェクションの可能性
- XSS（クロスサイトスクリプティング）
- 認証・認可の不備
- 機密情報のハードコーディング
- 依存ライブラリの既知脆弱性
問題を発見した場合は、重大度（Critical / High / Medium / Low）とともに具体的な修正案を示してください。frontmatterで指定できる主要フィールドを以下に整理します。
| フィールド | 説明 | 例 |
|---|---|---|
| name | エージェントの識別名（@name で呼び出し） | security-reviewer |
| description | 用途の説明。Claudeが自動委任の判断に使用 | セキュリティレビューに使用する |
| tools | 使用を許可するツールのリスト | Read, Bash, Write |
| disallowedTools | 使用を禁止するツールのリスト | Bash |
| model | 使用するモデル（省略時はデフォルト） | claude-opus-4-5 |
| permissionMode | 権限モード（default / acceptEdits / bypassPermissions） | default |
| maxTurns | 最大ターン数の制限 | 10 |
frontmatterのbodyはユーザープロンプトではなく、システムプロンプトとして機能します。「ユーザーから指示する言葉」ではなく「エージェントの性格・役割・行動原則」を書くようにしましょう。ここが最も多い誤解のポイントです。
エージェントの呼び出し方は2種類あります。
- @メンション呼び出し：プロンプト内で
@security-reviewer このコードをレビューしてと入力する - 自動委任：descriptionフィールドの内容をもとに、Claudeが適切なエージェントを自動的に選択して委任する
Skills（スキル）でスラッシュコマンドを作る
Skillsは 繰り返し使うワークフローをスラッシュコマンドとして登録 する仕組みです。毎回同じプロンプトを打ち込む代わりに、/review のように短いコマンドで呼び出せます。Agentsが「専門家チーム」だとすれば、Skillsは「手順書マクロ」のようなイメージです。
Skillファイルの作成例を示します。
---
name: review
description: コードレビューを行うスキル。変更差分を確認してバグや改善点を指摘する。
---
以下の手順でコードレビューを実施してください。
1. `git diff HEAD` を実行して変更差分を確認する
2. 変更されたファイルを読み込む
3. 以下の観点で問題点を列挙する
- バグの可能性
- パフォーマンス上の懸念
- 可読性・保守性
- テストの充足度
4. 修正が必要な箇所には具体的な改善案を提示する
5. 全体を通した総評を最後に述べるこのファイルを .claude/skills/SKILL.md（または .claude/skills/review/SKILL.md）に保存すると、/review コマンドで呼び出せるようになります。
CLAUDE.md・Skills・Agentsの使い分け
3つのカスタマイズ手段をどう使い分けるか、一言でまとめると次のとおりです。
- CLAUDE.md：「毎セッション必ず守らせたいルール」を書く場所。常時有効な制約や規約に使う
- Skills：「必要なときだけ呼び出すワークフロー手順書」。/コマンド名で明示的に実行する
- Agents：「専門家に丸ごと委任するタスク」。@メンションまたは自動委任で呼び出す
実際のプロジェクトでの活用パターン例を示します。
- CLAUDE.md：コーディング規約・禁止コマンド・ビルド手順
- Skills：/deploy（デプロイ手順）、/review（コードレビュー）、/test（テスト実行フロー）
- Agents：@security-reviewer（セキュリティ審査）、@doc-writer（ドキュメント生成）、@test-engineer（テスト自動化）
プロジェクトでの.claude/推奨ディレクトリ構成
チーム開発を想定した .claude/ ディレクトリの推奨構成を示します。
.claude/
├── CLAUDE.md # プロジェクト規約（git管理 ✅）
├── settings.json # 権限・Hooks（git管理 ✅）
├── settings.local.json # 個人設定（.gitignoreに追加 🚫）
├── agents/
│ ├── security-reviewer.md
│ ├── doc-writer.md
│ └── test-engineer.md
├── skills/
│ ├── review/
│ │ └── SKILL.md
│ ├── deploy/
│ │ └── SKILL.md
│ └── test/
│ └── SKILL.md
└── hooks/
├── pre-tool-validate.sh
└── post-write-lint.shsettings.local.json は個人の実験的な設定や機密情報を含む可能性があるため、必ず .gitignore に追加することを推奨します。settings.json（プロジェクト共有）と settings.local.json（個人設定）を明確に分けて管理しましょう。
まとめ
Claude Codeの .claude/ ディレクトリは、単なる設定ファイルの置き場所ではなく、AIの動作を細粒度でコントロールするための強力な拡張基盤です。本記事で解説した内容を振り返ります。
- CLAUDE.md：全セッションに共通する規約・制約を記述。200行以内が推奨
- settings.json：ツール権限（allow/ask/deny）・環境変数・Hooksをまとめて設定
- Hooks：PreToolUse・PostToolUse・SessionStartなどのライフサイクルイベントにシェルスクリプトを紐付ける
- Agents：YAML frontmatter付きMarkdownで専門サブエージェントを定義。@メンションで呼び出す
- Skills：繰り返しワークフローをスラッシュコマンド化。/コマンド名で呼び出す
まずは CLAUDE.md にプロジェクトの規約を書くところから始め、慣れてきたら Settings・Hooks・Skills・Agentsへと段階的に活用範囲を広げていくことをおすすめします。
参考リソース
- 公式ドキュメント – Claude Code settings
- 公式ドキュメント – Configure permissions
- 公式ドキュメント – Hooks reference
- 公式ドキュメント – Create custom subagents
- 公式ドキュメント – Extend Claude with skills
- The Complete .claude Directory Guide for Claude Code [2026]
- Anatomy of the .claude/ Folder – Daily Dose of Data Science
- Claude Code Hooks: A Practical Guide to Workflow Automation – DataCamp
- Claude Code Custom Subagents: Complete Guide to @ Mention and Specialized Agent Teams
コメント