CLAUDE.mdとrulesとREADMEを見直した話

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は人間がセットアップするときの入口、と割り切って整理したら迷いがなくなりました。

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

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

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

整理する前は、Claudeに新規スクリプトを書かせると毎回requestsを直で叩いたり、独自ロガーを書いたりと、共通モジュールを無視する事故が頻発していました。

原因は単純で、ルールが長すぎて重要な「共通モジュールを使え」という一文が埋もれていたからです。300行のCLAUDE.mdに紛れた1行は、もはや存在しないのと同じでした。

そもそもCLAUDE.md・rules・READMEは何が違うのか

3つの違いを言語化できると、新しいルールを追加するときに「これはどのファイルに書くべきか」で悩まなくなります。私は見直しのタイミングで、各ファイルに一言キャッチコピーをつけました。

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

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

CLAUDE.mdは、Claude Codeがセッションを開くたびに必ず全文読み込むファイルです。つまりここに書いた内容は、毎回コンテキストを消費します。軽く見積もって200行を超えると、他の重要な指示を押し出してしまうリスクがあります。

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

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

.claude/rules/配下のファイルは、Claudeが特定の領域を触るときだけ読み込まれる詳細ルールです。私の場合はブラウザ自動化・WordPress管理・launchdなど、領域ごとに分けています。

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

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

READMEは人間が読む前提のファイルです。ここにAI向けの細かい規約を書いても、人間は興味を持ちません。逆に、ClaudeはすでにCLAUDE.md経由で同じ情報を受け取っているので、READMEでの重複は完全に無駄になります。

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

CLAUDE.mdに書くべき5つの内容

見直しを通じて、私がCLAUDE.mdに残した要素は5種類に絞れました。どれも「書かないとClaudeが間違える」もので、逆に言えばコードやgit logから読み取れる情報は全部追い出しています。

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

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

冒頭にはプロジェクトの目的を1〜2文で書きます。「個人用の自動化スクリプト集。Python＋launchdのモノレポ」くらいの粒度です。その下にディレクトリ構成を5行程度で示すと、Claudeが新規ファイルを配置するときに迷わなくなります。

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

これが一番重要です。私の場合は「共通モジュールを必ず使う」「秘密情報をコミットしない」「依存管理はuv」の3つを箇条書きで置いています。各ルールには理由を1行添えると、Claudeがエッジケースで自分で判断できます。

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

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

テストとリントの実行コマンドは必ず書きます。Claudeは変更後に動作確認しようとするので、正しいコマンドがないと延々とパス探索を始めます。私はpre-commit run --all-filesとpytestの2つだけ載せました。

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

# browser_automation テスト
cd python/browser_automation && .venv/bin/pytest tests/ -v

書かないほうがよい情報

書かないと決めたのは、コードから読み取れる情報・git logで追える履歴・一般的なPython知識・特定タスクの一時的な指示、の4種類です。

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

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

私のCLAUDE.mdは現在80行ほどに収まっています。200行を目安にして、それ以上になりそうなら.claude/rules/に逃がすルールを徹底しています。ファイルサイズは正義ではありませんが、毎回読まれる以上、短いほどシグナル対ノイズ比は上がります。

.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はフロントマターでpathsを指定できますが、これを書き忘れると全ルールが毎回読み込まれて、CLAUDE.mdを分割した意味がなくなります。私は一度これをやって、トークン消費が倍近くに増えました。分割するならスコープ指定までセットで設計してください。

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

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

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

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

READMEを開く瞬間の目的は、ほぼ「動かしたい」の一択です。そこでセットアップ手順・前提ツール・初回のテスト実行だけに絞りました。コーディング規約や運用ルールはClaudeが読めばいいので、人間向けには出しません。結果、READMEは50行以下になりました。

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

以前はREADMEに全スクリプトの実行コマンドを並べていましたが、数十個を超えてから誰も読まなくなりました。今は.claude/rules/commands.mdに移動して、Claudeがコマンドを必要とするときだけ参照する構成です。

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

新しい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を眺めて「今も必要か？」を見直す時間を取るようにしました。一度きれいにしたファイルは汚したくない心理が働くので、棚卸しも5分で終わります。ルールファイルは植物と同じで、水やりしないと枯れるか雑草だらけになるかのどちらかでした。

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

もし今、ルールファイルが肥大化して困っているなら、まず3つのファイルを並べて「これは誰がいつ読むのか」を書き出すところから始めてみてください。見直し前の私のように、半分以上は別の場所に移せるはずです。