.claude フォルダの解剖：何をするのか、なぜ混乱するのか - Toolsify AI Blog

「.claude フォルダの構造」を検索したということは、このフォルダが実際に何をするのか、なぜ混乱を招くのか、どの部分に注目すべきかを知りたいということでしょう。

2026年3月のRedditスレッドで、はっきりと説明されました。配置規則が不明確でトラブルを経験した開発者が、.claude/ディレクトリレイアウト、フックイベント、settings.json、MCP設定、スキル構造、コンテキスト管理の閾値をまとめたチートシートを作成しました。

核心的な混乱：グローバル vs プロジェクトレベル

最大の混乱源は、グローバルディレクトリ ~/.claude とプロジェクトレベルのディレクトリ .claude/ の違いです。

グローバルディレクトリはホームフォルダにあり、すべてのプロジェクトに共通する動作を定義します。プロジェクトレベルの .claude/ は特定のリポジトリ内にあり、グローバル設定を上書きまたは拡張します。

スキルは .claude/skills/ に置きます。各スキルにはSKILL.mdファイルを含む専用ディレクトリがあります。

エージェントは .claude/agents/ に置きます。トップレベルにバラバラのファイルを置かないでください。

設定はプロジェクトレベルでは .claude/settings.json、グローバルでは ~/.claude/settings.json にあります。

最も一般的な間違いは、マッチャーの範囲が狭すぎることです。PostToolUseフックが「Write」のみにマッチすると、「Edit」や「MultiEdit」による変更を見逃します。「Edit|MultiEdit|Write」という広いマッチャーパターンの方が多くのケースを捕捉できます。

1. スコープ — グローバル vs プロジェクトレベルが最初の判断です。

2. 配置規則 — スキルにはSKILL.mdが必要、エージェントはagents/に置きます。

3. コンテンツ vs オーケストレーション — スキル、エージェント、設定、フック、MCP設定は同等の概念ではありません。

4. ドリフトの兆候 — ドキュメントは急速に変わります。設定が突然動かなくなったら、基盤となる規則が変わっていないか確認してください。

.claudeフォルダはスコープ、構造、動作を組み合わせたものです。この3層モデルを理解すれば、フォルダは隠された散らかりではなく、動作マップに見えてきます。