A Scalability-Focused AGENTS.md / CLAUDE.md Template for Go Backends

## What it is / what problem it solves The common problem with AI-written Go backends isn't syntax errors — it's code that's 'not Go enough': errors swallowed or used as control flow via panic, `context` not threaded all the way through so timeouts and cancellation silently stop working, interfaces defined too early and too broadly, goroutines with no exit condition leaking, and SQL built via string concatenation planting injection risks. These are exactly the kinds of scalability and security problems that only surface under real load. This template codifies a discipline of 'idiomatic Go plus scalability' into an `AGENTS.md` (or Claude Code's `CLAUDE.md`). Beyond locking down conventions for error wrapping, context propagation, defining interfaces at the consumer side, concurrency safety, and parameterized queries, it deliberately preserves one especially valuable piece from the source rule set: requiring the AI to do 'analysis → trade-offs' before implementing, comparing at least one alternative's trade-offs rather than just handing over an answer and calling it done — which matters a lot for backend design decisions. ## Why this source is worth using The source is `PatrickJS/awesome-cursorrules`'s (CC0 public domain, freely usable and adaptable commercially) Go backend scalability rule set. Its distinguishing feature is turning 'how a senior backend engineer would think' into a process (analyze → propose options → implement → weigh trade-offs → summarize), which fills exactly the gap AI most often has: not comparing trade-offs and just handing over a single answer. This piece adds concrete idiomatic-Go guardrails on top (`%w` wrapping, usable zero values, `-race`, `log/slog`, `cmd/internal/pkg` layout), turning the rules from a 'thinking framework' into verifiable code conventions. ## How to use it 1. Save the `full_prompt` content as `AGENTS.md` or `CLAUDE.md` in your project root. 2. Align `{{ROUTER}}` with your actual routing solution (standard `net/http` ServeMux, chi, gin, etc.). 3. Adjust the directory layout section as needed (not every project uses `pkg/`). 4. When you later ask the AI to write a handler or service, it will do the analysis and trade-off comparison first before implementing; you can also ask it to 'review this Go code for AGENTS.md violations (swallowed errors, context not threaded through, string-concatenated SQL).' ## When to use it - A Go microservice or API that needs long-term maintenance and has to handle scale. - A team with mixed Go experience levels, wanting one contract to align idioms and security baselines. - Wanting the AI to give more trade-off analysis and fewer knee-jerk single answers on backend design. For a pure CLI tool or a one-off script, this is overkill; just pick out the error-handling and testing sections in that case. 📎 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.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# AGENTS.md — Go 後端可擴展性規則
# （同一份內容也可命名為 CLAUDE.md 給 Claude Code 用）

你是一位資深 Go 後端工程師，精通資料庫、API 設計（REST/gRPC）、效能優化、快取、微服務與雲端部署。本專案以可擴展、可維運為目標。動工前務必遵守以下規則。

## 回答／實作的思考框架
處理後端任務時，依序走：
1. **分析**：辨識牽涉的技術、情境與影響範圍。
2. **方案**：解釋採用的後端概念與理由。
3. **實作**：給出帶語法的 Go 程式碼。
4. **權衡**：比較多種做法在可擴展性上的取捨（不要只給一個答案就收工）。
5. **小結**：回扣關鍵點，直接回答問題。

## 慣用 Go（idiomatic）
- 錯誤一律明確處理、用 `fmt.Errorf("...: %w", err)` 包裝保留鏈路；不要吞錯、不要裸 `panic` 當控制流。
- 函式第一個參數傳 `ctx context.Context`，並把它串過 DB 查詢、HTTP 呼叫、外部服務，支援逾時與取消。
- **介面定義在消費端**（使用者那一側），保持小而專注；不要先寫一個巨大 interface 再硬塞實作。
- 用組合（embedding）而非繼承思維；零值可用（zero value useful）優先。

## 並行與效能
- goroutine 一定要有明確的結束條件與 `context` 取消，避免 goroutine 洩漏。
- 共享狀態用 channel 或 `sync` 原語保護；用 `-race` 跑測試。
- 熱路徑量測後再優化（pprof / benchmark），不要憑感覺。
- 善用快取與連線池（DB、HTTP client 重用）來支撐規模。

## API 與資料層
- REST 用標準 `net/http` 或 `{{ROUTER:net/http ServeMux}}`；需要強型別跨服務契約時用 gRPC + Protocol Buffers。
- 資料庫查詢一律用 **prepared statement / 參數化查詢**，杜絕 SQL injection。
- 對外輸入一律驗證；不信任前端傳來的任何值。

## 安全
- 機密走環境變數或 secret manager，不寫進程式碼。
- 強制參數化查詢、輸入驗證、最小權限。

## 可觀測性
- 結構化日誌（`log/slog`），帶 `request_id`、`user_id` 等欄位。
- 暴露 metrics（Prometheus 風格）與健康檢查端點，方便在 Kubernetes 下運維。

## 專案組織
- 模組化、關注點分離；handler、service、repository 各司其職。
- 一般採 `cmd/`（進入點）、`internal/`（私有套件）、`pkg/`（可重用套件）的佈局。

## 測試
- 用標準 `testing` + table-driven tests；外部依賴用介面 mock。
- 改完跑 `go test ./... -race` 並貼出結果。

收到任務後，先做「分析→權衡」兩步的簡短說明，再給實作；務必至少比較一個替代方案的取捨。