ofershap When to use
Use this skill when working with Go code. It teaches you the current best practices and prevents common mistakes that AI agents make with outdated patterns.
Critical Rules
1. Always wrap errors with context using fmt.Errorf and %w
Wrong:
func createUser(name string) error {
user, err := db.Insert(name)
if err != nil {
return err
}
return nil
}
Correct:
func createUser(name string) error {
user, err := db.Insert(name)
if err != nil {
return fmt.Errorf("creating user %s: %w", name, err)
}
return nil
}
Why: Error chains need context at each level for debugging; unwrapped errors lose origin context.
2. Use log/slog for structured logging instead of log.Printf
Wrong:
log.Printf("user %s created with id %d", name, id)
Correct:
slog.Info("user created", "name", name, "id", id)
Why: slog is in the standard library since Go 1.21, produces structured (JSON/text) output, supports levels.
3. Pass context.Context as first parameter, never store in structs
Wrong:
type Service struct {
ctx context.Context
}
func (s *Service) Do() error {
return s.db.Query(s.ctx, "...")
}
Correct:
type Service struct {
db *sql.DB
}
func (s *Service) Do(ctx context.Context) error {
return s.db.QueryContext(ctx, "...")
}
Why: Context has a lifecycle tied to the request, not the service; storing it conflates lifecycles.
4. Prevent goroutine leaks — always ensure goroutines can exit
Wrong:
go func() {
for {
processItem(<-ch)
}
}()
Correct:
go func() {
for {
select {
case item, ok := <-ch:
if !ok {
return
}
processItem(item)
case <-ctx.Done():
return
}
}
}()
Why: Leaked goroutines consume memory (min 2KB stack each) and grow unboundedly.
5. Use errors.Is and errors.As for error checking, not == or type assertion
Wrong:
if err == sql.ErrNoRows {
return nil, nil
}
Correct:
if errors.Is(err, sql.ErrNoRows) {
return nil, nil
}
Why: errors.Is traverses the wrapped error chain; == only matches the outermost error.
6. Use range over integers (Go 1.22+) instead of C-style for loops
Wrong:
for i := 0; i < 10; i++ {
process(i)
}
Correct:
for i := range 10 {
process(i)
}
Why: Cleaner, less error-prone, idiomatic since Go 1.22.
7. Use table-driven tests with t.Run subtests
Wrong:
func TestAdd_Positive(t *testing.T) { ... }
func TestAdd_Negative(t *testing.T) { ... }
func TestAdd_Zero(t *testing.T) { ... }
Correct:
func TestAdd(t *testing.T) {
tests := []struct {
name string
a, b int
want int
}{
{"positive", 2, 3, 5},
{"negative", -1, -2, -3},
{"zero", 0, 5, 5},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := Add(tt.a, tt.b)
if got != tt.want {
t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, got, tt.want)
}
})
}
}
Why: DRY, easy to add cases, subtests run independently and can be filtered.
8. Return concrete types from constructors, accept interfaces
Wrong:
func NewService() ServiceInterface {
return &service{}
}
Correct:
func NewService() *Service {
return &Service{}
}
Why: Accept interfaces, return structs — keeps packages decoupled, lets consumers define interfaces they need.
9. Use errgroup for coordinated goroutine lifecycle
Wrong:
var wg sync.WaitGroup
var mu sync.Mutex
var errs []error
for _, task := range tasks {
wg.Add(1)
go func(t Task) {
defer wg.Done()
if err := t.Run(); err != nil {
mu.Lock()
errs = append(errs, err)
mu.Unlock()
}
}(task)
}
wg.Wait()
Correct:
g, ctx := errgroup.WithContext(ctx)
for _, task := range tasks {
task := task
g.Go(func() error {
return task.Run(ctx)
})
}
if err := g.Wait(); err != nil {
return fmt.Errorf("task failed: %w", err)
}
Why: errgroup handles sync, error collection, and context cancellation in one.
10. Avoid init() functions — use explicit initialization
Wrong:
var db *sql.DB
func init() {
db = connectDB()
}
Correct:
func NewApp() (*App, error) {
db, err := connectDB()
if err != nil {
return nil, fmt.Errorf("connect db: %w", err)
}
return &App{db: db}, nil
}
Why: init() creates hidden dependencies, makes testing difficult, order is unpredictable across packages.
11. Handle the loop variable capture fix (Go 1.22+)
Wrong (pre-1.22 pattern, unnecessary in 1.22+):
for _, item := range items {
item := item
go func() {
process(item)
}()
}
Correct (Go 1.22+):
for _, item := range items {
go func() {
process(item)
}()
}
Why: Go 1.22+ fixed loop variable capture; loop variables are per-iteration. Remove unnecessary re-declarations.
12. Use proper struct validation, not manual checks
Wrong:
func CreateUser(req *CreateUserRequest) error {
if req.Name == "" {
return errors.New("name required")
}
if len(req.Name) < 2 {
return errors.New("name too short")
}
if req.Email == "" {
return errors.New("email required")
}
// ...
}
Correct:
type CreateUserRequest struct {
Name string `validate:"required,min=2"`
Email string `validate:"required,email"`
}
func CreateUser(req *CreateUserRequest) error {
if err := validator.Validate(req); err != nil {
return fmt.Errorf("validation: %w", err)
}
// ...
}
Why: Declarative, consistent, handles complex validation rules.
Patterns
Functional options pattern for configurable constructors
type Server struct {
host string
port int
}
type Option func(*Server)
func WithHost(host string) Option {
return func(s *Server) { s.host = host }
}
func WithPort(port int) Option {
return func(s *Server) { s.port = port }
}
func NewServer(opts ...Option) *Server {
s := &Server{host: "localhost", port: 8080}
for _, opt := range opts {
opt(s)
}
return s
}
Repository pattern with interface
type UserRepository interface {
GetByID(ctx context.Context, id int64) (*User, error)
Create(ctx context.Context, u *User) error
}
type userRepo struct {
db *sql.DB
}
func NewUserRepository(db *sql.DB) *userRepo {
return &userRepo{db: db}
}
func (r *userRepo) GetByID(ctx context.Context, id int64) (*User, error) {
// ...
}
Middleware chain pattern
type Middleware func(http.Handler) http.Handler
func chain(middlewares ...Middleware) Middleware {
return func(final http.Handler) http.Handler {
for i := len(middlewares) - 1; i >= 0; i-- {
final = middlewares[i](final)
}
return final
}
}
func LoggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
slog.Info("request", "method", r.Method, "path", r.URL.Path)
next.ServeHTTP(w, r)
})
}
Graceful shutdown with signal handling
func main() {
srv := &http.Server{Addr: ":8080", Handler: mux}
go func() {
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
slog.Error("server failed", "err", err)
}
}()
sig := make(chan os.Signal, 1)
signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
<-sig
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
slog.Error("shutdown failed", "err", err)
}
}
Anti-Patterns
Do not use panic for expected errors — only for programmer bugs (nil dereference, out of bounds). Return errors for recoverable failures.
Do not ignore errors with
_ = someFunc()— handle or explicitly document why ignoring is acceptable.Do not use global variables for dependency injection — pass dependencies via constructors or function parameters.
Do not use naked goroutines without lifecycle management — ensure every goroutine has an exit path (context cancellation, done channel, or bounded loop).
Do not return interfaces from packages — return concrete types; let the consumer define the interface they need.