go-api-playbook

Go API Playbook

This is the literal procedure a frontier model follows when building or fixing Go HTTP services. Follow it step by step; the order is the point. Go's compiler catches type errors but is silent about the mistakes that actually ship bugs — dropped errors, leaked goroutines, unclosed rows — so those checks are yours.

Operating loop

1. Read go.mod before anything else. Note (a) the go directive — you may not use language features newer than it (loop-var semantics changed in 1.22, slices/maps packages need 1.21, generics need 1.18); (b) the dependency list — if chi/gin/echo/sqlx is there, the project uses it; if not, you use net/http and database/sql, never a new dependency on your own authority.
2. Find the local dialect and mirror it. Before writing a handler, read two existing ones: grep -rn "http.ResponseWriter" --include="*.go" . — copy the project's routing registration, error-response shape (JSON envelope? plain http.Error?), and middleware chaining style exactly. A "better" pattern that differs from the neighbors is a defect here.
3. Place code where the package layout says it goes. Match existing package boundaries (internal/, cmd/, handler vs service vs store layers). Do not invent a new package for one function.
4. Write the smallest coherent change, then immediately run go build ./.... Build after every file, not at the end — Go's unused import/variable errors compound fast.
5. For every function you add, decide the ctx story out loud: I/O functions take ctx context.Context as the first parameter, received from the caller (r.Context() in handlers), never context.Background() mid-path.
6. For every if err != nil you write, decide the wrap (see decision tree below) — the default is fmt.Errorf("what I was doing: %w", err).
7. Run the verification recipe (below) and read your own diff line by line before handing off. Hunt specifically for _ =, missing return after error responses, and defer inside loops.