go-idiomatic

Files (21)

• SKILL.md
• evals.json · evals/
• go.mod · evals/files/optional-field/
• user.go · evals/files/optional-field/internal/user/
• go.mod · evals/files/refactor-store/
• helpers.go · evals/files/refactor-store/helpers/
• store.go · evals/files/refactor-store/store/
• main.go · evals/files/server-settings/cmd/app/
• go.mod · evals/files/server-settings/
• server.go · evals/files/server-settings/internal/server/
• concurrency.md · references/
• database.md · references/
• errors.md · references/
• exec.md · references/
• http-client.md · references/
• logging.md · references/
• middleware.md · references/
• optional.md · references/
• patterns.md · references/
• secrets.md · references/
• value-vs-pointer.md · references/

SKILL.md (first lines)

# Go Idiomatic

This repo's rules for Go, where they differ from or sharpen general Go practice. The rules below
apply to every change; the references hold the detail and worked examples.

## Where to Look

Route to the right reference before reading further:

| If you're working on…                                                          | Load this                        |
| ------------------------------------------------------------------------------ | -------------------------------- |
| Goroutines, channels, sync primitives, errgroup, leaks, races                  | `references/concurrency.md`      |
| Adding a sentinel or error type, translating errors between packages or to HTTP responses, logging where an error came from, cleanup in `defer`, `panic` | `references/errors.md` |
| HTTP middleware: request Content-Type, CSRF, session cookie attributes         | `references/middleware.md`       |
| Storing session or reset tokens, password reset or change, encrypting a column | `references/secrets.md`          |
| Giving `main` or a component a logger, choosing a level, CLI output vs logs    | `references/logging.md`          |
| Interface design, zero values, identifier types, typed value sets, anti-patterns | `references/patterns.md`         |
| Writing or reviewing tests, benchmarks, fuzzing, test databases                | the `go-testing` skill           |
| Optional fields or return values — when to use `Option[T]`                     | `references/optional.md`         |
| Pointer vs value receivers, mutation vs optionality                             | `references/value-vs-pointer.md` |
| Scaffolding a Go HTTP client for a third-party API, writing a `NewXxxClient`, or attaching auth to outbound HTTP calls | `references/http-client.md` |
| Shelling out with `os/exec` to `git`, `gh` or another CLI, parsing its `--json` output, faking it in tests | `references/exec.md` |
| Storing data in SQL: store package boundary, transactions, NULLs, constraint errors, pool setup | `references/database.md` |
| Rendering `html/template` for htmx: page vs fragment vs redirect, `HX-*` headers, `.tmpl` files | the `htmx-go-templates` skill |

---

## Errors and Logging

Nearly every change returns an error or reports one, so these rules apply to all Go work, not only
to a task described as error handling:

1. Wrap with `fmt.Errorf("<verb> <noun>: %w", err)`. Error strings are lowercase, with no
   punctuation and no "failed to".
2. Handle an error once: return it with context, or log it at the top of the chain. Never both.
3. Export a sentinel only when a caller in another package branches on it. Define it where the
   condition is detected, and translate a dependency's errors into your own at the package seam.
4. Never discard an error with `_ =`. Join a cleanup error into the returned error, or log it at
   `Warn` when there is nothing to return to.
5. `panic` only for programmer errors: `Must` helpers on constant input, impossible cases.
6. Only components where an error stops travelling (handlers, workers, long-lived services) take
   an injected `*slog.Logger`, as a constructor field. Code below them returns errors and takes no
   logger. `main` builds the one logger; nothing calls `log.*`, `slog.Info` or `slog.Default()`.
7. Log messages are constant; variable data goes in snake_case key-value attributes, with `err`
   for the error. Never log secrets or personal data.
8. Output the user asked for goes to an injected `io.Writer`, not to the logger.

A routine `return fmt.Errorf(...)` or log line needs only these rules. Load `references/errors.md`
when adding a sentinel or error type, turning an error into an HTTP response, wrapping a driver or
outbound-call error, or handling a cleanup error, and `references/logging.md` when
wiring a logger, choosing a level or separating CLI output.

---

## Testing

Writing, editing or reviewing a `_test.go` file: load the `go-testing` skill, which owns how Go
tests are written, including test databases. What to test (the kinds of test, what each is
worth, the reusable patterns) is the repo's `testing-policy` when it ships one.

---

## Code Organisation

1. Applications keep `main` in `cmd/<app>/main.go`, which only wires dependencies, and everything
   else under `internal/`. `pkg/` is for library modules imported from outside the repo; in an
   application it signals a public API that doesn't exist.
2. Extract shared logic on the **third** repetition across meaningfully different packages, not
   the second. A helper coupled to one domain lives in `internal/` next to its primary caller.
3. Name a package by what it does (`stringx`, `idgen`, `timeutil`). `utils` is allowed only when
   it is used across many packages and imports nothing from `internal/`. `helpers` and `common`
   are never allowed: a real name is waiting to be found.
4. No package-level state such as a global `*sql.DB` set in `init()`. Pass dependencies through
   constructors.
5. `main` parses the environment once into a typed config struct, validates it, and exits on a bad
   value at startup rather than on the first request that needs it. Constructors receive only the
   fields they use, not the whole struct. Nothing below `cmd/` calls `os.Getenv`.

---

## Function Design

1. Past 3–4 arguments, group them into a struct, or use functional options (`opts ...Option`)
   for a constructor that will grow; a new option is backward-compatible, a new positional
   argument is not.
2. Declare complex arguments as named locals before the call instead of nesting constructor
   calls inline:

   ```go
   sentAt := time.Now().Add(-24 * time.Hour)
   priority := Priority(3)
   client.Send(NewMessage(sender, recipient, sentAt, priority))
   ```

3. Guard and return early; the happy path stays at the bottom, unindented, with no `else` after a
   `return`. Use `switch` over `if`/`else if` chains.
4. Use pointers for mutation and measurably large structs, values for small immutable types.
   Never use `*T` to mean "might not be set"; that is `Option[T]`.

---

## Naming and Comments

Name functions by what they return or do (`ParseConfig`, `IsExpired`) and booleans as predicates
(`canRetry`). Abbreviate only by Go convention (`ctx`, `err`, `id`, `r`, `w`).

`~/.claude/rules/comments.md` decides what earns a comment. It is the authority and this
skill does not restate or soften it. Read it before editing a file and apply it as written,
including its line cap and its exported-identifiers-only rule for doc comments. `internal/`
is not public API. When reviewing Go code for comment quality, use the `clean-comments` skill.
Do not instruct it to match the file's existing comment density.

---

## Tooling

Run `gofmt`, `goimports`, `go vet ./...` and `golangci-lint run` before finishing. Leave
mechanical rules to the linter rather than restating them here. Never add `//nolint` to existing
violations: fix them, or leave the rule off until they are fixed.

From O-Marsters-1997/my-claude-code, MIT.

More from O-Marsters-1997/my-claude-code