誰かが「CLAUDE.mdなどはちゃんと自分で書いたほうがいいよ〜」的なことを言っていたので。
参照。
CLAUDE.mdとは
Claudeがチャット開始時に毎回読み込む「メモリ（指示）ファイル」。
ここに Bashコマンド・コードスタイル・ワークフロールール などを置いておくと、Claudeが毎回それを前提に動いてくれる。
ポイントは「Claudeがコードを読めば推測できること」ではなく、コードだけだと推測しづらい前提を置くこと。
- 使ってほしいコマンド（build/test/lint）
- このリポジトリ固有のスタイル（例：ESM強制、importの癖）
- このチームの流儀（例：typecheckを必ず通す、PRの粒度）
- ハマりどころ（例：環境変数、特殊なディレクトリ構成）
CLAUDE.mdに書き込む内容
基本は 「広範に適用される情報のみ」。
Claudeは毎回CLAUDE.mdを読むので、ここが肥大化すると本当に守ってほしい指示が埋もれる。
自分の中での判断基準はこれが分かりやすい。
その1行を消したら、Claudeがミスりやすくなる？
→ なら残す。ならないなら切る。
ざっくり「書くもの / 書かないもの」
書くもの
書かないもの
CLAUDE.mdは「ドキュメント」じゃなくて コードとして扱う。
うまくいかなかったら直す。増えたら削る。定期的にレビューして整理すること。
CLAUDE.mdはどこに置けるか
配置場所はいくつかパターンがある。
- ホームフォルダ（ユーザー共通）：
~/.claude/CLAUDE.md
全プロジェクトに効く「自分の流儀」を置く場所。 - プロジェクトルート：
./CLAUDE.md（または./.claude/CLAUDE.md）
チーム共有したい内容はここ。 - 親ディレクトリ：モノレポで効く。
root/CLAUDE.mdとroot/foo/CLAUDE.mdの両方が読み込まれる、みたいな動きができる。 - 子ディレクトリ：必要になったときに追加で引かれる。
あるサブディレクトリ配下のファイルを触る時だけ、追加のルールを読み込ませる、みたいな使い方。
どう探索して読み込むのか
Claude Codeは、起動したカレントディレクトリから上に向かって（/直下までは行かずに）CLAUDE.md / CLAUDE.local.md を再帰的に探す。
さらに、作業中にサブツリー配下の CLAUDE.md も見つけて取り込む。
つまり「モノレポで親にも子にも置ける」のはこの探索方式のおかげ。
追加ファイルのインポート（分割して肥大化を防ぐ）
CLAUDE.mdは @path/to/import で追加ファイルを読み込める。
# Additional Instructions - Git workflow: @docs/git-instructions.md
分割のメリットはシンプルで、
- CLAUDE.md本体を短く保てる
- ルールを用途別に管理できる（git運用だけ切り出す等）
- チームで差分レビューしやすい
知っておくと良い仕様もある。
- 相対パスは「そのimportを書いたファイル」を基準に解決される（cwd基準じゃない）
- インポートは コードブロックやインラインコード内では評価されない
- 再帰インポートは可能だが深さに上限がある（無限に辿らない）
どのファイルが読み込まれているかは /memory で確認できる。
Skills / rules との住み分け
下記のような感じでいいのでは。
- 常に必要なこと → CLAUDE.md
- たまにしか使わないドメイン知識・手順 → Skills（必要な時だけ呼ぶ）
- 大きいプロジェクトのルール群 →
.claude/rules/で分割管理
ハッカソン優勝者の設定（everything-claude-code）を見て思ったこと
「CLAUDE.mdに書くトピック」は案外シンプルでOKで、つらつらと書く必要はないな〜と思った。
実際に書かれていたものは下記。
- プロジェクト概要（何を作ってるか）
- ルール（構成・スタイル・テスト・セキュリティ）
- ファイル構成（迷いやすい場所だけ）
- キーパターン（レスポンス形式、エラーハンドリング等）
- 環境変数
- 使用コマンド
- Gitのワークフロー
ただ、正直これを見て「概念（TDDとか）理解してないと書けへんなぁ」と思った。
でも逆に言うと、理解できた概念から順にCLAUDE.mdへ“自分の言葉で”落としていけばいいんじゃないかな。
