code-ai-installer 2.5.0 → 4.0.0

package/domains/development/.agents/skills/go-beast-practices/SKILL.md

@@ -1,11 +1,41 @@
 ---
 name: go-beast-practices
-description: Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD). Table-driven tests, errgroup, graceful shutdown, HTTP handlers. Активируй при написании или ревью Go-кода, или при вопросах «как правильно написать X на Go».
+description: "Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD). Table-driven tests, errgroup, graceful shutdown, HTTP handlers. Активируй при написании или ревью Go-кода, или при вопросах «как правильно написать X на Go»."
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - go
+topic:
+  - general
+triggers:
+  - Go код
+  - errgroup
+  - table-driven tests
+  - context.Context
+  - graceful shutdown Go
+  - HTTP handler Go
+  - интерфейсы Go
+related:
+  - go-beast-practices-reference
+  - node-express-beast-practices
+  - node-express-beast-practices-reference
+  - testing-strategy-js
+  - tdd-workflow
+  - security-baseline-dev
+  - observability-logging
+  - dev-reference-snippets
+budget_lines: 300
+schema_version: 1
 ---
 
+
 # Skill: Go Beast Practices
 
-Конкретные DO/DON'T паттерны для идиоматического Go.
+Decision rules + canonical tables для идиоматического Go. Полные DO/DON'T кодовые примеры — в `$go-beast-practices-reference`.
 
 **Разделы:**
 1. [Структура проекта](#1-структура-проекта)
@@ -28,20 +58,13 @@ project/
 │   └── server/
 │       └── main.go              # Entrypoint: wiring, start server
 ├── internal/                     # Private app code (not importable)
-│   ├── config/
-│   │   └── config.go            # Env loading + validation
-│   ├── handler/
-│   │   ├── coupon.go            # HTTP handlers
-│   │   └── middleware.go        # HTTP middleware
-│   ├── service/
-│   │   └── coupon.go            # Business logic
-│   ├── repository/
-│   │   └── coupon.go            # Data access
-│   └── model/
-│       └── coupon.go            # Domain types
+│   ├── config/config.go         # Env loading + validation
+│   ├── handler/                 # HTTP handlers + middleware
+│   ├── service/                 # Business logic
+│   ├── repository/              # Data access
+│   └── model/                   # Domain types
 ├── pkg/                          # Public reusable code (if any)
-│   └── httputil/
-│       └── response.go
+│   └── httputil/response.go
 ├── go.mod
 ├── go.sum
 ├── Makefile
@@ -49,487 +72,100 @@ project/
 ```
 
 > [!TIP]
-> `internal/` — Go enforces access control: code in `internal/` cannot be imported by external packages. Use it for app-specific code.
+> `internal/` — Go enforces access control: код в `internal/` не может быть импортирован внешними пакетами. Используй для app-specific кода.
 
 ---
 
 ## 2. Обработка ошибок
 
-### ✅ DO: оборачивать ошибки контекстом
-
-```go
-// ✅ fmt.Errorf с %w — сохраняет цепочку ошибок
-func (r *CouponRepo) FindByID(ctx context.Context, id string) (*model.Coupon, error) {
-    var coupon model.Coupon
-    err := r.db.QueryRowContext(ctx, "SELECT * FROM coupons WHERE id = $1", id).Scan(&coupon)
-    if err != nil {
-        if errors.Is(err, sql.ErrNoRows) {
-            return nil, fmt.Errorf("coupon %s: %w", id, ErrNotFound)
-        }
-        return nil, fmt.Errorf("query coupon %s: %w", id, err)
-    }
-    return &coupon, nil
-}
-```
-
-### ✅ DO: sentinel errors для бизнес-ошибок
-
-```go
-// errors.go
-package service
-
-import "errors"
-
-var (
-    ErrNotFound    = errors.New("not found")
-    ErrConflict    = errors.New("already exists")
-    ErrValidation  = errors.New("validation failed")
-    ErrUnauthorized = errors.New("unauthorized")
-)
-
-// В handler:
-func (h *Handler) GetCoupon(w http.ResponseWriter, r *http.Request) {
-    coupon, err := h.service.GetByID(r.Context(), id)
-    if err != nil {
-        switch {
-        case errors.Is(err, service.ErrNotFound):
-            httputil.Error(w, http.StatusNotFound, err.Error())
-        case errors.Is(err, service.ErrUnauthorized):
-            httputil.Error(w, http.StatusUnauthorized, "access denied")
-        default:
-            h.logger.Error("get coupon failed", "error", err, "id", id)
-            httputil.Error(w, http.StatusInternalServerError, "internal error")
-        }
-        return
-    }
-    httputil.JSON(w, http.StatusOK, coupon)
-}
-```
+**Правила:**
+- **Оборачивай ошибки** через `fmt.Errorf("op %s: %w", arg, err)` — сохраняет цепочку
+- **Sentinel errors** для бизнес-ошибок: `var ErrNotFound = errors.New("not found")` — проверяй через `errors.Is(err, ErrNotFound)`
+- **Никогда не игнорируй** `err` — всегда проверяй или хотя бы логируй
+- **Никогда `panic`** в production коде — только для programmer errors на startup
+- В handler — `switch { case errors.Is(...): ... }` для маппинга на HTTP status
+- ❌ `_ = json.Unmarshal(...)`, ❌ `func MustParse() { ... panic(err) }`
 
-### ❌ DON'T: игнорировать ошибки
-
-```go
-// ❌ Ошибка молча проглатывается
-json.Unmarshal(data, &result) // err ignored!
-
-// ✅ Всегда проверять
-if err := json.Unmarshal(data, &result); err != nil {
-    return fmt.Errorf("unmarshal response: %w", err)
-}
-
-// ❌ Паника вместо обработки
-func MustParse(s string) int {
-    n, err := strconv.Atoi(s)
-    if err != nil {
-        panic(err) // ❌ никогда в production
-    }
-    return n
-}
-```
+> Полный код error wrapping + sentinel errors + handler error switch → `$go-beast-practices-reference` §2.
 
 ---
 
 ## 3. Интерфейсы и DI
 
-### ✅ DO: маленькие интерфейсы на стороне потребителя
-
-```go
-// ✅ Интерфейс определяется там где ИСПОЛЬЗУЕТСЯ, а не там где реализуется
-// service/coupon.go
-type CouponRepository interface {
-    FindByID(ctx context.Context, id string) (*model.Coupon, error)
-    FindAll(ctx context.Context, offset, limit int) ([]model.Coupon, error)
-    Create(ctx context.Context, c *model.Coupon) error
-    Delete(ctx context.Context, id string) error
-}
-
-type CouponService struct {
-    repo   CouponRepository // ✅ зависимость от интерфейса
-    logger *slog.Logger
-}
-
-func NewCouponService(repo CouponRepository, logger *slog.Logger) *CouponService {
-    return &CouponService{repo: repo, logger: logger}
-}
-```
+**Правила:**
+- **Маленькие интерфейсы на стороне потребителя** — определяй там, где используется, не там, где реализуется
+- **Зависимость от интерфейса, не от конкретного типа** — `repo CouponRepository` (не `*CouponRepo`)
+- **Constructor injection** — `NewCouponService(repo CouponRepository, logger *slog.Logger)`
+- ❌ **Fat interfaces** (20+ методов) — невозможно мокать, нарушает ISP; разбивай по домену (`UserFinder`, `CouponFinder`)
 
-### ❌ DON'T: fat interfaces
-
-```go
-// ❌ Интерфейс с 20 методами — невозможно мокать, нарушает ISP
-type Database interface {
-    FindUser(ctx context.Context, id string) (*User, error)
-    FindCoupon(ctx context.Context, id string) (*Coupon, error)
-    FindOrder(ctx context.Context, id string) (*Order, error)
-    CreateUser(...) error
-    CreateCoupon(...) error
-    // ... ещё 15 методов
-}
-
-// ✅ Маленькие интерфейсы по домену
-type UserFinder interface {
-    FindUser(ctx context.Context, id string) (*User, error)
-}
-```
+> Полный код service + repository интерфейсов → `$go-beast-practices-reference` §3.
 
 ---
 
 ## 4. Context
 
-### ✅ DO: context первым параметром
-
-```go
-// ✅ ctx всегда первый, именуется ctx
-func (s *CouponService) GetByID(ctx context.Context, id string) (*model.Coupon, error) {
-    return s.repo.FindByID(ctx, id)
-}
+**Правила:**
+- **`ctx context.Context` ВСЕГДА первый параметр**, именуется `ctx`
+- **Timeout через context** — `ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second); defer cancel()`
+- **Пробрасывай `ctx` от handler к repo** — без обрыва цепочки
+- ❌ **Не храни `context` в struct** — context живёт по request lifetime
+- ❌ **Не используй `context.Background()`** где доступен `r.Context()` — теряешь отмену
 
-// ✅ Timeout через context
-func (h *Handler) ListCoupons(w http.ResponseWriter, r *http.Request) {
-    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
-    defer cancel()
-
-    coupons, err := h.service.ListAll(ctx)
-    // ...
-}
-
-// ❌ Не хранить context в struct
-type BadService struct {
-    ctx context.Context // ❌ context не хранится в struct!
-}
-```
+> Полный код context propagation + timeout patterns → `$go-beast-practices-reference` §4.
 
 ---
 
 ## 5. Конкурентность
 
-### ✅ DO: errgroup для параллельных задач
-
-```go
-import "golang.org/x/sync/errgroup"
-
-func (s *DashboardService) GetDashboard(ctx context.Context, userID string) (*Dashboard, error) {
-    g, ctx := errgroup.WithContext(ctx)
-
-    var user *model.User
-    var stats *model.Stats
-    var coupons []model.Coupon
-
-    g.Go(func() error {
-        var err error
-        user, err = s.userRepo.FindByID(ctx, userID)
-        return err
-    })
-
-    g.Go(func() error {
-        var err error
-        stats, err = s.statsRepo.GetForUser(ctx, userID)
-        return err
-    })
-
-    g.Go(func() error {
-        var err error
-        coupons, err = s.couponRepo.FindByUser(ctx, userID)
-        return err
-    })
-
-    if err := g.Wait(); err != nil {
-        return nil, fmt.Errorf("load dashboard for %s: %w", userID, err)
-    }
-
-    return &Dashboard{User: user, Stats: stats, Coupons: coupons}, nil
-}
-```
-
-### ✅ DO: worker pool с semaphore
-
-```go
-func processItems(ctx context.Context, items []Item, maxWorkers int) error {
-    g, ctx := errgroup.WithContext(ctx)
-    g.SetLimit(maxWorkers) // ✅ ограничение параллельности
-
-    for _, item := range items {
-        item := item // ✅ capture (Go < 1.22)
-        g.Go(func() error {
-            return processItem(ctx, item)
-        })
-    }
-
-    return g.Wait()
-}
-```
-
-### ✅ DO: graceful shutdown
-
-```go
-func main() {
-    srv := &http.Server{Addr: ":8080", Handler: mux}
-
-    // Start server in goroutine
-    go func() {
-        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-            log.Fatal("server error:", err)
-        }
-    }()
-
-    // Wait for signal
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-    <-quit
+**Правила:**
+- **`errgroup` для параллельных задач** с автоматической отменой при первой ошибке (`golang.org/x/sync/errgroup`)
+- **Worker pool через `g.SetLimit(n)`** — ограничение параллельности
+- **`item := item`** для capture в горутинах (Go < 1.22; в 1.22+ не нужно)
+- **Graceful shutdown** — `signal.Notify(quit, SIGINT, SIGTERM)` → `srv.Shutdown(ctx)` с timeout
+- ❌ **`go func()` без errgroup/recover** — паника в горутине ронит весь процесс
+- ❌ **Мутексы для concurrent Map** — используй `sync.Map` или channels
 
-    log.Println("Shutting down...")
-
-    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-    defer cancel()
-
-    if err := srv.Shutdown(ctx); err != nil {
-        log.Fatal("forced shutdown:", err)
-    }
-
-    log.Println("Server stopped")
-}
-```
+> Полный код errgroup + worker pool + graceful shutdown → `$go-beast-practices-reference` §5.
 
 ---
 
 ## 6. HTTP Handlers
 
-### ✅ DO: httputil response helpers
-
-```go
-// pkg/httputil/response.go
-package httputil
-
-import (
-    "encoding/json"
-    "net/http"
-)
-
-// JSON отправляет JSON response с указанным статусом.
-func JSON(w http.ResponseWriter, status int, data any) {
-    w.Header().Set("Content-Type", "application/json")
-    w.WriteHeader(status)
-    json.NewEncoder(w).Encode(data)
-}
+**Правила:**
+- **httputil helpers** (`JSON(w, status, data)`, `Error(w, status, msg)`) — единый формат ответа
+- **`Middleware = func(http.Handler) http.Handler`** — стандартный паттерн
+- **Chain middleware** через reverse-итерацию — внешний middleware первым
+- **RequestID в context** — для корреляции логов (`context.WithValue(r.Context(), requestIDKey, id)`)
+- **Logging middleware** оборачивает `ResponseWriter` для capture статуса и длительности
 
-// Error отправляет JSON error response.
-func Error(w http.ResponseWriter, status int, message string) {
-    JSON(w, status, map[string]string{"error": message})
-}
-```
-
-### ✅ DO: middleware pattern
-
-```go
-// Middleware type
-type Middleware func(http.Handler) http.Handler
-
-// RequestID middleware
-func RequestID(next http.Handler) http.Handler {
-    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-        id := r.Header.Get("X-Request-ID")
-        if id == "" {
-            id = uuid.NewString()
-        }
-        ctx := context.WithValue(r.Context(), requestIDKey, id)
-        w.Header().Set("X-Request-ID", id)
-        next.ServeHTTP(w, r.WithContext(ctx))
-    })
-}
-
-// Logging middleware
-func Logging(logger *slog.Logger) Middleware {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            start := time.Now()
-            ww := &responseWriter{ResponseWriter: w, status: http.StatusOK}
-
-            next.ServeHTTP(ww, r)
-
-            logger.Info("request",
-                "method", r.Method,
-                "path", r.URL.Path,
-                "status", ww.status,
-                "duration", time.Since(start),
-                "request_id", r.Context().Value(requestIDKey),
-            )
-        })
-    }
-}
-
-// Chain middleware
-func Chain(h http.Handler, mw ...Middleware) http.Handler {
-    for i := len(mw) - 1; i >= 0; i-- {
-        h = mw[i](h)
-    }
-    return h
-}
-```
+> Полный код httputil + RequestID + Logging + Chain middleware → `$go-beast-practices-reference` §6.
 
 ---
 
 ## 7. Тестирование
 
-### ✅ DO: table-driven tests
-
-```go
-func TestCalculateDiscount(t *testing.T) {
-    tests := []struct {
-        name     string
-        price    float64
-        percent  float64
-        want     float64
-        wantErr  bool
-    }{
-        {name: "20% off 100", price: 100, percent: 20, want: 80},
-        {name: "100% off", price: 50, percent: 100, want: 0},
-        {name: "0% off", price: 100, percent: 0, want: 100},
-        {name: "negative price", price: -10, percent: 5, wantErr: true},
-        {name: "discount > 100%", price: 100, percent: 120, wantErr: true},
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            got, err := CalculateDiscount(tt.price, tt.percent)
-
-            if tt.wantErr {
-                if err == nil {
-                    t.Fatal("expected error, got nil")
-                }
-                return
-            }
-
-            if err != nil {
-                t.Fatalf("unexpected error: %v", err)
-            }
-            if got != tt.want {
-                t.Errorf("got %v, want %v", got, tt.want)
-            }
-        })
-    }
-}
-```
-
-### ✅ DO: test helpers с t.Helper()
-
-```go
-func createTestCoupon(t *testing.T, db *sql.DB, code string) *model.Coupon {
-    t.Helper() // ✅ ошибки покажут вызывающую строку, не эту
-
-    coupon := &model.Coupon{
-        ID:       uuid.NewString(),
-        Code:     code,
-        Discount: 10,
-        Active:   true,
-    }
+**Правила:**
+- **Table-driven tests** — `tests := []struct{ name, ...; want, wantErr ... }` + `t.Run(tt.name, ...)`
+- **`t.Helper()`** в test helpers — ошибки покажут вызывающую строку
+- **`t.Cleanup()`** для автоматической очистки (вместо `defer`)
+- **`-race`** обязательно в `go test` — `go test -race -count=1 ./...`
+- **HTTP handler tests** через `httptest.NewRequest` + `httptest.NewRecorder`
+- **Mock services через interface** — small mock structs с function fields
 
-    _, err := db.Exec("INSERT INTO coupons (id, code, discount, active) VALUES ($1, $2, $3, $4)",
-        coupon.ID, coupon.Code, coupon.Discount, coupon.Active)
-    if err != nil {
-        t.Fatalf("create test coupon: %v", err)
-    }
-
-    t.Cleanup(func() { // ✅ автоматическая очистка
-        db.Exec("DELETE FROM coupons WHERE id = $1", coupon.ID)
-    })
-
-    return coupon
-}
-```
-
-### ✅ DO: HTTP handler tests
-
-```go
-func TestGetCoupon(t *testing.T) {
-    // Arrange
-    mockService := &MockCouponService{
-        GetByIDFn: func(ctx context.Context, id string) (*model.Coupon, error) {
-            return &model.Coupon{ID: id, Code: "TEST10"}, nil
-        },
-    }
-    handler := NewHandler(mockService, slog.Default())
-
-    req := httptest.NewRequest(http.MethodGet, "/coupons/abc", nil)
-    rec := httptest.NewRecorder()
-
-    // Act
-    handler.GetCoupon(rec, req)
-
-    // Assert
-    if rec.Code != http.StatusOK {
-        t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
-    }
-
-    var got model.Coupon
-    json.NewDecoder(rec.Body).Decode(&got)
-    if got.Code != "TEST10" {
-        t.Errorf("code = %q, want %q", got.Code, "TEST10")
-    }
-}
-```
+> Полный код table-driven + helpers + handler tests → `$go-beast-practices-reference` §7.
 
 ---
 
 ## 8. Tooling
 
-### Makefile
-
-```makefile
-.PHONY: run test lint fmt build
-
-run:
-	go run ./cmd/server
+**Правила:**
+- **Makefile** — `run`, `build`, `test`, `test-cover`, `lint`, `fmt` стандартные таргеты
+- **`golangci-lint`** обязателен в CI — минимум: `errcheck`, `govet`, `staticcheck`, `unused`, `gosimple`, `ineffassign`, `bodyclose`, `contextcheck`, `nilerr`
+- **`gofmt -w` + `goimports -w`** в pre-commit
+- **`go vet` shadow check** включён (`linters-settings.govet.shadow: true`)
+- **`errcheck check-blank: true`** — `_ = fn()` тоже флагается
 
-build:
-	go build -o bin/server ./cmd/server
-
-test:
-	go test -v -race -count=1 ./...
-
-test-cover:
-	go test -coverprofile=coverage.out ./...
-	go tool cover -html=coverage.out -o coverage.html
-
-lint:
-	golangci-lint run ./...
-
-fmt:
-	gofmt -w .
-	goimports -w .
-```
-
-### ✅ DO: golangci-lint конфиг
-
-```yaml
-# .golangci.yml
-linters:
-  enable:
-    - errcheck        # проверить все ошибки
-    - govet           # go vet
-    - staticcheck     # мощный статический анализ
-    - unused          # неиспользуемый код
-    - gosimple        # упрощения
-    - ineffassign     # бесполезные присваивания
-    - misspell        # опечатки в комментариях
-    - gofmt           # форматирование
-    - goimports       # import sorting
-    - bodyclose       # незакрытые http.Response.Body
-    - contextcheck    # context propagation
-    - nilerr          # return nil после проверки err != nil
-
-linters-settings:
-  errcheck:
-    check-blank: true
-  govet:
-    shadow: true
-
-run:
-  timeout: 3m
-
-issues:
-  max-issues-per-linter: 0
-  max-same-issues: 0
-```
+> Полный Makefile + `.golangci.yml` → `$go-beast-practices-reference` §8.
 
 ---
 
@@ -551,7 +187,11 @@ issues:
 ---
 
 ## См. также
+- `$go-beast-practices-reference` — полный справочник DO/DON'T Go кода
 - `$node-express-beast-practices` — Node.js/Express (если нужен JS backend)
+- `$node-express-beast-practices-reference` — Express code reference
 - `$testing-strategy-js` — TDD стратегия (JS, но паттерны переносимые)
+- `$tdd-workflow` — RED→GREEN→REFACTOR для services/handlers
 - `$security-baseline-dev` — безопасность в реализации
 - `$observability-logging` — логирование и метрики
+- `$dev-reference-snippets` — общие dev примеры

package/domains/development/.agents/skills/go-beast-practices/agents/kimi.yaml

@@ -1,15 +1,15 @@
-name: "go-beast-practices"
-display_name: "Практики Go"
-description: "Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD). Table-driven tests, errgroup, graceful shutdown, HTTP handlers. Активируй при написании или ревью Go-кода, или при вопросах «как правильно написать X на Go»."
-default_prompt: "Используй $go-beast-practices, когда задача относится к навыку \"Практики Go\"."
-triggers:
-  - "go-beast-practices"
-  - "go beast practices"
-  - "Практики Go"
-  - "Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD)"
-capabilities:
-  - "go"
-  - "beast"
-  - "practices"
-tools: []
-implicit_invocation: true
+name: "go-beast-practices"
+display_name: "Практики Go"
+description: "Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD). Table-driven tests, errgroup, graceful shutdown, HTTP handlers. Активируй при написании или ревью Go-кода, или при вопросах «как правильно написать X на Go»."
+default_prompt: "Используй $go-beast-practices, когда задача относится к навыку \"Практики Go\"."
+triggers:
+  - "go-beast-practices"
+  - "go beast practices"
+  - "Практики Go"
+  - "Go best practices — простота, ошибки как значения, интерфейсы, контекст, конкурентность, структура проекта, линтеры и тестирование (TDD)"
+capabilities:
+  - "go"
+  - "beast"
+  - "practices"
+tools: []
+implicit_invocation: true