You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+6-1Lines changed: 6 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,8 @@
2
2
3
3
Read `CLAUDE.md` first. This file defines how you execute, not what the project is.
4
4
5
+
Applies to every AI agent working in this repo. Primary targets are Claude Code (reads `CLAUDE.md`) and OpenAI Codex (reads this file). `CLAUDE.md` (project knowledge) + this file (execution contract) + `.golangci.yaml` (enforced style) form the complete brief. A `.cursor/rules/main.mdc` pointer exists for Cursor users but is not actively maintained.
6
+
5
7
## Mandatory Read-First, Plan-First Workflow
6
8
7
9
Do NOT write code until you have completed all steps below. No exceptions.
@@ -44,7 +46,10 @@ Skipping these steps leads to pattern violations, broken dual-mode, and pricing
44
46
## Done Checklist
45
47
46
48
-[ ]`make build` passes
47
-
-[ ]`make test` passes
49
+
-[ ]`make lint` passes with zero issues (do not rely on pre-commit to surface these)
50
+
-[ ]`make test` passes (runs lint + unit tests)
48
51
-[ ]`--help` renders correctly for changed commands
49
52
-[ ] Interactive and non-interactive modes both work
50
53
-[ ] No leftover debug code, TODOs, or commented-out blocks
54
+
55
+
If `make lint` reports issues, fix them *before* announcing completion. See `CLAUDE.md` § "Go House Style" for the patterns that prevent the common hits (http.NoBody, American spelling, reused constants, rangeValCopy, nilerr annotations, etc.).
|`cmd/availability/`| — | Instance availability by location |
@@ -67,6 +68,22 @@ Each command directory has its own `CLAUDE.md` (domain knowledge) and `README.md
67
68
68
69
## Conventions
69
70
71
+
### Go House Style — avoid avoidable lint hits
72
+
73
+
The repo lints with `golangci-lint` via `make lint` (included in `make test`). These are the patterns the linters enforce — write them correctly the first time instead of fixing them in a second pass:
74
+
75
+
-**HTTP bodies** — use `http.NoBody` for GET/DELETE/etc., never `nil`. Close with `defer func() { _ = resp.Body.Close() }()`, not bare `defer resp.Body.Close()` (errcheck).
76
+
-**American English** — `behavior`, `canceled`, `artifact`, `checkered`, `gray`. `misspell` runs with `locale: US` and rejects British spellings in code and comments.
77
+
-**Reuse constants** — before writing a string literal that might repeat, grep for an existing one. Current package-level constants worth knowing: `defaultTag` (`"latest"`) in `cmd/registry/refname.go`, `progressJSON` (`"json"`) in `cmd/registry/push.go`, `untaggedLabel` (`"<untagged>"`) in `cmd/registry/format.go`. `goconst` fails on ≥3 occurrences.
78
+
-**Strings over fmt.Sprintf** — `"prefix " + s` beats `fmt.Sprintf("prefix %s", s)` when there's only one substitution (perfsprint).
79
+
-**Range indexing for structs ≥96 B** — `for i := range xs { x := &xs[i] }` avoids the per-iteration copy `for _, x := range xs` incurs (gocritic rangeValCopy). `ArtifactInfo`, `VMDescribeResult`, etc. all cross the threshold.
80
+
-**Intentional `return nil` after error** — prompter cancellation returns an error that we deliberately swallow. Annotate with `return nil //nolint:nilerr // intentional: prompter cancel is a clean exit` so `nilerr` doesn't flag it and the reason survives.
81
+
-**No blank line after `{`** — `whitespace` linter flags it. Go straight into the first statement.
82
+
-**Type inference over explicit declaration** — `rt := http.DefaultTransport` over `var rt http.RoundTripper = http.DefaultTransport` (staticcheck ST1023).
83
+
-**Complexity budgets** — `gocyclo` trips at 20, `nestif` at 5. Extract helpers before you hit them; refactoring after the fact is more churn.
84
+
85
+
`.golangci.yaml` is the authoritative list — all of the above come from linters enabled there.
`make test` runs `golangci-lint` — **never** report work as complete with lint failures outstanding. Fix them before the "done" message; don't defer to the pre-commit hook. See the "Go House Style" section above for the patterns that prevent the common hits.
146
+
128
147
If you modified a command, also verify:
129
148
-`./bin/verda <command> --help` renders correctly
130
149
- Interactive mode works (prompts appear)
131
150
- Non-interactive mode works (flags only, no prompts)
132
151
-`--agent -o json` mode works (structured output, no TUI)
133
152
-`--debug` shows request/response payloads
153
+
154
+
## Other Agents
155
+
156
+
This repo targets Claude Code and OpenAI Codex. Claude auto-loads this file; Codex auto-loads `AGENTS.md` (execution contract). A `.cursor/rules/main.mdc` pointer exists for Cursor users but is not a primary target — if Cursor drops out of the stack, delete it rather than letting it drift.
0 commit comments