A Production-Grade Layered-Architecture AGENTS.md / CLAUDE.md Template for FastAPI

讓 AI 寫 FastAPI 不再把 SQL 塞進路由、不再在 service 裡丟 HTTPException。四層架構、薄 handler、防腐層、冪等鍵——一份規則檔全部釘死。

[ Log in to see the full prompt ]

## What it is / what problem it solves The most common technical debt that AI-written FastAPI backends accumulate is 'everything mixed together': raw SQL written directly inside route functions, `HTTPException` thrown from inside a service, raw dicts from external APIs passed around the whole codebase unchanged, and payment mutations with no idempotency protection leading to double charges. None of this shows up as a problem in a demo, but the moment it hits production it becomes hard to test, hard to change, and a landmine waiting to go off. This template codifies a battle-tested FastAPI layered architecture into an `AGENTS.md` (or Claude Code's `CLAUDE.md`). It enforces one-directional imports through Router→Service→Repository→ORM/HTTP, thin handlers, an anti-corruption layer (ACL) isolating external APIs, a separate httpx client per external service (bulkhead isolation), idempotency keys on mutations, and a list of anti-patterns that must be rejected. Once the AI reads it, it proactively avoids these traps before writing any code. ## Why this source is worth using The source is `PatrickJS/awesome-cursorrules` (CC0 public domain, freely usable and adaptable commercially), specifically its rule set written for 'production architecture' in FastAPI. Unlike vague 'please use FastAPI best practices' guidance, this rule set is concrete and opinionated: it explicitly names nine anti-patterns to reject, gives red-yellow-green governance thresholds by file line count, and requires services to only throw domain exceptions. This level of 'concrete enough to apply directly' is exactly what actually changes AI behavior — AI tends to blow off vague principles but follows concrete prohibitions. ## How to use it 1. Save the `full_prompt` content as `AGENTS.md` or `CLAUDE.md` in your project root. 2. Align `{{TEST_TOOL}}` and `{{TEST_CMD}}` with your actual testing framework and command. 3. Adjust path names like `app/routers` and `app/services` to match your project's directory layout (if you use different naming). 4. When you later ask the AI to add an endpoint, it will first state which layer it's touching and whether it violates the import direction before making changes; you can also ask it to 'review this PR for violations of AGENTS.md's anti-pattern list.' ## When to use it - A production-grade FastAPI service that needs long-term maintenance and touches payments or external APIs. - Multi-person collaboration where you want one contract to unify architectural discipline. - An existing project that's already started 'mixing everything into the routes' and you want to stop the bleeding and refactor gradually. For a small script or a one-off demo, this architecture is overkill; a lighter rule set is fine for that. 📎 Source: PatrickJS/awesome-cursorrules (by PatrickJS, CC0-1.0 public domain license) — this piece is a rewritten and reorganized version; see the link above for the original content.