.claude/ フォルダはClaude Codeの「司令塔」
Claude Codeを使っているエンジニアの多くは、プロジェクトルートに自動生成される .claude/ フォルダを「なんとなく存在は知っているが、中身は謎」として放置していることが多い。しかしこのフォルダこそ、Claudeの振る舞いを細かくコントロールする設定の中枢だ。指示内容・カスタムコマンド・パーミッションルール、さらにはセッションをまたいだClaudeの記憶までがここに集約されている。
実は2つある .claude/ ディレクトリ
まず押さえておきたいのは、.claude/ ディレクトリが2か所に存在するという点だ。
- プロジェクト直下の
.claude/— チーム共有の設定。gitにコミットすることで、メンバー全員が同じルール・コマンド・ポリシーを共有できる。 - ホームディレクトリの
~/.claude/— 個人設定とマシンローカルの状態管理（セッション履歴・自動メモリなど）。
この2層構造を意識することが、Claude Codeを使いこなす第一歩となる。
最重要ファイル CLAUDE.md
.claude/ の中核をなすのが CLAUDE.md だ。Claude Codeはセッション開始時にこのファイルを真っ先に読み込み、システムプロンプトとして会話全体に反映させる。端的に言えば、CLAUDE.md に書いたことはClaudeが忠実に従う。
「実装前に必ずテストを書く」「エラー処理には console.log ではなく自社のカスタムロガーを使う」といったルールを記載すれば、以降のセッションで一貫して適用される。
CLAUDE.md はプロジェクトルートだけでなく、~/.claude/CLAUDE.md（全プロジェクト共通のグローバル設定）やサブディレクトリ内（フォルダ固有のルール）にも置くことができ、Claudeはそれらをすべて読み込んで統合する。
CLAUDE.md に書くべきこと・書かないこと
書くべき内容:
- ビルド・テスト・Lintコマンド（
npm run testなど） - アーキテクチャ上の重要な決定事項（「モノレポにTurborepoを採用」など）
- 非自明な注意事項（「TypeScriptのstrict modeが有効で未使用変数はエラー」など）
- インポート規約・命名規則・エラー処理スタイル
- 主要モジュールのファイル・フォルダ構成
書かないこと:
- LinterやFormatterの設定ファイルに書くべき内容
- リンクで参照できる既存ドキュメントの全文
- 理論の説明に終始する長い段落
特に重要なのがファイルサイズだ。CLAUDE.md は200行以内に抑えることが推奨される。それ以上長くなるとコンテキストを過剰に消費し、Claudeの指示遵守率が実際に低下するという。
カスタムコマンド・パーミッション管理も .claude/ で
CLAUDE.md 以外にも、.claude/ フォルダにはカスタムコマンド（スラッシュコマンド）の定義や、ファイル操作・外部ツール実行などの権限ポリシーも格納できる。チームの開発フローに合わせたコマンドを定義しておくことで、繰り返し発生する作業を効率化できる。
日本のチーム開発への示唆
日本のソフトウェア開発現場では、コーディング規約や開発フローをWikiやREADMEに分散して管理しているケースが多い。CLAUDE.md を「AIへの指示書」として整備することで、規約の形骸化を防ぎつつAIアシスタントを即戦力として活用できる環境が整う。特にリモートチームや複数人開発において、Claudeの振る舞いを統一できる点は大きなメリットだ。
.claude/ フォルダをブラックボックスとして放置するのをやめ、チームのナレッジを凝縮した「AIとの契約書」として積極的に活用したい。