CLAUDE.mdとREADME.mdの違い｜rulesとの役割分担

Claude Codeを使い始めて半年くらい経った頃、ふと自分のCLAUDE.mdを見返したらカオスでした。

プロジェクト構造・コマンド集・秘密情報の注意・コーディング規約、全部1ファイルに詰め込まれていて、すでに300行オーバー。

おまけに.claude/rules/の中身とも重複していて、「このルールどっちに書いたっけ？」と自分で迷子になる始末です。

さらにREADME.mdを開いたら、Claude向けの指示と人間向けのセットアップ手順がごちゃ混ぜ。

3つのファイルが似たような内容を抱えていて、どこを直せば何が変わるのかが自分でも分からなくなっていました。

今回は、そんな状態からCLAUDE.md・.claude/rules/・README.mdの役割分担を整理し直した体験談です。

同じように「ルールファイルが肥大化してきた」「AIの初動ミスが減らない」と感じている方の参考になれば嬉しいです。

CLAUDE.md・rules・READMEを見直した結論

3つのファイルは「読む相手」と「読むタイミング」が違うので、役割をはっきり分けたほうが確実に機能します。

私の場合、CLAUDE.mdは毎回全文読まれる常時指示書です。.claude/rules/は領域別の詳細ルール、READMEは人間がセットアップするときの入口と位置づけました。

そう割り切って整理したら迷いがなくなりました。CLAUDE.mdそのものの書き方から押さえたい場合は、CLAUDE.mdとは？rulesとの違い・書き方まで完全ガイドが入口になります。

3つのファイルは役割がまったく違う

見直しの起点になったのは「同じ情報が3つのファイルに散らばっている」という気づきでした。AIも人間も、同じ内容を別の場所で読まされると混乱します。

まず役割を表で並べたら、何を残して何を削るかが一気に見えてきました。

見直し前に起きていた問題

整理する前は、Claudeに新規スクリプトを書かせると毎回requestsを直で叩いたり、独自ロガーを書いたりしていました。

共通モジュールを無視する事故が頻発していたのです。

原因は単純で、ルールが長すぎて重要な「共通モジュールを使え」という一文が埋もれていたからです。

300行のCLAUDE.mdに紛れた1行は、もはや存在しないのと同じでした。

CLAUDE.md・README.md・rulesの違い

3つの違いを言語化できると、新しいルールを追加するときに「これはどのファイルに書くべきか」で悩まなくなります。

私は見直しのタイミングで、各ファイルに一言キャッチコピーをつけました。

CLAUDE.mdは「常時指示書」、rulesは「領域別リファレンス」、READMEは「人間向け入口」。迷ったらこの3つに当てはめるだけです。

CLAUDE.mdはClaude Codeへの常時指示書

CLAUDE.mdは、Claude Codeがセッションを開くたびに必ず全文読み込むファイルです。

作業ディレクトリとその上の階層にあるCLAUDE.mdは起動時に読み込まれます。サブディレクトリに置いたCLAUDE.mdは、Claudeがそのディレクトリのファイルを読んだタイミングで追加されます。

つまりここに書いた内容は、毎回コンテキストを消費します。公式ドキュメントでも1ファイル200行未満が目安とされ、長くなるほど指示が守られにくくなると説明されています。

私は「放っておくと間違えること」だけを書く場所と割り切りました。

.claude/rules/は領域別のスコープ付きルール

.claude/rules/配下のファイルは、領域ごとの詳細ルールを置く場所です。フロントマターのpathsを指定したルールは、Claudeが対象ファイルを読んだときだけ読み込まれます。

逆にpathsを書かないルールは、.claude/CLAUDE.mdと同じ扱いで起動時に毎回読み込まれます。

私の場合はブラウザ自動化・WordPress管理・launchdなど、領域ごとに分けています。

CLAUDE.mdの末尾に「詳細は.claude/rules/参照」と1行書くだけで、本体を肥大化させずに必要な深さまで指示できます。

rulesのpaths指定の書き方

ファイル冒頭の---で囲んだ部分に、対象ファイルのパターンを並べます。私のリポジトリのブラウザ自動化用ルール（.claude/rules/browser-automation.md）は、実際に次のように書いています。

---
paths:
  - "python/browser_automation/**/*.py"
  - "python/browser_automation/**/*.md"
  - "python/browser_automation/**/pyproject.toml"
---

# ブラウザ自動化スクリプト ルール

パターンは**/*.pyのようなglob形式で、複数並べられます。

一方、秘密情報の扱いをまとめたsecrets-safety.mdには、あえてpathsを書いていません。どのファイルを触るときでも守ってほしいルールなので、毎回読み込ませています。

READMEは人間向けの入口ドキュメント

READMEは人間が読む前提のファイルです。ここにAI向けの細かい規約を書いても、人間は興味を持ちません。

逆に、ClaudeはすでにCLAUDE.md経由で同じ情報を受け取っているので、READMEでの重複は完全に無駄になります。

私はREADMEをセットアップ手順と主要スクリプトの紹介だけに絞りました。

CLAUDE.local.mdやユーザー向けCLAUDE.mdとの違い

整理していて気づいたのは、ファイルの混同です。

プロジェクト直下のCLAUDE.mdはチーム共有、CLAUDE.local.mdは個人設定（gitignore対象）の置き場です。以前の私は、この2つを区別せずに使っていました。

以前は自分だけのエディタ設定の好みまでCLAUDE.mdに書いていて、他の人が見ると余計な情報でした。

さらに~/.claude/CLAUDE.md（ユーザーメモリ）は全プロジェクト共通の個人設定を書く場所です。

プロジェクト固有の内容とユーザー個人の好みは別ファイルに分けるべきだと学びました。

2026年9月時点の公式ドキュメントでもCLAUDE.local.mdは現役の仕組みで、同じ階層のCLAUDE.mdの後に読み込まれます。.gitignoreへの追加は自分で行う必要があります。

全プロジェクト共通の個人ルールは、~/.claude/rules/に置く方法もあります。

ほかにも、Claudeが自分でメモを残す自動メモリ（MEMORY.mdの先頭200行または25KBまでを毎回読み込み）があります。CLAUDE.mdが無いリポジトリではAGENTS.mdを読む仕組み（v2.1.277以降）も加わりました。

新しいルールを思いついたとき、私が書き場所を決める流れを図にすると次のようになります。

CLAUDE.mdの書き方｜残す内容と削る内容

見直しを通じて、私がCLAUDE.mdに残した要素は5種類に絞れました。

どれも「書かないとClaudeが間違える」もので、逆に言えばコードやgit logから読み取れる情報は全部追い出しています。

ここで紹介する5つは、実際に私のリポジトリでも上から順に並べている内容です。

プロジェクトの一行要約とアーキテクチャ

冒頭にはプロジェクトの目的を1〜2文で書きます。「個人用の自動化スクリプト集。Python＋launchdのモノレポ」くらいの粒度です。

その下にディレクトリ構成を5行程度で示すと、Claudeが新規ファイルを配置するときに迷わなくなります。

放っておくと間違える行動原則

5つの中で一番効いたのが、この行動原則です。私の場合は次の3つを箇条書きで置いています。

• 共通モジュールを必ず使う
• 秘密情報をコミットしない
• 依存管理はuv

各ルールには理由を1行添えると、Claudeがエッジケースで自分で判断できます。

禁止だけでなく代替手段を必ず併記するのがコツです。

最低限のテスト・リントコマンド

テストとリントの実行コマンドは必ず書きます。Claudeは変更後に動作確認しようとするので、正しいコマンドがないと延々とパス探索を始めます。

私はpre-commit run --all-filesとpytestの2つだけ載せました。

# pre-commit（全ファイル）
pre-commit run --all-files

# browser_automation テスト（ルートの共有 .venv を使う）
cd python/browser_automation && ../../.venv/bin/pytest tests/ -v

書かないほうがよい情報

書かないと決めたのは、次の4種類です。

• コードから読み取れる情報
• git logで追える履歴
• 一般的なPython知識
• 特定タスクの一時的な指示

特に最後の「一時的な指示」は曲者で、「今週はこのリファクタを進めている」みたいな情報を書くと、終わった後に消し忘れてノイズになります。

人間向けのメモを残したいときは、HTMLコメント（<!-- メモ -->）でコメントアウトする方法があります。公式ドキュメントによると、ブロック単位のHTMLコメントはClaudeのコンテキストに入る前に取り除かれるため、トークンを消費しません。

200行を超えたら分割を検討する

私のCLAUDE.mdは現在60行ほどに収まっています。

200行を目安にして、それ以上になりそうなら.claude/rules/に逃がすルールを徹底しています。

ファイルサイズは正義ではありませんが、毎回読まれる以上、短いほどシグナル対ノイズ比は上がります。

Claude Codeおすすめ設定5選｜承認9割減の実例

Claude Codeのおすすめ設定を5要素で解説。settings.jsonのpermissions/hooksで承認9割減、CLAUDE.md・Skills・MCPまで1年運用した実例を公開します【2026年版】。

.claude/rules/の分割で失敗した3つのパターン

CLAUDE.mdを分割してrulesに逃がす運用は万能ではなく、私も何度か失敗しました。

分割しすぎたり、逆に統合しすぎたり、スコープを指定し忘れたり。ここでは実際に踏んだ3つの失敗と、どう直したかを紹介します。同じ罠を踏まないでください。

粒度が細かすぎて迷子になる

最初は「1ルール1ファイル」を試しました。結果、20個以上のファイルができて、Claudeがどのファイルを参照すべきか判断できずに結局全部読む羽目に。

今は領域ごと（ブラウザ自動化・WordPress・launchdなど）に1ファイルへ統合しています。7〜8ファイルが運用上のスイートスポットでした。

CLAUDE.mdと内容が重複する

CLAUDE.mdにも「共通モジュールを使う」、rulesにも同じ記述、という重複が起きがちです。

重複すると修正漏れが発生し、ファイル間で矛盾が生まれます。

ルールは「詳細はrulesを見る」という参照を1行置くだけにして、本体はrulesに寄せるのがおすすめです。

スコープ指定がなく毎回全部読まれる

rulesはYAMLフロントマターのpathsで、読み込むきっかけになるファイルを指定できます。

これを書き忘れると全ルールが毎回読み込まれて、CLAUDE.mdを分割した意味がなくなります。私は一度これをやって、トークン消費が倍近くに増えました。

分割するならスコープ指定までセットで設計してください。

注意したいのはフィールド名です。2026年9月時点の公式ドキュメントでは、ルールのフロントマターでClaude Codeが読むのはpathsだけと明記されています。globsなど他のフィールドはエラーも出ずに無視されます。

YAMLの書式が崩れている場合も、フロントマターごと無視されて「paths指定なし」の扱いになり、毎回読み込まれます。パースエラーはclaude --debugで確認できます。

トークン消費の倍増に気づけたのも見た目の勘ではありません。

/contextコマンドの「Memory files」欄で、実際どのrulesファイルが読み込まれているかを確認したからです。

設定した直後は必ずこれで検証する習慣をつけています。

READMEを人間向けに書き直した体験談

CLAUDE.mdとrulesを整えた後、最後にREADMEに手を入れました。

見直し前のREADMEは、コーディング規約・コマンド一覧・セットアップ手順が全部混在していました。新しいMacで復旧しようとしても「で、まず何すればいいの？」状態。

人間が3秒で迷うドキュメントは、誰の役にも立ちません。

セットアップ手順だけに絞った理由

READMEを開く瞬間の目的は、ほぼ「動かしたい」の一択です。そこで次の3つだけに絞りました。

• セットアップ手順
• 前提ツール
• 初回のテスト実行

コーディング規約や運用ルールはClaudeが読めばいいので、人間向けには出しません。結果、READMEからコーディング規約や運用ルールの記述がなくなりました。

コマンド一覧はSkillへ逃がす

以前はREADMEに全スクリプトの実行コマンドを並べていましたが、数十個を超えてから誰も読まなくなりました。

今は/commands-referenceというSkillに移動して、Claudeがコマンドを必要とするときだけ呼び出す構成です。

人間が必要になったらSkillのファイルを開けばいいので、二重管理も消えました。

Claude Skillsとは？使い方・作り方と標準スキル一覧を解説

Claude Skillsとは何かを実例つきで解説。仕組み・使い方・作り方に加え、標準スキル一覧やAPI/Web/Claude Codeの実行環境の違いも網羅。導入判断に迷わない完全ガイドです。

新しいMacで30分で復旧できた

整理の効果を試す機会がすぐに来ました。

Mac入れ替えのタイミングで、READMEだけを見ながらセットアップしたら30分で全スクリプトが動く状態に戻せました。

以前は半日かかっていたので、体感4倍くらいの時短です。ドキュメントの価値は結局こういう場面で出ます。

見直し後の運用で変わった3つのこと

3つのファイルを整理してから1ヶ月ほど運用してみて、日々の作業で明確に変わったことが3つあります。

AIに任せる精度・ファイル管理のしやすさ・ドキュメント更新の心理的ハードル、どれも小さい違いですが積み重なるとかなり効きます。

Claudeの初動ミスが体感で減った

一番の変化はここです。新規スクリプトを作らせたときに、最初からsetup_loggerやhttp_getを使った状態で出てくるようになりました。

以前は毎回「共通モジュール使って」と指示し直していたのが、ゼロ回に。

CLAUDE.mdの冒頭に行動原則を集約した効果がはっきり出ています。

ファイル肥大化に気づきやすくなった

各ファイルの役割が明確だと、「これはCLAUDE.mdに書くことじゃないな」と気づける瞬間が増えます。

以前は何でもかんでもCLAUDE.mdに追記していました。今は「これはrulesのwp-manager.mdに足そう」と自然に判断できるようになりました。

肥大化の予防線が自然に張られます。

定期的な棚卸しが習慣になった

月に1回、CLAUDE.mdとrulesを眺めて「今も必要か？」を見直す時間を取るようにしました。

見るのは「先月書いた一時的な指示が残っていないか」と「新しく増えたスクリプトのルールが漏れていないか」の2点だけに絞っています。

一度きれいにしたファイルは汚したくない心理が働くので、棚卸しも5分で終わります。

ルールファイルは植物と同じで、水やりしないと枯れるか雑草だらけになるかのどちらかでした。

以前、前任者が退職してドキュメントゼロのシステムを半年で引き継いだことがあります。

テストコードがあれば動作仕様はある程度わかるものの、「なぜこう書いたか」という意図まではコードから読み取れませんでした。

CLAUDE.mdやrulesに残す価値があるのは、まさにその意図の部分だと今は思っています。

コンテキストエンジニアリングとは？CLAUDE.mdの実例で解説

コンテキストエンジニアリングとは、AIに渡す情報全体を設計する技術です。プロンプトエンジニアリングとの違いを具体例で比べ、構成要素、Anthropicが示す手法、今日からできる5ステップをClaude Codeの実例つきで解説します。

よくある質問

Q1. CLAUDE.mdとREADME.mdはどう違いますか？

A1. CLAUDE.mdはClaude Codeがセッション開始時に毎回全文読み込む常時指示書です。README.mdは人間がセットアップ時に読む入口ドキュメントです。読み手とタイミングが違うため、内容を混在させると重複や矛盾が生まれます。

Q2. CLAUDE.mdとは何ですか？

A2. Claude Codeがセッションを開くたびに必ず全文読み込む、プロジェクト固有の常時指示書です。書きすぎると毎回のコンテキストを圧迫するため、公式ドキュメントでは1ファイル200行未満が目安とされています。

Q3. .claude/rules/にはどんな内容を書くべきですか？

A3. 特定の領域（ブラウザ自動化・WordPress管理等）を触るときだけ必要な詳細ルールです。フロントマターのpathsでスコープを指定すると、関連作業時のみ読み込まれ、CLAUDE.mdの肥大化を防げます。

Q4. CLAUDE.mdに書かないほうがいい情報は何ですか？

A4. コードから読み取れる情報、git logで追える履歴、一般的なプログラミング知識、特定タスクの一時的な指示の4種類です。これらは書いても陳腐化しやすく、消し忘れるとノイズになります。

Q5. rules.mdファイルを分割するときのコツは何ですか？

A5. 「1ルール1ファイル」まで細かく分割すると管理が煩雑になります。ブラウザ自動化・WordPress管理のような領域ごとに1ファイルへ統合し、7〜8ファイル程度に収めるのが運用しやすいラインです。

まとめ

CLAUDE.md・.claude/rules/・README.mdは読み手とタイミングで役割が違うので、混ぜずに分担させるのが近道でした。

途中経過は、また書きます。