CLAUDE.md 完全ガイド
AIに正しく伝えるための書き方とテンプレート【2026年版】

「Claude Code を導入したが、毎回同じ説明をしないといけない」「AIが我が社のルールを覚えてくれない」――そう感じる開発チームが見落としているのが CLAUDE.md の存在です。

CLAUDE.md は Claude Code がプロジェクトを開いた瞬間に自動的に読み込む指示ファイル。ここに「自社のルール」「コード規約」「禁止事項」「過去の意思決定」を書いておけば、AI が毎回それを参照しながらコードを生成します。

本記事では、CLAUDE.md の書き方を完全解説し、実際のプロジェクトで使えるテンプレートまで公開します。

CLAUDE.md とは何か？

Claude Code がプロジェクトディレクトリで自動的に読み込む、AI 向けの「プロジェクト取扱説明書」です。

Claude Code は起動時に以下の優先順位でファイルを読み込みます：

1. グローバル設定：~/.claude/CLAUDE.md（全プロジェクト共通）
2. プロジェクト設定：プロジェクトルートの CLAUDE.md（そのプロジェクト固有）
3. サブディレクトリ設定：作業中のディレクトリにある CLAUDE.md（部分的なルール）

この3層構造で、AI に「全社共通ルール」「プロジェクト固有ルール」「特定モジュールの注意点」を段階的に伝えられます。

なぜ CLAUDE.md がそこまで重要なのか？

CLAUDE.md があるかどうかで、AI の出力品質が体感3〜5倍変わるからです。

具体的な違い：

「毎回同じ説明をしている」と感じる開発者は、その説明を CLAUDE.md に書けば1度書けば永続的に効く仕組みになります。

CLAUDE.md に書くべき7項目

プロジェクト概要・技術スタック・コード規約・禁止事項・過去の意思決定・ファイル構造・実行コマンド、の7項目が標準テンプレートです。

それぞれの書き方を詳しく見ていきます。

1. プロジェクト概要

# プロジェクト名

## 概要
- このプロジェクトの目的（1-2行）
- 想定ユーザー
- 公開URL（あれば）
- 主要な技術スタックの概要

書く時のポイント：何のためのプロジェクトか、AIが瞬時に理解できるよう簡潔に。

2. 技術スタック

## 技術スタック
- フレームワーク: Next.js 16 (App Router)
- 言語: TypeScript (strict mode)
- スタイル: Tailwind CSS 4
- 状態管理: Zustand
- DB: Supabase (PostgreSQL)
- 認証: Firebase Auth
- デプロイ: Vercel

書く時のポイント：バージョンを必ず書く。「React」だけでなく「React 19」など。

3. コーディング規約

## コーディング規約
- **言語**: TypeScript strict、any 禁止
- **コンポーネント**: React functional component のみ（class 禁止）
- **状態管理**: Zustand を使う（useState は最小限）
- **API呼び出し**: tRPC または Server Actions を使う
- **ファイル名**: kebab-case
- **コンポーネント名**: PascalCase
- **コミットメッセージ**: Conventional Commits 準拠

書く時のポイント：曖昧さを残さない。「適切にやる」ではなく「◯◯を使う」と明示。

4. 禁止事項（最重要）

## 禁止事項
- ❌ `any` 型の使用（unknown を使う）
- ❌ `// @ts-ignore` の追加
- ❌ `console.log` のコミット（log は logger ライブラリ使用）
- ❌ ハードコードされたAPIキー・URL
- ❌ npm scripts のバックグラウンド実行（フリーズ事例あり）
- ❌ git push --force（--force-with-lease を使う）
- ❌ 確認なしでの DB マイグレーション本番反映

書く時のポイント：過去にチームが踏んだ地雷を全部書く。なぜ禁止かの理由も短く添えると効果的。

5. 過去の重要な意思決定

## 過去の意思決定
- 2025-12: zustand → Redux 移行を検討したが、現状の規模では不要と判断
- 2026-01: Firebase Auth → Auth0 移行検討、コスト面で却下
- 2026-03: API ルーティングを App Router に統一（Pages Router 廃止）

書く時のポイント：AI が「なぜこの選択？」と質問する前に答える。Why が分かると判断が一貫する。

6. ファイル構造

## ファイル構造
- `src/app/`: Next.js App Router ページ
- `src/components/`: 共通React コンポーネント
- `src/lib/`: ユーティリティ・型定義
- `src/hooks/`: カスタムフック
- `posts/`: ブログ記事の Markdown
- `public/images/`: 静的画像

書く時のポイント：AI が「このファイルどこ置く？」と迷わないように。

7. 実行コマンド

## 実行コマンド

### ローカル開発
```bash
npm run dev

ビルド

npm run build

型チェック

npx tsc --noEmit

ESLint

npm run lint

**書く時のポイント**：実際に使うコマンドを **コードブロックで** 書く。AI が即座にコピー&実行できる形に。

## CLAUDE.md のサンプル（実用テンプレート）

以下を雛形にすれば、5分で自社用の CLAUDE.md が書けます。

```markdown
# [プロジェクト名]

## 概要
[1-2行で目的・対象ユーザー]

## 技術スタック
- フレームワーク: [例: Next.js 16 App Router]
- 言語: [例: TypeScript strict]
- スタイル: [例: Tailwind CSS 4]
- DB: [例: Supabase]
- デプロイ: [例: Vercel]

## コーディング規約
- TypeScript: strict mode、any 禁止
- コンポーネント: React functional のみ
- ファイル名: kebab-case
- 状態管理: [使うもの]

## 禁止事項
- [自社の地雷を箇条書き]
- [なぜ禁止かを短く]

## 過去の意思決定
- [日付]: [決定内容と理由]

## ファイル構造
- src/app/: [説明]
- src/components/: [説明]
- src/lib/: [説明]

## 実行コマンド
\`\`\`bash
npm run dev    # ローカル起動
npm run build  # 本番ビルド
\`\`\`

## 開発フロー
- ブランチ運用: [説明]
- PR作成手順: [説明]
- マージ後の確認: [説明]

これを直下にコピーして埋めるだけで、Claude Code が即座にプロジェクト理解した状態で動き始めます。

グローバル CLAUDE.md とプロジェクト CLAUDE.md の使い分け

グローバルは「全プロジェクト共通の基本ルール」、プロジェクト個別は「そのプロジェクト固有のルール」を書きます。

グローバル（~/.claude/CLAUDE.md）に書く例

# グローバルルール

## 判断基準
- ファイル作成・分析・コード修正は確認不要、yes 前提で進める
- 有料サービス操作・本番影響は確認を取る

## 正直さ
- 保証できないことを「します」「しません」と断言しない
- イエスマンにならない

## バグ修正
- 推測で直さない、ログ・DB で事実を確認してから修正
- 1回で直らなかったら、前提を疑う
- 修正後は必ず実際に操作して検証

プロジェクト（プロジェクト直下の CLAUDE.md）に書く例

# まるっとAIブログ — Claude Code運用ガイド

## プロジェクト概要
- Next.js 16 ブログサイト（/column/ パスで配信）
- marutto-ai.jp の SEO コンテンツメディア

## 技術スタック
- Next.js 16 + TypeScript + Tailwind CSS 4
- 静的エクスポート（output: "export"）
- Vercel デプロイ

## 禁止事項
- npm install をバックグラウンド実行しない
- main 直 push 禁止、PR 経由
- 14日間無料 / TASKUL 関連の残留テキストを書かない

## 投稿フロー
1. /posts/ 直下に Markdown 作成
2. ブランチ → PR → マージ
3. Vercel 自動デプロイ

両方を併用することで、「グローバルで共通の判断軸」＋「プロジェクト固有の実装ルール」を漏れなく AI に伝えられます。

効果が出る CLAUDE.md の3つの特徴

①禁止事項が明確 ②具体例が豊富 ③定期的に更新、の3点で効果が圧倒的に変わります。

1. 禁止事項が明確

「適切にやる」「綺麗に書く」のような曖昧な指示は AI に伝わらない。「◯◯はやらない」と明確に書く。

良い例： - ❌ any 型の使用 - ❌ console.log のコミット - ❌ git push --force（--force-with-lease を使う）

2. 具体例が豊富

抽象論ではなく、実際のコード片・コマンド・パターンを示す。

良い例：

## API エラーハンドリング
- すべての API 呼び出しは try-catch で囲む
- エラー時は logger.error で記録、ユーザーには汎用メッセージ

例：
\`\`\`typescript
try {
  const data = await fetchUser(id);
  return { success: true, data };
} catch (e) {
  logger.error("fetchUser failed", { id, error: e });
  return { success: false, message: "ユーザー取得に失敗しました" };
}
\`\`\`

3. 定期的に更新

CLAUDE.md は1度書いて終わりではない。新しいミス・新しい意思決定・新しい禁止事項が出るたびに追記する習慣が必要。

おすすめは：

• 月次レビューで「先月起きたミス」を CLAUDE.md に追加
• PR レビュー時に「これは CLAUDE.md に書くべき」事項をフラグ
• 過去ミスから学んだルールはすぐ追記

CLAUDE.md でよくある失敗パターン

失敗1：一般論ばかり書いている

## コーディング規約
- 綺麗なコードを書く
- バグの少ないコードにする
- 適切な変数名を使う

→ AI には何も伝わらない。自社固有のルールを書く。

失敗2：具体例がない

## エラーハンドリング
- 適切にエラーを処理する

→ コード例を載せて「こう書く」を示す。

失敗3：1ヶ月以上更新されていない

→ 古い情報がそのまま残っていると、AI が古い前提で動いて事故になる。月次レビューを組む。

失敗4：長すぎて読み飛ばされる

3,000行以上になると AI が読み飛ばす可能性が増える。500〜2,000行が標準。「重要度の低い情報は別ファイル」に分離する手も有効。

大規模プロジェクトでの分割パターン

プロジェクトが大きくなったら、CLAUDE.md を分割管理：

project-root/
├── CLAUDE.md                    # 全体概要・コア規約
├── frontend/
│   └── CLAUDE.md                # フロントエンド固有のルール
├── backend/
│   └── CLAUDE.md                # バックエンド固有のルール
└── infrastructure/
    └── CLAUDE.md                # インフラ・デプロイのルール

Claude Code は作業中のディレクトリの CLAUDE.md を優先的に読むため、自然に「該当領域のルール」だけが適用されます。

---

自社の CLAUDE.md 設計を任せたい場合

CLAUDE.md の設計は、プロジェクトの長期生産性に直結します。「どこまで書くべきか分からない」「過去の意思決定を整理する時間がない」という場合、AI実装支援サービスで一緒に設計するのが早道です。

まるっとAIでは、月額¥200,000から、Claude Code 運用設計＋CLAUDE.md 整備＋プロジェクト全体のAI活用支援をまとめてご提供します。 30分の無料相談を予約する →

まとめ：CLAUDE.md は「書けば永続的に効く」AIへの指示書

CLAUDE.md の本質は、「同じ説明を毎回しなくていい」仕組みを作ること。

書くべき7項目：

1. プロジェクト概要
2. 技術スタック
3. コーディング規約
4. 禁止事項（最重要）
5. 過去の意思決定
6. ファイル構造
7. 実行コマンド

書き方のコツ：

• 禁止事項を明確に書く（「◯◯はやらない」）
• 具体例を豊富に（コード片・コマンド）
• 定期的に更新する（月次レビュー）
• 500〜2,000行を目安に簡潔に

CLAUDE.md がしっかり書かれているプロジェクトは、AI がチームの一員のように動きます。Claude Code を本格活用したいなら、まずここに時間を投資する価値があります。