はじめに

みなさんは Claude Code を使うときに CLAUDE.md をちゃんと書いていますか？

「書いたのに思った通りに動いてくれない…」という経験、ありませんか？

僕も最初は雑にルールを並べただけのファイルを置いていたのですが、よく見ると 書き方や配置場所 で挙動が大きく変わるんですよね。逆にいうと、ここをちゃんと押さえれば Claude Code はかなり頼れる相棒になってくれます。

そこで今回は、CLAUDE.md の基本から、配置場所の使い分け、構成、NG例と良い例までを一気に紹介していきます😇

CLAUDE.md とは？

プロジェクトのルールと知識を記述するファイル です。

Claude Code が起動時に 自動で読み込んでくれる
セッションをまたいで情報を 永続化 できる
プロジェクトルートに配置するのが基本

これがあると、Claude Code が プロジェクトを理解した状態 で作業を始めてくれます。具体的には、

コンテキストの共有: プロジェクトの文脈を理解してくれる
説明の省略: 毎回同じ説明をしなくていい
規約の遵守: コーディング規約を守らせやすい
チーム共有: 全員が同じルールで Claude を使える

といったメリットがありますね。

注意点：あくまで「指示」

ここは大事なポイントなのですが、CLAUDE.md は 「指示」であって絶対のルールではありません。複雑だったり曖昧な表現だったりすると、意図通りに解釈されないこともあります。

なので 具体的かつ簡潔 に書く、というのが大原則になります。

メモリの配置場所は4つある

CLAUDE.md 系のファイルにはいくつか配置場所があり、すべて読み込まれて組み合わせて使われます。

タイプ	場所	書く内容
Enterprise	組織管理フォルダ	組織共通ルール
Project	`./CLAUDE.md`	プロジェクト固有設定
User	`~/.claude/CLAUDE.md`	個人の共通設定
Local	`./CLAUDE.local.md`	個人 × プロジェクト設定

実戦では、Enterprise を除いた 3つを意識すれば OK です。

① プロジェクトルール `./CLAUDE.md`

チームメンバー全員で共有する 設定です。Git で管理して、全員が同じ設定で作業できるようにします。

# MyProject

## 技術スタック
- Next.js 16 + TypeScript

## コーディング規約
- 命名規則は camelCase
- テストカバレッジは 80% 以上

② ユーザーレベル `~/.claude/CLAUDE.md`

すべてのプロジェクトに適用される個人設定 です。

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

ここには プロジェクトに依存しない共通ルール を書きます。

# 個人設定

## 共通方針
- コミットメッセージは日本語で書く
- テストを書いてからコードを実装する

## エラーハンドリング
- エラーの抑制ではなく、根本原因を修正
- エラーケースもテストでカバー

③ ローカル専用 `./CLAUDE.local.md`

個人のローカル設定（チームには共有しない）を書きます。作成すると 自動で .gitignore に追加 されるのが地味に嬉しいポイントですね。

# ローカル設定

## 開発環境
- サンドボックスURL: http://localhost:3000
- テスト用DB接続先: ...
- APIモックサーバー: ...

プロジェクト vs ユーザーの使い分け

迷ったらこの表で判断してください。

種類	内容の例
プロジェクト	React 使用、`src/` 配置、API 仕様
ユーザー	日本語コミット、TDD 方針、品質基準

⚠️ セキュリティの注意点

情報	推奨配置場所
API キー・シークレット	環境変数 or `.env`
ローカル DB 接続先	`CLAUDE.local.md`
本番環境の情報	書かない

CLAUDE.md にシークレットを書くのは絶対に避けましょう。

書くときの注意点：長く書けば良いわけではない

ここ、勘違いしている方が結構多い気がします。

CLAUDE.md は起動時に すべてのコンテキストに読み込まれる
長すぎると、本来の作業に使える領域を圧迫してしまう
「詳しければ詳しいほど良い」は 間違い
簡潔かつ具体的 に書くのが正解

ぶっちゃけ、500行を超えてくると Claude も人間も読まなくなります😇

基本構成：このセクションを押さえれば OK

必要最低限の情報を、以下のセクションで整理して書くのがおすすめです。

セクション	書く内容
概要	プロジェクトの目的、主要機能
技術スタック	言語、フレームワーク、ライブラリ
ディレクトリ構造	主要フォルダの役割
コーディング規約	命名規則、フォーマット
開発ワークフロー	コミット規約、テスト方針

実例：概要〜ディレクトリ構造

# プロジェクト概要
EC サイトのバックエンド API。商品管理と注文処理を担当。

## 技術スタック
- 言語: TypeScript 5.x
- フレームワーク: Express.js
- DB: PostgreSQL + Prisma
- テスト: Vitest

## ディレクトリ構造
src/
├── domain/       # ビジネスロジック
├── application/  # ユースケース
├── infra/        # DB・外部API
└── presentation/ # コントローラー

※ ビジネスロジックは domain/ に集約

ディレクトリ構造は「Claude が ls で分かる情報」と思いがちですが、「どこに何を置くか」というルールは書き手の意図 なので、書いた方が圧倒的に効きます。新規ファイルの置き場所を Claude が迷わなくなるんですよね。

NG例 vs 良い例：曖昧さを排除する

ここからが本題です。CLAUDE.md でやりがちな失敗を見ていきましょう。

NG例①：「綺麗なコード」では伝わらない

書き方	例
❌ 曖昧	コードは綺麗に書いて
✅ 具体的	関数は 1 つの責務に限定する
✅ 具体的	変数名は camelCase で命名する
✅ 具体的	1 関数は 30 行以内に収める

「綺麗」の定義は人によって違うので、Claude もどう動けばいいか分かりません。数字や具体的なルールに落とし込む のが鉄則です。

NG例②：「ちゃんと」「しっかり」は解釈が分かれる

書き方	例
❌ 曖昧	テストをちゃんと書いて
✅ 具体的	カバレッジ 85% 以上を維持
❌ 曖昧	セキュリティはしっかり
✅ 具体的	入力値は必ずバリデーション

「ちゃんと」「しっかり」「いい感じに」は人間同士の会話でも揉めるワードですよね。Claude 相手だとなおさらです。

実例：良いコーディング規約の書き方

## コーディング規約
- ES Modules を使用（CommonJS 禁止）
- 型定義は interface を優先（type は合併型のみ）
- エラーは早期 return で処理
- マジックナンバー禁止 → 定数化する
- ネストは 3 段階以内

具体的で、判断基準がハッキリしていますね。これなら Claude もブレずに従ってくれます。

@ 記法でファイル参照する

CLAUDE.md 本体が膨らんできたら、@ 記法で外部ファイルを参照するのがおすすめです。

## API 仕様
@docs/API_SPECIFICATION.md

## コーディングスタイル
@docs/CODING_STYLE.md

これで CLAUDE.md 本体をシンプルに保ちつつ、必要な詳細情報も渡せます。

おわりに

今回は CLAUDE.md の書き方について、配置場所から構成、NG例までを一気に紹介しました。

ポイントをまとめると、

配置場所は 3 つ（プロジェクト / ユーザー / ローカル）を使い分ける
長く書けば良いわけではない、簡潔かつ具体的に
基本構成（概要・技術スタック・ディレクトリ構造・規約・ワークフロー）を押さえる
「綺麗」「ちゃんと」のような曖昧表現は禁止、数字や具体ルールに落とし込む
シークレットは絶対に書かない
大きくなってきたら @ 記法 で分割する

このあたりを意識するだけで、Claude Code との開発体験はグッと快適になります。

ぜひみなさんも、自分だけの CLAUDE.md を作成してみてください!

参考