「Claudeに毎回同じことを説明している気がする……」
Claude Code（Anthropic社のコーディング支援AI）を使い始めて少し経つと、多くの人がこの違和感に気づきます。プロジェクトの構成、使っているフレームワーク、命名ルール、テストコマンド——本来一度伝えれば済むはずの情報を、新しいセッション（AIとの一連のやり取り）のたびに繰り返し書いている。実は私も最初の1か月、これでかなりの時間を溶かしました。
その悩みを解決してくれるのがCLAUDE.mdというファイルです。本記事では、AI初心者の方でも今日から書き始められるよう、CLAUDE.mdの正体と書き方を15分でまとめてお伝えします。読み終えた頃には、同僚に「CLAUDE.mdって何？」と聞かれたら30秒で自分の言葉で説明できる状態を目指します。
![[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]](https://hbb.afl.rakuten.co.jp/hgb/19ae8be4.e750202b.19ae8be5.ab17822b/?me_id=1213310&item_id=21793433&pc=https%3A%2F%2Fthumbnail.image.rakuten.co.jp%2F%400_mall%2Fbook%2Fcabinet%2F3540%2F9784297153540_1_34.jpg%3F_ex%3D240x240&s=240x240&t=picttext "[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]")
目次
CLAUDE.mdとは？──プロジェクトの「取扱説明書」
CLAUDE.mdは、Claude Codeが起動時に自動的に読み込む、Markdown（マークダウン：見出しや箇条書きを記号で書ける軽量な文書形式）で書かれたコンテキストファイルです。
「コンテキスト」とは、AIに渡す前提情報のこと。ざっくり言えば、「うちのプロジェクトはこういうルールで動いていますよ」とClaudeに先回りで教える"取扱説明書"のようなものです。Claudeはこのファイルを毎回のセッション開始時に読んでから作業を始めるので、あなたが説明を省略しても、空気を読んだ提案をしてくれるようになります。
新しくジョインしたエンジニアに渡すオンボーディング資料を、AI向けに用意するイメージが一番近いかもしれません。
なぜCLAUDE.mdを書くと効くのか
CLAUDE.mdを整えるメリットは大きく3つあります。
1. 回答精度が上がる
プロジェクト固有の事情（使用言語、フレームワーク、社内ルール）を最初から共有できるので、的外れな提案が減ります。
2. やり取りが速くなる
「TypeScriptで」「テストはJestで」といった前提を毎回打ち込む必要がなくなり、本題からスタートできます。
3. チーム全員のClaudeが同じ品質になる
CLAUDE.mdをGitで管理すれば、チームメンバーのClaudeが全員同じルールで動くようになります。属人化していた「Claudeへの上手な頼み方」を共有資産にできるわけです。これは個人的に最大の恩恵だと感じています。
CLAUDE.mdは3か所に置ける（どこに置くか判断フロー）
CLAUDE.mdは配置場所によって適用範囲が変わります。まずは表で全体像をつかみましょう。
| 配置場所 | パス例 | 適用範囲 | 主な用途 |
|---|---|---|---|
| プロジェクトルート | ./CLAUDE.md | そのプロジェクト全体 | プロジェクト固有のルール |
| サブディレクトリ | ./src/api/CLAUDE.md | そのフォルダ配下のみ | 特定モジュールの細かいルール |
| ユーザーホーム | ~/.claude/CLAUDE.md | あなたが扱う全プロジェクト | 個人の好み（口調・出力形式など） |
書き方の5つのコツ（悪い例 → 良い例つき）
テンプレートだけでは伝わらない、実践で効いてくるコツを5つにまとめます。
1. 簡潔に書く
CLAUDE.mdは毎セッション読み込まれるので、長すぎるとAIの処理コスト（トークン：AIが文章を処理する単位）が増え、応答も遅くなります。「1項目1〜2行」を意識しましょう。
2. "やってほしくないこと"も書く
「〜する」だけでなく「〜しない」も同じくらい重要です。例えば「テストを勝手に削除しない」「データベース構造を変更するときは必ず確認を取る」など、ガードレールを敷くと安心です。
3. 抽象論ではなく具体例を入れる
ここが一番効きます。「悪い例」と「良い例」を並べてみましょう。
❌ 悪い例（抽象的でAIが判断できない）
# コーディング規約
- 読みやすいコードを書く
- 関数は小さくする
- ちゃんとエラーハンドリングをする⭕ 良い例（基準が明確でAIが従える）
# コーディング規約
- 1関数50行以内（超えそうなら分割を提案して）
- 関数名は動詞始まり (例: `fetchUser`, `validateInput`)
- 外部API呼び出しは必ず try-catch で囲み、失敗時はログ出力抽象的な指示は、AIにも人間にも"なんとなく"しか伝わりません。判断に迷ったときの基準になる粒度で書くのがコツです。
4. 会話の中で育てる
「これ、CLAUDE.mdに追記しておいて」と頼めば、Claude自身が更新してくれます。最初から完璧を目指さず、運用しながら育てるスタイルがおすすめです。
ちなみに、プロジェクトを横断して使い回したい技能（例：「コミットメッセージはこの形式で」「テストはこのパターンで書く」など）は、Claude Skillsという別の仕組みに切り出すと、さらにスッキリ整理できます。CLAUDE.md＝プロジェクト固有、Skills＝横断的なノウハウ、と覚えておくと迷いません。
5. Markdownの見出しで構造化する
# や ## でセクション分けすると、Claudeも人間も該当箇所を探しやすくなります。長文の散文より、見出し＋箇条書きが基本です。
ありがちな失敗と対処法
失敗①：盛り込みすぎて逆に読まれない
社内Wikiを丸ごとコピペしてしまうケース。CLAUDE.mdが肥大化すると、肝心な指示が埋もれます。
対処法：詳細はリポジトリ内の別ドキュメント（例：docs/architecture.md）に切り出し、CLAUDE.mdには「アーキテクチャの詳細は docs/architecture.md を参照」とリンクだけ書きましょう。
失敗②：更新されず化石化する
書いた直後はピカピカでも、半年後には実態と乖離していることがよくあります。古い情報はむしろ害になります。
対処法：プロジェクトのルール変更があったタイミングで、必ずCLAUDE.mdも見直す。プルリクエストのチェックリストに「CLAUDE.mdの更新は必要ないか？」を入れておくと忘れにくくなります。
失敗③：機密情報を書いてしまう
APIキーや顧客情報をうっかり書き、Gitにコミットしてしまう事故です。
対処法：CLAUDE.mdはGitで共有される前提のファイルだと意識する。秘密情報は環境変数（.env）に逃がし、CLAUDE.mdには「APIキーは .env を参照」程度にとどめましょう。
まとめ
ポイントを振り返ります。
- CLAUDE.mdは、AI（Claude）に毎回同じ説明をしなくて済むようにするコンテキストファイル
- 配置場所はプロジェクトルート／サブディレクトリ／ユーザーホームの3か所。迷ったらプロジェクトルートから
- 中身は「プロジェクト概要・技術スタック・ディレクトリ構成・規約・コマンド・注意事項」をMarkdownで簡潔に
- 具体的に・短く・"してほしくないこと"も書くのがコツ。抽象論はAIに伝わらない
- 一度書いて終わりにせず、会話の中で育てていく
最後に
CLAUDE.mdは、AIとの協働を「毎回ゼロから」ではなく「いつもの続きから」に変えてくれる小さな魔法です。完璧なものを最初から書こうとせず、まずは10分でテンプレートをコピペし、自分のプロジェクトに合わせて整えるところから始めてみてください。
明日Claudeを開いたとき、「あ、わかってるね」と感じる回数が確実に増えるはずです。
そして、CLAUDE.mdに慣れてきたら、ぜひ次のステップとしてClaude Skillsの解説記事にも進んでみてください。「プロジェクト固有のCLAUDE.md」と「横断的に使えるSkills」の両輪がそろうと、AIとの協働が一段と楽になります。
それでは、よきAI協働ライフを！
![[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]](https://hbb.afl.rakuten.co.jp/hgb/19ae8be4.e750202b.19ae8be5.ab17822b/?me_id=1213310&item_id=21763777&pc=https%3A%2F%2Fthumbnail.image.rakuten.co.jp%2F%400_mall%2Fbook%2Fcabinet%2F2758%2F9784297152758_1_58.jpg%3F_ex%3D240x240&s=240x240&t=picttext "[商品価格に関しましては、リンクが作成された時点と現時点で情報が変更されている場合がございます。]")