CLAUDE.md の書き方 ― 何を書き、何を書かないか

導入

CLAUDE.md は、Claude Code が会話のたびに最初に読む特別なファイルです。ビルドコマンド・コード規約・作業ルールなど、コードだけからは読み取れない前提をここに書いておきます。まず /init でたたき台を作り、使いながら育てるのが基本です。

説明

決まった書式はありません。短く・人が読めることが何より大切です。

# コマンド
- ビルド: `npm run build`
- テスト: `npm test`（全体より単体テストを優先）

# コード規約
- ESモジュール（import/export）を使う。CommonJS(require)は使わない
- 変更はまず小さく。既存の命名・インデントに合わせる

# 注意点
- 変更が一区切りしたら必ず型チェックを走らせる

何を書き、何を書かないかの線引きが肝心です。全文が毎回読み込まれるため、長すぎると肝心のルールが埋もれて無視されます。

✅ 書くべき	❌ 書かない
推測できないコマンド（ビルド・テスト）	コードを読めばわかること
既定と違うコード規約	言語の標準的な慣習
テスト方法・使うテストランナー	詳細なAPI仕様（リンクで十分）
ブランチ名・PRの決まり	頻繁に変わる情報
このプロジェクト特有の設計判断	長い解説やチュートリアル
環境の癖（必要な環境変数）	「きれいに書こう」等の自明な心得

各行について「これを消したら Claude がミスするか？」と問い、しなければ削る。守ってほしいルールには 重要: や 必ず と強調を付けると効きます。他のファイルは @パス で読み込めます。

プロジェクト概要は @README.md、コマンドは @package.json を参照。
- Git運用のルール: @docs/git-instructions.md

置き場所は複数あります。

~/.claude/CLAUDE.md：全プロジェクト共通の個人設定
./CLAUDE.md：プロジェクト直下。git に入れてチーム共有
./CLAUDE.local.md：個人メモ（.gitignore に入れて共有しない）
親・子ディレクトリ：モノレポで自動的に読み込まれる

対話中に行頭で # を打つと、その内容をその場で CLAUDE.md に追記できます。「これは毎回守ってほしい」と気づいた瞬間に書き足せます。

読んでみよう

CLAUDE.md は「新しく入ったメンバーへの引き継ぎメモ」。短く保ち、/init で作って、ミスに気づくたびに # で1行ずつ育てる。肥大化させないことが最大のコツです。