CLAUDE.md の書き方。プロジェクトの取扱説明書を Claude へ

はじめに

Claude Code を触り始めて少し慣れてくると、たいてい同じ違和感にたどり着きます。

「先週も似たようなことを伝えた気がする」「このプロジェクトは Astro を使っているので、Next.js の流儀でコードを書かないでほしい」「日本語で返してほしいのに、また英語で返ってきた」

その違和感の正体は、Claude が「このプロジェクトの空気」を覚えていない ことです。会話を新しく始めるたびに、毎回最初から全部伝え直さないといけない——これは消耗します。

その面倒を一手に引き受けてくれるのが、CLAUDE.md と呼ばれる1枚の Markdown ファイルです。

Claude Code は起動時に、プロジェクトの直下にある CLAUDE.md を 自動で読み込む 仕組みになっています。毎回伝えていたことを1回ここに書いておけば、以降は「もう知っているよ」という前提で会話が始まる。指示の手数が一段減ります。

この記事では、CLAUDE.md に何を・どう書けば、Claude にプロジェクトの空気を伝えられるかを、実際にこのメディア（マギのクロゼミ）の運用例を交えて整理します。

CLAUDE.md とは何か

ひと言でいうと、CLAUDE.md は プロジェクトの取扱説明書 です。

Claude Code を claude コマンドで起動すると、Claude は最初に作業ディレクトリの中を見て、CLAUDE.md という名前のファイルがあれば 会話の最初に丸ごと読みます。読まれた内容は、以降のすべてのやり取りに前提として効き続けます。

イメージとしては、Web 制作で <head> に書く meta タグに近いです。meta は本文に表示されないけれど、ブラウザや検索エンジンに「このページはこういう設定です」と伝える役目を持ちます。CLAUDE.md もちょうどそれと同じで、会話の本体には登場しないけれど、会話のすべてに影響を与える 隠れた前提として動きます。

置く場所は3階層あります。

階層	場所	用途
ユーザー全体	`~/.claude/CLAUDE.md`	すべてのプロジェクトに共通で効かせたい指示
プロジェクト	`<プロジェクト直下>/CLAUDE.md`	このプロジェクトだけの指示
サブディレクトリ	任意のフォルダ内の `CLAUDE.md`	その配下で作業しているときだけ追加で読まれる指示

ユーザー全体に書いた指示が一番広く効き、サブディレクトリに置いたものはそのフォルダで作業しているときだけ追加されます。今回扱うのは、真ん中の プロジェクト直下の CLAUDE.md です。

/init で雛形を見てみる

Claude Code には、CLAUDE.md の雛形を自動生成してくれる便利な機能があります。プロジェクトのルートディレクトリで claude を起動して、/init と打つだけです。

> /init

これを打つと、Claude は黙々とプロジェクトの中を覗き始めます。ファイル構成、package.json、README.md、よく出てくるディレクトリ名——だいたい1〜2分かけて、プロジェクトの全体像を読み取ります。

そのあと、こんな構成の CLAUDE.md がプロジェクト直下に作られます。

概要（このプロジェクトは何をするものか）
セットアップ手順
よく使うコマンド
ディレクトリ構成
コーディング規約（言語・フレームワークから推測）

この雛形、出来は悪くありません。事実ベースの内容（フレームワーク、ファイル構成）はかなり正確に書かれます。ただ、ここで安心して終わってしまうと、肝心な部分が抜け落ちる ことになります。

雛形だけでは足りない理由

雛形が拾ってくれるのは、コードを読めば分かる「事実」だけです。書かれていないけれど大事なものが、たくさん残ります。

このプロジェクトでは「修正する前に必ず確認する」のが慣習になっている
過去にハマった失敗の記憶（同じ失敗を繰り返してほしくない）
ドキュメントは増やさず、既存ファイルを更新する文化
出力スタイル：絵文字を使わない・前置きを書かない
「強い操作は必ず確認する」という運用ルール

このあたりは、コードを読んでも書かれていないから拾えません。プロジェクトの空気 とでもいうべき、暗黙の前提です。

これを CLAUDE.md に書き足してこそ、Claude が「このプロジェクトの一員」として動けるようになります。/init の出力をそのまま使うと、Claude は「優秀だけど初日のフリーランス」のままです。慣習を伝えてはじめて、半年いる中堅メンバーになります。

ここから先は、その「空気」を文章にする作業の話です。

CLAUDE.md に書くべき5つのこと

何を書くべきかを整理すると、5つに集約されます。

a. プロジェクトの目的・前提

最初に 「このプロジェクトは何のために存在するか」 を1〜3行で書きます。

## このプロジェクト

マギのクロゼミ（Claude × AI × Web制作の学習メディア）の Astro 実装。
記事は src/content/posts/ 配下の Markdown で管理する。
本番デプロイは Cloudflare Pages、ドメインは magi-kurozemi.com。

これがないと、Claude は判断のたびに迷います。「メディアサイト」と知っていれば、SEO・読みやすさ・記事一覧の見栄え——優先順位の付け方が変わります。「業務システム」と知っていれば、可読性より厳格性に寄せます。判断軸の最上位 にあたる情報なので、必ず冒頭に置きます。

b. ファイル運用ルール

次に書くべきは、「どこに何を置くか」のルールです。

## ファイル運用

- 新しい記事 → src/content/posts/<slug>.md
- 共通レイアウト → src/layouts/
- ページ単位のコンポーネント → src/components/
- 画像 → src/assets/（型安全に扱うもの）/ public/（直接配置でOKなもの）

これを書かないと、Claude は 「ありそうな場所」に勝手に作ってしまう ことがあります。レイアウトファイルが急に src/utils/ の中に生まれたり、画像が public/img/ という独自フォルダに置かれたり。発見が遅れると、あとから整理するのが面倒になります。

c. 守ってほしいこと・やめてほしいこと

ここが一番効きます。「やってほしいこと」と「やらないでほしいこと」を、はっきり分けて書く 区分です。

## 必ず守ること
- 推測で情報を補わない。不明点は質問する
- 大きな変更の前に計画を提示して承認を得る
- ファイルを変更したら何をどう変えたか簡潔に報告する

## やらないこと
- 指示された範囲を超えた「ついでの改善」
- 新規ライブラリ・外部サービスの無断導入
- ドキュメントファイルを勝手に増やす

特に「やらないこと」が大事です。Claude は基本的に親切なので、放っておくと「ついでに ESLint 入れておきました」のような気を利かせ方をします。それが嬉しい場合もあれば、迷惑な場合もある。何を嬉しがらないかを言語化する のが、CLAUDE.md の核心です。

d. 出力スタイル

口調・装飾の好みも書いておくと、毎回の体験が安定します。

## 出力のルール
- 前置き・総評は省略可
- 技術的な指摘は具体的に（ファイル名・行番号・修正案）
- 絵文字・過剰な装飾は使わない
- 反論は遠慮なく行う

「絵文字を使わない」は地味ですが効きます。これを書いておかないと、Claude は読みやすさのために絵文字を散りばめがちです。好みでない表現を 先回りして遮断する ことができます。

e. 参照ファイルへのリンク

最後に、CLAUDE.md からほかのドキュメントへ橋を架けます。

## 関連ファイル
- 戦略：[marketing/content/keyword-map.md](./marketing/content/keyword-map.md)
- 直近の意思決定：[secretary/notes/](./secretary/notes/)
- 部署別ルール：[marketing/CLAUDE.md](./marketing/CLAUDE.md)

CLAUDE.md 1枚にすべての情報を詰め込むと、すぐに肥大化して読まれなくなります。「詳しい話はあっち」と外に逃がす導線を持たせるのが、長く使える CLAUDE.md の作り方です。

書き方のコツ

書き終えたあと、いつも気をつけているコツが3つあります。

1. 短く書く。1ルール1〜2行が目安です。長く書くと読まれません。Claude は人間と違って長い文章でも全部読んではくれますが、長文の指示はほかの指示と矛盾を起こしやすくなります。短文の方が安全です。

2. 具体的に書く。「丁寧に書く」ではなく「ファイル名・行番号・修正案を含めて書く」と書きます。「気をつける」ではなく「実行前に必ず確認する」と書きます。動詞と目的語をはっきりさせる のが、効くルールの条件です。

3. Why を添える。守ってほしいルールには、できる範囲で理由を1行加えます。「強い操作は必ず確認する。過去に手を滑らせて重要なファイルを上書きした経験があるため」のように書くと、Claude はエッジケースで判断できるようになります。理由を書かないと、ルールが形骸化したときに「これは無視していい」と判断されることがあります。

ありがちな失敗

私自身、何度かやらかしてきた失敗があります。

1つめ：肥大化。CLAUDE.md は気をつけないとどんどん長くなります。200行を超えた頃から、書いたのに守られないルール が出始めます。これは Claude が悪いのではなく、優先度を判断しきれなくなるのが原因です。150行を目安に、超えたら別ファイルへ逃がす のが安全圏です。

2つめ：抽象論。「丁寧に書く」「ユーザーに優しく」などの抽象的な指示は、ほぼ効きません。Claude も人間と同じで、抽象論は 解釈の幅が広すぎて指針にならない からです。具体に落とし切れないルールは、いっそ書かないほうが CLAUDE.md は引き締まります。

3つめ：矛盾。書き足していくうちに、過去のルールと新しいルールがぶつかることがあります。「英語で書く」と書いてあるのに「日本語で報告する」と追記したり。追記時に矛盾チェックを必ず行う ようにしておくと事故が減ります。

4つめ：他人事。ありがちなテンプレを貼り付けただけの CLAUDE.md は機能しません。自分の言葉で、自分のプロジェクトに合わせて書いた指示 だけが、Claude にも自分にも残ります。

振り返りチェックリスト

書き終わったあと、こんな問いで点検しています。

行数は150行以内に収まっているか
1行ずつ「動詞＋目的語」がはっきりしているか
「やらないこと」セクションがあるか
過去にやらかした失敗のうち、再発防止したいものが書かれているか
矛盾するルールが共存していないか
関連ドキュメントへのリンクがあるか

ここが揃っていれば、CLAUDE.md は 書いた瞬間から効く 道具になります。

まとめと次回

CLAUDE.md は、Claude にプロジェクトの取扱説明書を渡す行為です。最初は雛形を /init で生成して、そこに「コードを読んでも分からない、自分のプロジェクトの空気」を書き足していく——この順番が一番ラクです。

書き終えたあとも、運用しながら追記・削除を繰り返すのが現実的です。最初から完璧を目指さず、Claude が「やらかした」「気が利いた」を見るたびに、CLAUDE.md に1行足す。1ヶ月もすれば、自分専用の指示書が育ちます。

次回は、CLAUDE.md と Skills・Slash Commands をどう使い分けるかを整理します。CLAUDE.md は「常に効かせたいルール」、Skills は「呼び出したいときに呼べる専門知識」、Slash Commands は「単発の操作命令」——それぞれの守備範囲を明確にすれば、プロンプト設計の地図が完成します。