この記事の目次
CLAUDE.mdとは何を書くファイルなのか
CLAUDE.mdは、Claude Code（Anthropicが提供するコーディング支援ツール）を起動したときに自動で読み込まれる、プロジェクト固有の指示書だ。人間が読むためのREADMEや、実装の細部を補足するコードコメントとは役割が異なる。README は初めてリポジトリを開いた人への説明が中心で、コードコメントは特定の処理の意図を補足するものだ。それに対してCLAUDE.mdは、AIがそのプロジェクトで作業するたびに前提として参照する、いわば作業指示書に近い。
そもそもClaude Code自体がどんなツールで何ができるかをまだ把握していない場合は、先にClaude Codeとは何かに目を通しておくと理解が早い。
書き始める前に決めておくこと
いきなり見出しを立てて書き始めると、後から構成を組み替える手間が増えやすい。先に「誰が読むファイルか」「何度も繰り返し伝えたいことは何か」の2点を整理しておこう。この2点さえ固まっていれば、見出しの決め方で悩む場面は少ない。読み手は人間ではなくAIなので、行間を読ませる書き方よりも、明文化した指示のほうが伝わりやすい。
なお、「どこまで自動で作業させてよいか」という権限の範囲や、「社外秘の情報をどこまで扱わせてよいか」という情報の取り扱いといった判断軸は、この記事では扱わない。これらは書き方の技術というより運用ルールの設計にあたるため、Claude Codeの運用ルールの決め方で個別に整理している。CLAUDE.mdを書く前にこの判断軸を一度決めておくと、後述の「やってよいこと／やってはいけないこと」の欄も書きやすくなる。
CLAUDE.mdの基本構成（見出しテンプレート）
以下は、多くのプロジェクトに応用しやすい見出し構成の一例だ。そのままコピーして、各項目を自分のプロジェクトの内容に置き換えて使える。
# プロジェクト概要
（プロジェクトの目的、技術構成、主なディレクトリ構造を簡潔に）
# コーディング規約・スタイル
（インデント、命名規則、ファイル分割の方針など）
# よく使うコマンド
（ビルド、テスト、起動などのコマンド）
# やってよいこと／やってはいけないこと
（このプロジェクトで許可する作業範囲、禁止する作業範囲）
# 参照してほしい外部情報・ファイル
（設計資料や関連ドキュメントのパス）プロジェクト概要
何のためのプロジェクトか、使っている主要な技術、ディレクトリの大まかな構造など、AIが文脈をつかむための最小限の情報を書く。詳細な仕様まで書き込む必要はなく、作業の前提を短時間で理解できる粒度で十分だ。
コーディング規約・スタイル
インデントの幅、変数や関数の命名規則、ファイルの分け方といった、そのプロジェクト固有の書き方の癖を明文化する。一般的なベストプラクティスと違う選択をしている場合ほど、書いておく価値がある。
よく使うコマンド
ビルド、テスト、起動など、開発の中で繰り返し使うコマンドを列挙しておく。コマンドが一覧になっていれば、AIは作業のたびに推測したり聞き返したりせずに済む。
やってよいこと／やってはいけないこと
この見出しの役割は、AIが自己判断で作業範囲の外まで進めてしまう事態を防ぐための宣言枠を用意することにある。許可する範囲と禁止する範囲は、それぞれ箇条書きで具体的に書き出しておこう。AIが判断に迷ったとき、この記述が拠り所になる。
参照してほしい外部情報・ファイル
設計資料や仕様書、別リポジトリの関連ファイルなど、AIに追加で読んでほしいものがあれば、そのファイルパスをここに書いておく。パスはプロジェクトのルートを基準にした相対パスで書くのが基本だ。
書き方のコツ（伝わる指示・伝わらない指示）
同じ意図を伝えるつもりでも、書き方次第でAIの解釈は変わる。たとえば「きれいに書いて」という指示は、何を基準に「きれい」と判断するかが読み手に委ねられてしまう。一方で「関数は20行以内に収める」「条件分岐は早期returnで浅くする」のように具体的な基準を書けば、解釈のぶれが小さくなる。
実務で意識しておきたい点をいくつか挙げる。
- 命令形で簡潔に書く。説明文よりも指示文のほうが誤読されにくい
- 優先順位が高い項目ほど上のほうに置く。長いファイルほど後半は読み飛ばされやすくなる
- 1項目を長文にしない。一文一意識で、箇条書きを積極的に使う
- 抽象語（「適切に」「柔軟に」など）を使う場合は、具体例を一つ添える
育てていくCLAUDE.md
CLAUDE.mdは一度書いて完成させるものではない。実際に使ってみて、AIの認識がずれた場面や、意図しない動きをした場面に気づくたびに、その原因を一行加えて補っていく運用が現実的だ。初版から完璧な内容を目指す必要はなく、むしろ最小限の骨格から始めて、使いながら育てるほうが手戻りが少ない。
更新を忘れないためには、見直しのタイミングをあらかじめ決めておくのが有効だ。簡単なチェックリストとして次のような項目を使える。
- 直近の作業で、指示していないのに想定外の変更をされた箇所はないか
- 毎回同じ説明を繰り返している内容はないか（あればCLAUDE.mdに移す候補）
- コマンドやディレクトリ構成が変わったのに、記載が古いままの箇所はないか
まとめ
CLAUDE.mdは、書き終えた時点がゴールではなく、書きながら判断軸や運用ルールを整えていく性質のドキュメントだ。まずは本記事のテンプレートを土台に、自分のプロジェクト用の雛形を一度書いてみるところから始めるとよい。権限の範囲や情報の扱いで迷ったらClaude Codeの運用ルールの決め方を参照し、自分のプロジェクトに合わせた設計を誰かと相談しながら詰めたい場合はコーチングの相談窓口も選択肢になる。