writing-go

Go Development

Use only for Go modules. Follow the module's target Go version.

Read First

Read principles.md before writing, changing, or reviewing Go code. Read conditional references only when the change touches that area.

Conditional References

• patterns.md — package layout, interfaces, errors, HTTP/service boundaries, concurrency, comments.
• testing.md — adding or reshaping Go tests; keep the local test loop fast.
• linting.md — changing lint config, lint commands, or slow lint workflows.
• cli.md — writing or changing Go CLIs.

Comments

• Use doc comments for exported declarations. Start with the identifier and end with a period.
• Comment non-trivial unexported declarations only when their contract is not obvious.
• Add implementation comments only for non-obvious constraints, invariants, side effects, tradeoffs, or tuning decisions.
• Keep comments short. Move longer rationale to docs, issue links, or design notes.
• Do not comment obvious code or restate names and types.
• Keep tests readable without comments; add one only for unobvious fixtures, timing, concurrency, or regression context.

Version-Gated APIs

• Confirm go.mod, toolchain, CI, and nearby code before using version-specific APIs.
• Go 1.25+: use sync.WaitGroup.Go when no error propagation is needed.
• Use existing errgroup for goroutine errors or shared cancellation; add it only when the dependency is justified.
• Go 1.25+: use testing/synctest for deterministic concurrent tests when available.
• Go 1.25+: prefer stdlib crypto/hpke and testing/cryptotest over third-party code when they fit.
• Treat encoding/json/v2 as experimental unless the project opts into GOEXPERIMENT=jsonv2.
• Go 1.26+: use new(expr) only when clearer than a local variable, composite literal, or address expression.
• Go 1.26+: keep recursive type constraints in generic libraries; keep business logic concrete.

Verification

Run focused package tests and lint while editing, then the project-configured build, tests, lint, vet, and formatting checks before final output. Add race or concurrency-specific checks when the change touches goroutines, shared state, timers, or channels.

If a check is unavailable, state that and run the closest configured gate. If a check fails, quote the failure, diagnose the cause, fix one issue, and rerun the relevant check.

Failure Cases

• No clear Go root: locate go.mod before choosing files, commands, or import paths.
• Unknown Go target: inspect go.mod, toolchain, CI, and lockfiles before using version-specific APIs.
• New dependency requested: confirm stdlib or existing dependencies cannot meet the requirement.
• Broad or risky edit: state the risk and ask before acting. Do not run destructive commands.

Final Response

Include:

• changed files
• checks run and results
• checks skipped with reasons
• remaining risks or follow-ups