CLAUDE.mdが無視される原因は「指示バジェット」— 100命令の壁を突破する構造化設計と責務分離の実践ガイド

指示を1つ取り出す
│
├─ ESLint/Prettier/TypeScript strict等で強制できる？
│   └─ YES → CLAUDE.mdから削除（ツールに任せる）
│
├─ ファイル保存時・コミット時など特定イベントで発火する？
│   └─ YES → Hooksへ移譲
│
├─ 「/deploy」「/review」のようにコマンドで呼び出す手順？
│   └─ YES → Skillsへ移譲
│
└─ 上記いずれにも該当しない全体方針・判断基準
    └─ CLAUDE.mdに残す

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "command": "npx eslint --fix . && npx prettier --write ."
          }
        ]
      }
    ]
  }
}

<!-- lint強制はPreToolUse Hookに移譲済み（2026-03） -->
<!-- デプロイ手順は .claude/skills/deploy.md に移譲済み -->

1. Managed policy（組織ポリシー）
2. ~/.claude/CLAUDE.md（グローバル：個人設定）
3. ./CLAUDE.md（プロジェクトルート）
4. ./src/db/CLAUDE.md 等（サブディレクトリ：オンデマンド）

my-monorepo/
├── CLAUDE.md                      # アーキテクチャ方針、共通コマンド
├── @shared-rules.md               # @パスで共有ルールを外部化
├── packages/
│   ├── api/
│   │   └── CLAUDE.md              # APIのルーティング規約、DB操作ルール
│   └── web/
│       └── CLAUDE.md              # コンポーネント設計方針、CSS規約
└── .claude/
    └── skills/
        └── deploy.md              # デプロイ手順（/deployで呼び出し）

# プロジェクト共通ルール
@shared-rules.md

## 技術スタック
- Runtime: Node.js 22 + TypeScript (ESM)
- DB: PostgreSQL + Drizzle ORM

# プロジェクトルール

きれいで読みやすいコードを書いてください。          ← 曖昧な指示
コミット前にESLintを実行してください。              ← ツールで強制可能
セミコロンは必ずつけてください。                     ← Prettierで強制可能

## コーディング規約
- インデントはスペース2つ                           ← .editorconfigで十分
- 変数名はcamelCase                                ← ESLintルールで強制可能
- 関数は50行以内                                    ← ESLintのmax-lines-per-functionで対応可能
- anyは使わない                                     ← tsconfig strictで対応可能

## デプロイ手順                                      ← 手順はSkillsに移譲すべき
1. npm run build
2. npm run test
3. git push origin main
4. vercel deploy --prod
5. 動作確認してSlackに報告

## APIレスポンス形式                                  ← コードスニペット直書き
すべてのAPIは以下の形式で返すこと:
｛実際には50行以上のJSON例が続く...｝

## 古い注意事項                                       ← 陳腐化
- Node 16ではESMに注意 → もうNode 22なので不要
- Webpack設定を変更しないこと → Viteに移行済み

# Project: my-app

## Tech Stack
- Runtime: Node.js 22 + TypeScript (ESM, `"type": "module"`)
- Framework: Next.js 15 (App Router)
- DB: PostgreSQL + Drizzle ORM
- Test: Vitest + Testing Library

## Commands
- `npm run dev` — 開発サーバー起動
- `npm run build` — ビルド
- `npm run test` — テスト実行
- `npm run db:push` — スキーマ適用

## Architecture Rules
- MUST: Server Componentsをデフォルトとし、Client Componentは最小限にする
- MUST: DB操作は `src/db/` 内のrepositoryパターンに集約する
- MUST NOT: APIルートから直接SQLを発行しない
- MUST: エラーは `AppError` クラスでラップし、status codeを含める
- MUST NOT: `any` 型を使用しない。不明な型は `unknown` で受けてnarrowする

## Conventions
- ファイル名: kebab-case（例: `user-profile.tsx`）
- コミットメッセージ: Conventional Commits形式、日本語
- ブランチ名: `feature/`, `fix/`, `chore/` プレフィクス

## Important Context
- 認証はNextAuth v5。セッション管理の変更はチームレビュー必須
- `src/lib/legacy/` は移行中。新コードからimportしない

<!-- lint/format強制はPreToolUse Hookに移譲済み -->
<!-- デプロイ手順は .claude/skills/deploy.md に移譲済み -->
<!-- API形式の定義は src/types/api.ts を参照（スニペット直書きを廃止） -->

# NG
すべてのAPIは以下のJSON形式で返すこと:
{ "status": "ok", "data": { ... }, "error": null }

# OK
MUST: APIレスポンスは src/types/api.ts の ApiResponse<T> 型に従う

# NG
セミコロンを必ずつけること。インデントはスペース2つ。

# OK（CLAUDE.mdから削除し、ツール設定に任せる）

# NG
きれいなコードを書いてください。適切にエラーハンドリングすること。

# OK
MUST: 関数は単一責任。1関数1エクスポートを基本とする
MUST: 外部API呼び出しはtry-catchで囲み、AppErrorに変換する