agents: Skill for Claude Code

Go Developer

Expert in idiomatic Go for production backend services.

Reference Rules

Load these rules for the relevant context:

• .agents/layers/language/go/go-patterns.md — idiomatic Go, error handling, concurrency, testing
• .agents/layers/concern/backend/api-design.md — REST API design principles
• .agents/layers/universal/security-baseline.md — security requirements
• .agents/layers/universal/error-handling.md — error handling principles

Core Go Architecture

/cmd
  /api
    main.go              ← entry point: setup, wire dependencies, start server

/internal                ← private application code (cannot be imported externally)
  /user                  ← one package per domain
    handler.go           ← HTTP handlers (parse request → call service → write response)
    service.go           ← business logic
    repository.go        ← database access
    model.go             ← domain types, DTOs, input/output structs
    service_test.go      ← tests next to source
    handler_test.go
  /middleware
    auth.go
    logging.go
    rate_limit.go
  /config
    config.go            ← load and validate env vars (envconfig or viper)

/pkg                     ← reusable code safe for external import
  /apperr                ← shared error types
  /httputil              ← shared HTTP helpers
  /dbutil                ← shared DB helpers

/migrations              ← SQL migration files (golang-migrate or goose)

Dependency Injection — Constructor Injection

// ✅ Explicit dependency injection — testable, no globals
type UserService struct {
    repo        UserRepository
    emailSender EmailSender
    logger      *slog.Logger
}

func NewUserService(repo UserRepository, email EmailSender, logger *slog.Logger) *UserService {
    return &UserService{repo: repo, emailSender: email, logger: logger}
}

Never use init() or global variables for dependencies — they make testing impossible.

Repository Pattern

// Define interface in the domain package
type UserRepository interface {
    GetByID(ctx context.Context, id string) (*User, error)
    GetByEmail(ctx context.Context, email string) (*User, error)
    Create(ctx context.Context, input CreateUserInput) (*User, error)
    Update(ctx context.Context, id string, input UpdateUserInput) (*User, error)
    SoftDelete(ctx context.Context, id string) error
    List(ctx context.Context, filter UserFilter) ([]User, int, error)
}

// Implement with concrete DB driver
type postgresUserRepo struct {
    db *pgxpool.Pool
}

func (r *postgresUserRepo) GetByID(ctx context.Context, id string) (*User, error) {
    var user User
    err := r.db.QueryRow(ctx,
        `SELECT id, email, name, role, created_at
         FROM users WHERE id = $1 AND deleted_at IS NULL`,
        id,
    ).Scan(&user.ID, &user.Email, &user.Name, &user.Role, &user.CreatedAt)
    
    if errors.Is(err, pgx.ErrNoRows) {
        return nil, ErrNotFound
    }
    if err != nil {
        return nil, fmt.Errorf("UserRepo.GetByID: %w", err)
    }
    return &user, nil
}