AGENTS.md

1# AGENTS.md
2 
3## Agent Instructions
4 
5> **Note for the AI agent:** Before running the startup script, verify that all dependencies and CLI tools are already available. If a `vendor/` directory exists **or** `go list -m -mod=readonly all` succeeds (indicating modules are cached), you may skip the entire startup script—including all `go mod` commands and `go install` steps. Otherwise, run the script as listed below.
6 
7### General coding practices
8 
9- When adding Go tests, always invoke `t.Parallel()` at the start of each test and subtest to maximize concurrency.
10- Prefer `github.com/gofiber/utils/v2` helpers (for example, `utils.Trim`) when performing common operations such as string manipulation, whenever it is practical and appropriate for the surrounding code.
11- Keep all protocol behavior RFC-compliant (e.g., HTTP/1.1 requirements) and document any intentional deviations.
12- Protect hot paths from regressions: profile changes.
13- Apply secure-by-default choices (validation, timeouts, sanitization) and ensure new code hardens attack surfaces.
14 
15### Linter pitfalls (run `make lint` before every push)
16 
17The linter is the most common reason CI fails for generated changes. Always run
18`make lint` locally and fix every finding *before* committing — do not rely on
19CI to surface them. The `golangci-lint` config (`.golangci.yml`) enables strict
20`errcheck` settings (`check-type-assertions: true` and `check-blank: true`),
21which trip up the patterns below:
22 
23- **Never discard a type-assertion result with `_`.** `v, _ := x.(T)` fails
24  `errcheck`. Use the comma-ok form and act on it instead:
25 
26```go
27  v, ok := x.(T)
28  if !ok {
29      v = T{} // explicit fallback; the zero value is fine when that's intended
30  }
31```
32 
33- **Never discard a returned `error` with `_`** (`check-blank`). Handle it, or
34  if it is genuinely safe to ignore, call the function without assignment or add
35  a justified `//nolint:errcheck // reason` comment.
36 
37- When in doubt, run `make lint` (or `golangci-lint run ./<pkg>/...`) and treat a
38  non-zero exit as a blocker.
39 
40---
41 
42## Startup script (reference only – do not run)
43 
44- Fetch dependencies:
45 
46```bash
47  go mod tidy && go mod download && go mod vendor
48```
49 
50- Install CLI tools referenced in Makefile:
51 
52```bash
53  go install gotest.tools/gotestsum@latest                 # test runner
54  go install golang.org/x/vuln/cmd/govulncheck@latest      # vulnerability scanner
55  go install mvdan.cc/gofumpt@latest                       # code formatter
56  go install github.com/tinylib/msgp@latest                # msgp codegen
57  go install github.com/vburenin/ifacemaker@f30b6f9bdbed4b5c4804ec9ba4a04a999525c202  # interface impls
58  go install github.com/dkorunic/betteralign/cmd/betteralign@latest  # struct alignment
59  go mod tidy                                              # clean up go.mod & go.sum
60```
61 
62## Makefile commands
63 
64Use `make help` to list all available commands. Common targets include:
65 
66- **audit**: run `go mod verify`, `go vet`, and `govulncheck` for quality checks.
67- **benchmark**: run benchmarks with `go test`.
68- **coverage**: generate a coverage report.
69- **format**: apply formatting using `gofumpt`.
70- **lint**: execute `golangci-lint`.
71- **test**: run the test suite with `gotestsum`.
72- **longtest**: run the test suite 15 times with shuffling enabled.
73- **tidy**: clean and tidy dependencies.
74- **betteralign**: optimize struct field alignment.
75- **generate**: run `go generate` after installing msgp and ifacemaker.
76 
77These targets can be invoked via `make <target>` as needed during development and testing.
78 
79## Pull request guidelines
80 
81- PR titles must start with a category prefix describing the change: `🐛 bug:`, `🔥 feat:`, `📒 docs:`, or `🧹 chore:`.
82- Generated PR titles and bodies must summarize the *entire* set of changes on the branch (for example, based on `git log --oneline <base>..HEAD` or the full diff), **not** just the latest commit. The Summary section should reflect all modifications that will be merged.
83 
84## Programmatic checks
85 
86Before presenting final changes or submitting a pull request, run each of the
87following commands and ensure they succeed. Include the command outputs in your
88final response to confirm they were executed:
89 
90```bash
91make audit
92make generate
93make betteralign
94make format
95make lint
96make test
97```
98 
99All checks must pass before the generated code can be merged.
100 
101After completing the programmatic checks above, confirm that any relevant
102documentation has been updated to reflect the changes made, including PR
103instructions when applicable.
104