When you're shipping FastAPI services with LLM integrations, it's tempting to dump all your system prompts into the code and call it done. But as your agentic workflows grow, that hardcoded approach becomes a maintenance nightmare—unreviewable, unversioned, and impossible to iterate on without touching production logic.

The Three File Types That Actually Matter

The ecosystem has settled on three distinct rule files, each tied to specific tooling. CLAUDE.md targets Claude Code CLI users and handles codebase conventions plus explicit prohibitions. .cursorrules lives in Cursor IDE for completion and generation styling. AGENTS.md serves OpenAI Agents SDK teams for sharing rules across multiple agent instances. For FastAPI projects specifically, placing a CLAUDE.md at your repository root while referencing AGENTS.md from agent definition files gives you the cleanest separation between team standards and orchestration logic.

A Real CLAUDE.md Example for FastAPI

The source material breaks down an actual working configuration that hits production-grade requirements. The stack targets Python 3.12 with FastAPI 0.115 and Pydantic v2, mandates async/await throughout (threading is explicitly forbidden), and restricts database access to SQLAlchemy 2.0 async sessions only. On the coding side, endpoints live in src/api/v1/, response models use schemas/ with model_validate() instead of orm_mode=True, and exceptions route through a custom AppError hierarchy rather than raw HTTPException raises. The prohibitions are surgical: no os.system() calls, no direct DROP/TRUNCATE on production databases, and absolutely no .env content in logs. Testing requires pytest coverage for new endpoints using pytest-mock's mocker instead of unittest.mock.

AGENTS.md for Multi-Agent Orchestration

OpenAI Agents SDK v2 introduces shared rule references between sub-agents—an approach that works best when you strip the orchestrator configuration to essentials. A working example defines strict role boundaries: research_agent handles data gathering only with no file write permissions, writer_agent produces Markdown and cannot call external APIs, and publish_agent posts approved content without autonomous draft publishing authority. Both agents share loop detection (stopping after three consecutive identical tool calls) and cost ceilings ($0.10 per task maximum before interruption). This constraint-first design prevents the kind of agent drift that burns through budgets and generates garbage output.

Operational Tips That Actually Stick

The article's most valuable insight: negative lists alone fail because agents find workarounds. Every prohibition needs a one-line explanation of why it exists—"DROP on production DB is unrecoverable, therefore forbidden" hits differently than just saying "no DROP." Version your rule files in the same PRs as code changes to prevent specification drift. Add markdownlint to CI pipelines to catch formatting issues that cause misreads under load. For developer flexibility, support environment-specific overrides via CLAUDE.local.md (gitignored) layered on top of shared team rules.

The Bottom Line

Rule files aren't set-and-forget artifacts—they're living contracts between you and your agents that require iteration based on actual failure reports. Start minimal, observe what breaks in production, then add constraints with context. Teams that treat CLAUDE.md as a first-class codebase file with proper review discipline ship more predictable agentic behavior than those who treat it as an afterthought.