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

なぜルールファイルがエージェントの品質を左右するか

LLMベースのAIエージェントは、指示が曖昧なほど「それっぽいが間違った」コードを返す。FastAPIプロジェクトで顕著なのが、async def の混在・依存注入の誤用・レスポンスモデルの省略といったパターンだ。ルールファイルはこれを防ぐ「コンテキストの壁」として機能する。Claude CodeやCursor、OpenAI Agents SDKはいずれもプロジェクトルートのファイルを自動で読み込み、生成の前提条件として扱う。

ルールファイルの種類と使い分け

FastAPIプロジェクトでは CLAUDE.md と AGENTS.md を併置するのが現実的だ。前者はコード規約、後者はエージェントの振る舞いを定義する。

実例：FastAPI向けCLAUDE.md

# Project Rules

## Stack
- Python 3.12 / FastAPI 0.115 / SQLAlchemy 2.x (async)
- Pydantic v2 (BaseModel, model_validator)
- テストは pytest-asyncio + httpx.AsyncClient

## コーディング規約
- ルーターは `src/routers/` に機能単位で分割。`__init__.py` への直接実装禁止
- 依存注入は `Annotated[T, Depends(f)]` 形式のみ。引数デフォルト値への Depends 禁止
- 全エンドポイントに `response_model=` と `status_code=` を明示する
- DB アクセスは必ず `async with AsyncSession` を使い、セッションをリークしない
- `print()` 禁止。`logging.getLogger(__name__)` を使う

## コメント
- WHYが自明でない場合のみ1行。docstringはPublic APIのみ

## テスト
- ユニットテストはモック可。DBを触るテストは実DB(SQLite インメモリ)必須
- モックで済ませたDBテストはマージ不可

## 禁止事項
- `from __future__ import annotations` は使わない(Pydantic v2との競合)
- `.env` をコミットしない。サンプルは `.env.example` のみ

実例：AGENTS.md（エージェント行動ポリシー）

# Agent Policy

## ツール使用ルール
- `read_file` は確認用。編集前に必ず1回呼ぶ
- `run_tests` は変更後に必ず呼び、PASS確認後に完了を報告する
- DBスキーマ変更(ALTER TABLE等)は人間の承認なしに実行しない

## 出力形式
- 変更ファイルのパスと変更理由を箇条書きで先に述べる
- コードブロックにはファイルパスをコメントで明記する

## 禁止行為
- `--no-verify` でフックをスキップしない
- 存在しないファイルパスを推測で返さない
- テストが通らない状態でタスク完了を宣言しない

運用Tips

• 具体性が命：「良いコードを書け」は機能しない。「response_model= を省略したらエラー扱いにせよ」のように検証可能な形で書く。
• 禁止事項を必ず書く：何をしてはいけないかを明示しないと、エージェントは過去の学習データから「よくあるが間違った」パターンを引いてくる。
• ファイルは小さく保つ：300行を超えると肝心な制約が読み飛ばされる。プロジェクト規約・エージェントポリシー・環境セットアップは分割し、CLAUDE.md から @include で参照するか、ディレクトリ別に CLAUDE.md を置く階層構造にする。
• 変更履歴をルールに残さない：「2026-06-30追加」のような注釈はgit logに任せ、ルールファイルには現在有効な規約だけを書く。コメントの腐敗が最大の落とし穴だ。

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

Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。

👉 詳細・入手はこちら