MENU
Claude Code × 生成AI 実践ガイド
  1. ホーム
  2. Claude Code
  3. CLAUDE.mdの書き方：プロジェクトのAI設定を最適化する

CLAUDE.mdの書き方：プロジェクトのAI設定を最適化する

Claude Code

CLAUDE.mdは、Claude Codeがプロジェクトのコンテキストを理解するための設定ファイルです。このファイルを適切に書くことで、AIの回答精度が劇的に向上し、プロジェクトの規約に沿ったコード生成が可能になります。この記事では、効果的なCLAUDE.mdの書き方を段階的に解説します。

目次

CLAUDE.mdとは

CLAUDE.mdは、プロジェクトのルートディレクトリに配置するマークダウンファイルです。Claude Codeはセッション開始時にこのファイルを自動的に読み込み、内容をコンテキストとして保持します。これにより：

  • プロジェクトの技術スタックを理解できる
  • コーディング規約に従ったコードを生成できる
  • アーキテクチャ上の決定事項を把握できる
  • 注意すべきセキュリティ要件や制約を認識できる

基本的な構造

CLAUDE.mdは通常のマークダウン形式で記述します。以下は基本的な構成例です：

# CLAUDE.md

## プロジェクト概要
ECサイトのフロントエンドアプリケーション。
顧客向けの商品閲覧・購入フローと、管理画面を提供する。

## 技術スタック
- Next.js 15 (App Router)
- TypeScript 5.4
- Tailwind CSS 4
- Zustand (状態管理)
- Prisma (ORM)
- PostgreSQL 16

## プロジェクト構造
```
src/
  app/          # Next.js App Routerのページとレイアウト
  components/   # 再利用可能なUIコンポーネント
  lib/          # ユーティリティ関数とヘルパー
  stores/       # Zustandストア
  types/        # TypeScript型定義
prisma/
  schema.prisma # データベーススキーマ
```

## コーディング規約

### 命名規則
- コンポーネント: PascalCase (例: ProductCard.tsx)
- ユーティリティ関数: camelCase (例: formatDate.ts)
- 定数: UPPER_SNAKE_CASE (例: MAX_RETRY_COUNT)
- CSS classes: Tailwindユーティリティを直接使用

### コンポーネント設計
- 関数コンポーネントのみ（クラスコンポーネント禁止）
- Propsには必ずinterfaceを定義し、exportする
- 副作用はuseEffectではなく、SWRまたはReact Queryで管理
- フォーム状態はReact Hook Formを使用

### エラーハンドリング
- API呼び出しは必ずtry-catchで囲む
- ユーザー向けエラーはtoast通知で表示
- エラーログは構造化ログとして出力

## テスト
- Vitest + React Testing Library
- テストファイルは対象ファイルと同じディレクトリに *.test.tsx として配置
- E2EテストはPlaywrightを使用

## Git運用
- ブランチ名: feature/xxx, fix/xxx, refactor/xxx
- コミットメッセージ: Conventional Commits形式
  - feat: 新機能
  - fix: バグ修正
  - refactor: リファクタリング

## 注意事項
- 決済関連のコード変更は必ずレビュー前にテストを実行
- 個人情報を扱うコンポーネントには対応するテストが必須
- 環境変数は .env.local に定義（.envには書かない）

効果的な書き方のポイント

1. 具体的に書く

「いい感じに」といった曖昧な指示ではなく、具体的な規約を記述します：

# ❌ 悪い例
コンポーネントはきれいに書いてください

# ✅ 良い例
- 1コンポーネントあたり200行以内
- ロジックはカスタムフックに抽出
- presentationalとcontainerを分離

2. やってはいけないことを明記する

AIが避けるべきパターンを明示的に書くことで、ミスを防ぎます：

## 禁止事項
- any型の使用は禁止（unknownを使う）
- console.logの残置は禁止
- インラインスタイルの使用は禁止（Tailwindを使う）
- default exportは禁止（named exportのみ）
- moment.jsは禁止（date-fnsを使う）

3. 既存コードへの参照を含める

参考にすべき既存ファイルを明記すると、AIがプロジェクトのパターンを一貫して踏襲します：

## 参考実装
- API呼び出しパターン: src/lib/api-client.ts を参照
- 認証フロー: src/app/(auth)/login/page.tsx を参照
- フォーム実装: src/components/forms/ContactForm.tsx を参照

4. プロジェクト固有の文脈を共有する

## ビジネス要件
- 価格表示は税込価格をデフォルトとする（日本市場向け）
- 配送先は日本国内のみ対応
- 決済通貨はJPY固定
- 消費税率は10%（軽減税率8%対象商品は food カテゴリ配下）

チーム開発での運用

CLAUDE.mdはバージョン管理に含めるべきファイルです。チームで合意した規約をCLAUDE.mdに集約することで：

  • 新規メンバーのオンボーディングが容易になる
  • コードレビューの基準が明確になる
  • AIの生成コードがチームの規約に自動的に準拠する
  • 規約の変更履歴がGitで追跡可能

CLAUDE.md vs 設定ファイル

ESLintやPrettierの設定ファイルとCLAUDE.mdは補完関係にあります：

  • ESLint/Prettier：構文的な規則（セミコロン、インデント等）を自動強制
  • CLAUDE.md：意味的な規約（設計パターン、命名哲学、ビジネスルール等）をAIに指示

両方を適切に設定することで、AIが生成したコードがそのままレビュー可能な品質になります。

まとめ

CLAUDE.mdは、Claude Codeを単なる汎用AIからプロジェクト専用の開発アシスタントに変えるための設定ファイルです。一度しっかりと書いておけば、その後の開発効率が大幅に向上します。まずは基本構造から始めて、プロジェクトの成長に合わせて内容を充実させていきましょう。

Claude Code

関連記事

目次