CLAUDE.mdは、プロジェクトのルートにあるプレーンなMarkdownファイルです。Claudeはこれをすべてのセッションで自動的に読み取ります。プロジェクトレベル: ./CLAUDE.md。グローバル (すべてのプロジェクト): ~/.claude/CLAUDE.md。プロジェクトはグローバルを上書きします: グローバルファイルにはデフォルト設定が、プロジェクトファイルにはこのリポジトリ固有の設定が含まれます。
これは、あなたのプロジェクトについて何も知らない非常に熟練した請負業者に渡すオンボーディング文書だと考えてください。これがないと、すべてのセッションはClaudeがあなたのスタック、命名規則、過去の決定を推測することから始まります。推測はコードになり、コードはバグになります。CLAUDE.mdはその連鎖を短絡させます。ファイルは、あなたが覚えていようがいまいが機能するため、巧妙なプロンプトよりも優れています。
役立つ5つのセクション。 各3〜6行の箇条書き:
1. スタック: フレームワーク、DB、認証、メール、バージョン付き。「Next.js 16、Neon上のPostgres、メールはResend、決済はStripe、認証はSupabase。」
2. ルート: ものがどこにあるか。「アプリは/app、サーバーアクションは/actions、APIは/app/api/v2、共有コンポーネントは/components/ui。」
3. 規約: あなたには明白だがClaudeには見えないルール。「金額はセント単位 (int)、日付はUTC、ファイル名はケバブケース、IDはUUID v4。」
4. セキュリティルール: 決して起こしてはならないこと。「APIキーをログに記録しない。すべてのSQLをパラメータ化する。すべての公開エンドポイントにレート制限をかける。」
5. これをしてはいけない: 既に陥った罠。「尋ねずに依存関係を追加しない。ローカルからプロダクションに対してマイグレーションを実行しない。」
作業済みのテンプレート。実際のプロジェクトの詳細に置き換えてください:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)具体性に注目してください。「IPあたり10回/分」は実行可能です。「レート制限を使用する」はそうではありません。
最も高価な間違い: 具体的に聞こえる漠然としたルール。
弱い例: 「お金は慎重に扱う。」 Claudeは最善だと思う方法でお金を扱いますが、それはあなたのシステムと一致しないかもしれません。
強い例: 「すべての金額は整数セントです。浮動小数点数は使用しません。生のセントを表示せず、100で割って通貨記号でフォーマットします。」 ストレージタイプ、処理ルール、表示ルール。曖昧さはありません。
2番目の間違い: 制約ではなく願望を書くこと。「クリーンで読みやすいコードを重視します」は願望です。「200行を超えるファイルはモジュールに分割されます」は制約です。願望は判断を必要としますが、制約は一貫した動作を生み出します。CLAUDE.mdを制約で満たしてください。
CLAUDE.mdは生きた文書です。 更新が必要な3つの兆候:
同じコンテキストをプロンプトに2回貼り付けた場合。もう一度言っているなら、それはCLAUDE.mdに属します。
Claudeがルールで防げたはずの間違いを犯した場合。その間違いがルールです。次のセッションの前に書き留めてください。
同僚に規約を説明した場合。声に出して言う価値があるなら、自動的にロードする価値があります。
長さの規律: 各セクション3〜6箇条書き。8箇条書きを超えたら、セクションを分割します。ざっと目を通すには長すぎるCLAUDE.mdは、重要なルールが埋もれてしまうため機能しなくなります。適切な6行は、60行の埋め草よりも優れています。
約300行を超えてスケーリングする場合: @filenameインクルードを使用してトピックファイルに分割します:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.md各トピックファイルは焦点を絞り、ルートは短く保たれます。
CLAUDE.mdをバージョン管理にコミットします。 ルールはPRでレビュー可能になり、新しいチームメイトはClaudeが既に設定された状態でリポジトリをクローンします。各「これをしてはいけない」ルールは、それを教えたバグ修正と同じコミットに追加してください。1つ注意点: コミットする前にマシン固有のパスを一般化してください。
CLAUDE.mdとプロンプトのどちらに含めるべきか？ 影響範囲です。修正に1時間以上かかる種類の間違いを防ぐルールであれば、CLAUDE.mdに入れます。セッション固有の指示はプロンプトに残します。
10分で最初のCLAUDE.mdを作成します。 Claudeにこのプロンプトを与えてください:
「私はこのスタックでプロジェクトのためにClaude Codeをセットアップしています: [スタック]。新しい人が知らないであろう主要な規約: [規約]。決して違反してはならないセキュリティルール: [ルール]。以前バグを引き起こしたこと: [罠]。スタック、ルート、規約、セキュリティルール、これをしてはいけないの5つのセクションを持つCLAUDE.mdをドラフトしてください。」
最初のドラフトで80パーセントが得られます。Claudeが見落としたもので修正してください。残りの20パーセントは、プロジェクトでの実際の経験に固有のものです。
プロジェクトルートにあるCLAUDE.mdは、スタック、ルート、規約、セキュリティルール、罠をすべてのセッションにロードします。クロスプロジェクトのデフォルト設定にはグローバルファイル、上書きにはプロジェクトファイルを使用します。願望ではなく制約を記述します。適切な6行は60行よりも優れています。Claudeが書かれたルールで防げたはずの間違いを犯した場合はいつでも更新してください。