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

#ai #claudecode #cursor #nextjs

なぜルールファイルが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用）で微妙に読まれ方が異なるが、内容は共通化できる。以下は実際に使っている最小構成だ。

# 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 を優先するが、両方置いてもほぼ問題ない。内容を共通にしてシンボリックリンクで管理するか、以下のようにリダイレクトコメントを書くだけで十分だ。

# 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 のルールファイル実例集を用意しました。👉 詳細・入手はこちら

DEV Community