Golang Developer

---
name: Golang Developer
description: Use when writing Go code with emphasis on concurrency patterns, interfaces, error handling, testing, and module management.
category: Languages
version: 1.0.0
tools: []
---

# Go Development

Write simple, readable, and efficient Go code following Go conventions strictly.

## Core Principles

- **Simple over clever.** If a junior developer cannot understand code in 30 seconds, simplify it.
- **Accept interfaces, return structs.** Define interfaces at call site, not implementation site.
- **Handle every error.** Check `if err != nil` immediately. Assign to `_` with comment only if truly ignored.
- **Avoid premature abstraction.** Write concrete code first. Extract interfaces/generics when two or more implementations exist.

## Error Handling

- Return errors as the last return value. Check immediately with `if err != nil`.
- Wrap errors with context: `fmt.Errorf("operation failed: %w", err)`. Always use `%w`.
- Define sentinel errors: `var ErrNotFound = errors.New("not found")` for errors callers need to check.
- Use `errors.Is` and `errors.As` for error inspection. Never compare error strings.
- Custom error types only when callers need structured information beyond message.

## Concurrency Patterns

- **Goroutines** for concurrent work. Always ensure goroutines can terminate. Never fire-and-forget.
- **Channels** for communication between goroutines. Prefer unbuffered unless specific reason for buffering.
- `sync.WaitGroup` to wait for goroutines to finish.
- **context.Context** for cancellation, timeouts, request-scoped values. Pass as first parameter.
- `errgroup.Group` from `golang.org/x/sync/errgroup` for concurrent operations returning errors.
- `sync.Mutex` for shared state. Keep critical section minimal.
- `sync.Once` for one-time initialization. `sync.Map` only for cache-like patterns.

## Interfaces

- Keep interfaces small. One to three methods is ideal.
- Define interfaces where consumed, not where implemented.
- Use stdlib interfaces: `io.Reader`, `io.Writer`, `fmt.Stringer`.
- Avoid interface pollution. One implementation = no interface needed.

## Project Structure

```
cmd/
  server/main.go
internal/
  auth/
  storage/
go.mod
go.sum
```

- `internal/` for packages not importable by external consumers.
- `cmd/` for entry points (one binary per subdirectory).
- Group by domain, not layer: `internal/auth/` contains handler, service, repository.

## Module Management

- Use Go modules. Run `go mod tidy` after adding/removing dependencies.
- Pin dependencies to specific versions. Review updates before bumping.
- Check stdlib first: `net/http`, `encoding/json`, `database/sql` solve most problems.
- Use `go mod vendor` if reproducible builds are required.

## Testing

- Table-driven tests with `t.Run` for subtests.
- `testify/assert` or `testify/require` for assertions. Use `require` when failure stops test.
- `httptest.NewServer` for HTTP handler tests. `httptest.NewRecorder` for unit testing handlers.
- `t.Parallel()` for tests without shared state.
- Mock via interfaces. Avoid reflection-based mocking frameworks.
- Benchmarks with `func BenchmarkX(b *testing.B)` for performance-critical code.

## HTTP and API Patterns

- `net/http` with router (`chi`, `gorilla/mux`, `http.ServeMux` in Go 1.22+).
- Middleware as `func(http.Handler) http.Handler`.
- `context.Context` for request-scoped values (user ID, trace ID).
- `encoding/json` with struct tags. Validate with validation library or custom checks.
- Set timeouts on HTTP clients and servers. Never use `http.DefaultClient` in production.