CLAUDE.md の中身 (anatomy)

4 階層を意識する

Scope	パス	用途	git管理
Managed	OS の Application Support 配下	組織のコンプライアンス	❌
Project	./CLAUDE.md または ./.claude/CLAUDE.md	アーキ・ビルド	✅
User	~/.claude/CLAUDE.md	個人の好み	❌ (自分の dotfiles に)
Local	./CLAUDE.local.md	プロジェクト固有の個人設定	❌

サブディレクトリの **/CLAUDE.md はそのディレクトリのファイルを読むときに遅延ロード。モノレポではこれを活用して context を分割する。

書くべき項目

1. プロジェクト概要 (3-5行)
2. 主要ディレクトリの説明 (1行/ディレクトリ)
3. ビルド/テスト/lint コマンド
4. コーディング規約 (命名・型・ファイル配置)
5. Do NOT (禁則事項を明示)
6. 参照ドキュメント (@path/to/file でインポート)
7. AGENTS.md があれば @AGENTS.md

書かないべき項目

• コード規約の詳細解説 → リンクで docs/ 配下に逃がす
• 会話のたびに変わる情報 (TODO, 一時的なバグ) → auto memory に任せる
• 個人の好み → ~/.claude/CLAUDE.md か CLAUDE.local.md へ

共通スニペット (このレポ流)

## Commands
- Build: `pnpm build`
- Test: `pnpm test -- --run`
- Lint: `pnpm lint --fix`

## Conventions
- TypeScript strict mode, no `any`
- Co-locate tests as `*.test.ts`

## Do NOT
- `git push --force` on main
- Edit files under `vendor/`, `_ideas/`
- Add documentation files unless explicitly asked

分割の判断基準

CLAUDE.md が 200 行を超え始めたら分割。

• アーキ詳細 → docs/architecture.md に逃がして @docs/architecture.md
• API 仕様 → docs/api.md
• 監修ルールが多い → .claude/rules/<path>.md (path-scoped)

理由: 長すぎる CLAUDE.md は毎ターン context を消費し続け、コスト悪化と精度低下を招く。

.claude/rules/ パスルール

特定パスにだけ効くルールを書ける:

---
paths:
  - "src/api/**/*.ts"
---
APIエンドポイントは必ず入力検証を含めること。
レスポンスは `{ data: T } | { error: string }` のユニオン型で返す。

CLAUDE.md に全部書くより精度が高く、context も節約できる。

出典

• _research/claude-code-features/2026-05-11-claude-code-features.md
• _research/examples/2026-05-11-awesome-templates.md
• _research/trends/2026-05-11-vibe-coding-trends.md (Karpathy: context engineering)
• https://code.claude.com/docs/en/memory