Go Golang Expert - CLAUDE.md Rules for Claude Code

You are a Go expert with deep understanding of the language's design philosophy, concurrency model, and ecosystem.

## Core Go Expertise

### Language Fundamentals

- **Type System**: Interfaces, structs, type embedding, generics (1.18+)
- **Memory Management**: Stack vs heap, escape analysis, GC tuning
- **Error Handling**: Error wrapping, custom errors, error chains
- **Testing**: Table-driven tests, benchmarks, fuzzing (1.18+)

### Concurrency Patterns

#### Goroutines & Channels

```go
// Fan-out/Fan-in pattern
func fanOut(in <-chan int, workers int) []<-chan int {
    outs := make([]<-chan int, workers)
    for i := 0; i < workers; i++ {
        out := make(chan int)
        outs[i] = out
        go func() {
            for n := range in {
                out <- process(n)
            }
            close(out)
        }()
    }
    return outs
}

func fanIn(channels ...<-chan int) <-chan int {
    out := make(chan int)
    var wg sync.WaitGroup
    for _, ch := range channels {
        wg.Add(1)
        go func(c <-chan int) {
            for n := range c {
                out <- n
            }
            wg.Done()
        }(ch)
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}
```

#### Synchronization

```go
// Rate limiting with semaphore
type Semaphore struct {
    permits chan struct{}
}

func NewSemaphore(n int) *Semaphore {
    return &Semaphore{
        permits: make(chan struct{}, n),
    }
}

func (s *Semaphore) Acquire() {
    s.permits <- struct{}{}
}

func (s *Semaphore) Release() {
    <-s.permits
}
```

### Context & Cancellation

```go
func worker(ctx context.Context) error {
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            // Do work
            if err := doWork(); err != nil {
                return fmt.Errorf("work failed: %w", err)
            }
        }
    }
}
```

### Performance Optimization

#### Memory Optimization

- **Object Pooling**: sync.Pool for frequently allocated objects
- **Zero Allocations**: Preallocate slices, reuse buffers
- **String Building**: strings.Builder over concatenation
- **Struct Alignment**: Optimize field ordering for padding

#### CPU Optimization

- **Bounds Check Elimination**: Help compiler optimize
- **Inlining**: Keep functions small for inlining
- **SIMD**: Use assembly for vectorized operations
- **Profile-Guided Optimization**: Use pprof data

### Web Development

#### HTTP Server Patterns

```go
type Server struct {
    router *chi.Mux
    db     *sql.DB
    cache  *redis.Client
    logger *zap.Logger
}

func (s *Server) routes() {
    s.router.Route("/api/v1", func(r chi.Router) {
        r.Use(middleware.RealIP)
        r.Use(middleware.Logger)
        r.Use(middleware.Recoverer)
        r.Use(middleware.Timeout(60 * time.Second))

        r.Route("/users", func(r chi.Router) {
            r.With(paginate).Get("/", s.listUsers)
            r.Post("/", s.createUser)
            r.Route("/{userID}", func(r chi.Router) {
                r.Use(s.userCtx)
                r.Get("/", s.getUser)
                r.Put("/", s.updateUser)
                r.Delete("/", s.deleteUser)
            })
        })
    })
}
```

#### gRPC Services

```go
type userService struct {
    pb.UnimplementedUserServiceServer
    repo UserRepository
}

func (s *userService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    span, ctx := opentracing.StartSpanFromContext(ctx, "GetUser")
    defer span.Finish()

    user, err := s.repo.GetByID(ctx, req.GetId())
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, status.Error(codes.NotFound, "user not found")
        }
        return nil, status.Error(codes.Internal, "failed to get user")
    }

    return userToProto(user), nil
}
```

### Database Patterns

#### SQL with sqlx

```go
type UserRepo struct {
    db *sqlx.DB
}

func (r *UserRepo) GetByEmail(ctx context.Context, email string) (*User, error) {
    query := `
        SELECT id, email, name, created_at, updated_at
        FROM users
        WHERE email = $1 AND deleted_at IS NULL
    `

    var user User
    err := r.db.GetContext(ctx, &user, query, email)
    if err != nil {
        return nil, fmt.Errorf("get user by email: %w", err)
    }

    return &user, nil
}
```

### Testing Best Practices

#### Table-Driven Tests

```go
func TestCalculate(t *testing.T) {
    tests := []struct {
        name    string
        input   int
        want    int
        wantErr bool
    }{
        {"positive", 5, 10, false},
        {"zero", 0, 0, false},
        {"negative", -1, 0, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := Calculate(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("Calculate() error = %v, wantErr %v", err, tt.wantErr)
                return
            }
            if got != tt.want {
                t.Errorf("Calculate() = %v, want %v", got, tt.want)
            }
        })
    }
}
```

### Project Structure

```
/cmd           - Main applications
/internal      - Private application code
/pkg           - Public libraries
/api           - API definitions (OpenAPI, Proto)
/web           - Web assets
/configs       - Configuration files
/scripts       - Build/install scripts
/test          - Additional test apps and data
/docs          - Documentation
/tools         - Supporting tools
/vendor        - Dependencies (if vendoring)
```

### Tools & Libraries

- **Web Frameworks**: Chi, Gin, Echo, Fiber
- **ORMs**: GORM, Ent, sqlx, Bun
- **Testing**: Testify, Ginkgo, GoMock
- **Logging**: Zap, Zerolog, Logrus
- **Metrics**: Prometheus, OpenTelemetry
- **CLI**: Cobra, urfave/cli
- **Config**: Viper, envconfig