導入
ClaudeCodeを使い始めて少し経つと、「同じ指示を何度も繰り返している」「プロジェクト固有のルールを毎回説明している」と感じる瞬間が訪れます。例えば「このプロジェクトはNext.jsを使っていて」「データベースはこれで」「コーディング規約はこう」といった前提情報を、新しいセッションのたびに伝え直すのは大きな無駄です。この問題を一発で解決してくれるのがCLAUDE.mdというファイルです。プロジェクトのルートに置いておくだけで、ClaudeCodeは起動時にその内容を自動で読み込み、プロジェクトの文脈を理解した状態で会話を始めてくれます。本記事では、CLAUDE.mdの役割から書き方の基本、実践的なテンプレート、@インポート機能の使い方、よくある落とし穴まで、徹底的に解説します。
結論
CLAUDE.mdは、ClaudeCodeに「このプロジェクトはこういうものだ」と教えるための説明書です。これを書いておくと、ClaudeCodeは起動するたびに自動でこのファイルを読み込み、毎回ゼロから説明しなくてもプロジェクトの文脈を把握した状態で作業を始められます。書くべき主な内容は5つに集約されます。第1に「プロジェクトの概要」、第2に「使用している技術スタック」、第3に「コーディング規約とスタイル」、第4に「やってはいけないこと（禁止事項）」、第5に「よく使うコマンドや手順」です。書き方のコツは、曖昧な日本語ではなく具体的な指示にすること、長文ではなく箇条書きで簡潔にまとめること、そして変化があったら都度更新することです。長すぎると逆に重要なルールが埋もれてしまうので、目安は500行以内、できれば300行程度に抑えるのが理想です。@インポート機能を使えば、複数のファイルに分割して管理することもできます。CLAUDE.mdを整備するかしないかで、ClaudeCodeの作業品質は劇的に変わります。最初の30分を投資して書いておく価値が、その後の数十時間の効率化となって返ってきます。
CLAUDE.mdとは何か
CLAUDE.mdは、ClaudeCodeが特定のプロジェクトディレクトリで起動されたときに、自動的に読み込む特別なマークダウンファイルです。中身は普通のMarkdown形式で書かれており、人間も読めますし、ClaudeCodeも文脈として理解します。
ファイルの置き場所は主に3パターンあります。
- プロジェクトルート: 各プロジェクトのトップディレクトリに置く。そのプロジェクトでだけ有効
- サブディレクトリ: 特定のフォルダ配下にだけ適用したい指示を書ける
- ユーザーグローバル:
~/.claude/CLAUDE.mdに置くと、すべてのプロジェクトで有効になる
ClaudeCodeはこれらを階層的に読み込み、より深い場所のルールを優先します。例えばグローバルで「コメントは英語で」と書いていても、特定プロジェクトのCLAUDE.mdで「コメントは日本語で」と上書きすれば、そのプロジェクトでは日本語が優先されます。
書く前に決めておくべきこと
闇雲に書き始めるとまとまりのない長文になりがちです。書く前に次の3点を整理しておきましょう。
- 「このプロジェクトを誰かに30秒で説明するなら、何を伝えるか」
- 「ClaudeCodeに毎回伝えていた指示は何か」
- 「絶対にやってはいけないことは何か」
この3つに答えられれば、CLAUDE.mdの骨格はほぼ完成です。
基本構成のテンプレート
まずはコピペで使える基本テンプレートを示します。
# プロジェクト概要
- 名称: 〇〇システム
- 目的: 〇〇を効率化する社内ツール
- 利用者: 営業部メンバー約20名
# 技術スタック
- フレームワーク: Next.js (App Router)
- 言語: TypeScript
- スタイル: Tailwind CSS
- DB: Cloudflare D1
- ホスティング: Cloudflare Workers
- 認証: Cloudflare Access
# コーディング規約
- インデントはスペース2つ
- セミコロン必須
- 変数名はキャメルケース
- コンポーネントはPascalCase
- ファイル名はkebab-case
# 禁止事項
- APIキーやトークンをコードに直接書かない（環境変数を使う）
- 個人情報をコミットしない
- node_modules を編集しない
- main ブランチに直接 push しない
# よく使うコマンド
- 開発サーバー起動: `npm run dev`
- ビルド: `npm run build`
- デプロイ: `npm run deploy`
- テスト: `npm test`
# プロジェクト固有のルール
- ページ追加時は app/ 配下に作成
- DBスキーマ変更は migration ファイルを必ず作る
- 環境変数追加時は .env.example も更新する
このテンプレートをプロジェクトに合わせて書き換えるだけで、すぐに使い始められます。
効果的な書き方の5つの原則
原則1: 具体的に書く
「綺麗なコードを書いてください」ではなく「関数は1つあたり50行以内、引数は4つまで」のように、判断基準を明示します。
# Good
- 関数は50行以内、引数は4つまで
- ネストは3階層まで
# Bad
- 綺麗なコードを書いてください
- なるべくシンプルに
原則2: 箇条書きを多用する
長文の段落より、箇条書きのほうがClaudeCodeも人間も読みやすいです。
原則3: やってほしいことだけでなく、やってほしくないことも書く
「禁止事項」セクションは特に重要です。AIは指示されないと「常識的に避けるべきこと」をやってしまう場合があります。
原則4: 例を示す
抽象的な説明より、Good/Badの具体例を示したほうが伝わります。
# 命名規則の例
- Good: getUserName, fetchOrderList
- Bad: get_user_name, GetUserName, getusername
原則5: 定期的に見直す
プロジェクトが進化すると、CLAUDE.mdの内容も古くなります。月に1回程度、見直して更新する習慣をつけましょう。
用途別の記述例
Webアプリ開発向け
# ディレクトリ構成
- app/ : ページとレイアウト
- components/ : 再利用可能なUIコンポーネント
- lib/ : サーバーサイドのロジック
- types/ : 型定義
# コンポーネント設計のルール
- props は必ず型を定義する
- 状態管理は useState を基本とし、複雑な場合のみ Zustand を使う
- 副作用は useEffect ではなく、可能な限りサーバーコンポーネントで処理する
データ分析プロジェクト向け
# データの取り扱い
- 元データ（raw/）は絶対に書き換えない
- 加工後のデータは processed/ に保存
- pandas は import pandas as pd で読み込む
- 大きなデータは parquet 形式で保存する
# 出力ルール
- グラフは figures/ に保存
- ファイル名は YYYYMMDD_内容.png の形式
社内ツール向け
# セキュリティ要件
- 認証は Cloudflare Access に任せる（独自実装しない）
- DB アクセスは必ず prepared statement を使う
- ログに個人情報を出力しない
- エラーメッセージにスタックトレースをユーザーに見せない
@インポート機能を使う
CLAUDE.mdが長くなりすぎたら、@記法で別ファイルを読み込むことができます。
# プロジェクトルート
プロジェクトの基本情報はここに記載
# 詳細ドキュメント
@docs/architecture.md
@docs/coding-standards.md
@docs/deployment.md
このように書いておくと、ClaudeCodeは指定したファイルも合わせて読み込みます。役割ごとにファイルを分けることで、保守性が向上します。
ただし、無限ループになるような循環インポートは避けてください。また、インポートするファイルもプロジェクト内に置いておくのが基本です。
グローバルとプロジェクト別の使い分け
~/.claude/CLAUDE.mdに書くべき内容と、各プロジェクトに書くべき内容は分けるのがおすすめです。
グローバル（共通設定）
- 自分の好みの説明スタイル（例: 平易な日本語で）
- セキュリティ上の絶対ルール（例: APIキーを直書きしない）
- 自分のスキルレベル（例: 非エンジニア）
プロジェクト別
- 技術スタック
- ディレクトリ構成
- そのプロジェクト固有のコマンド
- そのプロジェクトの規約
この役割分担を意識すると、CLAUDE.mdが管理しやすくなります。
よくある書き方ミス
ミス1: 長すぎる
熱意のあまり1000行、2000行と書いてしまうと、重要なルールが埋もれます。300〜500行程度が目安です。
ミス2: 抽象的すぎる
「品質の高いコードを書く」「ベストプラクティスに従う」のような表現は、ClaudeCodeにとっても判断が難しい指示です。具体的な基準で書き直しましょう。
ミス3: 矛盾している
「TypeScript で書く」と書いた直後に「.js ファイルで保存」のような矛盾は、ClaudeCodeを混乱させます。書いた後に通読して矛盾がないかチェックしましょう。
ミス4: 古い情報を放置
技術スタックを変更したのにCLAUDE.mdが古いまま、というケースは要注意。古い指示を信じて間違ったコードが生成されます。
ミス5: 機密情報を書いてしまう
CLAUDE.mdはgitで共有することが多いので、APIキーやパスワードは絶対に書かないでください。代わりに「環境変数 XXX に設定してある」とだけ書きます。
既存プロジェクトへのCLAUDE.md導入手順
すでに動いているプロジェクトにCLAUDE.mdを導入するときは、/initコマンドを使うのが手っ取り早いです。
cd /path/to/your/project
claude
/init
これだけで、ClaudeCodeがプロジェクトを分析して、CLAUDE.mdのたたき台を自動生成してくれます。生成された内容を確認し、必要に応じて加筆修正していきましょう。詳しくはinitコマンドの使い方を参照してください。
チーム開発でのCLAUDE.md
CLAUDE.mdはチームで共有することで真価を発揮します。メンバー全員のClaudeCodeが同じルールで動作するようになるので、コードの一貫性が保たれます。
チーム導入のポイントは次の通りです。
- CLAUDE.mdをgitで管理し、変更はPRレビューを通す
- 個人的なメモは別ファイル（CLAUDE.local.mdなど）に分ける
- 新メンバー参加時はCLAUDE.mdの読み込みを推奨する
- ルール変更時はチーム全員に通知する
高度な使い方: 条件付き指示
特定の条件下でのみ有効なルールを書きたい場合、自然言語で条件を明示します。
# テストコードを書くとき
- フレームワークは Jest を使う
- ファイル名は *.test.ts
- describe で機能ごとにグループ化する
# 本番デプロイ前
- 必ず npm run lint を実行
- すべてのテストがパスすることを確認
- READMEのバージョン情報を更新
このように「いつ」「どんなとき」というコンテキストを明示しておくと、ClaudeCodeが状況に応じて適切にルールを適用してくれます。
FAQ
Q1. CLAUDE.mdは必ず作らないといけませんか?
必須ではありません。なくてもClaudeCodeは動きます。ただし、同じプロジェクトで継続的に作業するなら、作っておいたほうが圧倒的に効率が良くなります。
Q2. CLAUDE.mdは何文字くらいが適切ですか?
明確な制限はありませんが、5000〜15000字程度が読みやすい範囲です。それ以上になるなら、@インポートで分割を検討してください。
Q3. グローバルとプロジェクトで設定が競合したらどうなりますか?
より具体的・より近いスコープのルールが優先されます。プロジェクトのCLAUDE.mdがグローバルを上書きする形になります。
Q4. gitに含めるべきですか?
基本はYesです。チームで共有することでメリットが最大化されます。ただし個人的なメモを書いたCLAUDE.local.mdは.gitignoreに入れて共有しないのが普通です。
Q5. 自然言語と箇条書き、どちらがいいですか?
箇条書きが基本的におすすめです。読みやすく、ClaudeCodeも構造を理解しやすいからです。
Q6. CLAUDE.mdを書いたのに反映されません
正しい場所に置かれているか確認してください。ClaudeCodeを再起動すると確実に再読み込みされます。また、/clearで会話履歴をリセットすると、新しいルールが効きやすくなります。
Q7. 機密情報は書いていいですか?
絶対にダメです。APIキー、パスワード、個人情報は書かないでください。代わりに「環境変数を参照する」など、参照先だけを書きます。
まとめ
CLAUDE.mdは、ClaudeCodeを使い続ける上で最も投資対効果が高い設定ファイルです。最初の30分を使って整備しておけば、その後の作業効率が劇的に向上します。書き方のコツは、具体的に、簡潔に、定期的に更新すること。テンプレートをそのまま使うのもよし、@インポートで分割するのもよし、自分のプロジェクトに合った形でカスタマイズしていきましょう。重要なのは、完璧を目指さずまず書き始めること。CLAUDE.mdは生きたドキュメントです。プロジェクトの成長と共に育てていくものだと考えれば、最初の一歩はとても気軽に踏み出せるはずです。