Cursor rule

1---
2description:
3globs:
4alwaysApply: true
5---
6# Go Coding Standards
7 
8<role>
9You are an expert in Go, microservices architecture, and clean backend development practices. Your role is to ensure code is idiomatic, modular, testable, and aligned with Compozy's established patterns and best practices.
10</role>
11 
12## Project Structure and Organization
13 
14- Group code by feature/domain when appropriate (agent, task, tool, workflow)
15- Keep package names simple and descriptive
16- Follow the established pattern of separating interfaces from implementations
17 
18## Code Style and Standards
19 
20<limits type="mandatory">
21- Adhere to Go's official style guide and the project's `.golangci.yml` configuration
22- Function length should not exceed 30 lines for business logic
23- Line length should not exceed 120 characters
24- Cyclomatic complexity should be kept below 10
25</limits>
26 
27<documentation_policy>
28- **DON'T ADD** comments to explain code changes - explanation belongs in text responses
29- Only add code comments when user explicitly requests them or code is complex and requires context for future developers
30</documentation_policy>
31 
32## Error Handling
33 
34<unified_strategy type="mandatory">
35**UNIFIED ERROR HANDLING STRATEGY - SINGLE SOURCE OF TRUTH**
36 
371. **Internal Error Propagation (within domains):**
38   - Use `fmt.Errorf()` for all internal error propagation within a domain
39   - Always wrap errors with context: `fmt.Errorf("failed to load user: %w", err)`
40   - This keeps internal code simple and avoids unnecessary abstraction
41 
422. **Domain Boundaries (public service methods):**
43   - Use `core.NewError()` ONLY when returning errors from public service methods
44   - These are the methods exposed to other domains or external consumers
45   - Provides structured error information for cross-domain communication
46 
473. **Always Required:**
48   - Check and handle errors explicitly - never ignore errors
49   - Return early on errors to avoid deep nesting
50   - Avoid naked returns in longer functions (as enforced by nakedret linter)
51</unified_strategy>
52 
53<examples type="implementation">
54```go
55// ✅ INTERNAL: Use fmt.Errorf within domain
56func (s *userService) validateUser(ctx context.Context, user *User) error {
57    if user.Email == "" {
58        return fmt.Errorf("email is required")
59    }
60    if err := s.repo.CheckEmailExists(ctx, user.Email); err != nil {
61        return fmt.Errorf("failed to check email existence: %w", err)
62    }
63    return nil
64}
65 
66// ✅ DOMAIN BOUNDARY: Use core.NewError for public methods
67func (s *userService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
68    user := &User{Email: req.Email, Name: req.Name}
69    if err := s.validateUser(ctx, user); err != nil {
70        return nil, core.NewError(err, "USER_VALIDATION_FAILED", map[string]any{
71            "email": req.Email,
72        })
73    }
74    // ... rest of implementation using fmt.Errorf internally
75}
76```
77</examples>
78 
79<pattern type="transaction">
80```go
81defer func() {
82    if err != nil { tx.Rollback(ctx) } else { tx.Commit(ctx) }
83}()
84```
85</pattern>
86 
87## Dependencies and Interfaces
88 
89- Prefer explicit dependency injection through constructor functions
90- Use interfaces to define behavior and enable testing
91 
92<pattern type="interface_implementation">
93```go
94// Define interface
95type Service interface {
96  DoSomething(ctx context.Context, param string) error
97}
98 
99// Implement interface
100type ServiceImpl struct {
101  dependency Dependency
102}
103 
104// Constructor function
105func NewService(dependency Dependency) Service {
106  return &serviceImpl{
107    dependency: dependency,
108  }
109}
110```
111</pattern>
112 
113## Context and Concurrency
114 
115<requirements type="context">
116- Use `context.Context` for request-scoped values, deadlines, and cancellations
117- Pass context as the first parameter to functions that make external calls
118- Use the noctx linter to enforce context propagation
119- Ensure goroutines are properly managed and cleaned up
120</requirements>
121