2026年版：AIエージェントへのNext.js TypeScriptプロジェクトルールファイル完全解説

#ai #claudecode #cursor #nextjs

なぜルールファイルが必要か

GitHub Copilot・Claude Code・Cursor などのAIエージェントは、プロジェクト固有のコンテキストを持たない状態でコードを生成する。App Router への移行後も pages/ を使ったコードを提案したり、any 型を乱発したりするのはこのためだ。

ルールファイル（CLAUDE.md / .cursorrules / AGENTS.md）は「このプロジェクトではこう書く」という制約を宣言的に与える仕組みで、プロンプトを毎回書き直すより安定して効く。エージェントがファイルを生成・修正するたびに参照するため、レビュー指摘が構造的に減る。

各ファイルの用途整理

ファイル	読むエージェント	置き場所
`CLAUDE.md`	Claude Code	プロジェクトルート or サブディレクトリ
`.cursorrules`	Cursor	プロジェクトルート
`AGENTS.md`	OpenAI Codex系	プロジェクトルート

内容はほぼ共通化できる。CLAUDE.md を正として、他はシンボリックリンクか同内容コピーで管理するのが現実的だ。

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

# Project Rules

## Stack
- Next.js 15 App Router (src/app/ ディレクトリ)
- TypeScript strict mode (tsconfig strict: true)
- Tailwind CSS v4
- Prisma + PostgreSQL

## ディレクトリ規約
- ページ: src/app/(routes)/[slug]/page.tsx
- サーバーコンポーネントをデフォルトとし、インタラクションが必要な場合のみ "use client" を追加
- API Route は src/app/api/ 以下、Route Handler (route.ts) を使う。pages/api/ は使わない

## TypeScript
- `any` 禁止。型が不明な場合は `unknown` を使い、型ガードで絞る
- Server Actions は src/app/actions/ に置き、ファイル先頭に "use server" を記載
- Props 型は inline interface ではなく export type Props = {...} で定義する

## データフェッチ
- fetch は Server Component 内で直接呼ぶ。useSWR / React Query はクライアント側のみ
- キャッシュ戦略は { next: { revalidate: N } } で明示する。cache: "no-store" をデフォルトにしない

## 命名
- コンポーネント: PascalCase (UserCard.tsx)
- ユーティリティ関数: camelCase (formatDate.ts)
- 定数: SCREAMING_SNAKE_CASE

## テスト
- ユニットテストは Vitest + Testing Library
- E2E は Playwright (tests/e2e/)
- テストファイルは対象ファイルと同階層に置く (UserCard.test.tsx)

## 禁止事項
- `console.log` をコミットしない (console.error は可)
- `eslint-disable` コメントを新規追加しない
- `pages/` ディレクトリへの新規ファイル追加禁止

運用Tips

粒度を絞る：ルールが長すぎるとエージェントが重要度を判断できなくなる。「禁止事項」は5件以内を目安にし、守らせたいものだけ書く。

サブディレクトリに分割する：Claude Code は src/app/CLAUDE.md のようにサブディレクトリのルールファイルも読む。src/app/api/CLAUDE.md にAPI固有ルールを書くと、関係ない箇所への影響を局所化できる。

CI で整合性を検証する：ルールファイルに書いた規約をESLintやtsc --noEmitのCIチェックと対応させる。エージェントが違反コードを生成しても、CIが自動で検出できる状態にしておく。

定期的に更新する：Next.jsのバージョンアップや方針変更があったときは即座に更新する。古いルールが残ると、エージェントが矛盾したコードを生成する原因になる。git管理し、変更理由をコミットメッセージに残すと後から追える。

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

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

DEV Community