FastAPI 生產級分層架構的 AGENTS.md／CLAUDE.md 規則範本

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

[ Log in to see the full prompt ]

## 這是什麼／解決什麼痛點 用 AI 寫 FastAPI 後端，最容易長出的技術債就是「全部混在一起」：路由函式裡直接寫 SQL、service 裡丟 `HTTPException`、外部 API 的原始 dict 在整個 codebase 裡傳來傳去、扣款沒有冪等保護導致重複扣錢。這些在 demo 階段看不出問題，一上生產就變成難測、難改、會出事的地雷。 這份範本把一套經過實戰打磨的 FastAPI 分層架構固化成 `AGENTS.md`（或 Claude Code 的 `CLAUDE.md`）。它強制 Router→Service→Repository→ORM/HTTP 的單向匯入、薄 handler、防腐層（ACL）隔離外部 API、每個外部服務獨立的 httpx client（隔艙隔離）、mutation 帶冪等鍵、以及一份「必須拒絕的反模式」清單。AI 讀到它之後，會在寫程式前就主動避開這些陷阱。 ## 為什麼這來源值得用 來源是 `PatrickJS/awesome-cursorrules`（CC0 公眾領域，可任意商用改作）裡專為「生產架構」寫的 FastAPI 規則。和坊間泛泛的「請用 FastAPI 最佳實踐」不同，這份規則非常具體且有意見：它明確點名要拒絕哪九種反模式、給出檔案行數的紅黃綠燈治理、要求 service 只丟領域例外。這種「具體到可以直接套用」的程度，正是讓 AI 真的改變行為的關鍵——模糊的原則 AI 會敷衍，具體的禁令 AI 會遵守。 ## 怎麼用 1. 把 `full_prompt` 存成專案根目錄的 `AGENTS.md` 或 `CLAUDE.md`。 2. 用 `{{TEST_TOOL}}`、`{{TEST_CMD}}` 對齊你的測試框架與指令。 3. 對照你的專案目錄調整 `app/routers`、`app/services` 等路徑名稱（若你用不同命名）。 4. 之後請 AI 加 endpoint 時，它會先說明動哪一層、是否違反匯入方向，再動手；你也可以叫它「審查這個 PR 有沒有違反 AGENTS.md 的反模式清單」。 ## 何時用 - 需要長期維護、會接金流或外部 API 的生產級 FastAPI 服務。 - 多人協作，想用一份契約統一架構紀律。 - 既有專案已經開始「什麼都混在路由裡」，想止血並逐步重構。 對只是寫個小腳本或一次性 demo 的場景，這套架構偏重；那種情況用更輕的規則即可。 📎 來源：PatrickJS/awesome-cursorrules（作者 PatrickJS，CC0-1.0 公眾領域授權）— 本篇為繁中改寫整理，原始內容見上方連結。