Go 後端可擴展性的 AGENTS.md／CLAUDE.md 規則範本

讓 AI 寫 Go 後端時走慣用法：錯誤包裝、context 串全鏈、介面定義在消費端、prepared statement 防注入。一份規則檔搞定可擴展性與安全。

[ Log in to see the full prompt ]

## 這是什麼／解決什麼痛點 用 AI 寫 Go 後端時，常見問題不是語法錯，而是「不夠 Go」：錯誤被吞掉或用 panic 當控制流、`context` 沒串到底導致逾時與取消失效、介面寫得又大又早、goroutine 沒有結束條件造成洩漏、SQL 用字串拼接埋下注入風險。這些都是會在高負載下才爆出來的可擴展性與安全問題。 這份範本把一套「慣用 Go ＋可擴展性」的紀律固化成 `AGENTS.md`（或 Claude Code 的 `CLAUDE.md`）。除了釘死錯誤包裝、context 傳遞、介面定義在消費端、並行安全、參數化查詢等慣例，它還特別保留了來源規則裡很有價值的一點：要求 AI 在實作前先做「分析→權衡」，至少比較一個替代方案的取捨，而不是給一個答案就收工——這對後端設計決策特別重要。 ## 為什麼這來源值得用 來源是 `PatrickJS/awesome-cursorrules`（CC0 公眾領域，可任意商用改作）裡的 Go 後端可擴展性規則。它的特色是把「資深後端工程師會怎麼思考」流程化（分析→方案→實作→權衡→小結），這正好補上 AI 最常缺的一塊：不去比較取捨、直接給單一解。本篇在此基礎上補強了具體的慣用 Go 護欄（`%w` 包裝、零值可用、`-race`、`log/slog`、`cmd/internal/pkg` 佈局），讓規則從「思考框架」落到「可驗證的程式碼慣例」。 ## 怎麼用 1. 把 `full_prompt` 存成專案根目錄的 `AGENTS.md` 或 `CLAUDE.md`。 2. 用 `{{ROUTER}}` 對齊你的路由方案（標準 `net/http` ServeMux、chi、gin 等）。 3. 視專案調整目錄佈局段落（不是每個專案都用 `pkg/`）。 4. 之後請 AI 寫 handler 或 service 時，它會先做分析與權衡再實作；你也可以要求它「審查這段 Go 有沒有違反 AGENTS.md（吞錯、context 沒串、字串拼 SQL）」。 ## 何時用 - 要長期維護、需承載規模的 Go 微服務或 API。 - 團隊裡有人 Go 經驗不一，想用一份契約拉齊慣用法與安全底線。 - 想讓 AI 在後端設計上多給取捨分析、少給拍腦袋的單一解。 對純 CLI 小工具或一次性腳本，這套偏重；那種情況挑其中錯誤處理與測試兩段即可。 📎 來源：PatrickJS/awesome-cursorrules（作者 PatrickJS，CC0-1.0 公眾領域授權）— 本篇為繁中改寫整理，原始內容見上方連結。