CLAUDE.mdファイルでAIコーディング速度を2倍にする方法

「TypeScriptとTailwindを使ってください」——新しいチャットを開くたびに、同じ説明を繰り返していませんか。Claude 3.5 Sonnetにエラーログを貼り付けたら、自信満々にPythonで修正案を提示してきた。でも、あなたのプロジェクトはRustで書かれている。訂正すると今度はRustで返してきたが、使っていない古いライブラリを参照している。またも訂正。AIがプロジェクトの全体像を理解するまでに、10分と5,000トークンを浪費してしまった——そんな経験はないでしょうか。本記事では、この問題を根本から解決する「CLAUDE.md」ファイルについて解説します。

この記事のポイント
CLAUDE.mdとは何か
4つの必須セクション
実践してみよう
知っておくと便利なTips
まとめ

この記事のポイント

CLAUDE.mdは「AIのためのREADME」として機能するコンテキストファイル
プロジェクト固有の情報を1つのファイルにまとめることで、毎回の説明が不要に
ビルドコマンド、コーディング規約、アーキテクチャ、技術スタックの4セクションで構成
人間の新規メンバーのオンボーディングにも活用可能

CLAUDE.mdとは何か

通常のREADME.mdは人間向けに書かれています。きれいなバッジ、プロジェクトの説明、インストール手順など、人間が読んで理解するための文書です。一方、CLAUDE.mdはAIのために書かれた「ロボット向けREADME」です。装飾は不要、事実だけを凝縮し、AIモデルがコーディングを即座に開始するために必要な情報だけを含みます。

新しいチャットセッションを開始する際、このファイルを添付するか内容をペーストするだけで、AIはあなたのリポジトリについて「シニアエンジニア」レベルの文脈を即座に獲得します。毎回ゼロから説明する必要がなくなり、最初のプロンプトから正確なコードを生成できるようになります。

Builder.ioのチームがこの手法を実践しており、開発効率の大幅な向上を報告しています。この記事では、効果的なCLAUDE.mdファイルの構造と書き方を詳しく解説します。

4つの必須セクション

効果的なCLAUDE.mdファイルは、4つの主要セクションで構成されます。

1. ビルド＆実行コマンド

開発環境のセットアップに必要なコマンドを明記します。

## Build & Run
- Dev Server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Database: `npx prisma db push`

これにより、AIは「このプロジェクトをどう実行するか」を即座に理解できます。「npm run dev で起動して」と言うだけで、正しいコマンドを使用してくれます。

2. コーディング規約

プロジェクト固有のルールを明示的に記述します。これが最も重要なセクションです。

## Coding Standards
- Language: TypeScript (strict mode)
- Components: Functional components only, no class components
- Styling: Tailwind CSS, NOT CSS modules
- State: Use Zustand, DO NOT use Redux
- Error Handling: All async functions must have try-catch

「DO NOT」を明記することが重要です。AIは一般的なパターンを提案しがちなので、避けるべきパターンを明示することでハルシネーションを防げます。「Reduxを使わない」と書いておけば、AIがReduxのコードを生成することはありません。

3. アーキテクチャ概要

ディレクトリ構造と設計原則を記述します。

## Architecture
- `/src/components` - UI components only
- `/src/features` - Feature modules with business logic
- `/src/hooks` - Custom React hooks
- `/src/utils` - Pure utility functions

Key Principle: Business logic should NEVER exist inside UI components

「どこに何を置くか」が明確になることで、AIは新しいコードを適切な場所に配置できます。既存のアーキテクチャを壊すような提案を防ぐ効果もあります。

4. 技術スタック

使用しているライブラリとバージョンを列挙します。

## Tech Stack
- Framework: Next.js 14 (App Router)
- UI: shadcn/ui, Radix UI primitives
- Icons: Lucide React
- Database: Prisma + PostgreSQL
- Auth: NextAuth.js v5

これにより、AIが存在しないライブラリや古いバージョンのAPIを提案することを防げます。ライブラリ名を明示することで、正確なインポート文やAPIの使用法を得られます。

実践してみよう

CLAUDE.mdの作成は、テキストエディタでファイルを作成するだけです。プロジェクトのルートディレクトリに配置します。

# プロジェクトルートにCLAUDE.mdを作成
touch CLAUDE.md

以下は実際のテンプレート例です。自分のプロジェクトに合わせてカスタマイズしてください。

# CLAUDE.md - Project Context for AI

## Quick Commands
- `npm run dev` - Start development server
- `npm run build` - Production build
- `npm test` - Run tests

## Stack
- Next.js 14 (App Router)
- TypeScript (strict)
- Tailwind CSS
- Prisma + PostgreSQL

## Rules
- Functional components only
- Use server actions for mutations
- All files use .tsx extension
- Prefer composition over inheritance

## Structure
/app - Next.js app router pages
/components - Reusable UI components
/lib - Utilities and helpers
/prisma - Database schema

Claude Codeのセッションでは、このファイルがプロジェクトルートにあれば自動的に読み込まれます。Claudeの通常のチャットインターフェースでは、セッション開始時にファイルの内容をペーストするか、ファイルをアップロードしてください。

知っておくと便利なTips

自動コピースクリプト: よく使う場合は、CLAUDE.mdの内容をクリップボードにコピーするシェルスクリプトを作成すると便利です。cat CLAUDE.md | pbcopy（macOS）やcat CLAUDE.md | xclip（Linux）を.bashrcにエイリアス登録しておくと、ワンコマンドでコピーできます。
バージョン管理に含める: CLAUDE.mdはプロジェクトの一部としてGitで管理しましょう。チームメンバー全員が同じ文脈をAIと共有できるようになります。
定期的な更新: ライブラリのアップデートやアーキテクチャの変更があったら、CLAUDE.mdも更新することを忘れずに。古い情報は逆効果になります。
人間のオンボーディングにも活用: CLAUDE.mdは新しいチームメンバーの参入時にも役立ちます。AIのために書いた簡潔な情報は、人間にとっても理解しやすいものです。