MaemaemaeMaemaemae

CLAUDE.mdで Claude Code をプロジェクトに最適化する

Claude Code を使うなら CLAUDE.md は必ず押さえておきたい仕組みです。この記事では、CLAUDE.md の役割・書き方・実際の活用パターンをまとめます。

CLAUDE.md とは

CLAUDE.md は、Claude Code（Anthropic が提供する AI コーディングアシスタント）がリポジトリを開いたときに自動的に読み込む設定ファイルです。

プロジェクト固有の情報・規約・禁止事項などをここに書いておくと、Claude がそれを前提に動作してくれます。公式では「Claude's memory」とも呼ばれており、セッションをまたいで一貫したコンテキストを提供します。

読み込まれるタイミング・ロケーション

Claude Code を起動したとき、以下の場所にある CLAUDE.md がこの順番で読み込まれます：

  1. ホームディレクトリ（~/.claude/CLAUDE.md）― 全プロジェクト共通のグローバル設定
  2. リポジトリルート（./CLAUDE.md）― プロジェクト全体の設定（Git にコミットしてチームで共有）
  3. .claude/CLAUDE.md（./CLAUDE.md の代替として使えるサブディレクトリ配置）
  4. サブディレクトリ（./src/CLAUDE.md など）― オンデマンドで読み込み（そのディレクトリ内のファイルを Claude が読んだときに初めて読み込まれる）

また、.claude/rules/ ディレクトリ内に置いた .md ファイルも自動的にプロジェクトメモリとして読み込まれます。ルールをファイル単位で分割管理したい場合に便利です。

注意: ファイル名は大文字・小文字を区別します。CLAUDE.md（CLAUDE は大文字、.md は小文字）でなければなりません。claude.md や Claude.md では認識されません。

何を書くべきか

公式ドキュメントでは、以下の内容を書くことが推奨されています。

1. プロジェクト概要

## プロジェクト概要

個人ブログ — Next.js 14 (Static Export) + TypeScript + Tailwind CSS で構築。
記事は `posts/*.md` の Markdown ファイルで管理し、GitHub Pages にデプロイする。

Claude はプロジェクトの「何を作っているのか」を把握することで、的外れな提案を減らせます。

2. 技術スタックと重要ファイル

## 技術スタック

- フレームワーク: Next.js 14
- スタイリング: Tailwind CSS
- 記事形式: Markdown (gray-matter)

## 重要なファイル

| パス | 役割 |
|---|---|
| `src/app/lib/functions.ts` | 記事取得・ページ生成のユーティリティ |
| `src/components/` | 共通コンポーネント |

ファイル構成を教えておくと、「どこに何を書けばいいか」を Claude が自力で判断しやすくなります。

3. よく使うコマンド

## コマンド

\`\`\`bash
npm run dev        # 開発サーバー起動
npm run build      # ビルド
npm run lint       # ESLint チェック
\`\`\`

Claude はコマンドを直接実行する機能を持っているため、どのコマンドを使うべきかを明示しておくと効率的です。

4. コーディング規約

## コーディング規約

- TypeScript を使用する（型推論を活用し、明示的な型付けは必要な箇所のみ）
- コンポーネントは `src/components/` に配置する
- スタイルは Tailwind CSS クラスで記述する（インライン style は最小限）
- ダークモード対応: Tailwind の `dark:` プレフィックスを使用する

チームやプロジェクトで決めているルールを書いておくと、Claude が提案するコードがそのルールに沿ったものになります。

5. 禁止事項・制約

## 禁止事項

- `node_modules/` や `out/` 内のファイルを直接編集しない
- `npm run build` 前に `out/` を手動削除しない
- 本番コミットに `.env` ファイルを含めない

「やってはいけないこと」を明記することで、Claude の誤操作を防ぎます。

実際の書き方のポイント

簡潔に書く

CLAUDE.md はコンテキストウィンドウに入るため、長すぎると他の情報を圧迫します。200行を目安に、箇条書きや表を活用してコンパクトにまとめましょう。

「なぜ」より「何を」を優先する

理由よりも、Claude に取ってほしい行動・避けてほしい行動を具体的に書きます。

# 良い例
- コンポーネントは `src/components/` に配置する

# 悪い例
- コンポーネントの配置場所には歴史的な経緯があり、過去に何度かリファクタリングを...

動的な情報は入れない

日付やバージョン番号のような変化しやすい情報は、古くなったときに混乱の元になります。「最新のドキュメントを参照してください」のように書くほうが安全です。

業務での使いどころ

チーム開発での共有設定

CLAUDE.md をリポジトリにコミットしておくと、チーム全員が同じコンテキストで Claude を使えます。オンボーディング資料としても機能します。

プロジェクトルート
├── CLAUDE.md          ← チーム共通設定（コミット対象）
├── src/
│   ├── CLAUDE.md      ← フロントエンド固有のルール
│   └── api/
│       └── CLAUDE.md  ← API レイヤー固有のルール

コードレビューの基準を伝える

「このプロジェクトでは XXX パターンを使う」「YYY ライブラリは禁止」などの方針を書いておけば、Claude が提案するコードがレビュー基準に沿ったものになります。

スキル・カスタムコマンドの説明

Claude Code は / から始まるカスタムコマンド（スキル）を .claude/commands/ に定義できます。CLAUDE.md にその説明を書いておくと、どのコマンドがあるかを Claude が把握できます。

## カスタムコマンド

- `/new-post` : 新しいブログ記事を作成する
- `/check-post` : 記事のファクトチェックとレビューを行う

ハマりやすいポイント

ファイルが長すぎて無視される

CLAUDE.md が長すぎると、後半の内容がコンテキストウィンドウに収まらず無視されることがあります。重要な情報は上部に書くことを意識し、詳細は別ファイルに分けて CLAUDE.md からリンクする方法が有効です。

## 詳細ドキュメント

- コーディング規約の詳細: [docs/coding-rules.md](docs/coding-rules.md)
- デプロイ手順: [docs/deploy.md](docs/deploy.md)

グローバルとプロジェクトの設定が衝突する

~/.claude/CLAUDE.md（グローバル）に書いたルールとプロジェクトの CLAUDE.md のルールが矛盾すると、Claude が混乱します。グローバルには本当に全プロジェクト共通のことだけを書き、プロジェクト固有のことはプロジェクトの CLAUDE.md に書きましょう。

設定を書いても Claude が従わない場合

指示が曖昧だと Claude が解釈を誤ることがあります。「推奨する」より「必ず〜する」「〜してはいけない」のように断定的な表現を使うほうが効果的です。

また、Claude Code の設定ファイル（.claude/settings.json）で permissions を設定することで、ファイルへのアクセス制限などをより確実に制御できます。

/init コマンドで自動生成する

CLAUDE.md を一から書くのが面倒な場合は、Claude Code のターミナルで以下のコマンドを実行します。

/init

Claude がリポジトリを解析して、プロジェクト概要・ディレクトリ構造・使用技術などを盛り込んだ CLAUDE.md の初期テンプレートを自動生成してくれます。生成後に不要な箇所を削ったり、禁止事項を追記したりするのが現実的なワークフローです。

このブログの CLAUDE.md を例に見る

このブログ自体にも CLAUDE.md が用意されています。実際の構成を抜粋します。

## 記事作成ガイド

### ファイル命名規則
`posts/[カテゴリ]_[YYYYMMDD].md`

| カテゴリプレフィックス | 対象 |
|---|---|
| `react_` | React / フロントエンド |
| `blog_` | ブログ・サイト自体について |

### フロントマター仕様
\`\`\`yaml
---
title: "記事タイトル"
date: "YYYY-MM-DD"
tags: ["タグ1", "タグ2"]
---
\`\`\`

このように「記事の命名規則」「フロントマターの必須フィールド」「既存タグ一覧」を書いておくことで、Claude に /new-post コマンドを使って記事を作らせたとき、形式がずれることなく一貫したファイルが生成されます。カスタムコマンドと CLAUDE.md の組み合わせが、繰り返し作業の自動化において特に効果的です。

まとめ

CLAUDE.md を適切に整備すると、Claude Code がプロジェクトの文脈を理解した状態で作業してくれるため、コードの一貫性が上がり、指示のやり取りも減ります。

最初は /init で自動生成したものから始めて、「Claude に誤解されたな」と感じたときに都度追記していくのがおすすめです。プロジェクトと一緒に育てていくドキュメントとして活用しましょう。

タグ

生産性向上開発環境自動化