CLAUDE.md のベストプラクティス：Claude Code にプロジェクトルールを正しく覚えさせる

CLAUDE.md は人が明示的に書き下し、関連する毎回のセッションに従ってほしいルールを保存します。自動メモリは Claude Code が作業過程に応じて蓄積し、ユーザーがレビューできます。どちらもコードや正式なドキュメントの代わりにはなりません。

書き込むのに適するのは、ツールが確実に推論できないテストコマンド、リポジトリの作法、アーキテクチャの制約、環境の落とし穴です。標準的な言語の常識、完全な API ドキュメント、ファイルごとの説明はコンテキストを消費するだけです。

プロジェクトのルートディレクトリで Claude Code を起動してから /init を実行すると、ツールがビルドシステム、テストフレームワーク、プロジェクト構造に基づいて初稿を生成します。生成内容はプロジェクトのメンテナが必ずレビューしてください。

初稿はあくまで候補となるルールです。Claude が package.json、Makefile やコードから直接導出できる内容は削除し、実行の正確性に本当に影響する制約だけを残してください。

各ルールは「いつ何をするか」「どう検証するか」に答えるべきです。「高品質なコードを書く」には操作上の価値がありませんが、「TypeScript を変更したら pnpm typecheck を実行する」は直接実行できます。

ある行を削除しても Claude が間違えないなら、削るべきです。ルールが長すぎると、ユーザーの現在のプロンプトや本当に重要な制約が薄まります。

~/.claude/CLAUDE.md は個人のプロジェクト横断的な設定に適し、プロジェクトルートの CLAUDE.md はチームルールに適し、CLAUDE.local.md は共有しないプロジェクトのメモに適しています。サブディレクトリのルールは Claude が該当ディレクトリにアクセスする際にオンデマンドで読み込まれます。

Monorepo ではすべてのパッケージのコマンドをルートファイルに詰め込まないでください。ルート層にはリポジトリ全体のルールだけを置き、各パッケージは自身のディレクトリで具体的なテスト、ビルド、アーキテクチャの制約をメンテナンスします。

CLAUDE.md は @path で追加ファイルを取り込めます。.claude/rules/ のうち paths frontmatter を持つルールだけがマッチするファイルに応じてオンデマンドで読み込まれ、paths のないルールは起動時に無条件でコンテキストに入ります。

インポートは安定して短いドキュメントを指すべきです。大型の README ツリーを再帰的にインポートしたり、秘密鍵を含む可能性のある個人ファイルをインポートしたりしないでください。

/context で現在のコンテキストに入っている CLAUDE.md とルールを確認します。ルールが有効にならない場合は、起動ディレクトリ、ファイルの位置、文の競合、ファイルが長すぎないかを先に確認してください。

CLAUDE.md をコードレビューとして扱う：挙動にズレが出たら最小のルールを追加し、デフォルトの挙動がすでに正しければ冗長なルールを削除します。確定性のある強制アクションは Hooks に移行し、表現を強めるだけで済ませないでください。