2026年版：FastAPIエージェントに渡すルールファイル(CLAUDE.md/AGENTS.md)の実例と書き方

#ai #claudecode #cursor #fastapi

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

DEV Community