なぜルールファイルがAIエージェントに効くのか

AIエージェント(Claude Code / Cursor / OpenAI Codex CLI など)はプロジェクトルートの設定ファイルを毎セッション読み込む。指示が無い状態では、エージェントは汎用的なコーディング規約を適用するため、React + TypeScript(Vite)特有の慣習——たとえば src/features/ 単位のコロケーション構成や zod によるバリデーション層——が守られないコードを生成しやすい。ルールファイルを置くことで「このプロジェクトにおけるデフォルト判断」を明文化できる。副次効果として、レビューコメントの繰り返しが減り、PR差分が一貫したスタイルに収束しやすくなる。効果は「書いた分だけ」であり、魔法的な品質向上ではない点に注意。

ファイルの使い分け

単一リポジトリで複数エージェントを使う場合は CLAUDE.md にマスター定義を書き、他ファイルからインクルード指示を添える運用が現実的だ。

React + TypeScript(Vite)向け実例

以下は中規模SPAに実際に使用しているルールの抜粋。コンポーネント設計とテスト方針に絞っている。

# CLAUDE.md

## プロジェクト構成
- フレームワーク: React 19 + TypeScript 5.8 + Vite 6
- 状態管理: Zustand(グローバル) + TanStack Query(サーバー状態)
- スタイル: Tailwind CSS v4、CSS Modules は使わない

## コンポーネント規約
- `src/features/<ドメイン>/` 以下にコロケーション配置
  例: `features/auth/LoginForm.tsx`, `features/auth/useAuth.ts`
- UIプリミティブは `src/components/ui/` に分離
- propsの型定義はコンポーネントファイル内にインラインで書く(別ファイル不要)
- `React.FC` は使わず、通常の関数宣言を使う

## 型・バリデーション
- API境界はすべて zod スキーマを経由する
- `as unknown as T` のキャストは禁止。型が合わない場合はスキーマを修正する

## テスト
- ユニットテスト: Vitest + Testing Library
- 外部APIはモックしてよいが、Zustandストアは実インスタンスを使う
- カバレッジ目標はなし。回帰が怖い箇所だけテストを書く

## エージェントへの制約
- package.json の依存追加は提案のみ行い、npm install は実行しない
- .env ファイルは読まない・書かない・出力しない
- 既存ファイルを削除する前にユーザーに確認を取る

運用Tips

段階的に育てる。 最初から完璧なルールを書こうとしない。エージェントが誤った判断をするたびにルールを1行追記する方が、実際の問題を反映したドキュメントになる。

否定形より肯定形を優先する。 「〜するな」より「〜する」と書いた方がエージェントの解釈がブレにくい。ただし as unknown as T 禁止のような安全制約は否定形のまま残す。

AIに草案を書かせる。 CLAUDE.md の草案を現在の src/ ディレクトリ構造から生成して と依頼すると初期版が得られる。その後、間違っている箇所を人間が修正する方が白紙から書くより速い。

コミット管理。 ルールファイルはコードと同じく git 管理する。変更時はコミットメッセージに「なぜ変えたか」を書いておくと、数週間後に見直したときに判断根拠が残る。

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

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