Progressive Disclosure — 全部書かず参照先を示す

Progressive Disclosure（段階的開示）は、最初に概要だけを見せ、詳細は必要になった時に参照する設計パターンです。CLAUDE.mdでもこの考え方が非常に有効です。

原則: コードスニペットより参照先のパスを書く

悪い例 — CLAUDE.mdにコードを直接貼る:

## エラーハンドリング

カスタム例外クラスは以下のように定義しています:

\`\`\`typescript
export class AppError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public code: string
  ) {
    super(message);
  }
}
// ... (20行のコード)
\`\`\`

良い例 — パスだけ示す:

## エラーハンドリング

- カスタム例外クラス: \`src/lib/errors.ts\` を参照
- エラーハンドリングミドルウェア: \`src/middleware/error-handler.ts\`
- HTTPエラーは直接throwせず、カスタム例外を使用する

「詳細は@path参照」パターン

## アーキテクチャ

レイヤード・アーキテクチャを採用。Controller → Service → Repository の3層構成。
詳細は @docs/architecture.md 参照。

## テスト方針

Vitest + Testing Library。カバレッジ目標80%。
詳細は @.claude/rules/testing.md 参照。

オンデマンド読み込みの仕組み

Claudeは指示された参照先のファイルを、必要になった時に読みに行きます。

1. CLAUDE.mdの概要から全体像を把握する
2. 具体的な作業に入る時、関連ファイルを読む
3. rulesファイルはglobsにマッチした時だけ読み込まれる

この仕組みを理解すると、CLAUDE.mdの設計方針が変わります。

• 書くべきこと — 概要、方針、「どこを見ればいいか」のポインタ
• 書かないこと — コードスニペット、詳細な実装例、変更頻度が高い情報

コードスニペットをCLAUDE.mdに貼ると、コードが変更された際にCLAUDE.mdとの不整合が生まれます。パスを示しておけば、Claudeは常に最新のコードを参照できます。これが「腐らないCLAUDE.md」を作るコツです。