CLAUDE.md設計パターン集|プロジェクト規模別に使い分けるテンプレート活用術

「毎回同じことをClaudeに説明している」と感じていませんか

Claude Codeを使っていて、プロジェクトのルールやコマンドを毎回チャットで説明し直すのが地味に手間だと感じたことはないでしょうか。特に複数のプロジェクトを掛け持ちしていると、「このプロジェクトのビルドコマンドは何だっけ」「コーディング規約はどこまで伝えたっけ」と、同じ説明を繰り返すことになりがちです。

この手間を解消してくれるのが、プロジェクトのルートなどに置くCLAUDE.mdです。Claude Codeが自動的に参照する設定ファイルで、ここに書いた内容がセッションの前提知識として使われます。

この記事でできるようになること

この記事では、CLAUDE.mdをプロジェクトの規模に応じて書き分ける考え方を、実際に手を動かせる手順に落とし込んで紹介します。個人の小さなスクリプトから、チームで運用する中規模リポジトリ、さらに複数モジュールを抱える大規模プロジェクトまで、それぞれに合った書き方の型を持っておくと、CLAUDE.mdの作成・見直しにかかる時間がぐっと減ります。

大事なのは「情報を詰め込む」ことではなく、規模に応じて必要な情報だけを残すことです。

ステップ1：プロジェクトの規模を3段階に分類する

まず、今扱っているプロジェクトがどの規模に近いかを大まかに分類します。

• 小規模：個人開発、検証用スクリプト、ファイル数十個程度
• 中規模：チームで運用するアプリ、複数人がPRを出すリポジトリ
• 大規模：複数サービス・モジュールが連携するプロダクト、社内標準がある組織

この分類自体に厳密な基準はありません。感覚で構わないので、まずは「今のプロジェクトはどれに近いか」を決めてしまいましょう。ここで悩みすぎるとテンプレート作りが進まないので、ざっくりで大丈夫です。

ステップ2：小規模プロジェクト用の型を作る

個人開発や検証段階のプロジェクトでは、CLAUDE.mdに書く内容は最小限にとどめます。

• 使用言語・フレームワーク
• ビルド・テストの実行コマンド
• 「これだけは守ってほしい」という最重要ルール1〜2個

欲張って詳細な設計方針まで書き込みたくなりますが、小規模プロジェクトは変化が速いので、書いた内容がすぐ古くなってしまいます。最初は本当に短くて構いません。数行のメモ程度から始めて、必要に応じて育てていく感覚で十分です。

ステップ3：中規模プロジェクト用の型を作る

チームで運用するリポジトリになると、個人開発と同じ書き方では情報が足りなくなります。ここでは以下の項目を意識して追加します。

• ディレクトリ構成の簡単な説明
• コーディング規約（命名規則、フォーマッタの有無など）
• レビュー・PRの運用ルール
• よく使うコマンド一覧（開発サーバー起動、Lint、テストなど）

ここで正直に言うと、コーディング規約をどこまで細かく書くかは毎回悩むポイントです。細かすぎるとメンテナンスが追いつかず、粗すぎると効果が薄い。まずは「レビューで毎回指摘されること」だけを書き出すところから始めるのがおすすめです。

ステップ4：大規模プロジェクト用の型を作る

複数モジュールが連携するような大規模プロダクトでは、1つのCLAUDE.mdにすべてを詰め込むと逆に読みにくくなります。この規模では、プロジェクトルートのCLAUDE.mdを「全体の地図」として簡潔に保ち、モジュールごとの詳細は各サブディレクトリ側に分けて置くという考え方が有効です。

• ルート：全体アーキテクチャの概要、共通ルール、関連ドキュメントへの導線
• 各モジュール：そのモジュール固有のコマンドや注意点

階層を分けて書くことで、Claudeが今作業している範囲に関係のある情報だけを参照しやすくなります。これは正直、最初は少し面倒に感じる作業です。ただ一度型を作ってしまえば、新しいモジュールを追加するたびに同じフォーマットを複製するだけで済むようになります。

ステップ5：テンプレートを使い回す仕組みを作る

規模別に3つの型ができたら、それぞれをテンプレートファイルとして手元に保存しておきましょう。新しいプロジェクトを始めるたびに、該当する型をコピーして中身を埋めるだけにすると、CLAUDE.mdの作成にかかる時間が大幅に短縮できます。

つまずきやすいポイントと対処

• 書きすぎてしまう：情報を盛り込むほど良いと思いがちですが、古くなった情報が残ると逆に誤解を生みます。定期的に見直す前提で、最初は短めに書くのが安全です。
• チームで温度差が出る：CLAUDE.mdを誰が更新するか決めていないと、放置されがちです。PRのテンプレートに「CLAUDE.mdの更新が必要か」のチェック項目を入れておくと運用が回りやすくなります。
• 規模の変化に追いつかない：小規模で始めたプロジェクトが育ってきたら、中規模用の型に書き換えるタイミングを意識しておくと良いのではないでしょうか。

まとめ

CLAUDE.mdは、書けば書くほど良いというものではなく、プロジェクトの規模に合わせて必要な情報量を見極めることが継続的な運用のコツです。まずは今関わっているプロジェクトがどの規模に近いかを判断し、小規模・中規模・大規模のいずれかの型から手をつけてみてください。最初から完璧な型を作る必要はなく、使いながら育てていく感覚で十分だと思います。