2026年版: Next.jsエージェント開発でルールファイルを書く実践ガイド

## なぜルールファイルがAIエージェントに効くのか Claude CodeやCursor、OpenAI Agentsなどのコーディングエージェントは、プロジェクトルートに置かれた`CLAUDE.md`・`.cursorrules`・`AGENTS.md`を会話コンテキストの先頭に自動注入する。つまり「毎回口頭で言わなければならなかった制約」を一度書くだけで全セッションに効かせられる。 Next.js App Router × TypeScript プロジェクトでは特に次の問題が頻出する。 - `pages/` ディレクトリに新規ルートを作ろうとする（旧Router混入） - `'use client'` を付け忘れてサーバーコンポーネントからフックを呼ぶ - `fetch` をクライアントコンポーネントで直書きし、キャッシュ戦略が消える - `any` 型を多用して型安全が崩壊する これらはすべてルールファイルに書けば防ぎやすくなる。「防ぎやすくなる」であって、完全に防止できると保証するものではない点は留意してほしい。 ## 実例: CLAUDE.md の書き方 ファイル名は `CLAUDE.md`（Claude Code用）と `.cursorrules`（Cursor用）で微妙に読まれ方が異なるが、内容は共通化できる。以下は実際に使っている最小構成だ。 ```markdown # Project Rules ## Stack - Next.js 15 App Router (TypeScript strict) - Runtime: Node.js 20 LTS - Styling: Tailwind CSS v4 - State: React Server Components first, Zustand only for client state ## Directory Conventions - Route segments: `app/` only. `pages/` は作らない - Server Components are the default. Add `'use client'` only when hooks or browser APIs are needed - Data fetching: `fetch` in Server Components with explicit `cache` option (`force-cache` or `no-store`) - API Routes: `app/api/**/route.ts` のみ ## TypeScript - `any` 禁止。型が不明なら `unknown` + 型ガードを使う - Zod でバリデーションし、型推論を `z.infer<>` で引き出す ## File Generation Rules - Component: PascalCase、`*.tsx` - Utility: camelCase、`*.ts` - テストは `__tests__/` または `*.test.ts` に配置 ## What NOT to Do - `useEffect` でデータフェッチしない（Server Componentで完結させる） - `export default` の無名関数禁止（デバッグ困難になるため） - console.log をコミットしない ``` このファイルをプロジェクトルートに置くだけで、エージェントは App Router の慣習を踏まえたコードを生成しやすくなる。 ## AGENTS.md との使い分け `AGENTS.md` は OpenAI の Codex / Agents API が読む仕様として提唱された。Claude Code は `CLAUDE.md` を優先するが、両方置いてもほぼ問題ない。内容を共通にしてシンボリックリンクで管理するか、以下のようにリダイレクトコメントを書くだけで十分だ。 ```markdown # AGENTS.md <!-- See CLAUDE.md for the canonical rules --> ``` プロジェクトが複数エージェントを横断する場合は、`CLAUDE.md`（Claude Code）・`.cursorrules`（Cursor）・`AGENTS.md`（OpenAI系）の3ファイルを同じ内容で保つ運用がシンプルだ。 ## 運用Tips **サブディレクトリにも置ける** `app/api/CLAUDE.md` を作ると、APIルート専用の追加ルール（認証必須・レートリミット実装パターンなど）をスコープして書ける。上位ファイルと合算されて読まれる。 **ルールは増やしすぎない** 行数が増えるほどエージェントのコンテキスト消費が増え、肝心なルールが薄まる。「違反が実際に起きたもの」だけを追記する運用が長持ちする。 **変更履歴をコミットに残す** ルールファイルの変更は `git blame` で追えるようにしておくと、「なぜこのルールがあるか」が後から分かる。コメントで理由を書くより git log の方が腐りにくい。 **効果測定は現実的に** ルールファイルはエージェントへのヒントであり、必ず従うことを強制するものではない。レビューフローと組み合わせて初めて品質ゲートとして機能する。CI で `tsc --noEmit` と ESLint を通すことが最後の砦だ。 --- ### 5フレームワーク分の実例をまとめたキット Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。[👉 詳細・入手はこちら](https://itsuya.gumroad.com/l/agentrules260619)