CLAUDE.md の書き方完全ガイド｜Claude Codeを最大限活用する
CLAUDE.md とは
CLAUDE.mdは、Claude Codeがプロジェクトを理解するためのガイドファイルです。プロジェクトのディレクトリ構造、技術スタック、コーディング規約、ワークフローなどを記述しておくと、Claude Codeがそれを読み込んでコンテキストとして活用します。
人間の開発者がプロジェクトに参加したとき、READMEや開発ガイドを読んでプロジェクトを理解するのと同じように、Claude CodeはCLAUDE.mdを参照してプロジェクト固有のルールに従った出力を行います。Claude Codeの基本的な使い方についてはClaude Code 使い方 完全ガイドをご覧ください。
CLAUDE.md を置く場所
CLAUDE.mdは複数の場所に配置でき、それぞれ異なるスコープで適用されます。
| ファイルパス | スコープ |
|---|---|
~/.claude/CLAUDE.md | グローバル（全プロジェクト共通） |
プロジェクトルート/CLAUDE.md | プロジェクト全体 |
サブディレクトリ/CLAUDE.md | 特定のディレクトリ以下 |
複数のCLAUDE.mdが存在する場合、すべてが読み込まれます。グローバル設定とプロジェクト固有の設定を組み合わせて使えます。
基本的な構成
効果的なCLAUDE.mdの構成例を紹介します。
# プロジェクト概要
ECサイトのバックエンドAPI。TypeScript + Hono + Drizzle ORM で構築。
# 技術スタック
- 言語: TypeScript (strict mode)
- ランタイム: Node.js 20
- フレームワーク: Hono
- ORM: Drizzle
- データベース: PostgreSQL
- テスト: Vitest
- パッケージマネージャー: pnpm
# ディレクトリ構造
- src/routes/ - APIルート定義
- src/services/ - ビジネスロジック
- src/db/ - データベース関連（スキーマ、マイグレーション）
- src/middleware/ - ミドルウェア
- src/utils/ - ユーティリティ関数
- tests/ - テストファイル
# コーディング規約
- 変数名・関数名: camelCase
- 型名・クラス名: PascalCase
- ファイル名: kebab-case
- インデント: スペース2つ
- セミコロン: なし
- 文字列: シングルクォート
# コマンド
- `pnpm dev` - 開発サーバー起動
- `pnpm build` - ビルド
- `pnpm test` - テスト実行
- `pnpm test:watch` - テスト（ウォッチモード）
- `pnpm lint` - リント
- `pnpm db:migrate` - マイグレーション実行書き方のベストプラクティス
1. 簡潔に、箇条書きで書く
CLAUDE.mdはClaude Codeのコンテキストウィンドウを消費します。冗長な説明は避け、箇条書きや表を活用して簡潔に記述しましょう。
# 良い例
- エラーハンドリング: AppError クラスを使用
- レスポンス形式: { data, error, meta }
- 認証: Bearer トークン（JWT）
# 悪い例
このプロジェクトでは、エラーハンドリングにおいてAppErrorという
カスタムエラークラスを使用しています。これは src/utils/errors.ts に
定義されており、HTTPステータスコードとエラーメッセージを...（長文）2. プロジェクト固有のルールを重点的に
一般的なTypeScriptのベストプラクティスはClaude Codeが既に知っています。プロジェクト固有のルールや慣習に焦点を当てましょう。
# プロジェクト固有のルール
- API レスポンスは必ず ApiResponse<T> 型でラップする
- DB クエリは services 層でのみ実行する（routes から直接呼ばない）
- 環境変数は src/config.ts の env オブジェクト経由でアクセスする
- 新規テーブル追加時は必ず created_at, updated_at カラムを含める3. よく使うコマンドを記載する
テスト実行、ビルド、リントなどのコマンドを書いておくと、Claude Codeが適切なタイミングで実行してくれます。
# コマンド
- 単一テスト実行: `pnpm test -- src/services/user.test.ts`
- 型チェック: `pnpm tsc --noEmit`
- DB スキーマ生成: `pnpm db:generate`4. やってはいけないことを明記する
「何をすべきか」だけでなく「何をしてはいけないか」を書くことで、意図しない変更を防げます。
# 注意事項
- node_modules や .env ファイルは絶対に編集しない
- pnpm-lock.yaml は手動で編集しない
- src/generated/ 配下は自動生成ファイルのため編集不可
- main ブランチに直接コミットしない5. 定期的に更新する
プロジェクトの成長に合わせてCLAUDE.mdも更新しましょう。古い情報が残っていると、Claude Codeが誤った判断をする原因になります。
グローバル CLAUDE.md の活用
~/.claude/CLAUDE.mdには、全プロジェクトで共通のルールを記載します。
# 全プロジェクト共通ルール
- コミットメッセージ: Conventional Commits 形式
- 日本語でコメントを書く
- console.log でのデバッグは残さないCLAUDE.md が効果を発揮する場面
- 新しいファイルの生成: プロジェクトの規約に沿ったコードが生成される
- リファクタリング: 既存の命名規則やパターンを維持した修正が行われる
- テスト作成: 指定したフレームワークとパターンでテストが書かれる
- バグ修正: プロジェクト構造を理解した上で、適切な場所を修正する
よくある間違い
情報を詰め込みすぎる
CLAUDE.mdが何百行にもなると、かえって重要な情報が埋もれます。必要最小限の情報に絞りましょう。
一般的すぎる内容を書く
「変数名はわかりやすくする」のような一般論は不要です。プロジェクト固有の具体的なルールを書きましょう。
更新を怠る
技術スタックの変更やディレクトリ構成の変更を反映しないと、Claude Codeの出力精度が低下します。
まとめ
CLAUDE.mdは、Claude Codeの出力品質を大きく左右する重要なファイルです。簡潔に、プロジェクト固有のルールを中心に、よく使うコマンドと注意事項を記載しましょう。適切なCLAUDE.mdがあれば、Claude Codeは「プロジェクトの慣習を理解したチームメンバー」として機能します。まだ作成していない方は、まず技術スタックとディレクトリ構造の記載から始めてみてください。タスク固有の手順はSkillsでテンプレート化すると、さらに効率的です。外部ツール連携にはMCP設定も合わせて活用しましょう。