ai-driven-dev Procedure — add an endpoint
Written down because the first three times we did it, we forgot a different step each time.
- Contract first. Add the path to
openapi.yaml. Request, response, error codes. Nothing else until this is reviewed. - Failing test.
internal/api/<resource>_test.go, one case per error code in the contract. Run it, watch it fail for the right reason. - Handler. Transport only: decode, call the domain, encode. No business
logic in
internal/api/. - Domain function, with its own tests, in the package that owns the data.
- Store query if needed. Follow
.claude/rules/sql.md— deadline, named columns,EXPLAINin the PR if the table is large. - Metric. One counter and one histogram, named after the endpoint.
- Regenerate the client.
make client. Commit the diff separately.
Done when
make verify is green, the contract diff is in the PR, and the metric appears
in the local Grafana.