CLAUDE.mdの書き方：42個のプロジェクトで使った実例

更新（2026年11月9日）：Claude Fable 5.2とMythos 5.2がリリースされ、料金・提供範囲・ベンチマークはClaude Fable 5.2まとめで解説しています。

👁 111閲覧数

私のディスクには、AIエージェント向けの指示ファイルが42個あります。16個のCLAUDE.mdと26個のAGENTS.mdで、それぞれ別のプロジェクトのフォルダーに置いています。最短は1行、最長は402行です。最長のファイルはAnthropicが推奨する長さの2倍で、こうしたファイルに何が書かれているのかをよく示しているので、まずはこれから紹介します。

CLAUDE.mdとは

CLAUDE.mdは、Claude Codeがセッションの開始時に読むMarkdownファイルです。エージェントとの会話は毎回、記憶が空の状態から始まります。そのため、コードを読んでも分からないことは、その都度伝える必要があります。CLAUDE.mdを使えば、テストのコマンドやプロジェクトのルール、エージェントにしてほしくないこと、過去に遭遇した注意点をまとめておけます。

Claude Codeのドキュメントでは、これは厳格な設定ではなく、コンテキストだとはっきり説明されています。エージェントは通常ファイルの指示に従いますが、必ず従うとは限りません。ファイルの削除やサーバーへのデプロイなど、常に禁止したい操作には、CLAUDE.mdに書くのではなく、フックや設定の権限機能を使います。

CLAUDE.mdの配置場所と読み込み方

複数のファイルを同時に使えます。Claude Codeはひとつだけを選ぶのではなく、見つかったファイルを、最も広い範囲から作業中のフォルダーに近い順にまとめて読み込みます。

エージェントを起動した場所より上のフォルダーにあるファイルは、すぐに読み込まれます。下の階層にあるファイルは、エージェントがその中のファイルを読み込んだり変更したりするときに読み込まれます。そのため、大きなリポジトリでも、エージェントがデータベースを扱っている間にフロントエンド向けの指示がコンテキストを占めることはありません。

最初のファイルは/initコマンドで生成できます。Claudeがコードを調べて、見つけたコマンドや規約を記録します。出発点としては便利ですが、私はいつも手作業で追記します。特に役立つのは、コードから読み取れないことだからです。

私の最長ファイルは402行

ドキュメントでは、コンテキストを消費し、エージェントが指示に従いにくくなるため、ひとつのCLAUDE.mdを200行未満にすることが推奨されています。Jantarisのプロジェクトにある私のファイルは402行、46,095バイトです。16個のCLAUDE.mdのうち、200行を超えるのはこれだけで、中央値は35行です。

最初から長かったわけではありません。エラーが起きるたびに、注意点を追加してきました。サーバーが画像をキャッシュする仕組みと、同じ名前でファイルを差し替えても利用者に届くまで1週間かかる理由、1時間あたりの登録数を制限する仕組みとテスト時のリセット方法、サーバーの場所やメールの送信方法などです。どの行にも、実際に起きた問題の跡があります。積み重なって、長くなりすぎました。

私の考えでは、CLAUDE.mdはプロジェクトのドキュメントではなく、地雷の地図です。アプリの仕組みは、エージェントがコードやREADMEを読めば分かります。CLAUDE.mdには、コードからは見えず、過去に一度問題を起こしたことを書くべきです。200行を超えたら、内容ごとに.claude/rules/内のファイルへ分割します。@ファイル.mdによるインポートは整理には役立ちますが、読み込まれるファイル全体が展開されます。

講座で紹介している34行のファイル

よい例が、私のClaude Codeで週末にSaaSを作る講座でゼロから開発している、自動車整備工場向けアプリ「修理データベース」のCLAUDE.mdです。省略せず、ファイル全体を掲載します。

# 修理データベース - エージェント向けメモ

製品、画面、ルール：@SPEC.md
SCOPE.mdの「必須」セクションだけを実装する。範囲外のアイデアは
「後で」に戻る条件とともに追記し、私に確認する。

## 技術構成
- Node 22.13以降、npm依存関係なし：node:http、node:sqlite、node:test、fetch。
- SQLiteはdata/app.db、マイグレーションはmigrations/NNN_name.sql。
- HTMLはサーバーでレンダリングし、ブラウザーでは素のJavaScriptを使う。

## コマンド
- npm run dev                 ポート8080でサーバーを起動。ファイル変更後は再起動
- npm test                    node --test "test/*.test.js"（globを引用符で囲む）
- npm run reset               データベースを初期化し、テストデータとテスト用アカウントを作成
- python tools/screenshots.py URL  1440 pxと390 pxのスクリーンショットをdata/shots/に保存

## ルール
- 金額はグロシュ単位のINTEGERで扱う。浮動小数点数は使わない。
- プランの上限（R1〜R3）はサーバーで確認する。ブラウザーでは表示だけを行う。
- SPEC.mdの各Rルールに対し、ルール番号を名前に含むテストを作成する。
- テキストファイルの改行コードはLFにする。
- コンテンツではハイフン「-」だけを使う。すべてのテンプレートをテストで確認する。

## 禁止事項
- .envを読まない。デプロイしない。git push、git reset、git cleanを実行しない。
- data/app.dbを使ってテストを実行しない（テスト用データベースはメモリ上に作る）。
- 自動車メーカーのデータ（Autodata、HaynesPro、メーカーのポータル）を取り込まない：
  EUではメーカーのライセンスとデータベース保護がある。

## 環境上の注意
- Git Bashはパスを書き換えることがある。/...を含むコマンドの前にMSYS_NO_PATHCONV=1を設定する。
- 正規表現を含むファイルは、bashのヒアドキュメントではなくファイル書き込みツールで保存する（バックスラッシュが失われる）。

各セクションには、それぞれ理由があります。

• 仕様への参照。製品の説明はSPEC.mdにあり、CLAUDE.mdはそれをインポートするだけです。「必須」セクションだけを実装するという指示で、エージェントが範囲を守れるようにします。この指示がないと、1時間後には誰も求めていない機能ができていることがあります。
• 構文を正確に書いたコマンド。テストでglobを引用符で囲むのは、見落としやすい構文上の細部です。これによって、すべてのテストファイルが実行されるかどうかが変わります。
• 確認可能なルール。金額はグロシュ単位で扱う、上限はサーバー側で確認する、各ルールにテストを用意する、といった内容です。「きれいなコードを書く」のように検証できない指示は避けます。
• 禁止事項。ファイルの指示はあくまで依頼なので、重要な禁止事項は設定の権限機能にも重ねて記載します。
• 開発環境の注意点。WindowsのGit Bashでは、スラッシュで始まるパスが書き換えられることがあります。コマンドが失敗するまでは、エージェントには分かりません。

編集作業をやり直す原因になった一文

具体例を見ると、このファイルの意味がよく分かります。10月30日、DYGOT誌の記事を編集していたとき、サーバーの最新状態を取得するスクリプトを、修正とアップロードの間に実行しました。その結果、ローカルの変更が上書きされ、編集の最初の作業が失われました。それ以来、このプロジェクトの指示ファイルには次の一文を入れています。「実行するのは作業開始前のみ。編集後、アップロード前に実行すると変更が上書きされる」。スクリプトのコードを読んでも、実行してよいタイミングまでは分からないので、どんなジェネレーターもこの一文は書けなかったでしょう。

AGENTS.mdは、ほかのエージェント向けの同種ファイル

AGENTS.mdも指示を書くファイルですが、OpenAIのCodex、Cursor、Gemini CLI、GitHub Copilotのエージェントなど、さまざまなツールが読む名前になっています。この形式はLinux FoundationのAgentic AI Foundationが運営しています。私の手元には26個あり、中央値は8行です。ほとんどがCodexにグラフィック関連の単一タスクをさせるための短い指示だからです。

Claude Codeもバージョン2.1.277以降はAGENTS.mdを読めます。ただし、標準ではプロジェクトにCLAUDE.mdがない場合に限られます。両方あると、Claudeは自分用のファイルを読み、AGENTS.mdは読み飛ばします。両方のツールで同じルールを使うなら、AGENTS.mdにまとめ、CLAUDE.mdに@AGENTS.mdでインポートする1行を追加するのが簡単です。スキルやMCPサーバーも含めて一式を移す方法は、Claude CodeからCodexへ移行する方法で紹介しています。

ClaudeとCodexが交互に作業するプロジェクトでは、ファイルの最後にもうひとつルールを加えています。作業後、日付、エージェント名、変更点を共通のエージェント日誌に記録するというものです。次のエージェントは開始前に日誌を読めば、前のエージェントが何を変更したか分かります。2つのツールの記憶を同期するより簡単です。

書かないこと

• キーやパスワード。プロジェクトのファイルはリポジトリに入ることがあります。私のファイルには、.envの内容ではなく、.envを読まないようにという指示を入れています。
• フォルダー構成。エージェントは数秒で確認できるので、ファイルに書いても最初の変更で古くなります。
• 曖昧な指示。「品質を大切にする」では何も変わりません。「各ルールに、その番号を名前に含むテストを用意する」なら動作が変わります。
• 矛盾するルール。ドキュメントでは、指示が矛盾するとClaudeがどちらを選ぶか分からないと注意されています。私は定期的にファイルを読み返し、もう有効でない内容を削除しています。
• 人向けのメモ。残す必要がある場合は、HTMLコメント<!-- -->に入れます。Claude Codeは読み込み前にこうしたコメントを削除するため、コンテキストを消費しません。

まず何から始めるか

Claude Codeを使い始めるとき、CLAUDE.mdを先回りして書く必要はありません。/initを実行して、役立つ内容を残し、エージェントが同じ間違いを2度したら、そのたびに1行ずつ追加します。1週間後には、ガイド記事に出てくるような架空のプロジェクトではなく、自分のプロジェクトを説明するファイルになっています。インストールと最初の手順はClaude Codeのインストール方法、プランの費用はClaude Codeの料金で説明しています。

講座Claude Codeで週末にSaaSを作るそれでは、仕様とCLAUDE.mdを順に作成していきます。アイデアの需要検証から、データベース、ログイン機能、決済、独自サーバーへのデプロイに至るまで、30のレッスンで学ぶことができます。この講座は、ラボの他の27講座とともにkombAInのセットにも含まれています。

出典と確認日

2026年11月6日時点。

• 自分のプロジェクトのCLAUDE.mdとAGENTS.md。コピーと他者のリポジトリを除いた42ファイルを2026年11月6日に集計。
• Claude Codeドキュメント「How Claude remembers your project（CLAUDE.md、AGENTS.md、インポート、200行の目安）」
• AGENTS.mdの形式について
• SaaSを週末に作るClaude Code講座のカリキュラム

// 続きを読むClaude Duetは日本で使える?現状と代替策ガイド国防総省にClaude Code接続か WIRED報道の疑惑速報GPT-6.1 Terra vs Claude Sonnet 5.5：日本語以外のテスト結果を比較ベンチマーク