CLAUDE.mdの書き方完全ガイド — Claude Codeのプロジェクト設定で開発効率を最大化

CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むMarkdownファイルです。プロジェクトのコーディング規約、技術スタック、禁止パターン、ビルド手順などを記述することで、セッションが変わってもAIが一貫したルールに従うようになります。

通常のAIチャットでは、セッションごとにプロジェクトのルールを伝え直す必要があります。CLAUDE.mdを使えば、その手間が完全に不要になります。一度書けば、チームの全メンバーが同じルールでClaude Codeを使えます。

CLAUDE.mdがないClaude Codeは、プロジェクトの文脈を知らない新人エンジニアのようなものです。コードは書けるが、チームの規約を知らないため一貫性のないコードが生成されます。CLAUDE.mdはAIに「チームの暗黙知」を教えるドキュメントです。

CLAUDE.mdに記述すべき項目は7つです。

①技術スタック: 使用するフレームワーク、言語、ライブラリを明記。「Next.js 16 + React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui」のように具体的に。

②コーディング規約: `any`型禁止、1関数50行以下、命名規則（camelCase/PascalCase）など。既存コードベースのパターンを踏襲する旨も書きます。

③ディレクトリ構成: `src/components/` はUIコンポーネント、`src/lib/` はユーティリティなど、主要ディレクトリの役割を説明。

④ビルド・テストコマンド: `pnpm build`, `pnpm test`, `pnpm lint` など、品質確認に使うコマンド。

⑤禁止パターン: 自前認証の実装禁止（Clerk/Supabase Authを使う）、インラインスタイル禁止など、やってはいけないことを明示。

⑥外部サービス連携: Stripe、Sentry、PostHogなどの設定方針。

⑦ワークフロー: 変更前にコードを読む→実装→ビルド確認、のような作業フローを定義。

以下はSalesNowの実プロジェクトで使用しているCLAUDE.mdの骨格です。

```markdown # プロジェクト名 — Claude Code設定

## 技術スタック - Next.js 16 + React 19 + TypeScript - Tailwind CSS 4 + shadcn/ui - Supabase（DB・認証） - Vercel（ホスティング）

## コード品質 - TypeScript: any型はMUST NOT。unknown + 型ガードを使う - 1関数50行以下 - 既存パターンを踏襲。新しいパターンを勝手に導入しない

## ワークフロー - 変更前に既存コードを読んで既存パターンに従う - 変更後はMUST `pnpm build` でビルド確認 ```

この骨格に、プロジェクト固有の情報を追加していきます。最初は短くてOK。使いながら「Claudeに守ってほしいルール」を追記していくのがベストプラクティスです。1行のCLAUDE.mdでも、ないよりはるかに良い結果が得られます。

CLAUDE.mdは3つのレベルで配置でき、下層が上層を補完する形で適用されます。

①グローバル（`~/.claude/CLAUDE.md`）: 全プロジェクトに適用される共通ルール。使用言語（日本語返答）、UIライブラリ（Tailwind + shadcn/ui）、禁止事項（any型禁止）など、組織全体の基準を定義します。

②プロジェクトルート（`./CLAUDE.md`）: そのリポジトリ固有のルール。技術スタック、ディレクトリ構成、固有のビジネスロジック（料金計算式、診断アルゴリズムなど）を記述します。Gitリポジトリに含めてチーム全員で共有します。

③サブディレクトリ: 特定モジュールに限定したルール。`packages/api/CLAUDE.md` に「このディレクトリではExpress.jsのミドルウェアパターンに従う」のように書きます。

SalesNowでは、グローバルCLAUDE.mdに200行以上のルールを定義し、20以上のプロジェクトで共通適用しています。各プロジェクトのCLAUDE.mdには50〜100行のプロジェクト固有ルールを追記。この3層構成により、組織の統一性とプロジェクトの柔軟性を両立しています。

CLAUDE.md運用でよく見る失敗パターンと、その対策を紹介します。

ミス①: 書きすぎて読まれない: 1,000行を超えるCLAUDE.mdは、コンテキストウィンドウを圧迫し逆効果です。対策: 核心的なルールに絞り、200行以内を目安にする。詳細は別ドキュメントに分離し、必要時に参照させます。

ミス②: 曖昧な指示: 「きれいなコードを書いて」は意味がありません。対策: 「1関数50行以下」「変数名はcamelCase」のように、定量的・具体的に書きます。

ミス③: 更新されない: 技術スタックが変わってもCLAUDE.mdが古いままだと、間違ったパターンでコードが生成されます。対策: 技術選定を変更したら即座にCLAUDE.mdも更新。PRレビューの対象に含めます。

ミス④: Gitに含めない: 個人のローカルだけにCLAUDE.mdを置くと、チームメンバー間でAIの出力品質にばらつきが出ます。対策: プロジェクトルートのCLAUDE.mdは必ずGit管理し、チーム全体で共有します。

ミス⑤: MUSTとSHOULDを区別しない: すべてを「MUST」にすると優先度が分からなくなります。対策: 絶対に守るべきルールには「MUST」、推奨事項には「SHOULD」を付けて優先度を明示します。