2026年版・FastAPIエージェントに渡すルールファイルの書き方と実例

#ai #claudecode #cursor #fastapi

なぜルールファイルがエージェントの精度を上げるか

LLMベースのAIエージェントは、プロンプトに何も制約を与えなければ「それっぽい」コードを返す。しかしFastAPIプロジェクトで実際に使うと、async defを忘れたエンドポイントやインポート順の不統一、プロジェクト固有の命名規則の無視といった問題が毎回発生する。

ルールファイル（CLAUDE.md / .cursorrules / AGENTS.md）は、エージェントがコンテキストとして毎回読み込む「チームの取り決め書」だ。個別プロンプトで都度指示するより、リポジトリに置いておく方が再現性が高く、チームメンバーが増えても一元管理できる。

実例：FastAPI向けCLAUDE.md

# プロジェクトルール（CLAUDE.md）

## 言語・フレームワーク
- Python 3.12 / FastAPI 0.115 / Pydantic v2
- 非同期エンドポイントは必ず `async def` を使う
- `from __future__ import annotations` を各ファイル先頭に入れる

## ディレクトリ構成
src/
  api/        # ルーター（router.py）
  schemas/    # Pydantic モデル（request.py / response.py）
  services/   # ビジネスロジック（副作用のある処理）
  repos/      # DB アクセス層（SQLAlchemy Core のみ）

## 命名規則
- エンドポイント関数: `get_xxx` / `create_xxx` / `delete_xxx`
- Pydantic モデル: `XxxRequest` / `XxxResponse`
- 環境変数は `settings.py` の `Settings` クラス経由。os.environ直読み禁止

## 禁止事項
- ORM の `relationship` による遅延ロード（N+1防止のため join で取る）
- `print()` デバッグ（ログは `structlog` を使う）
- テストなしの新規エンドポイント追加

## テスト
- pytest + httpx の `AsyncClient` でエンドポイントテストを書く
- テストファイルは `tests/api/test_<router名>.py` に配置

このように「なぜそのルールか」をコメントで補足しておくと、エージェントが文脈を理解しやすくなる。

.cursorrules と AGENTS.md の使い分け

.cursorrules は Cursor IDE が自動ロードする形式で、エディタ統合が目的の場合に使う。AGENTS.md は OpenAI Agents SDK や社内フレームワークがデフォルトで参照するファイル名として広まりつつある。Claude Code は CLAUDE.md を優先する。

複数ツールを併用するなら、共通ルールを rules/base.md に切り出して各ファイルから # include rules/base.md のようにパスを記載し、DRYに保つのが現実的だ。

運用Tips

スコープを絞る：全プロジェクト共通ルールをルートに、サブパッケージ固有ルールをそのディレクトリの CLAUDE.md に分割する。エージェントは近いスコープのファイルを優先するため、上書き関係が直感的になる。

バージョン管理に含める：.gitignore に入れず、PR レビューの対象にする。ルールが変わった経緯が git log で追える。

定期的に棚卸しする：ライブラリのメジャーバージョンアップ時にルールが古くなりやすい。月1回 CLAUDE.md を読み直し、実態と乖離していないか確認する習慣をつける。

出力を検証する：ルールファイルはエージェントの出力を「誘導」するが、保証しない。CI でリント・型チェック・テストを必ず通し、ルールに違反した出力を機械的に弾く仕組みと組み合わせて使う。

ルールファイルは書いて終わりではなく、チームとエージェントが学習しながら育てるドキュメントだ。まず最小限から始め、問題が起きたときにルールを追加するアプローチが長続きする。

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

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

DEV Community