Claude Code使ってる人、これ読んだ方がいい。海外で「CLAUDE.mdの正しい使い方」がバズってる。ブックマーク3000近く。
ほとんどの人がCLAUDE.mdを「プロンプトファイル」として使ってる。プロジェクトの説明をダーッと書いて、あとは祈る。でもそれだとClaude Codeは毎回「初見のインターン」になる。
この人が提案してるのは「プロジェクト構造」で解決するアプローチ
① CLAUDE.md = Repo Memory（短く保つ）
目的（WHY）、リポジトリマップ（WHAT）、ルール＋コマンド（HOW）だけ。長すぎると重要なコンテキストを見落とす
② .claude/skills/ = 再利用可能なエキスパートモード
コードレビュー、リファクタリング手順、リリース手順をスキル化。セッション間で一貫性が出る
③ .claude/hooks/ = ガードレール
フォーマッター自動実行、テスト自動実行、auth/billing等の危険ディレクトリのブロック。「AIは忘れるけどhooksは忘れない」
④ docs/ = 段階的コンテキスト
アーキテクチャ概要、ADR、運用手順書を配置。プロンプトを肥大化させずに「真実の置き場所」を教える
⑤ ローカルCLAUDE.md
src/auth/CLAUDE.md、infra/CLAUDE.mdのように危険なモジュールの近くに配置。Claude Codeがそこで作業する時だけ注意事項が見える
特にhooksは本当に効果がデカい。さっきバズってたClaude Codeが本番DB消した事故も、hooksで破壊的コマンドをブロックしてたら防げる。
「プロンプトは一時的。構造は永続的。」これが全て。
① CLAUDE.md = Repo Memory（短く保つ）
目的（WHY）、リポジトリマップ（WHAT）、ルール＋コマンド（HOW）だけ。長すぎると重要なコンテキストを見落とす
② .claude/skills/ = 再利用可能なエキスパートモード
コードレビュー、リファクタリング手順、リリース手順をスキル化。セッション間で一貫性が出る
③ .claude/hooks/ = ガードレール
フォーマッター自動実行、テスト自動実行、auth/billing等の危険ディレクトリのブロック。「AIは忘れるけどhooksは忘れない」
④ docs/ = 段階的コンテキスト
アーキテクチャ概要、ADR、運用手順書を配置。プロンプトを肥大化させずに「真実の置き場所」を教える
⑤ ローカルCLAUDE.md
src/auth/CLAUDE.md、infra/CLAUDE.mdのように危険なモジュールの近くに配置。Claude Codeがそこで作業する時だけ注意事項が見える
特にhooksは本当に効果がデカい。さっきバズってたClaude Codeが本番DB消した事故も、hooksで破壊的コマンドをブロックしてたら防げる。
「プロンプトは一時的。構造は永続的。」これが全て。
Quote
Shraddha Bharuka
@BharukaShraddha
Most people treat CLAUDE.md like a prompt file.
That’s the mistake.
If you want Claude Code to feel like a senior engineer living inside your repo, your project needs structure.
Claude needs 4 things at all times:
• the why → what the system does
• the map → where things
