agentic-team-templates 0.11.0 → 0.12.1

package/templates/golang-expert/.cursorrules/interfaces-and-types.md

@@ -0,0 +1,255 @@
+# Go Interfaces and Type Design
+
+Go's type system is intentionally simple. Interfaces are implicit. Composition replaces inheritance. The goal is clarity, not cleverness.
+
+## Interface Design
+
+### Keep Interfaces Small
+
+```go
+// Good: Single-method interfaces are the most powerful abstraction in Go
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+// Compose small interfaces into larger ones when needed
+type ReadWriter interface {
+    Reader
+    Writer
+}
+
+// Bad: Large interfaces that force implementers to satisfy methods they don't need
+type Repository interface {
+    Create(ctx context.Context, entity Entity) error
+    GetByID(ctx context.Context, id string) (*Entity, error)
+    Update(ctx context.Context, entity Entity) error
+    Delete(ctx context.Context, id string) error
+    List(ctx context.Context, filter Filter) ([]Entity, error)
+    Count(ctx context.Context, filter Filter) (int, error)
+    // 6 methods — any mock must implement all 6
+}
+
+// Better: Separate interfaces by consumer need
+type EntityReader interface {
+    GetByID(ctx context.Context, id string) (*Entity, error)
+}
+
+type EntityWriter interface {
+    Create(ctx context.Context, entity Entity) error
+    Update(ctx context.Context, entity Entity) error
+}
+```
+
+### Define Interfaces at the Consumer, Not the Producer
+
+```go
+// Good: The consumer defines what it needs
+// In package "handler":
+type UserFinder interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+
+type Handler struct {
+    users UserFinder // Only needs one method
+}
+
+// In package "postgres":
+// *UserRepo satisfies handler.UserFinder implicitly
+type UserRepo struct { db *sql.DB }
+
+func (r *UserRepo) FindByID(ctx context.Context, id string) (*User, error) { ... }
+func (r *UserRepo) Create(ctx context.Context, u *User) error { ... }
+func (r *UserRepo) Delete(ctx context.Context, id string) error { ... }
+
+// Bad: Producer defines an interface and forces consumers to accept all of it
+// package "postgres"
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+    Create(ctx context.Context, u *User) error
+    Delete(ctx context.Context, id string) error
+}
+```
+
+### Interface Naming
+
+```go
+// Single-method interfaces: method name + "er"
+type Reader interface { Read(p []byte) (int, error) }
+type Closer interface { Close() error }
+type Stringer interface { String() string }
+type Handler interface { ServeHTTP(ResponseWriter, *Request) }
+
+// Multi-method interfaces: descriptive noun
+type ReadCloser interface {
+    Reader
+    Closer
+}
+```
+
+## Struct Design
+
+### Functional Options
+
+```go
+// For constructors with many optional parameters
+type Server struct {
+    addr         string
+    readTimeout  time.Duration
+    writeTimeout time.Duration
+    logger       *slog.Logger
+}
+
+type Option func(*Server)
+
+func WithReadTimeout(d time.Duration) Option {
+    return func(s *Server) { s.readTimeout = d }
+}
+
+func WithWriteTimeout(d time.Duration) Option {
+    return func(s *Server) { s.writeTimeout = d }
+}
+
+func WithLogger(l *slog.Logger) Option {
+    return func(s *Server) { s.logger = l }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+    s := &Server{
+        addr:         addr,
+        readTimeout:  30 * time.Second, // Sensible defaults
+        writeTimeout: 30 * time.Second,
+        logger:       slog.Default(),
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+srv := NewServer(":8080",
+    WithReadTimeout(10*time.Second),
+    WithLogger(logger),
+)
+```
+
+### Embedding for Composition
+
+```go
+// Good: Embed to compose behavior
+type LoggingMiddleware struct {
+    next   http.Handler
+    logger *slog.Logger
+}
+
+// Good: Embed mutex to protect struct fields
+type SafeMap struct {
+    mu sync.RWMutex
+    m  map[string]string
+}
+
+// Bad: Embedding to "inherit" — Go doesn't have inheritance
+type Animal struct { Name string }
+type Dog struct {
+    Animal // This is composition, not inheritance — don't treat it as inheritance
+}
+```
+
+### Method Receivers
+
+```go
+// Use pointer receivers when:
+// - The method mutates the receiver
+// - The struct is large (avoid copying)
+// - Consistency: if any method needs a pointer, use pointers for all
+func (s *Server) Start() error { ... }
+
+// Use value receivers when:
+// - The struct is small and immutable (time.Time, etc.)
+// - The method doesn't modify the receiver
+func (p Point) Distance(other Point) float64 { ... }
+
+// Never mix pointer and value receivers on the same type
+// Pick one and be consistent
+```
+
+## Type Aliases and Definitions
+
+```go
+// Type definitions create a new, distinct type
+type UserID string
+type Celsius float64
+
+// Prevents mixing incompatible values
+func GetUser(id UserID) (*User, error) { ... }
+// GetUser("raw-string") won't compile — must be UserID("raw-string")
+
+// Type aliases are for migration, not abstraction
+type OldName = NewName // Both are the same type — useful for gradual refactors
+```
+
+## Generics (Go 1.18+)
+
+```go
+// Use generics when the logic is identical across types
+// and the type parameter adds real value
+
+// Good: Generic data structures and algorithms
+func Map[T, U any](s []T, f func(T) U) []U {
+    result := make([]U, len(s))
+    for i, v := range s {
+        result[i] = f(v)
+    }
+    return result
+}
+
+func Filter[T any](s []T, predicate func(T) bool) []T {
+    var result []T
+    for _, v := range s {
+        if predicate(v) {
+            result = append(result, v)
+        }
+    }
+    return result
+}
+
+// Good: Type constraints for compile-time safety
+type Ordered interface {
+    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
+    ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
+    ~float32 | ~float64 | ~string
+}
+
+func Max[T Ordered](a, b T) T {
+    if a > b {
+        return a
+    }
+    return b
+}
+
+// Bad: Generics for the sake of generics
+// If there's only one concrete type, don't make it generic
+// If an interface works, prefer the interface
+```
+
+## Anti-Patterns
+
+```go
+// Never: Empty interface (any) as a parameter when the type is known
+func Process(data any) { ... } // What is data? No one knows without reading the implementation.
+
+// Never: Interface pollution — defining interfaces you don't consume
+// If only one type implements the interface, you probably don't need the interface
+
+// Never: Returning interfaces from constructors (hides information)
+func New() MyInterface { return &myImpl{} } // BAD — return *myImpl
+
+// Never: Stuttering — the package name is part of the identifier
+package user
+type UserService struct{} // user.UserService stutters
+type Service struct{}     // user.Service reads cleanly
+```

package/templates/golang-expert/.cursorrules/overview.md

@@ -0,0 +1,139 @@
+# Go Expert
+
+Guidelines for principal-level Go engineering. Idiomatic Go, production systems, and deep runtime knowledge.
+
+## Scope
+
+This ruleset applies to:
+- HTTP services and gRPC servers
+- CLI tools and system utilities
+- Libraries and shared packages
+- Distributed systems and microservices
+- Data pipelines and stream processing
+- Infrastructure tooling and platform code
+
+## Core Philosophy
+
+Go is a language of restraint. The best Go code is boring Go code.
+
+- **Simplicity is the highest virtue.** If a junior engineer can't read it, it's too clever.
+- **The standard library is your first dependency.** Reach for third-party packages only when the stdlib genuinely falls short.
+- **Errors are values, not exceptions.** Handle them explicitly at every call site.
+- **Concurrency is a tool, not a default.** Don't use goroutines because you can — use them because the problem demands it.
+- **Interfaces are discovered, not designed.** Accept interfaces, return structs.
+- **If you don't know, say you don't know.** Guessing at behavior you haven't verified is worse than admitting uncertainty.
+
+## Key Principles
+
+### 1. Effective Go Is the Baseline
+
+The official [Effective Go](https://go.dev/doc/effective_go) document and the [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) wiki are not suggestions — they are the floor. Everything in this guide builds on top of those foundations.
+
+### 2. Package Design
+
+```go
+// A package should have a single, clear purpose.
+// The package name IS the documentation.
+
+// Good: package names that describe what they do
+package httputil   // HTTP utility functions
+package authz      // Authorization logic
+package sqlmigrate // SQL migration runner
+
+// Bad: package names that describe nothing
+package util       // Util of what?
+package common     // Common to whom?
+package helpers    // Helping with what?
+package base       // Base of what?
+```
+
+### 3. Accept Interfaces, Return Structs
+
+```go
+// Good: Accept the narrowest interface that satisfies the need
+func ProcessRecords(r io.Reader) error { ... }
+
+// Good: Return concrete types — let callers decide abstraction
+func NewServer(cfg Config) *Server { ... }
+
+// Bad: Returning an interface hides information and prevents extension
+func NewServer(cfg Config) ServerInterface { ... }
+
+// Bad: Accepting a concrete type when only one method is needed
+func ProcessRecords(f *os.File) error { ... }
+```
+
+### 4. Zero Values Are Useful
+
+```go
+// Design types so zero values are valid and usable
+type Buffer struct {
+    buf  []byte
+    // No constructor needed — zero value is an empty, ready-to-use buffer
+}
+
+// sync.Mutex zero value is an unlocked mutex — no Init() needed
+var mu sync.Mutex
+
+// bytes.Buffer zero value is an empty buffer ready for writes
+var buf bytes.Buffer
+buf.WriteString("hello")
+```
+
+### 5. Error Handling Is Not Boilerplate
+
+```go
+// Every error check is a conscious decision about what happens next.
+// If you find yourself writing the same error handling repeatedly,
+// the API design needs work — not the error handling.
+
+// Good: Add context at every level
+result, err := db.QueryContext(ctx, query, args...)
+if err != nil {
+    return fmt.Errorf("querying users by email %q: %w", email, err)
+}
+```
+
+## Project Structure
+
+```
+project/
+├── cmd/                    # Main applications
+│   └── myapp/
+│       └── main.go         # Minimal — wiring only
+├── internal/               # Private application code
+│   ├── domain/             # Core business types and logic
+│   ├── service/            # Application services / use cases
+│   ├── repository/         # Data access implementations
+│   ├── handler/            # HTTP/gRPC handlers
+│   └── platform/           # Infrastructure concerns (logging, metrics, config)
+├── pkg/                    # Public library code (use sparingly)
+├── api/                    # API definitions (OpenAPI, protobuf)
+├── migrations/             # Database migrations
+├── testdata/               # Test fixtures
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+### Layout Rules
+
+- `cmd/` contains only `main.go` files that wire dependencies and call `run()`
+- `internal/` is your private code — the compiler enforces this boundary
+- `pkg/` is for genuinely reusable library code intended for other projects — most projects don't need it
+- Never put business logic in `cmd/` or `handler/`
+- Co-locate tests with the code they test: `foo.go` and `foo_test.go` in the same package
+
+## Definition of Done
+
+A Go feature is complete when:
+- [ ] `go vet ./...` reports zero issues
+- [ ] `staticcheck ./...` reports zero issues
+- [ ] `golangci-lint run` passes with the project's config
+- [ ] `go test -race ./...` passes with no race conditions
+- [ ] Test coverage covers meaningful behavior (not just lines)
+- [ ] Error paths are tested, not just happy paths
+- [ ] Documentation comments on all exported identifiers
+- [ ] No `TODO` or `FIXME` without an associated issue
+- [ ] Context propagation is correct (no `context.Background()` in request paths)
+- [ ] Resource cleanup verified (deferred closes, connection pools)

package/templates/golang-expert/.cursorrules/performance.md

@@ -0,0 +1,234 @@
+# Go Performance
+
+Go is fast by default. The garbage collector, runtime scheduler, and compiler do heavy lifting. Your job is to not get in the way — and to know how to profile when something is slow.
+
+## Profile First
+
+Never optimize without profiling data. Intuition about bottlenecks is wrong more often than it's right.
+
+```go
+// CPU profiling
+import "runtime/pprof"
+
+f, _ := os.Create("cpu.prof")
+pprof.StartCPUProfile(f)
+defer pprof.StopCPUProfile()
+
+// Memory profiling
+f, _ := os.Create("mem.prof")
+pprof.WriteHeapProfile(f)
+
+// In HTTP servers — import for side effects
+import _ "net/http/pprof"
+// Then: go tool pprof http://localhost:6060/debug/pprof/heap
+
+// Analyze
+// go tool pprof cpu.prof
+// (pprof) top10
+// (pprof) web    # Opens in browser
+// (pprof) list FunctionName
+```
+
+## Memory Allocation
+
+### Preallocate Slices
+
+```go
+// Good: Preallocate when length is known
+users := make([]User, 0, len(ids))
+for _, id := range ids {
+    u, err := getUser(id)
+    if err != nil {
+        return nil, err
+    }
+    users = append(users, u)
+}
+
+// Bad: Growing slice dynamically
+var users []User // Repeated reallocation as it grows
+```
+
+### Avoid Unnecessary Allocations
+
+```go
+// Good: Reuse buffers
+var bufPool = sync.Pool{
+    New: func() any { return new(bytes.Buffer) },
+}
+
+func process(data []byte) string {
+    buf := bufPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufPool.Put(buf)
+    }()
+
+    buf.Write(data)
+    // ... process ...
+    return buf.String()
+}
+
+// Good: strings.Builder for string concatenation
+var b strings.Builder
+for _, s := range parts {
+    b.WriteString(s)
+}
+result := b.String()
+
+// Bad: String concatenation in a loop
+result := ""
+for _, s := range parts {
+    result += s // Allocates a new string every iteration
+}
+```
+
+### Pointer vs Value Semantics
+
+```go
+// Small structs (< ~64 bytes): pass by value — avoids heap allocation
+type Point struct{ X, Y float64 }
+func Distance(a, b Point) float64 { ... } // Copies are cheap, stays on stack
+
+// Large structs or structs that must be shared: pass by pointer
+type Config struct { /* many fields */ }
+func NewServer(cfg *Config) *Server { ... }
+
+// Slices, maps, and channels are already reference types — don't pass pointers to them
+func Process(items []Item) { ... }     // Good
+func Process(items *[]Item) { ... }    // Bad (unless you need to modify the slice header)
+```
+
+## Concurrency Performance
+
+### Minimize Lock Contention
+
+```go
+// Use sync.RWMutex for read-heavy workloads
+type Cache struct {
+    mu   sync.RWMutex
+    data map[string]Entry
+}
+
+func (c *Cache) Get(key string) (Entry, bool) {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    e, ok := c.data[key]
+    return e, ok
+}
+
+func (c *Cache) Set(key string, entry Entry) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.data[key] = entry
+}
+
+// For high-contention counters, use atomic operations
+var requestCount atomic.Int64
+requestCount.Add(1)
+```
+
+### Avoid Goroutine Leaks
+
+```go
+// Every goroutine must have a clear exit condition
+// Use context cancellation to signal shutdown
+
+func startWorkers(ctx context.Context, n int) {
+    var wg sync.WaitGroup
+    for range n {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for {
+                select {
+                case <-ctx.Done():
+                    return
+                default:
+                    doWork()
+                }
+            }
+        }()
+    }
+    wg.Wait()
+}
+```
+
+## Compiler Optimizations
+
+```go
+// Inlining: Small functions are automatically inlined
+// Check: go build -gcflags="-m" ./...
+
+// Escape analysis: The compiler decides stack vs heap
+// Check: go build -gcflags="-m" ./...
+// "moved to heap" = allocation — consider if avoidable
+
+// Bounds check elimination: The compiler removes bounds checks
+// when it can prove safety
+s := data[0:10]
+for i := range s { // Compiler knows i is in bounds — no check needed
+    process(s[i])
+}
+```
+
+## Database Performance
+
+```go
+// Always use connection pooling
+db, err := sql.Open("postgres", connString)
+db.SetMaxOpenConns(25)           // Limit concurrent connections
+db.SetMaxIdleConns(5)            // Keep some connections warm
+db.SetConnMaxLifetime(5 * time.Minute) // Rotate connections
+
+// Use prepared statements for repeated queries
+stmt, err := db.PrepareContext(ctx, "SELECT * FROM users WHERE id = $1")
+defer stmt.Close()
+
+// Use batch operations for bulk inserts
+// Use COPY protocol (pgx) for large data loads
+```
+
+## Benchmarking Best Practices
+
+```go
+func BenchmarkJSON(b *testing.B) {
+    data := loadTestData()
+
+    b.ResetTimer()        // Exclude setup time
+    b.ReportAllocs()      // Report memory allocations
+
+    for b.Loop() {
+        var result MyStruct
+        if err := json.Unmarshal(data, &result); err != nil {
+            b.Fatal(err)
+        }
+    }
+}
+
+// Compare implementations
+func BenchmarkJSON_StdLib(b *testing.B) { ... }
+func BenchmarkJSON_Sonic(b *testing.B) { ... }
+
+// Run: go test -bench=. -benchmem -count=5 ./...
+// Use benchstat to compare: benchstat old.txt new.txt
+```
+
+## Anti-Patterns
+
+```go
+// Never: Premature optimization
+// Profile first. The bottleneck is almost never where you think it is.
+
+// Never: sync.Pool for small, short-lived objects
+// The GC handles these efficiently. Pool is for large buffers.
+
+// Never: Manual memory management tricks
+// Go's GC is highly optimized. Fight the runtime and you'll lose.
+
+// Never: Caching without bounds
+cache := make(map[string]Result) // Grows forever — OOM eventually
+// Use an LRU cache with a max size.
+
+// Never: Blocking operations in hot paths without timeouts
+resp, err := http.Get(url) // No timeout! Use http.Client with Timeout set.
+```