2026年版 Next.jsエージェントに渡すルールファイルの実例と書き方

#ai #claudecode #cursor #nextjs

なぜルールファイルが効くのか

Claude CodeやCursorなどのAIエージェントは、プロジェクトごとに振る舞いを変えられる「コンテキストファイル」を読み込む。このファイルがないと、エージェントはコードスタイル・アーキテクチャ方針・禁止事項を毎回推定しながら動くため、レビュー指摘の繰り返しや一貫性のないコードが増える。

Next.js App Router + TypeScript のプロジェクトで顕著なのが「use client の判断ミス」「fetch vs axios どちらを使うか」「Server Actions の使用方針」といった曖昧な判断だ。これらをルールファイルに明示するだけで、エージェントの出力精度は体感で大きく安定する。

ファイル名と読み込みタイミング

ファイル名	読み込まれるツール
`CLAUDE.md`	Claude Code（プロジェクトルートに置く）
`.cursorrules`	Cursor（非推奨化されつつある。`AGENTS.md`へ移行推奨）
`AGENTS.md`	OpenAI Codex・汎用エージェント向け

Claude CodeはリポジトリルートのCLAUDE.mdを自動で読み込む。サブディレクトリ（src/CLAUDE.mdなど）にも置けばスコープを絞れる。

実例：Next.js App Router 向け CLAUDE.md

# Project Rules

## Stack
- Next.js 15 (App Router), TypeScript strict mode
- Tailwind CSS v4, Shadcn/ui
- データフェッチ: fetch API (axios 禁止)
- 状態管理: Zustand のみ (Redux/Recoil 新規導入禁止)

## コンポーネント方針
- Server Component をデフォルト。インタラクションが必要なときのみ "use client" を追加
- "use client" を追加する場合はファイル冒頭にコメントで理由を記載する
- Server Actions は app/actions/ 以下に配置し、ファイル名を *.action.ts とする

## 型
- any 禁止。unknown + 型ガードで代替
- API レスポンスは zod でバリデーションし、型推論を使う

## 禁止事項
- console.log を本番コードに残さない
- .env ファイルをコミットしない
- ページコンポーネントに直接ビジネスロジックを書かない

## テスト
- ユニットテスト: Vitest
- E2E: Playwright
- 新機能は最低1件のテストを添付する

## コミットメッセージ
- Conventional Commits 形式 (feat/fix/chore...)
- 日本語可、50字以内

運用 Tips

最小から始める。 最初から100行のルールファイルを書こうとすると、実態と乖離したルールが増える。まずレビューで何度も指摘したことを5〜10行にまとめるだけで十分だ。

エージェントに矛盾を検知させる。 「このルールは現在のコードと矛盾していないか？」と問いかけるプロンプトをCI上で定期実行すると、ルールファイルの陳腐化を防げる。

チームで育てる。 プルリクエストで同じ指摘が2回発生したら、そのルールをCLAUDE.mdに追記するフローをチームの慣習にする。ルールファイルはコードベースと一緒にバージョン管理されるため、git blameで変更理由を追える。

スコープを分ける。 src/app/CLAUDE.mdにルーティング方針、src/components/CLAUDE.mdにUI原則を分けて書くと、エージェントが関連ルールだけを読み込み、ノイズが減る。

ルールファイルはエージェントへの「仕様書」だ。書くほどレビュー負荷が下がるが、実態から離れたルールはむしろ誤誘導になる。定期的に見直しながら育てていくものとして扱うのが現実的な運用だ。

5フレームワーク分の実例をまとめたキット

Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。👉 詳細・入手はこちら

DEV Community