CLAUDE.md の書き方ガイド：Claude Code をプロジェクトに馴染ませる設定ファイル

Claude Code を使い始めると、毎回同じことを説明しなければならないと感じることがあります。「このプロジェクトは TypeScript を使っている」「テストは Jest で書いている」「コミットメッセージは英語で書く」——そういった文脈を毎回伝えるのは手間がかかります。CLAUDE.md はそのような情報をあらかじめ記述しておくことで、Claude Code がプロジェクトの文脈を自動的に把握できるようにするファイルです。

Claude があなたのプロジェクトを記憶する方法 - Claude Code Docs

CLAUDE.md ファイルで Claude に永続的な指示を与え、自動メモリで Claude が自動的に学習を蓄積できるようにします。

docs.anthropic.com

CLAUDE.md とは

CLAUDE.md は Claude Code が会話を開始するたびに自動で読み込む Markdown ファイルです。プロジェクトのルートや ~/.claude/ など、複数の場所に配置でき、それぞれの役割が異なります。Claude Code はこれらを合算して読み込むため、共通ルールはグローバルに、プロジェクト固有のルールはローカルに書き分けることができます。

配置場所	適用範囲	主な用途
./CLAUDE.md	現在のプロジェクト	プロジェクト固有のルール・構成
~/.claude/CLAUDE.md	全プロジェクト共通	個人の好みや汎用ルール
./subdir/CLAUDE.md	サブディレクトリ以下	特定ディレクトリの補足情報

何を書くべきか

CLAUDE.md に書くべき内容は、「毎回会話で説明しなければならない情報」です。具体的には次のような内容が該当します。

プロジェクトの概要と技術スタック

使用している言語・フレームワーク・ライブラリを明記しておくと、Claude Code が適切な構文やライブラリを選んで回答しやすくなります。

## プロジェクト概要

- フロントエンド: Next.js 14 (App Router)、TypeScript
- バックエンド: Go 1.22、Gin フレームワーク
- データベース: PostgreSQL 16
- テスト: Jest（フロントエンド）、testify（バックエンド）

開発ルールやコーディング規約

コミットメッセージの書き方、ブランチ命名規則、コードスタイルなど、チーム固有のルールを書いておくと一貫した提案が得られます。

## 開発ルール

- コミットメッセージは英語で Conventional Commits 形式で書く
- ブランチ名は `feature/YYYY-MM-DD-slug` の形式にする
- インデントはスペース 2 つ

よく使うコマンド

ビルドやテスト、デプロイのコマンドを記載しておくと、Claude Code が適切なコマンドを提示しやすくなります。

## コマンド

- `npm run dev` — 開発サーバー起動
- `npm run test` — テスト実行
- `npm run build` — プロダクションビルド

注意事項・禁止事項

やってほしくない操作や気をつけてほしい点を書いておくことも重要です。たとえば「本番環境のデータベースへの接続情報をコードに含めない」「特定のライブラリは使わない」といった制約を明記しておくと、意図しない提案を防ぎやすくなります。

## 注意事項

- `console.log` をコードに残さない
- `any` 型の使用は避ける
- 外部ライブラリを追加する場合は先に相談する

どういう書き方が良いか

CLAUDE.md は長ければよいわけではなく、簡潔で読みやすい記述が効果的です。以下のポイントを押さえておくとより精度の高い提案が得られます。

ポイント	内容
箇条書きと見出しを活用する	Claude Code はファイルを上から読み込むため、構造化されていると重要な情報が伝わりやすいです。長い文章より箇条書きやテーブルで整理するほうが効果的に機能します。
具体的に書く	「TypeScript を使っている」より「TypeScript 5.4、strict モードで運用している」と書くほうが精度の高い回答につながります。曖昧な表現より、実際のバージョンや設定値を明記するのが良いです。
変化したら更新する	CLAUDE.md は一度書いたら終わりではなく、プロジェクトの変化に合わせて更新することが大切です。古い情報が残っていると誤った文脈を与えることになります。
長くなりすぎない	あまりに長い CLAUDE.md はかえって重要な情報が埋もれる原因になります。必須の情報に絞り込み、詳細な仕様書はリンクで参照する形にするとすっきりまとまります。

CLAUDE.md がある場合とない場合の挙動

CLAUDE.md がない状態でも Claude Code は動作しますが、プロジェクトの文脈を毎回自分で説明する必要があります。特にチーム開発では CLAUDE.md をリポジトリに含めておくことで、新しいメンバーがすぐに Claude Code を使いこなせる状態になるというメリットもあります。

CLAUDE.md なし	CLAUDE.md あり
使用言語やフレームワークをコードを読んで推測する	会話の冒頭から文脈を把握した状態でやり取りが始まる
プロジェクト固有のルールを知らないため、汎用的な提案になりやすい	コーディング規約やコマンドを踏まえた具体的な提案が得られる
毎回「このプロジェクトでは〇〇を使っています」と説明する手間が生じる	「〇〇は使わないでほしい」という制約が自然に守られる
同じ指示を繰り返すうちに会話のコンテキストが埋まりやすくなる	チームで共有すれば、メンバー全員が同じ文脈で使えるようになる

CLAUDE.md のサンプル

ここまでの内容を踏まえた、CLAUDE.md の記述例を示します。実際のプロジェクトに合わせて内容を書き換えてみましょう。

## プロジェクト概要

Next.js 14 (App Router) + TypeScript のフロントエンドと、Go 1.22 + Gin のバックエンドで構成されています。

## 技術スタック

- フロントエンド: Next.js 14 (App Router)、TypeScript 5.4（strict モード）
- バックエンド: Go 1.22、Gin フレームワーク
- データベース: PostgreSQL 16
- テスト: Jest（フロントエンド）、testify（バックエンド）

## コマンド

- `npm run dev` — 開発サーバー起動
- `npm run test` — フロントエンドテスト実行
- `go test ./...` — バックエンドテスト実行
- `npm run build` — プロダクションビルド

## 開発ルール

- コミットメッセージは英語で Conventional Commits 形式で書く（例: `feat: add user profile page`）
- ブランチ名は `feature/YYYY-MM-DD-slug` の形式にする
- `any` 型の使用は避ける
- 外部ライブラリを追加する場合は先に相談する

まとめ

• CLAUDE.md は Claude Code が自動で読み込む設定ファイルで、会話ごとにプロジェクトの文脈を共有できる
• プロジェクトの技術スタック・開発ルール・よく使うコマンド・注意事項を書いておくのが効果的
• 長い文章より箇条書きと見出しで構造化し、具体的に記述するほうが精度が上がる
• CLAUDE.md がないと毎回同じ説明が必要になるが、あれば最初から文脈を踏まえた提案が得られる
• プロジェクトの変化に合わせて定期的に更新することが大切