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

#ai #claudecode #cursor #fastapi

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

LLMを組み込んだFastAPIサービスでは、モデルへの指示をコード内にハードコードしがちだ。しかしシステムプロンプトが肥大化すると可読性が落ち、チームで管理しにくくなる。そこで注目されているのが CLAUDE.md / .cursorrules / AGENTS.md といった「ルールファイル」だ。

これらは本質的にはただのテキストファイルだが、ツール（Claude Code・Cursor・OpenAI Agents SDK等）が起動時に自動で読み込むことで、エージェントの振る舞いをコードから切り離して管理できる。変更履歴はgitで追えるし、レビューもしやすい。

3種ファイルの役割分担

ファイル	主な読込ツール	用途
`CLAUDE.md`	Claude Code CLI	コードベース規約・禁止操作
`.cursorrules`	Cursor IDE	補完・生成スタイル
`AGENTS.md`	OpenAI Agents SDK	エージェント間のルール共有

FastAPIプロジェクトでは、リポジトリルートに CLAUDE.md を置き、エージェント定義ファイル側から AGENTS.md を参照する構成が扱いやすい。

実例：FastAPIエージェント向け CLAUDE.md

# Project Rules for AI Agents

## Stack
- Python 3.12 / FastAPI 0.115 / Pydantic v2
- 非同期処理は async/await 統一（threading 禁止）
- DBアクセスは SQLAlchemy 2.0 async session のみ

## コーディング規約
- エンドポイントは src/api/v1/ 配下に配置
- レスポンスモデルは必ず schemas/ に定義し、orm_mode=True を使わず model_validate() を使う
- 例外は HTTPException を直接 raise せず、src/exceptions.py の AppError サブクラスを使う

## 禁止操作
- os.system() / subprocess の直接呼び出し禁止
- 本番DBへの直接 DROP / TRUNCATE 禁止
- .env の内容をログに出力禁止

## テスト
- 新規エンドポイントには tests/api/ に pytest テストを必ず追加
- モックは unittest.mock ではなく pytest-mock の mocker を使う

## AIエージェント固有
- ツール呼び出し1回あたりの最大トークン数: 4096
- 不確かな場合は実行せず、人間に確認を求める（ask_human ツールを使う）
- 外部APIへの書き込み操作（POST/PUT/DELETE）は必ずユーザー確認後に実行

このファイルをリポジトリルートに置くだけで、Claude Codeが自動的に読み込み、補完・生成・コードレビューの全フェーズで制約として機能する。

AGENTS.md でマルチエージェント間のルールを共有する

OpenAI Agents SDK（v2）では、サブエージェントが AGENTS.md を参照できる。オーケストレーター側に渡す場合は以下のように最小限に絞るのが実際の運用でうまくいく。

# Agent Behavior Rules

## 役割境界
- research_agent: 情報収集のみ。ファイル書き込み不可
- writer_agent: Markdown生成のみ。外部API呼び出し不可
- publish_agent: 承認済みコンテンツの投稿のみ。下書きを勝手に公開禁止

## 共通制約
- ループ検出: 同一ツールを連続3回呼んだら停止してレポート
- コスト上限: 1タスクあたり $0.10 を超えたら処理中断

運用Tips

1. ルールはネガティブリストより意図を書く
「〜禁止」だけのリストはエージェントが迂回策を探す。「なぜその制約があるか」を一行添えると遵守率が上がる傾向がある（例：「本番DBへのDROPは復旧不能なため禁止」）。

2. バージョン管理をgitと統一する
ルールファイルをコードと同じPRに含めることで、仕様変更とルール変更のズレを防げる。

3. CI でルールファイルの構文チェックを入れる
markdownlint をCIに追加し、意図しない空白やリスト崩れで誤読されるリスクを減らす。

4. 環境ごとにオーバーライドする
CLAUDE.local.md（gitignore済み）に開発者個人の設定を書き、チーム共通の CLAUDE.md を上書きできる構成にすると柔軟性が増す。

ルールファイルは「書いたら終わり」ではなく、エージェントの誤動作レポートを見てイテレーションするものだ。まず最小限のルールから始め、実際に問題が起きたときに追記していくのが現実的な進め方になる。

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

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

DEV Community