Claude.md でさらにスマートに Claude を使おう！

開発プロジェクトを始めるたびに、同じパターンやルールを Claude に繰り返し説明するのに疲れたことはありませんか？Claude Code と claude.md ファイルを活用すれば、この煩雑さを完全に解消できます。本稿では、claude.md を使って AI ペアプログラミングの効率を最大化する方法を、実践例とともに詳しく紹介します。

Claude Code は単なる AI コーディングツールではありません。プロジェクトの文脈を理解し、チームの開発規則を学び、一貫したコーディングスタイルを保てる強力なペアプログラミングパートナーです。そして、このすべての核にあるのが claude.md ファイルです。

Claude.md とは何か？

claude.md は Claude Code が自動的に読み込む Markdown ファイルです。新しい開発者がチームに参加した際に渡されるオンボーディング文書のような役割を果たします。プロジェクトの技術スタック、開発規則、ワークフロー、そして暗黙のコンベンションを Claude に伝える “プロジェクト説明書” と考えてください。

Claude Code はプロジェクトを開くたびにこのファイルを自動で読み、そこに記された情報をもとにプロジェクトに最適なコードを生成します。一度書いておけば、Claude はこの情報を永続的に記憶し、新しいセッションや別のブランチでも同じコンテキストを維持できます。

Claude.md の使い方：プロジェクト文脈の構築

claude.md の最大の強みは、プロジェクトの「暗黙のルール」を文書化できる点です。例えば、チームでは ES モジュールを使うことにしているが明示的に文書化していない場合、Claude は CommonJS方式でコードを書いてしまうかもしれません。しかし、claude.md にこう記述しておけば：

# 開発規則
- ES モジュールを使用する（import/export 構文を使用）
- API 呼び出しは必ず try-catch で囲む
- TypeScript では 'any' 型の使用禁止

このように記述しておけば、Claude は常にこれらの規則を守ったコードを書いてくれます。

また、ディレクトリ構造や各フォルダの役割も明確に定義できます：

# プロジェクト構造
- `src/components`: 再利用可能な UI コンポーネント
- `src/lib`: コアビジネスロジック
- `src/utils`: ヘルパー関数群
- `scripts/`: ビルドおよびデプロイ用スクリプト

Claude.md ベストプラクティス

技術スタックとバージョンの明記

バージョン情報は非常に重要です。Next.js 13 と 15 は完全に異なるアプローチを要求するからです：

# 技術スタック
- Framework: Next.js 14
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.4
- Database: Prisma 5.x + PostgreSQL
- State Management: Zustand 4.x

開発規則の詳細な明記

Claude が従うべき具体的な規則を明記できます：

# 開発規則
- すべての API 呼び出しは try-catch でラップする
- コンポーネントは関数型で記述（React hooks を使用）
- CSS-in-JS の代わりに Tailwind クラスを使用
- 状態管理は Zustand の store パターンを遵守
- エラー処理には toast 通知を使用

ワークフローの文書化

開発ワークフローも重要な情報です：

# ワークフロー
- ブランチ名: feature/TICKET-123-description
- コミットメッセージ: conventional commits 規則を守る
- PR 前には必ず lint と type check を通過
- テストカバレッジは 80% 以上を維持

Claude 専用指示事項

Claude が特に注意すべき事項も追加できます：

# Claude 指示事項
- レガシーコードをリファクタリングする際は注意（動作しているコードは安易に変更しないこと）
- アクセシビリティチェックを省略しないように
- 設定ファイルを修正する場合は必ず確認を求める
- 重要な変更点は TODO コメントで明示

コンテキストスイッチャーとしての Claude.md

claude.md は単なるルールファイルではありません。プロジェクトのさまざまな領域で異なるルールを適用できる “コンテキストスイッチャー” の役割も果たします。

Claude Code は複数の場所から CLAUDE.md ファイルを検索して統合します：

1. ホームディレクトリ (~/.claude/CLAUDE.md)：すべての Claude Code セッションにグローバル適用
2. プロジェクトルート (your-repo/CLAUDE.md)：最も一般的な場所で、バージョン管理に含める
3. サブディレクトリ (your-repo/feature/CLAUDE.md)：特定機能作業時に適用
4. ローカルオーバーライド (CLAUDE.local.md)：個人設定用（gitignore に追加）

たとえば、エンティティディレクトリで作業する際のみ適用されるルールを作成できます：

# src/entities/CLAUDE.md
- すべてのエンティティは Zod スキーマによる検証必須
- データベース関連ロジックのみ含める
- ビジネスロジックは services レイヤーに分離

こうすれば、エンティティディレクトリで作業する際、Claude は自動的にこれらのルールを適用します。

プロジェクト成長に応じた進化

claude.md はプロジェクトとともに管理されるべきです。新しい機能が追加されたり、開発手法が変わったりした場合には更新しておきましょう。Claude に過去のコミットをレビューさせ、claude.md のアップデートを提案させることもできます：

claude -p "最近の 10 件のコミットをレビューして、CLAUDE.md に追加すべき新しいパターンや規則があるか確認して。"

Claude Code の設定

Claude Code を始めるのはとても簡単です。

インストール手順

# Claude Code CLI のインストール
npm install -g @anthropic-ai/claude-code

# バージョン確認
claude --version

# プロジェクトディレクトリに移動
cd your-project

# Claude Code を起動
claude

具体例：こう書ける！

以下は Next.js プロジェクト用の完全な claude.md の例です：

# プロジェクト：E-commerce Dashboard

## 技術スタック
- Framework: Next.js 14.0 (App Router)
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.4
- Database: Prisma 5.x + PostgreSQL
- Authentication: NextAuth.js 4.x
- State Management: Zustand 4.x
- UI Components: Radix UI + Shadcn/ui

## プロジェクト構造
- `app/`: Next.js 13+ App Router 構造
- `components/ui/`: Shadcn/ui ベースの再利用可能コンポーネント
- `components/`: ビジネスロジックを含むコンポーネント
- `lib/`: ユーティリティおよび設定
- `stores/`: Zustand による状態管理
- `types/`: TypeScript 型定義

## 開発規則
- すべてのコンポーネントは TypeScript で記述
- サーバーコンポーネントを優先し、必要な場合のみクライアントコンポーネントを使用
- API ルートは `/app/api/` ディレクトリを使用
- データベースアクセスは Prisma Client 経由のみ
- 状態管理は Zustand store パターンを遵守
- スタイリングは Tailwind CSS クラスのみを使用

## コマンド
- `npm run dev`: 開発サーバー起動
- `npm run build`: プロダクションビルド
- `npm run lint`: ESLint 実行
- `npm run type-check`: TypeScript チェック
- `npx prisma studio`: データベース GUI

## コーディングコンベンション
- コンポーネント名: PascalCase
- ファイル名: kebab-case
- 変数名: camelCase
- 定数: UPPER_SNAKE_CASE
- インターフェース: 接頭辞 “I” は使用しない

## ブランチとコミット
- ブランチ名: `feature/TASK-123-short-description`
- コミットメッセージ: Conventional Commits 規則
- PR 前には必ず `npm run lint && npm run type-check` を通過

## Claude 指示事項
- `any` 型の使用は絶対禁止
- コンポーネント記述時にはアクセシビリティを必ず考慮
- エラーハンドリングは toast 通知で行う
- ローディング状態は Suspense 境界を活用
- 重要なビジネスロジックの変更時には TODO コメントで明示

Claude と Claude.md が開発を革新する方法

claude.md をうまく活用すれば、開発体験は完全に変わります。同じ説明を繰り返す必要はなく、Claude はプロジェクト文脈を完璧に理解した状態でコードを書いてくれます。チーム全体で一貫したコーディングスタイルを維持でき、新しいメンバーも速やかにプロジェクトに馴染むことができます。

特に複雑なエンタープライズプロジェクトでは、claude.md がなければ Claude がプロジェクトの複雑性を理解するのは難しいかもしれません。しかし、しっかり書かれた claude.md があれば、Claude をプロジェクトの完璧なペアプログラミングパートナーに変えることも可能です！