なぜルールファイルがAIエージェントに効くのか
Claude CodeやCursorなどのAIエージェントは、プロジェクト直下の CLAUDE.md / .cursorrules / AGENTS.md をシステムプロンプト的に読み込む。これにより、エージェントが生成するコードのスタイルや禁止事項をリポジトリ単位で固定できる。
FastAPIプロジェクトで典型的に起きる問題は「エージェントが毎回異なる構造でエンドポイントを生成する」「依存性注入の書き方がバラバラになる」といったものだ。ルールファイルはその揺れを吸収する。
実例：FastAPI向けCLAUDE.md
# Project Rules
## Stack
- Python 3.12 / FastAPI 0.115 / SQLAlchemy 2.x (async)
- Pydantic v2。BaseModelは`model_config = ConfigDict(from_attributes=True)`を必ず付ける
## ルーター設計
- 1ファイル1ルーター。`router = APIRouter(prefix="/v1/xxx", tags=["xxx"])`
- エンドポイント関数名は `動詞_名詞` 形式 (例: `create_user`, `list_orders`)
## 依存性注入
- DBセッションは必ず `Annotated[AsyncSession, Depends(get_db)]` で受け取る
- 認証は `CurrentUser = Annotated[User, Depends(get_current_user)]` に統一
## 禁止事項
- グローバルな `db = SessionLocal()` は書かない
- `response_model` の省略禁止。必ずスキーマを明示する
- `print()` デバッグ禁止。`logger.info()` を使う
## テスト
- pytest + httpx.AsyncClient。fixtureは `tests/conftest.py` に集約
- モック対象は外部HTTP呼び出しのみ。DBはSQLiteインメモリを使う
## エラーハンドリング
- 業務エラーは `raise HTTPException(status_code=422, detail={"code": "...", "message": "..."})` の形式
- 500系は上位ミドルウェアに任せ、各エンドポイントでは握りつぶさない
このファイルをリポジトリ直下に置くだけで、Claude CodeやCursorは新規ファイル生成時にこのルールを参照する。
.cursorrules と AGENTS.md の使い分け
| ファイル | 読むツール | 特徴 |
|---|---|---|
CLAUDE.md | Claude Code | 階層ディレクトリごとに複数置ける |
.cursorrules | Cursor | ルートの1ファイルのみ |
AGENTS.md | OpenAI Codex系 | 同上、書式は自由 |
複数ツールを併用するなら CLAUDE.md をマスターにして .cursorrules にシンボリックリンクを張る運用が現実的だ。
運用Tips
スコープを絞る。 ルールが多すぎるとエージェントが全体を読み飛ばす。1ファイルあたり50行以内を目安にする。
禁止より構造を書く。 「〜するな」より「〜のパターンを使え」の方がエージェントは従いやすい。実際のコードスニペットを1行でも添えると精度が上がる。
変更履歴をコメントで残さない。 ルールファイルはgit管理されるのでdiffで追える。「2026-06 追加」などのコメントは削除して本文だけにする。
チームレビューに乗せる。 ルールファイルの変更がPRに含まれていれば、エージェントの挙動変化をレビュー対象にできる。インフラのIaCと同じ扱いが妥当だ。
ルールファイルは「AIへの型」であり、一度書けばプロジェクト全体のコード生成品質を均質化できる。FastAPIのように規約が多いフレームワークほど効果が出やすい。
5フレームワーク分の実例をまとめたキット
Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。👉 詳細・入手はこちら
SOCIAL SHARE CARD GENERATOR