claude-md

CLAUDE.md の作成

基本ルール

すべての行に次の判断基準を適用します。「これを削除したら、Claude は間違えるだろうか？」

コード、README、または標準的な慣習から Claude が推測できる内容は削除してください。CLAUDE.md は毎回のセッションで読み込まれる、コストの高いコンテキストです。すべての行にはコストがかかると考えてください。

CLAUDE.md に記載する内容

明示的な指示がないと Claude が誤る内容だけを記載してください。

• Claude が推測できないビルド／テスト／Lint コマンド（make test-integration、独自スクリプトなど）
• 言語のデフォルトやフォーマッターの設定と異なるコードスタイルのルール
• このコードベース特有の、わかりにくい注意点や落とし穴
• テストの手順 — 推奨するランナー、必要なセットアップ、テスト用 DB の規約
• リポジトリのエチケット — ブランチの命名、PR の規約、コミットメッセージの形式
• コード構造からは自明でないアーキテクチャ上の決定
• 開発環境特有の注意点 — 必須の環境変数、バージョンの固定、ローカルセットアップ時の落とし穴
• ドキュメントへの参照（@path/to/file）。ドキュメントのコピーは避けてください。

記載しない内容

以下の追加はやめてください。毎回のセッションでコンテキストを浪費します。

• プロジェクトの概要／エレベーターピッチ — README に記載する内容です
• ディレクトリツリー／ファイルの説明 — Claude はファイルシステムを確認できます
• 一般的な言語の慣習 — Claude はすでに把握しています
• コードスニペット — 古くなるため、代わりに @file:line で参照してください
• API ドキュメント — 貼り付けず、リンクしてください
• 一般的なベストプラクティス — 「きれいなコードを書く」では何も学べません
• README やドキュメントにすでに記載されている内容 — コミット済みのファイルと重複させないでください
• 頻繁に変わる情報 — 実態とずれて、誤解を招くようになります

構成ルール

• 300 行未満を目指してください。 大幅に下回るのが理想です。300 行に近づいたら内容を見直してください。
• 詳細情報への誘導を使ってください — 数行を超える内容は @path/to/detailed-doc.md に記載します。
• 重要なルールは冒頭と末尾に置いてください — 初頭効果と新近性バイアスにより、中間部分は読み飛ばされがちです。
• 肯定形の指示を優先してください — 「デフォルトエクスポートを使わない」より「名前付きエクスポートを使う」とします。
• 厳守が必要なルールにはフックを使ってください — 絶対に破ってはならないルールは、文章ではなく pre-commit フックで強制します。

新しい CLAUDE.md の作成

1. まず、既存の README、ドキュメント、コードベースの構造を確認します。
2. Claude が推測できる内容ではなく、つまずく内容だけを特定します。
3. 重複を避けるため、親ディレクトリや兄弟ディレクトリの CLAUDE.md ファイルを確認します。
4. 簡潔なファイルを作成し、提示する前にこれらのルールに照らして自分で見直します。
5. サブディレクトリの CLAUDE.md ファイルでは、そのディレクトリに関係する内容だけに絞ります。

出力： 行数を添えてドラフトを提示します。書き込む前にユーザーの確認を待ちます。

既存の CLAUDE.md の編集

1. 現在のファイルを読みます。
2. 変更にこれらのルールを適用し、内容を膨らませないようにします。
3. 新しい内容が判断基準を満たすことを確認します。
4. 300 行を超える場合は、削減や別ファイルへの切り分けを提案します。

出力： 編集を行います。300 行を超える場合は、その旨を伝えます。

既存の CLAUDE.md の監査

1. README と、重複している可能性のあるドキュメントをあわせてファイルを読みます。
2. 1 行ずつ判断基準を適用します。
3. 判定を報告します。残す／削除／別ファイルに切り出す（理由も記載）。
4. 記載すべき内容が詳しすぎる場合は、適切な参照方法を提案します。
5. 行数を確認します。

出力： 判定、現在と変更後の行数を含む構造化されたレポートを作成します。適用する変更をユーザーに尋ねます。

アシスタント設定の検出

CLAUDE.md にペルソナや役割（「あなたは…です」、性格、コーチングの指示、コミュニケーションスタイル）が定義されている場合、それはアシスタント設定ファイルであり、用途がまったく異なります。その場合は、次のように伝えてください。「これはプロジェクトの規約ファイルではなく、AI アシスタントの設定ファイルのようです。標準的な CLAUDE.md のルールは適用されません。」その後、判断基準を適用せずにユーザーの依頼を進めます。ただし、構成ルール（行数、参照先への誘導）は引き続き適用します。

対象外

• リンターではありません — このスキルは考え方をガイドするものであり、ファイルを自動修正するものではありません。
• テンプレートではありません — 厳格な構造ではなく、原則を徹底します。CLAUDE.md の形式には意図的に柔軟性を持たせています。
• CLAUDE.md 以外のファイルは変更しません — 内容を README やドキュメントファイルに移すべき場合は、移動を提案しますが、実際には移動しません。

例外的なケース

• ファイルが存在せず、ユーザーが「監査して」と言った場合： その旨を伝え、作成することを提案します。
• CLAUDE.md ファイルが複数ある場合： 文脈上もっとも関連性の高いファイルを対象にします。判断が難しい場合は確認します。監査の際は、すべてのファイルを監査することを提案します。
• ユーザーが明示的にアンチパターンを希望する場合： そのとおりにしますが、通常は README に記載する内容であり、毎回のセッションでコンテキストを消費することを伝えます。ユーザーの指示が常に優先されます。
• モノレポの場合： 継承された指示の重複を避けるため、親ディレクトリにある CLAUDE.md ファイルを確認します。

参考資料

• ベストプラクティス — 公式の対象／対象外一覧
• CLAUDE.md のドキュメント — CLAUDE.md ファイルの仕組み