oh-my-customcode 0.1.1 → 0.1.3

package/templates/agents/sw-engineer/backend/go-backend-expert/refs/go-backend/project-layout.md

@@ -0,0 +1,243 @@
+# Standard Go Project Layout
+
+> Source: https://github.com/golang-standards/project-layout
+
+## Directory Structure
+
+```
+project/
+├── cmd/                    # Main applications
+│   ├── server/
+│   │   └── main.go
+│   └── worker/
+│       └── main.go
+├── internal/               # Private code
+│   ├── handler/
+│   ├── service/
+│   ├── repository/
+│   ├── model/
+│   └── config/
+├── pkg/                    # Public library code
+│   └── validator/
+├── api/                    # API definitions
+│   ├── openapi.yaml
+│   └── proto/
+├── configs/                # Configuration files
+│   └── config.yaml
+├── scripts/                # Build scripts
+│   └── build.sh
+├── test/                   # Additional test data
+│   └── testdata/
+├── docs/                   # Documentation
+├── Dockerfile
+├── Makefile
+├── go.mod
+└── go.sum
+```
+
+## Directory Descriptions
+
+### `/cmd`
+
+Main applications for this project. Each application has its own subdirectory.
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "log"
+    "myapp/internal/config"
+    "myapp/internal/handler"
+    "myapp/internal/service"
+)
+
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    svc := service.New(cfg)
+    h := handler.New(svc)
+
+    log.Fatal(h.ListenAndServe(cfg.Addr))
+}
+```
+
+### `/internal`
+
+Private application and library code. Not importable by other projects.
+
+```
+internal/
+├── handler/        # HTTP/gRPC handlers
+│   └── user.go
+├── service/        # Business logic
+│   └── user.go
+├── repository/     # Data access
+│   └── user.go
+├── model/          # Domain models
+│   └── user.go
+└── config/         # Configuration
+    └── config.go
+```
+
+### `/pkg`
+
+Library code safe for external use.
+
+```go
+// pkg/validator/validator.go
+package validator
+
+func ValidateEmail(email string) bool {
+    // validation logic
+}
+```
+
+### `/api`
+
+API definitions (OpenAPI/Swagger, Protocol Buffers).
+
+```yaml
+# api/openapi.yaml
+openapi: "3.0.0"
+info:
+  title: "My API"
+  version: "1.0.0"
+paths:
+  /users:
+    get:
+      summary: "List users"
+```
+
+## Common Patterns
+
+### Application Structure
+
+```go
+// internal/app/app.go
+type App struct {
+    config  *config.Config
+    db      *sql.DB
+    cache   *redis.Client
+    handler *handler.Handler
+}
+
+func New(cfg *config.Config) (*App, error) {
+    db, err := sql.Open("postgres", cfg.DatabaseURL)
+    if err != nil {
+        return nil, fmt.Errorf("open db: %w", err)
+    }
+
+    cache := redis.NewClient(&redis.Options{
+        Addr: cfg.RedisURL,
+    })
+
+    repo := repository.New(db)
+    svc := service.New(repo, cache)
+    h := handler.New(svc)
+
+    return &App{
+        config:  cfg,
+        db:      db,
+        cache:   cache,
+        handler: h,
+    }, nil
+}
+
+func (a *App) Run() error {
+    return http.ListenAndServe(a.config.Addr, a.handler.Router())
+}
+
+func (a *App) Shutdown(ctx context.Context) error {
+    if err := a.db.Close(); err != nil {
+        return err
+    }
+    return a.cache.Close()
+}
+```
+
+### Main Entry Point
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "context"
+    "log/slog"
+    "os"
+    "os/signal"
+    "syscall"
+
+    "myapp/internal/app"
+    "myapp/internal/config"
+)
+
+func main() {
+    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+    slog.SetDefault(logger)
+
+    cfg, err := config.Load()
+    if err != nil {
+        slog.Error("load config", "error", err)
+        os.Exit(1)
+    }
+
+    application, err := app.New(cfg)
+    if err != nil {
+        slog.Error("create app", "error", err)
+        os.Exit(1)
+    }
+
+    // Graceful shutdown
+    ctx, stop := signal.NotifyContext(
+        context.Background(),
+        syscall.SIGINT, syscall.SIGTERM,
+    )
+    defer stop()
+
+    go func() {
+        slog.Info("starting server", "addr", cfg.Addr)
+        if err := application.Run(); err != nil {
+            slog.Error("server error", "error", err)
+        }
+    }()
+
+    <-ctx.Done()
+    slog.Info("shutting down")
+
+    shutdownCtx, cancel := context.WithTimeout(
+        context.Background(),
+        30*time.Second,
+    )
+    defer cancel()
+
+    if err := application.Shutdown(shutdownCtx); err != nil {
+        slog.Error("shutdown error", "error", err)
+    }
+}
+```
+
+### Makefile
+
+```makefile
+.PHONY: build run test lint
+
+build:
+	go build -o bin/server ./cmd/server
+
+run:
+	go run ./cmd/server
+
+test:
+	go test -v -race ./...
+
+lint:
+	golangci-lint run
+
+docker:
+	docker build -t myapp .
+```

package/templates/agents/sw-engineer/backend/go-backend-expert/refs/go-backend/uber-style.md

@@ -0,0 +1,212 @@
+# Uber Go Style Guide
+
+> Source: https://github.com/uber-go/guide/blob/master/style.md
+
+## Guidelines
+
+### Verify Interface Compliance
+
+```go
+// Compile-time check
+var _ http.Handler = (*Handler)(nil)
+var _ io.Reader = (*MyReader)(nil)
+```
+
+### Receiver Type
+
+```go
+// Value receiver: doesn't modify state
+func (s Stack) Length() int {
+    return len(s.items)
+}
+
+// Pointer receiver: modifies state or is large
+func (s *Stack) Push(item int) {
+    s.items = append(s.items, item)
+}
+```
+
+### Zero-value Mutexes
+
+```go
+// Good: zero-value is valid
+var mu sync.Mutex
+
+// Good: embedded in struct
+type Store struct {
+    mu    sync.Mutex
+    items map[string]Item
+}
+```
+
+### Copy Slices and Maps
+
+```go
+// Returning: copy to prevent external modification
+func (s *Store) GetItems() []Item {
+    s.mu.RLock()
+    defer s.mu.RUnlock()
+    items := make([]Item, len(s.items))
+    copy(items, s.items)
+    return items
+}
+
+// Receiving: copy to prevent caller modification
+func (s *Store) SetItems(items []Item) {
+    s.mu.Lock()
+    defer s.mu.Unlock()
+    s.items = make([]Item, len(items))
+    copy(s.items, items)
+}
+```
+
+### Defer for Cleanup
+
+```go
+func readFile(path string) ([]byte, error) {
+    f, err := os.Open(path)
+    if err != nil {
+        return nil, err
+    }
+    defer f.Close()
+    return io.ReadAll(f)
+}
+
+func process() {
+    mu.Lock()
+    defer mu.Unlock()
+    // ...
+}
+```
+
+### Channel Size
+
+```go
+// Good: unbuffered or 1
+ch := make(chan int)
+ch := make(chan int, 1)
+
+// Requires justification
+ch := make(chan int, 100) // Why 100?
+```
+
+### Start Enums at One
+
+```go
+type Operation int
+
+const (
+    Add Operation = iota + 1
+    Subtract
+    Multiply
+)
+```
+
+### Error Types
+
+```go
+// Sentinel errors
+var ErrNotFound = errors.New("not found")
+
+// Error wrapping
+if err != nil {
+    return fmt.Errorf("failed to get user: %w", err)
+}
+
+// Checking errors
+if errors.Is(err, ErrNotFound) {
+    // handle not found
+}
+```
+
+### Handle Errors Once
+
+```go
+// Bad: logs AND returns
+if err != nil {
+    log.Printf("error: %v", err)
+    return err
+}
+
+// Good: return with context
+if err != nil {
+    return fmt.Errorf("process: %w", err)
+}
+```
+
+### Use strconv Over fmt
+
+```go
+// Good
+s := strconv.Itoa(n)
+n, err := strconv.Atoi(s)
+
+// Slower
+s := fmt.Sprintf("%d", n)
+```
+
+### Table-Driven Tests
+
+```go
+func TestSplit(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+        sep   string
+        want  []string
+    }{
+        {
+            name:  "simple",
+            input: "a/b/c",
+            sep:   "/",
+            want:  []string{"a", "b", "c"},
+        },
+        {
+            name:  "empty",
+            input: "",
+            sep:   "/",
+            want:  []string{""},
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got := strings.Split(tt.input, tt.sep)
+            if diff := cmp.Diff(tt.want, got); diff != "" {
+                t.Errorf("mismatch (-want +got):\n%s", diff)
+            }
+        })
+    }
+}
+```
+
+### Functional Options
+
+```go
+type Server struct {
+    addr    string
+    timeout time.Duration
+}
+
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) {
+        s.timeout = d
+    }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+    s := &Server{
+        addr:    addr,
+        timeout: time.Second * 30,
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+server := NewServer(":8080", WithTimeout(time.Minute))
+```