なぜルールファイルがエージェントの品質を左右するか
LLMベースのAIエージェントは、指示が曖昧なほど「それっぽいが間違った」コードを返す。FastAPIプロジェクトで顕著なのが、async defの混在・依存注入の誤用・レスポンスモデルの省略といったパターンだ。ルールファイルはこれを防ぐ「コンテキストの壁」として機能する。Claude CodeやCursor、OpenAI Agents SDKはいずれもプロジェクトルートのファイルを自動で読み込み、生成の前提条件として扱う。
ルールファイルの種類と使い分け
| ファイル | 読み込むツール | 用途 |
|---|---|---|
CLAUDE.md |
Claude Code | プロジェクト全体の規約・コマンド |
.cursorrules |
Cursor | エディタ補完・生成スタイル |
AGENTS.md |
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 のルールファイル実例集を用意しました。👉 詳細・入手はこちら
Top comments (0)