メインコンテンツへスキップ
見出し画像

Claude CodeのCLAUDE.mdの書き方｜「書けば効く」ではなく「削るほど効く」

    AIを使う全ての人へ｜WEEL

    Claude Codeを使い始めると、早い段階で作ることになるファイルが CLAUDE.mdです。

    必須ではありませんが、公式も/initでの作成を勧めています。そして、使い込んだ人がいちばん後悔しているのも、たいていこのファイルです。

    • 「日本語で答えて」

    • 「太字は使わないで」

    • 「テストを先に書いて」

    気づいたことを片っ端から書き足していくと、数ヶ月後には200行を超えた指示書ができあがります。

    そして、書いてあるはずのルールが守られにくくなります。

    本記事は、CLAUDE.mdを「書けば効くもの」ではなく、「毎回コンテキストを消費する、限りある枠」として設計するための記事です。公式ドキュメントの仕様を土台に、私が実際に運用しているファイルやそのまま使えるテンプレートを紹介します。

    CLAUDE.mdとは何か

    CLAUDE.mdは、Claude Codeがセッション開始のたびに自動で読み込むMarkdownファイルです。書いておけば、毎回同じ説明を繰り返す必要がなくなります。

    押さえておきたいのは、公式ドキュメントが繰り返し書いている次の一文です。

    Claude treats them as context, not enforced configuration.
    日本語訳：クロードはそれらを、強制的な設定ではなく、コンテキストとして扱っています。

    CLAUDE.mdは「設定」ではなく「文脈」です。

    内部的には、システムプロンプトの後ろにユーザーメッセージとして差し込まれ、Claudeがそれを読んで従おうとします。

    だから、曖昧な指示や矛盾した指示は素通りしますし、長すぎれば埋もれます。「絶対に守らせたい」ことをCLAUDE.mdに書くのは、そもそもファイルが違います。

    ※強制したいならHooksや権限設定の拒否ルールpermissions.denyの仕事です。

    CLAUDE.mdの置き場所は4箇所

    CLAUDE.mdは複数の場所に置けて、それぞれ効く範囲が違います。公式の一覧を、読み込まれる順に並べます。

    画像

    ここで間違えやすいのは、上書きではなく結合されるという点です。

    ユーザー層に「日本語で」、プロジェクト層に「英語で」と書けば、Claudeは両方を読んだうえでどちらかを選びます。

    「近いほうが優先される」という保証はありません。公式も「矛盾する2つのルールがあると、Claudeは任意に一方を選ぶことがある」と明記しています。

    また、プロジェクトのサブフォルダに置いたCLAUDE.mdは、起動時には読まれません。

    Claudeがそのフォルダのファイルを読んだときに、はじめて読み込まれます。「フロントエンド配下だけの約束」を書くのに向いていますが、起動直後から効いてほしい前提を書く場所ではありません。

    CLAUDE.mdをデスクトップ版でどう作る・どう開くか

    CLAUDE.mdはただのテキストファイルなので、作り方は3つあります。

    1. Claudeに頼む：「このプロジェクトのCLAUDE.mdを作って。ビルドはnpm run build、テストはnpm test」と伝えれば、その場で書いてくれます。

    2. /initを実行する：プロンプト入力欄で「/」を打つとスラッシュコマンドの一覧が出ます。/initを選ぶと、Claudeがコードベースを分析して、ビルドコマンドやテスト手順、規約を拾った叩き台を作ります。すでにCLAUDE.mdがある場合は上書きせず、改善案を出してくれます

    3. 内蔵エディタで直接編集する：デスクトップ版にはファイルエディタのペインがあります（v1.2581.0以降）。ファイルツリーから開いて直接書き換えられます

    ファイルの一覧と編集は/memoryからもできます。

    ユーザー層・プロジェクト層のCLAUDE.mdやCLAUDE.local.mdが並び、選ぶとエディタで開きます。

    一方、実際に読み込まれているかの確認は/contextです。Memory filesの欄に、いま効いているCLAUDE.mdの一覧が出ます。ここに無いファイルは、どれだけ丁寧に書いてもClaudeには見えていません。

    CLAUDE.mdに何を書き、何を書かないか

    公式のベストプラクティスに、CLAUDE.mdの各行に対して問うべき質問が書かれています。

    "Would removing this cause Claude to make mistakes?" If not, cut it.
    日本語訳：「これを削除すると、クロードがミスを犯すことになるだろうか？」 そうでなければ、削除してください。

    「この行を消したら、Claudeは間違えるか？」間違えないなら消す。これだけです。このフィルタを通すと、多くの人のCLAUDE.mdは半分以下になります。

    公式が挙げている「書くもの／書かないもの」を整理します。

    画像

    右の列で特に多いのが「ファイルごとの説明」と「言語の一般的な規約」です。

    どちらもClaudeは自力で把握できます。ただしフォルダ構成については線引きがあって、公式は「プロジェクトのレイアウト」を常時持たせる事実の例に挙げています。

    コードを見れば自明なファイル一覧は不要、見ても分からない構造（モノレポの役割分担など）は残す、と考えると良いでしょう。

    書いてあること自体が害になるわけではないのですが、その行が「本当に守ってほしい1行」を埋もれさせます。

    なぜ「書きすぎ」が逆効果になるのか

    公式は1ファイルあたり200行以下を目安にしています。理由は2つです。

    1. コンテキストの消費：CLAUDE.mdは毎セッション、会話と同じ枠に読み込まれます。長いほど、実作業に使える余地が減る

    2. 指示追従の低下：公式の表現をそのまま借りると「Bloated CLAUDE.md files cause Claude to ignore your actual instructions!」。膨らんだファイルは、本当の指示を無視させることになります。

    2つ目については、Claude Codeの活用事例を多く発信しているHumanLayer社の記事が具体的な数字を出しています。

    同社は「厳密に研究されたテーマではない」と断ったうえで、限定的な研究を踏まえ、最前線のLLMが安定して従える指示は150〜200個程度、指示が増えると新しい指示だけでなく全体の追従品質が一様に落ちる、と紹介しています。

    画像
    参考：https://www.humanlayer.dev/blog/writing-a-good-claude-md

    さらに同社の独自解析では、Claude Code自身のシステムプロンプトにすでに50個前後の指示が含まれているとされます。

    いずれも経験則の域を出ないので目安に留めるべきですが、「枠は有限で、しかも思っているより狭い」という感覚は、この数字で掴めると思います。

    だから、CLAUDE.mdは足し算ではなく引き算で設計します。

    書き足すときは、代わりに何を消すかを一緒に考える。この習慣があるかどうかで、半年後のファイルの質が決まります。

    「自社だけでClaude Codeをうまく活用できるか不安」「どこから手をつければいいかわからない」という方がいらっしゃれば、私たちWEELにご相談ください。

    Claude Codeの導入支援からプロンプト設計、社内展開のサポートまで、実務に即した形でしっかり伴走します。

    CLAUDE.mdに書かないものは、どこに書くのか

    「消せ」と言われても、消した指示が必要なものだったら困ります。実際には消すのではなく、正しい置き場所へ移すのがほとんどです。

    Claude Codeには、CLAUDE.md以外にも受け皿があります。サブエージェントや設定ファイルも含めればもっとありますが、代表的なのは次の4つです。

    画像

    判断の順番はこうです。

    ①手順になっていないか？「デプロイは①テスト②ビルド③……」のような番号付きの段取りが育ってきたら、それはスキルです。
    CLAUDE.mdには事実だけを残し、手順はSKILL.mdに移して名前で呼べるようにします。

    ②守られないと困るものか？「.envは触らないで」「編集後はフォーマッタをかけて」
    これをCLAUDE.mdに書いても、守られる保証はありません。公式も「特定のタイミングで必ず実行したいものはフックとして書け」と言い切っています。

    ③特定のファイルにしか関係ないか？「APIのハンドラには必ず入力検証を」のような、src/api/配下でしか意味のないルールは、.claude/rules/にパスを指定して置きます。

    ---
paths:
  - "src/api/**/*.ts"
---

# API開発ルール
- すべてのエンドポイントに入力検証を入れる
- エラーレスポンスは共通フォーマットを使う

    pathsを付けたルールは、Claudeが該当ファイルを読んだときだけコンテキストに載ります。

    ④自分で書く必要があるか？「pnpmを使って、npmじゃなくて」と会話で訂正したことは、Claude自身が自動メモリに書き留めます。
    CLAUDE.mdにすでに書いてあることは重複して保存しない仕様なので、訂正は一度会話で伝え、定着させたいものだけCLAUDE.mdへ昇格させる運用にすると、CLAUDE.mdが訂正メモで膨らみません。

    この5つに振り分けたあとにCLAUDE.mdに残るのが、そのプロジェクト（またはあなた）の「前提」となります。

    筆者のCLAUDE.mdを紹介

    ここからは、私が使っている~/.claude/CLAUDE.md（全プロジェクト共通）を紹介します。

    # CLAUDE.md — 全プロジェクト共通の指示

## セキュリティ（最高優先度）
コーディング・実装タスクでは、着手前に必ず `secure-implementation` スキルを読むこと。
チェックリストの実体はそちらにあり、ここには重複させない。

このプロジェクト固有で、外から推測できない境界：
- 本業のデータを個人事業のコードに混入させない
- 新規パッケージはレジストリで実在・DL数・最終更新を確認してから入れる

## 作業スタイル
- PoC優先：動くものを最速で作る
- タスクが複雑な場合、先に計画を提示してから実装する
- ファイルを削除する前に必ず確認を取る
- 成果物に言及するときは必ずフルパスで表示する

## 技術スタック（優先順位順）
| カテゴリ | 使用技術 |
|---|---|
| 言語 | Python（第一言語）、TypeScript |
| フレームワーク | FastAPI、Next.js |
| DB | PostgreSQL、SQLite、Supabase |

## コードスタイル規約
### 大原則
既存コードがある場合は、その構造・命名・コメント密度に合わせる。
以下は新規作成時の既定であって、既存コードの流儀を上書きする理由にはならない。
### 新規作成時の既定
- Python：型ヒントを付ける。ログは `logging`（`print()` は使わない）
- 環境変数は `.env` から読む。コードに直接書かない

## 専用エージェントの自動呼び出し
| トピック | エージェント |
|---|---|
| 事業アイデア・GO/NO-GO判断 | `ceo` |
| 批判・弱点洗い出し | `devil` |
| コードレビュー・セキュリティ確認 | `reviewer` |

## トリガー → スキル対応
| ユーザーの発言 | 起動するスキル |
|---|---|
| 「おはよう」 | `morning` |
| 「TODO」「タスク整理」 | `todo` |

    見てほしいポイントは4つです。

    1.いちばん重要な項目に、手順を書いていない。セキュリティは私にとって最優先ですが、CLAUDE.mdに書いてあるのは「着手前にsecure-implementationスキルを読め」という1行のポインタだけです。

    100項目のチェックリスト本体はスキル側にあり、実装タスクのときだけ読み込まれます。

    2.「既存コードに合わせる」を、個別ルールより上に置いている。コードスタイルの節で最初に書いてあるのは「既存コードがあればそれに合わせる」です。ルールの優先順位は、書く順番と見出しの階層で表現します。

    3.表で「対応関係」だけを書いている。エージェントもスキルも、ここには「いつ・何を呼ぶか」の対応表しかありません。CLAUDE.mdは目次であって、本文ではありません。

    4.「外から推測できないこと」だけを境界として書いている。「本業のデータを個人事業のコードに混ぜない」は、コードを読んでも分かりません。「秘密情報をコミットしない」はClaudeがすでに知っているので書いていません。

    このファイルの実際の長さは、執筆時点で表と空行を含めて135行です。筆者の場合、今年6月に一度、大きく削りました。削ったもののほとんどは「スキルに移した手順」（朝のレポート、タスク整理、セキュリティチェックリスト）と「Claudeがすでにやれていたこと」です。

    個人用・非エンジニア向けCLAUDE.md

    開発以外の業務（資料作成、分析、文章）にClaude Codeを使う人向けのCLAUDE.mdです。実際に私が使っているものになります。

    # 全プロジェクト共通の指示

## 私について
- 職種：マーケティング担当。プログラミングは初心者
- Claude Codeの用途：週次レポート、SNS原稿、データ集計

## 出力の約束
- 回答は日本語。専門用語には（かっこ書き）で一言説明を添える
- 成果物は必ずファイルに保存し、保存先をフルパスで教える
- 提案は多くても2案まで。3案以上並べない

## 作業の進め方
- 3ステップ以上かかる作業は、先に手順を示してから着手する
- ファイルを削除・上書きする前に必ず確認を取る
- 分からないことは推測で進めず、質問する

## 触らないもの
- `個人/` フォルダ配下（私用ファイル）
- 拡張子 `.xlsx` の原本（コピーを作って作業する）

    「触らないもの」の節は、あくまでお願いです。

    本当に触られたくないファイルがあるなら、Hooksの記事で紹介した保護フックか、権限設定の拒否ルールを併用してください。

    CLAUDE.mdに書くのは「Claudeが理由を理解して避けられるようにする」ため、Hooksは「理解しなくても止まる」ためです。両方あって初めて安心できます。

    CLAUDE.mdは「前提」の目次

    CLAUDE.mdは、Claude Codeが毎回読む前提のファイルです。命令ではなく文脈として渡されるので、長くすれば長くするほど、本当に伝えたい1行が埋もれます。

    設計の原則を3つにまとめます。

    1. 「消したら間違えるか」で1行ずつ判定する。間違えないなら消す。フォルダ構成も、言語の一般常識も、Claudeは知っている

    2. 手順はスキルへ、強制はHooksへ、ファイル限定のルールは .claude/rules/へ。CLAUDE.mdに残るのは、それらへのポインタと、コードから読み取れない前提だけ

    3. 追記は「同じ訂正2回目」、削除は「守られなくなったとき」。足すときは、代わりに何を消すかを一緒に決める

    ぜひ本記事を参考にCLAUDE.mdを活用してみてください。

    WEELでは
    生成AIやAIエージェントに関する無料オンラインセミナーも開催中です！
    この機会にぜひお気軽にご参加いただけますと幸いです！
    ✅ セミナーに参加する

    生成AIの最新ニュース・事例・イベント情報をいち早く知りたい方は、ぜひWEELの無料メルマガをご購読ください！
    ✉️ メルマガに登録する

    💡 AI活用、どこから始めればいいかお悩みの方へ
    「Claude Codeの使い方を知りたい」
    「業務効率化をして、仕事を楽にしたい！」

    そんな方向けに、無料の個別相談をやってます！
    現場での事例も交えて、わかりやすくお話しします。
    ✨今すぐAIの専門家と話す✨

     
     

    AIを使う全ての人へ｜WEEL

     
     
    「日本一透明性の高いAIプロフェッショナル集団」を目指す株式会社WEELです。 社内外のセミナーレポやよくいただくご質問などをお届けします！ ビジネスユーザーが見るべき記事や最新情報については こちらのサイトからご覧ください。（https://weel.co.jp/）

    あなたへのおすすめ