なぜルールファイルがエージェント品質を左右するか
FastAPIで構築したAIエージェントにClaude CLIやCursorを組み合わせるとき、LLMへの「指示の揺れ」が最大のボトルネックになる。同じコードベースを触らせても、プロンプトが毎回違えば出力も毎回ブレる。CLAUDE.md / .cursorrules / AGENTS.md といったルールファイルは、その揺れをゼロにするための静的な仕様書だ。
LLMはコンテキストウィンドウの先頭に近いテキストを強く参照する。リポジトリルートに置いたルールファイルはツールが自動でコンテキスト先頭に挿入するため、毎回プロンプトに書かなくても設計意図が伝わる。
実例：FastAPIプロジェクト向け CLAUDE.md
# CLAUDE.md — AIエージェント行動ルール
## プロジェクト概要
Python 3.12 / FastAPI 0.111 / PostgreSQL 16 で構築した
REST API サーバー。非同期 I/O (asyncpg) を全面採用。
## コーディング規約
- 型アノテーションを必ず付ける(py.typed 準拠)
- Pydantic v2 モデルで入出力を定義する
- ルーターは `src/routers/` に機能単位で分割する
- テストは pytest-asyncio + httpx.AsyncClient で書く
## 禁止事項
- `time.sleep()` の使用禁止。`asyncio.sleep()` を使う
- グローバル変数への副作用を持つ関数を作らない
- `.env` の値をコードにハードコードしない
## エージェントへの追加指示
- 既存関数を書き換える前に「変更理由」を1行コメントで残す
- DBスキーマ変更を伴う場合は Alembic マイグレーションファイルも生成する
- PR説明文は英語、コードコメントは日本語で統一する
## 参照ドキュメント
- API仕様: docs/openapi.yaml
- ERD: docs/erd.png
- 環境変数一覧: .env.example
ファイル種別の使い分け
| ファイル名 | 読み込むツール | 主な用途 |
|---|---|---|
CLAUDE.md |
Claude CLI / Claude Code | プロジェクト全体の設計思想と禁止事項 |
.cursorrules |
Cursor IDE | エディタ操作レベルの補完ルール |
AGENTS.md |
OpenAI Agents SDK など | エージェント同士の役割分担と通信プロトコル |
FastAPIプロジェクトでは CLAUDE.md を最上位に置き、サブディレクトリ(src/routers/など)にも局所的な補足を置く階層構造が実用的だ。Claude CLIはディレクトリを上から下へ収集して結合するため、上位の方針を下位で上書きできる。
運用Tips
1. 「禁止事項」を先に書く
LLMは許可より禁止の方が遵守率が高い。asyncio.sleep() の強制など、型チェッカーで検出できないルールほど明示する効果が大きい。
2. ルールは測定可能な形にする
「良いコードを書く」ではなく「型アノテーションを必ず付ける」のように、LLMが自己検証できる粒度にする。曖昧なルールは無視される。
3. CIでルールの整合性を検証する
ruff や mypy をCIに組み込み、ルールファイルで定めた規約が守られているかを自動確認する。エージェントが破ったルールはCIが検知し、次のプロンプトでフィードバックする仕組みにすると自己修正ループが回る。
4. 変更履歴をコミットメッセージに残す
ルールファイル自体もGit管理し、なぜそのルールを追加・削除したかをコミットメッセージに書く。3ヶ月後に「このルールは何のために？」と迷う時間を省ける。
ルールファイルは銀の弾丸ではないが、エージェントの出力を「毎回ゼロから説明する」から「既知の前提の上に積む」に変える最も低コストな手段だ。まず10行の CLAUDE.md から始めて、エージェントが迷うたびに1行追加する運用が現実的に続く。
5フレームワーク分の実例をまとめたキット
Next.js/React/FastAPI/Godot/Express のルールファイル実例集を用意しました。👉 詳細・入手はこちら
Top comments (0)