【徹底解剖】謎の「.claude/」フォルダの中身はどうなってる？その内部構造を読み解く

この記事では、AnthropicのClaude関連ツールやプロジェクトで使用される「.claude/」フォルダの内部構造について解説しています。中身は空ですが、一般的にこのディレクトリは、プロジェクト固有の設定、MCP（Model Context Protocol）の構成ファイル、ローカルのコンテキスト情報など、Claudeがプロジェクトを理解するための重要なメタデータが格納される場所です。エンジニアなら知っておきたい、その「解剖図（Anatomy）」を深掘りします。

エージェントコーディングを試すのに、越えなきゃいけない「人工的な壁」を勝手に作っちゃってる人を最近よく見かける。それは全く正しい始め方じゃない。まずはまっさらな.claude、空のAGENTS.md、スキルもMCPもゼロの状態から始めて、まずはそのツール自体の動かし方を学ぶべき。

状況に応じてClaude、Codex、Cursor、Opencodeを簡単に切り替えられるように、すべてのモデルプロバイダーが標準のファイル構成に統一してくれればいいのにね。

Claude Fastに、これについてのすごく良い代替ドキュメントがあるよ。[0] .claude/を定義することに、なんでそんなに否定的な意見があるのか理解できないな。メインのエージェントにファイルを書かせるのはかなり簡単だし。ワンショットでコーディングするんじゃなくて、.claude/を素早くアップデートしながらイテレーションを回していくんだ。僕は今、.claude/が自分自身のコピーを作って、タスクを実行し、評価して自己更新するっていう段階まで来てる。コードを書いてるんじゃなくて、他のすべてをやってくれる.claude/をコーディングしてる感じ。これは.claudeやエージェント、指示をテストする仕組みにもなるし、組織内での共有や再利用にも役立つと思う。[0] https://claudefa.st/blog/guide/mechanics/claude-md-mastery

みんなが話してない本当の障壁は、Claudeにどのファイルを更新させることもできるけど、もしそれが.claude/INSTRUCTIONS.mdやCLAUDE.mdなら、Claudeにそのファイルを「読み直す」ように伝えないといけないってこと。内容は書き込めても、それを最新の指示として扱ってくれるわけじゃない。最後にそのファイルを読み込んだ時の状態のまま動いちゃうから、もし元々存在しなかったら、ファイルがあることすら認識しないんだ。Claudeはそういう指示をコンテキストウィンドウのかなり特定の場所に配置してるんだと思うよ。

いいね！記事には書かれてないけど、プランモードで実行しているときは ~/.claude/plans にプランのmdファイルが保存される。そのディレクトリからプランを開いたりバックアップしたりできるから便利だよ。

これ、なんとなく経験に基づいたものじゃなくてAI生成っぽい感じがするな。Claude.mdは短くあるべき。Typescriptのstrictモードは別にハマりポイントじゃないし、モデルなら自分で簡単に判断できるから、そういうのは省いちゃっていい。みんなClaudeに詰め込みすぎだよ、数行の指示とドキュメントへのリンクがあれば十分。代わりに@Agents.mdを使って全部そこにまとめることもできる。コマンドよりスキルのほうが優先されるんじゃない？サブエージェントは、モデル指定やメモリのフォーク、スキルの紐付けとかをやるなら特に有効だね。Claudeが空回りしてるのを見たら、何を最適化できるか考えて、それをエンコードする（あるいはスクリプトやコードをリファクタリングする）のを忘れないこと。プランと実装は常に分けて、その間でコンテキストをクリアにするのが大事。経験上、コンテキストが溜まりすぎると精度が落ちるからね。

AIエージェントの「ツールキット」作りって、ブログを読んだりYouTubeで生産性向上動画を見たりして習慣や儀式を作ることに時間を費やす「完璧な生産性セットアップ」の追求に似てきてる気がする。結局、紙のToDoリストで淡々とタスクをこなす人に追い抜かれちゃうんだよね。僕の経験では、普通のClaudeにプランを書かせて、レビューして、実行させるのが今でも一番うまくいく。

僕は最近、グローバルに設定されたMCPサーバーとCopilotを使った複合エージェントをメインに使っていて、ほとんどの場合は自分でMCPサーバーを作っちゃってる。あとは、限定されたツールとサブエージェントのセットを与えて、どうやって達成するかをエージェント自身に考えさせるだけ。これが驚くほど上手くいくんだ。だって.agent.mdなんて、利用可能なツールの説明に過ぎないからね。複雑なものも、大袈裟な指示もいらない。「君が持ってるのはこれだよ」って伝えるだけで十分。サブエージェントに権限委譲できるようになれば、ワークフローは勝手に回る。特定のビルドシステムを扱ってる？それ用のMCPサーバーを「バイブスで」さっと書けばいい。自分のツールを作ってる？開発テスト用、そして後でエージェントが使う用のMCPサーバーを用意する。逆に、スキルや使い回しのプロンプトにどれだけの価値があるかは疑問かな。建築家が開発者と話すときに、数週間前の自分の録音を流してるようなものだよ。モデルはすでに十分な知識を持ってるんだから、今はしつこく指示するより、方向付けをしてあげるだけでいい。

こういう投稿をよく見かけるけど、個人的に一番面白いと思うのはこれ。スキルや余計な設定を最小限にしたときが一番結果が良いんだよね。みんなドキュメントで指示を詰め込みすぎてる。AIは有能だけど神経質な大人みたいなもので、情報を与えれば与えるほどバカになっちゃうんだよ。

~/.claude/projectsこそが、本当の楽しみがある場所だね :)