---
agent: engineer
allowed-tools:
- Read
- Bash
- Grep
- Glob
context: fork
description: Idiomatic Go 1.25+ development. Use when writing Go code, designing APIs,
  discussing Go patterns, or reviewing Go implementations. Emphasizes stdlib, concrete
  types, simple error handling, and minimal dependencies. NOT for Python, TypeScript,
  or shell scripting tasks.
name: writing-go
user-invocable: false
---

# Go Development (1.25+)

## Critical Output Rules

- State stdlib-first choices explicitly: use `net/http`, `encoding/json`, `context`, and `testing` where practical before adding dependencies.
- Avoid unnecessary dependencies. Add a library only when concrete requirements beat stdlib simplicity.
- Prefer concrete types and small consumer-side interfaces only at real seams; do not abstract everything by default.
- Error handling guidance must say normal failures return `error`, not `panic`; wrap with context using `%w`; avoid custom error hierarchies unless callers need distinct behavior.
- Always mention behavior tests for success and error paths, even when only giving design or error-handling advice. Prefer table-driven tests with `t.Run`; stdlib `testing` is enough unless the project already uses another test library.
- For handlers/services, pass `context.Context` through API boundaries and map service errors to HTTP status at the edge.
- Do not run destructive shell commands. For broad or risky changes, state the risk and ask before acting.

## Core Philosophy

Stdlib-first stance, concrete-types-over-`any`, consumer-side interfaces, flat control flow, explicit error handling, the no-destructive-commands safety rule, and the post-generation verification loop are in [references/principles.md](references/principles.md) — read it before generating code.

## Quick Patterns

### Private Interface at Consumer

```go
// service/user.go - private interface where it's USED
type userStore interface {
    Get(ctx context.Context, id string) (*User, error)
}

type Service struct {
    store userStore  // accepts interface
}

// repo/postgres.go - returns concrete type
func NewPostgresStore(db *sql.DB) *PostgresStore {
    return &PostgresStore{db: db}
}
```

### Flat Control Flow (No Nesting)

```go
// GOOD: guard clauses, early returns
func process(user *User) error {
    if user == nil {
        return ErrNilUser
    }
    if user.Email == "" {
        return ErrMissingEmail
    }
    if !isValidEmail(user.Email) {
        return ErrInvalidEmail
    }
    return doWork(user)
}

// BAD: nested conditions
func process(user *User) error {
    if user != nil {
        if user.Email != "" {
            if isValidEmail(user.Email) {
                return doWork(user)
            }
        }
    }
    return nil
}
```

### Error Handling

```go
if err := doThing(); err != nil {
    return fmt.Errorf("do thing: %w", err)  // always wrap
}

// Sentinel errors
if errors.Is(err, ErrNotFound) {
    return http.StatusNotFound
}
```

### Concrete Types (Avoid `any`)

```go
// GOOD: concrete types
func ProcessUsers(users []User) error { ... }
func GetUserByID(id string) (*User, error) { ... }

// BAD: unnecessary any
func ProcessItems(items []any) error { ... }
func GetByID(id any) (any, error) { ... }
```

### Table-Driven Tests

```go
tests := []struct {
    name    string
    input   string
    want    string
    wantErr bool
}{
    {"valid", "hello", "HELLO", false},
    {"empty", "", "", true},
}
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        got, err := Process(tt.input)
        if tt.wantErr {
            require.Error(t, err)
            return
        }
        require.NoError(t, err)
        assert.Equal(t, tt.want, got)
    })
}
```

## Go 1.25 Features

- **testing/synctest**: Deterministic concurrent testing
- **encoding/json/v2**: 3-10x faster (GOEXPERIMENT=jsonv2)
- **runtime/trace.FlightRecorder**: Production trace capture
- **Container-aware GOMAXPROCS**: Auto-detects cgroup limits

## References

- [principles.md](references/principles.md) - Core philosophy, safety rule, and verification loop (read before generating code)
- [PATTERNS.md](references/PATTERNS.md) - Detailed code patterns
- [TESTING.md](references/TESTING.md) - Testing with testify/mockery
- [CLI.md](references/CLI.md) - CLI application patterns

## Tooling

```bash
go build ./...           # Build
go test -race ./...      # Test with race detector
golangci-lint run        # Lint
mockery --all            # Generate mocks
```

## Failure Cases

- **No Go files in repo / ambiguous project root**: run `find . -name 'go.mod'` to locate modules before generating code; do not assume a single root.
- **Compilation or test failure after generation**: quote the failing line, state the cause, show the exact fix. Do not retry blindly—diagnose first.
