なぜルールファイルが必要なのか
Claude CodeやCursor、GitHub Copilot Workspaceなどのエージェントは、会話ごとにコンテキストをリセットする。「App RouterではServer Componentを優先して」「anyは禁止」といった方針を毎回伝えるのは非現実的だ。CLAUDE.md・.cursorrules・AGENTS.mdはその解決策で、リポジトリに置くだけでエージェントが読み込み、ルールを前提として動くようになる。
ただし「書けば万能」ではない。ルールが長すぎると無視されやすく、矛盾した指示があると挙動がぶれる。実用上は短く・具体的に・優先順位つきで書くのが原則だ。
ファイルの使い分け
| ファイル | 読み込むツール |
|---|---|
CLAUDE.md |
Claude Code |
.cursorrules |
Cursor |
AGENTS.md |
OpenAI Codex系、汎用 |
内容はほぼ共通化できる。プロジェクトルートにCLAUDE.mdを置き、.cursorrulesからそれを参照する形にすると管理が楽だ。
Next.js App Router向けの実例
# Project Rules
## Stack
- Next.js 15 App Router / TypeScript strict mode
- Tailwind CSS v4 / Prisma / Zod
## Component rules
- デフォルトは Server Component。クライアント操作が必要な場合のみ `"use client"` を追加する
- `app/` 配下のファイルは page.tsx / layout.tsx / loading.tsx / error.tsx のみ
- 共有UIは `components/` に置き、ロジックは `lib/` に分離する
## TypeScript
- `any` 禁止。不明な型は `unknown` + 型ガードで処理する
- Prismaの返り値は必ず Zod スキーマで検証してからAPIレスポンスに使う
## API Routes (Route Handlers)
- `app/api/` の Route Handler は必ず `NextRequest` / `NextResponse` を使う
- 認証チェックは `lib/auth.ts` の `requireSession()` を必ず先頭で呼ぶ
- エラーは `{ error: string }` 形式で返し、HTTPステータスを明示する
## 禁止事項
- `pages/` ディレクトリへの新規ファイル追加
- `console.log` のコミット（デバッグは `logger.ts` 経由）
- `fetch` の直書き（`lib/api-client.ts` のラッパーを使う）
## コード生成時の優先順位
1. 既存の型定義・ユーティリティを再利用する
2. 新規ファイルを作る前にコンポーネントの分割を検討する
3. テストは Vitest + React Testing Library で書く
運用Tips
短く保つ: 500行を超えたルールファイルはエージェントのコンテキスト消費を圧迫する。「なぜそうするか」は省略し、ルールだけを箇条書きにする。
禁止事項を明示する: 「推奨」より「禁止」のほうがエージェントは従いやすい。pages/への追記禁止やany禁止のように、ネガティブルールを必ず書く。
定期的に削除する: Next.jsのバージョンアップやリファクタ後に古いルールが残ると、エージェントが矛盾した判断をする。git blameでルールの追加日を確認し、半年ごとに棚卸しする。
チームで合意してからコミットする: エージェントへの指示はそのままコーディング規約になる。個人の好みで追加せず、PRレビューと同じ合意フローを踏むとチーム全体の一貫性が保てる。
ルールファイルはあくまで「エージェントへの継続的な指示書」だ。万能薬ではないが、積み重ねれば指摘の繰り返しが確実に減る。
5フレームワーク分の実例をまとめたキット
Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。👉 詳細・入手はこちら