CLAUDE.mdの役割と書き方の基本

この章で学ぶこと

CLAUDE.mdというファイルをプロジェクトに置くことで、Claude Codeがそのプロジェクトの前提を自動的に理解した状態で作業を始められることを学びます。基本的な記述項目と、簡単な記述例を通じて、CLAUDE.mdの役割を理解することを目指します。

CLAUDE.mdとは何か

CLAUDE.mdは、プロジェクトのルートディレクトリなどに配置しておくと、Claude Codeがそのプロジェクトを扱う際に自動的に読み込むMarkdownファイルです。会話の最初に読み込まれ、以降のやり取りの前提となる「永続的なコンテキスト」として機能します。

CLAUDE.mdがない状態でAIに作業を依頼すると、プロジェクトの構成や規約を毎回説明し直す必要があります。たとえば「このプロジェクトはReactとTypeScriptを使っている」「関数名はキャメルケースで書く」といった情報を、依頼のたびに伝えなければなりません。

CLAUDE.mdにこれらの情報をあらかじめ書いておけば、AIはその内容を踏まえた状態で作業を開始できます。結果として、指示文が短く済むだけでなく、プロジェクトの前提から外れた提案や、規約に反したコードが生成されるリスクも減らせます。

何を書くべきか（基本レベル）

CLAUDE.mdに書く内容に厳密な決まりはありませんが、基本的には次のような項目を含めておくと効果的です。

• プロジェクトの概要: どのようなサービス・アプリケーションで、何を目的としているか
• 技術スタックや主要なディレクトリ構成: 使用している言語・フレームワーク、主要なフォルダの役割
• コーディング規約: 命名規則、フォーマットルール、コメントの書き方など
• 開発・ビルド・テストの実行コマンド: npm run dev や npm test など、日常的に使うコマンド
• 注意事項: 触ってはいけないファイル、特殊な運用ルール、外部サービスとの連携時の制約など

これらはすべてを完璧に書く必要はありません。まずは「毎回説明し直すのが面倒な情報」を中心に書き出していくとよいでしょう。

具体的な記述例

簡単なWebアプリケーションを想定したCLAUDE.mdの例を示します。

CLAUDE.md

## プロジェクト概要
社内向けの経費精算アプリケーション。従業員が経費を申請し、
上長が承認するワークフローを提供する。

## 技術スタック
- フロントエンド: React + TypeScript
- バックエンド: Node.js (Express)
- データベース: PostgreSQL
- 主要ディレクトリ:
  - src/components: UIコンポーネント
  - src/api: APIエンドポイント
  - src/db: データベース関連の処理

## コーディング規約
- 変数・関数名はキャメルケース、コンポーネント名はパスカルケース
- インデントはスペース2つ
- コンポーネントは1ファイル1コンポーネントとする

## 開発コマンド
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
- ビルド: `npm run build`

## 注意事項
- `src/db/migrations` 配下のファイルは直接編集せず、
  マイグレーションコマンドを通じて生成する

このように、プロジェクトの前提を簡潔にまとめておくだけで、AIとのやり取りの精度が大きく変わります。なお、大規模なプロジェクトでCLAUDE.mdをどのように設計・運用していくかについては、第4章で改めて詳しく扱います。

次のレッスンでは、実際にCLAUDE.mdを用意した状態で、はじめてのタスクをAIに依頼する演習に取り組みます。