Go style rules
Standing rules for Go an assistant writes, covering wrapped errors, context propagation, small consumer-side interfaces, table-driven tests and no goroutines without an owner.
When you write or change Go code in this project:
Tooling
- Code must be
gofmt-formatted with imports grouped bygoimports, and passgo vet. Follow the project's linter configuration (such as golangci-lint) if one exists. - Use the Go version in
go.mod. Keepgo.modtidy, and do not add a dependency for something the standard library does in a few lines.
Errors
- Return errors as the last result and handle every one. Never discard an error with
_unless a comment says why it is safe. - Add context once per layer with
fmt.Errorf("load config %q: %w", path, err). Use%wso callers can inspect the cause witherrors.Isanderrors.As; never compare error strings. - Either handle an error or return it. Do not log it and return it too.
- Do not panic for expected failures. Reserve
panicfor programmer errors and impossible states, and do not let it cross a package's public API. - Error strings start lowercase and have no trailing punctuation.
Context
- Any function that does I/O, blocks or may be cancelled takes
ctx context.Contextas its first parameter and passes it on. - Never store a context in a struct, never pass
nil, and createcontext.Background()only inmain, initialisation and tests. - Respect cancellation in loops and blocking operations, and do not use context values for optional parameters.
Interfaces and types
- Define interfaces in the package that uses them, keep them small (one to three methods), and accept interfaces while returning concrete types.
- Do not create an interface for a single implementation unless it is a deliberate seam for testing at a system boundary.
- Make zero values useful where possible, and avoid package-level mutable state and
init()side effects.
Concurrency
- Write sequential code first. Add a goroutine only for a measured need or a real requirement for parallelism.
- Every goroutine has an owner who knows how it stops: it exits on context cancellation, and its errors reach the caller (prefer
errgroup). - The sender closes a channel. Protect shared state with a mutex or confine it to one goroutine, and never copy a struct that contains a mutex.
- Run tests with
-racewhen concurrency is involved.
Tests
- Write table-driven tests with named
t.Runsubtests. Uset.Helper()in helpers andt.Parallel()where tests are independent. - Report failures as
got X, want Y, and usecmp.Diffor similar for structs. - No
time.Sleepfor synchronisation. Wait on channels or conditions with a timeout. Put fixtures undertestdata/.
Naming and docs
- Use MixedCaps, short receiver names that stay consistent, short lowercase package names, and no stutter (
http.Server, nothttp.HTTPServer). - Every exported identifier has a doc comment that starts with its name.
- Check the error from
Closeon anything you wrote to.
details
- kind
- Rule: standing instructions for everything the assistant does
- domain
- Software engineering
- category
- Conventions
- depth
- Specific
- made for
- Software engineer, Backend engineer, DevOps / platform engineer, Site reliability engineer
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install go-style-rules --target claude-codenpx skills add hermes-hq/hodios-dist --skill go-style-rules -a claude-codeRules are always-on instructions, so they are not in the plugins: add the skill, or paste the text into CLAUDE.md.
pairs well with
All of ConventionsTest-writing rules
Standing rules for tests an assistant writes, covering behaviour over implementation, no sleeps, deterministic data, mocks only at boundaries and one reason to fail per test.
test-writing-rulesWrite a team coding standards document
Drafts a team's coding standards from its actual code, lint config and review comments, splitting what tools enforce from what needs judgement, with a reason and example for every rule.
write-team-coding-standardsTailwind CSS rules
Standing rules for Tailwind CSS covering design tokens in the theme, class ordering, extracting components instead of repeated class strings, responsive and dark variants and visible focus states.
tailwind-rulesHTTP API design rules
Rules for HTTP APIs covering resource naming, status codes, problem+json errors, cursor pagination, idempotency keys and versioning. Load when designing or changing HTTP endpoints.
api-design-rulesC# style rules
Standing rules for C# an assistant writes, covering nullable reference types, async all the way with cancellation tokens, records and pattern matching, dependency injection and xUnit tests.
csharp-style-rulesJava style rules
Standing rules for Java an assistant writes, covering modern language features, immutability, Optional and null handling, exceptions, restrained streams, records and JUnit 5 tests.
java-style-rules