git.giacomolli.uk - onechat/blob - .agents/skills/go-code/SKILL.md

   1 ---
   2 name: go-code
   3 description: Go style rules. Use before you write or review Go code.
   4 ---
   5
   6 # Go code
   7
   8 ## Packages and files
   9
  10 - Keep Go code in one root `main` package. Do not add `internal/`,
  11   `cmd/`, or one-file packages until the user asks for them.
  12 - Keep `main.go` limited to the entry point. Name other files for their
  13   function. Do not create `main_test.go`.
  14 - A file carries its own context. Keep each struct and all of its
  15   methods in one file. Give a separate responsibility its own type.
  16 - Put entry points first, then each struct's methods as a group, then
  17   standalone utility functions. Do not put a utility function between
  18   the methods of one type.
  19 - In each group, order functions by first use in the file.
  20
  21 ## Entry point and context
  22
  23 - `main` calls `run()` and handles its returned error. Do not use
  24   `log.Fatal`.
  25 - `run()` creates the SIGINT/SIGTERM signal context and defers its
  26   cancellation. Pass that context through operations and let cleanup
  27   finish before `main` exits.
  28 - Use `ctx` for a context and `cancel` for its cancellation function.
  29   Call `defer cancel()` immediately after you create the context.
  30 - Reuse `ctx` when a child context replaces its parent. Use a different
  31   name only when both contexts stay in use. Return `ctx.Err()` directly.
  32
  33 ## Errors
  34
  35 - Handle every returned error.
  36 - Reuse an existing `err` for later operations in the same scope. Use a
  37   different variable only to keep or join errors.
  38 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an
  39   error directly with a sentinel, because errors can be wrapped.
  40 - When a function has more than one error path, wrap each returned error
  41   with the context of its operation. A function with one error path can
  42   return the error directly.
  43 - When deferred cleanup can fail, use a named `err` result and join the
  44   cleanup error with `errors.Join`.
  45
  46 ## Style
  47
  48 - Keep function signatures on one line. Write function bodies on more
  49   than one line, also for anonymous functions, deferred cleanup, and
  50   test callbacks.
  51 - Do not use short `if` initializers.
  52 - Use a one-letter receiver name for each method.
  53 - Put each field of a keyed struct literal on its own line when you set
  54   more than one field.
  55 - Put an empty line between logical blocks, also after multiline
  56   declarations, assignments, literals, and calls. Keep an operation with
  57   its immediate error or result check. Keep a short declaration with its
  58   immediate use.
  59 - Use GNU-style command flags: two dashes for long flags, such as
  60   `--cwd`, and one dash only for one-letter flags, such as `-h`.
  61 - Prefer the Go standard library. Prefer Go over cgo.
  62 - Do not add compile-time interface assertions. Prove compatibility
  63   through actual assignments and calls.
  64 - Use `// nolint: name` for lint directives.
  65
  66 ## Dependencies
  67
  68 - After a change to `go.mod` or `go.sum`, update `vendorHash` in
  69   `nix/package.nix`. While the module has no dependencies, `vendorHash`
  70   is `null`.
  71
  72 ## Tests
  73
  74 - Add tests for meaningful behavior. Do not add tests that only repeat
  75   implementation details.
  76 - Use `testify/require` for assertions.
  77 - Name a table-driven case slice `testCases` and its range variable
  78   `tc`. A subtest name describes the behavior, not a generic outcome or
  79   input.
  80 - In a test file, put constants immediately after the imports, then the
  81   tests, then supporting types, methods, and helpers.
  82 - Supply valid required dependencies in tests. Do not make a dependency
  83   optional only to make a test simpler.