CLAUDE.mdの書き方｜AIに文脈を伝える設計書の作り方

はじめに

Claudeとの対話を効率化するには、プロジェクトの全体像をAIに正確に伝える必要があります。その鍵となるのがCLAUDE.mdです。このファイルはプロジェクトルートに配置して、技術スタック・開発ルール・ディレクトリ構成をAIが即座に理解できる形で記述する設計書です。毎回プロンプトで説明する手間が減り、AIも一貫性のあるコードを書くようになります。

CLAUDE.mdの役割

CLAUDE.mdは単なるREADMEではなく、AIエージェント向けのコンテキスト仕様書です。自分が感じるのは、これがあるとないとでAIの出力品質が大きく変わるということです。

プロジェクトの技術スタックをここで一元管理することで、AIが古いAPIを使う罠を防ぎます。コーディング規約や命名規則を明記することで、AIがプロジェクトのコード風に合わせて実装できます。ディレクトリ構造を示すことで、ファイルを追加する時に「あ、このファイルはここに置くべきなんだな」とAIが判断できるわけです。デプロイ環境や依存関係の制約、禁止事項なども記載することで、プロジェクト固有のルールをAIに周知させます。

書くべき主要セクション

1. プロジェクト概要

プロジェクト名、目的、対象ユーザーを簡潔に書きます。AIがスコープを把握するために必須です。ここで「何を作るのか」が曖昧だと、AIの提案がズレていきます。

2. 技術スタック

使用言語・フレームワーク・ライブラリのバージョンを明記することが肝心です。バージョンを書いておくことで、APIが変わった新しい書き方をAIが勝手に使ってしまうのを防げます。

3. ディレクトリ構成

ツリー形式でディレクトリ階層を示し、各ディレクトリが何の役割なのか説明しておきます。AIがファイルを追加する際に正しい場所を選べるようになります。

4. 開発ルール

命名規則（camelCase / snake_case / PascalCase）、インデントやフォーマットの設定、ESLintやPrettierなどの使い方、エラーハンドリングの方針を記載します。統一感のあるコードが出来上がります。

5. 禁止事項

使用してはいけないライブラリ、避けるべき実装パターン、環境変数に関する注意事項を明示します。ここでセキュリティの落とし穴を指摘しておくことで、AIがやらかしてくれる心配が減ります。

効果的なテンプレート例

以下は実運用に即したテンプレートです。プロジェクトに合わせてカスタマイズしてください。

# CLAUDE.md - Project Context

## プロジェクト概要

**プロジェクト名:** E-commerce API Platform
**目的:** 複数ストアの商品・注文管理をするマイクロサービス型API
**主要ユーザー:** ストア運営者、開発者パートナー

## 技術スタック