Claude Code for Golang: Setup, Best Practices, and the Optimal Workflow

 1claude
 2> Implement the CancelOrder feature with all edge cases
 3
 4Claude Code:
 5"Before I start the implementation, let me understand the context:
 6
 71. I read CLAUDE.md and see the error handling pattern used
 82. I need to check the existing Order entity to know which methods already exist
 93. Implementation plan:
10   - Entity: add a CanBeCancelled() method
11   - Repository: add CancelWithStockRestore() + interface update
12   - Usecase: CancelOrderUseCase with all ACs
13   - Handler: DELETE /orders/:id with auth middleware
14   - Router: add the route
15   
164. Start from the entity layer first?
17   (yes/no)"

 1// Claude Code always generates this for error handling:
 2func (uc *CancelOrderUseCase) Execute(ctx context.Context, input CancelOrderInput) error {
 3    order, err := uc.orderRepo.GetByIDAndUserID(ctx, input.OrderID, input.UserID)
 4    if err != nil {
 5        return fmt.Errorf("cancelOrder.Execute: %w", err)  // ← always wraps
 6    }
 7    if order == nil {
 8        return ErrOrderNotFound  // ← domain error, not a wrapped error
 9    }
10    // ...
11}
12
13// And it NEVER generates this (though other tools sometimes do):
14result, _ := operation()  // ← ignore error
15return err  // ← no context wrap
16if err != nil { panic(err) }  // ← panic in production code

 1claude
 2> Implement data fetching for CancelOrder
 3
 4Claude Code:
 5"This implementation will touch several layers:
 6
 7Repository Interface (in the domain/usecase layer):
 8  - GetByIDAndUserID: verify ownership
 9  - CancelWithStockRestore: atomic operation
10
11Repository Implementation (in the repository/postgres layer):
12  - Needs a transaction for atomic cancel + restore
13
14I will not import pgx directly in the usecase layer.
15Start from the repository interface definition?"

 1# Start of session:
 2claude > Read CLAUDE.md and confirm the top 3 rules
 3Claude: "Top 3 rules:
 4  1. Error handling: fmt.Errorf('pkg.Method: %w', err) always
 5  2. Repository not-found: return nil, nil (never error)
 6  3. Monetary: int64 cents, NEVER float64"
 7
 8# 25 exchanges later:
 9claude > Implement get product price
10Claude: [generates with int64 cents, no reminder needed]
11# ✅ Still following rule #3

 1claude
 2> go test -race ./... produces:
 3> WARN: DATA RACE
 4> Write at 0x00c0001a4b88 by goroutine 45 (ProcessOrders.func1):
 5> Read at 0x00c0001a4b88 by goroutine 12 (ProcessOrders.func1):
 6>
 7> Code:
 8> func ProcessOrders(orders []*Order) []Result {
 9>     results := make([]Result, 0)
10>     for _, order := range orders {
11>         go func() {
12>             result := process(order)
13>             results = append(results, result)
14>         }()
15>     }
16>     wg.Wait()
17>     return results
18> }
19
20Claude Code:
21"There are TWO race conditions in this code, not one:
22
23Race 1: Variable capture in the goroutine
24  Problem: The 'order' variable is captured by reference by all goroutines.
25  All goroutines will process the last 'order' in the loop.
26  Fix: pass an explicit parameter to the goroutine function
27
28Race 2: Concurrent slice append
29  Problem: results = append(results, result) from multiple goroutines
30  without synchronization.
31  Fix: use a channel or a pre-allocated slice with an index
32
33The correct fix implementation:
34
35Option A (channel-based, more idiomatic):
36func ProcessOrders(orders []*Order) []Result {
37    resultCh := make(chan Result, len(orders))
38    var wg sync.WaitGroup
39    
40    for _, order := range orders {
41        wg.Add(1)
42        go func(o *Order) {
43            defer wg.Done()
44            resultCh <- process(o)  // send to channel
45        }(order)  // explicit copy
46    }
47    
48    go func() {
49        wg.Wait()
50        close(resultCh)
51    }()
52    
53    results := make([]Result, 0, len(orders))
54    for r := range resultCh {
55        results = append(results, r)
56    }
57    return results
58}
59
60Option B (pre-allocated slice, simpler):
61func ProcessOrders(orders []*Order) []Result {
62    results := make([]Result, len(orders))  // pre-allocate
63    var wg sync.WaitGroup
64    
65    for i, order := range orders {
66        wg.Add(1)
67        go func(idx int, o *Order) {
68            defer wg.Done()
69            results[idx] = process(o)  // index assignment, no contention
70        }(i, order)
71    }
72    
73    wg.Wait()
74    return results
75}"

 1claude --plan
 2> Refactor all error handling in the order service
 3
 4Claude Code (Plan Mode):
 5"Plan for refactoring error handling in the order service:
 6
 7Files to be modified (12 total):
 81. internal/usecase/order/create_order.go (8 changes)
 92. internal/usecase/order/cancel_order.go (5 changes)
103. internal/usecase/order/get_order.go (3 changes)
11...
12
13Type of changes:
14- Wrap all 'return err' with fmt.Errorf context
15- Update repository calls that lack an error wrap
16- Ensure domain errors propagate correctly
17
18Estimated impact:
19- No behavior change
20- All existing tests should pass
21- Better debugging trace in production logs
22
23Proceed? [y/n/detail]"
24
25# You review the plan first, then approve

 1claude
 2> Refactor create_order.go — move validation into the domain entity
 3
 4Claude Code:
 5"I have updated:
 6- internal/domain/order/entity.go (added a Validate() method)
 7- internal/usecase/order/create_order.go (removed inline validation)
 8- internal/usecase/order/create_order_test.go (updated the test)"
 9
10# You don't know exactly what changed until:
11git diff  # or open the files one by one

 1# Set up git tracking before the Claude Code session
 2git add -A
 3git commit -m "checkpoint before AI session"
 4
 5# After Claude finishes:
 6git diff HEAD  # see all changes
 7git diff HEAD internal/usecase/order/  # per directory
 8
 9# Or use a difftool:
10git difftool HEAD  # opens a visual diff tool

 1# Tracking cost:
 2claude --show-cost
 3# Output: "Session cost: $0.14 (input: 45K tokens, output: 8K tokens)"
 4
 5# Daily estimate for a heavy user:
 6# 10-15 complex tasks × $0.10-0.20 = $1.50-3.00/day
 7# Monthly: $30-60/month (API cost only)
 8
 9# Budget management tips:
10# 1. Use claude-haiku for simple tasks
11claude --model claude-haiku-4-5-20251001 > Add a godoc comment to this function
12
13# 2. Start a new session for unrelated tasks
14# (no carry-over context = less token overhead)
15
16# 3. Budget alert: set an AWS billing alert if using via Bedrock

  1# CLAUDE.md — [Project Name]
  2## Go [version] | [Framework] | [Database] | [Architecture]
  3
  4---
  5
  6## CRITICAL: Architecture (NEVER violate)
  7
  8Layer hierarchy (strict):
  9```
 10delivery/http/handler → usecase → repository → domain
 11```
 12
 13Rules:
 14- handler: ONLY imports usecase interfaces (never concrete types)
 15- usecase: ONLY imports domain types + repository interfaces
 16- repository: ONLY imports domain types + DB/infra drivers  
 17- domain: ZERO external imports (pure Go standard library only)
 18
 19Violation examples (NEVER do these):
 20```go
 21// WRONG — repository imported in usecase:
 22import "github.com/santekno/santekno-shop/internal/repository/postgres"
 23
 24// WRONG — pgx error exposed from repository:
 25return pgx.ErrNoRows  // use nil, nil instead
 26
 27// CORRECT — interface at consumer side:
 28// In usecase package:
 29type OrderRepository interface {
 30    GetByIDAndUserID(ctx context.Context, orderID, userID uuid.UUID) (*Order, error)
 31}
 32```
 33
 34---
 35
 36## CRITICAL: Error Handling (follow exactly)
 37
 38### Repository Layer
 39```go
 40// Not found → return nil, nil (NEVER return error for not-found)
 41if err == pgx.ErrNoRows {
 42    return nil, nil  // CORRECT
 43}
 44// DB error → wrap and return
 45if err != nil {
 46    return nil, fmt.Errorf("orderRepo.GetByIDAndUserID: %w", err)
 47}
 48```
 49
 50### Usecase Layer
 51```go
 52// Check nil first (means not-found from repo):
 53if order == nil {
 54    return ErrOrderNotFound  // domain error, not wrapped
 55}
 56// Infrastructure errors → wrap with usecase context:
 57if err != nil {
 58    return fmt.Errorf("cancelOrder.Execute: %w", err)
 59}
 60```
 61
 62### Handler Layer  
 63```go
 64// Map domain errors to HTTP:
 65switch {
 66case errors.Is(err, domain.ErrOrderNotFound):
 67    return c.JSON(http.StatusNotFound, ErrorResponse{Error: "ORDER_NOT_FOUND"})
 68case errors.As(err, &notCancellable):
 69    return c.JSON(http.StatusConflict, ErrorResponse{Error: "ORDER_NOT_CANCELLABLE"})
 70}
 71// HTTP error codes: ALWAYS UPPERCASE_SNAKE_CASE
 72```
 73
 74---
 75
 76## CRITICAL: Types
 77
 78```go
 79// Monetary: ALWAYS int64 cents
 80type Order struct {
 81    TotalPrice int64  // 50000 = Rp 500.00 (NOT 5.00, NOT 500.00)
 82}
 83// NEVER: float64, float32, decimal for money
 84
 85// IDs: ALWAYS uuid.UUID
 86import "github.com/google/uuid"
 87type Order struct {
 88    ID uuid.UUID
 89}
 90// NEVER: string, int for IDs
 91
 92// Time: time.Time (UTC in DB, local for display)
 93```
 94
 95---
 96
 97## External Packages (exact import paths — no alternatives)
 98
 99```
100PostgreSQL:    github.com/jackc/pgx/v5         (NEVER database/sql)
101Redis:         github.com/redis/go-redis/v9    
102HTTP:          github.com/labstack/echo/v4      
103Mocking:       go.uber.org/mock/gomock          (NEVER testify mock)
104Test suite:    github.com/stretchr/testify/suite
105UUID:          github.com/google/uuid           
106Kafka:         github.com/confluentinc/confluent-kafka-go/v2
107```
108
109---
110
111## Go Version Constraint: Go 1.22
112
113NEVER use features from Go 1.23+:
114- range-over-func (1.23+): NOT available
115- iter.Seq (1.23+): NOT available
116- slices.Collect (1.23+): NOT available
117
118---
119
120## Testing Standards
121
122```go
123// Suite structure:
124type CancelOrderSuite struct {
125    suite.Suite
126    ctrl     *gomock.Controller
127    mockRepo *mock.MockOrderRepository
128    uc       *usecase.CancelOrderUseCase
129}
130
131func (s *CancelOrderSuite) SetupTest() {
132    s.ctrl = gomock.NewController(s.T())
133    s.mockRepo = mock.NewMockOrderRepository(s.ctrl)
134    s.uc = usecase.NewCancelOrderUseCase(s.mockRepo)
135}
136
137func (s *CancelOrderSuite) TearDownTest() {
138    s.ctrl.Finish()
139}
140
141// Test naming: Test{Subject}_{Scenario}_{ExpectedResult}
142// Example: TestCancelOrder_PendingWithinWindow_Success
143//          TestCancelOrder_WindowExpired_ReturnsCancelWindowExpired
144```
145
146---
147
148## HTTP Response Standards
149
150```go
151type ErrorResponse struct {
152    Error string `json:"error"`  // UPPERCASE_SNAKE_CASE always
153}
154
155// Success: HTTP 2xx, body as specified per endpoint
156// Not found: 404 + {"error": "RESOURCE_NOT_FOUND"}
157// Conflict: 409 + {"error": "SPECIFIC_CONFLICT_REASON"}
158// Server error: 500 + {"error": "INTERNAL_SERVER_ERROR"}
159```
160
161---
162
163## NEVER do these (absolute rules)
164
165```go
166// 1. NEVER ignore errors:
167result, _ := operation()  // FORBIDDEN
168
169// 2. NEVER panic in business logic:
170if err != nil { panic(err) }  // FORBIDDEN
171
172// 3. NEVER float64 for money:
173price := 50.00  // FORBIDDEN
174
175// 4. NEVER string for IDs:
176func GetOrder(id string)  // FORBIDDEN — use uuid.UUID
177
178// 5. NEVER raw error return from usecase:
179return err  // FORBIDDEN — always wrap with context
180
181// 6. NEVER import across layers incorrectly:
182import "internal/repository/postgres"  // FORBIDDEN in usecase
183
184// 7. NEVER use a goroutine without a termination condition:
185go func() { doForever() }()  // FORBIDDEN
186```

 1claude
 2> Let's implement Task 04 from .specify/features/cancel-order/tasks.md.
 3> Read spec.md and tasks.md first, confirm what will be done.
 4
 5Claude: "Task 04: Implement CancelOrderUseCase
 6  - New file: internal/usecase/order/cancel_order.go
 7  - Dependency: OrderRepository interface (from Task 02)
 8  - Covers: AC1-AC10 from spec.md
 9  
10  I'll implement step by step. Start from the struct definition?"
11
12> Yes, go ahead.

1claude
2> Here are the tests that must pass (don't change the tests, only implement):
3
4@internal/usecase/order/cancel_order_test.go
5
6> Implement CancelOrderUseCase.Execute that makes all 8 of these tests pass.
7
8Claude: [implements based on the very specific test expectations]

 1claude
 2> Review the following files before I open a PR.
 3> Check against CLAUDE.md and spec.md:
 4
 5[list the newly implemented files]
 6
 7> Output format:
 8> CRITICAL — file:line — issue — fix
 9> SUGGESTION — file:line — improvement
10> SCORE — READY/NEEDS WORK
11
12Claude: [detailed review with findings]

 1# Copy-paste the error output straight into claude:
 2claude
 3> go test -race ./internal/usecase/order/... failed:
 4>
 5> --- FAIL: TestCancelOrderSuite/TestExecute_AtomicRollback (0.15s)
 6>     cancel_order_test.go:89: Error: expected nil, got:
 7>         cancelOrder.Execute: cancel with stock restore: context deadline exceeded
 8>
 9> Code:
10> @internal/usecase/order/cancel_order.go
11>
12> Analyze and fix.

 1claude
 2> A new feature needs coordination across 4 layers:
 3> 
 4> 1. Domain: add a ValidateForCancellation() method to the Order entity
 5> 2. Repository interface: add a CancelWithRestore(ctx, orderID) method
 6> 3. Usecase: implement CancelOrderUseCase using the new method
 7> 4. Handler: DELETE /orders/:id endpoint
 8>
 9> Implement in this order, verify the compile of each layer before continuing.
10> Don't skip verification — the CLAUDE.md architecture must be preserved.

1claude
2> Run this bash command first and paste the result:
3> grep -rn "return err$" internal/usecase/ --include="*.go" | grep -v "_test.go"
4
5[paste the grep output]
6
7> Update all these instances with proper error wrapping.
8> Format: fmt.Errorf("[package].[function]: %w", err)
9> Use the package and function name from the file context.

1claude
2> internal/usecase/order/cancel_order.go needs mocking for tests.
3> 
4> 1. Extract an OrderRepository interface from the struct the usecase uses
5>    (define the interface in the usecase package, not the repository package)
6> 2. Generate the mock using a go:generate directive
7> 3. Update the usecase constructor to inject the interface
8>
9> When done, show the go generate command to re-generate the mock.

 1# Strategy 1: Pick the model to match task complexity
 2
 3# Simple task (rename, add comment, simple function):
 4claude --model claude-haiku-4-5-20251001
 5# ~10x cheaper, enough for simple tasks
 6
 7# Medium task (implement a single usecase, write tests):
 8claude  # default claude-sonnet-4
 9
10# Very complex task (architecture decision, complex debugging):
11claude --model claude-opus-4
12# ~3x more expensive than sonnet, for tasks that truly need it
13
14# Strategy 2: Efficient prompting
15
16# INEFFICIENT — multiple small sessions:
17claude > Add error handling
18claude > Add a test
19claude > Add godoc
20# 3 sessions = 3x overhead
21
22# EFFICIENT — batch in one session:
23claude > Add error handling (wrap pattern from CLAUDE.md), 
24        a unit test (testify/suite), and a godoc comment 
25        for the ProcessOrder function
26
27# Strategy 3: Monitor usage
28claude --usage-stats
29# See token consumption per task type
30# Identify bottlenecks and optimize
31
32# Strategy 4: Use prompt caching
33# Claude automatically caches the CLAUDE.md content
34# Start a new session every 50+ exchanges to refresh the cache

 1# Step 1: Compile check
 2go build ./...
 3
 4# Step 2: Feed the error to Claude
 5claude
 6> Build error:
 7> ./internal/usecase/order/cancel_order.go:45:3:
 8>   undefined: domain.ErrOrderNotFound
 9> 
10> The domain package is in internal/domain/order/errors.go.
11> Import and use the existing one.
12
13# Step 3: If it's still wrong, check the import
14claude > Read internal/domain/order/errors.go and let me know
15        all the error types available.

1# Symptoms: float64 appears, errors not wrapped, etc.
2
3# Fix 1: Explicit reminder
4claude > Remember: CLAUDE.md rule #1: NEVER float64 for monetary.
5        Please fix the function you just made.
6
7# Fix 2: Start a new session with orientation
8claude  # new session
9> Read CLAUDE.md and confirm the 5 most important rules before we start.

1# Add to CLAUDE.md:
2## Code Style
3- Minimal comments: only explain WHY, never WHAT
4- No "// Implementation of X" comments
5- Function names should be self-documenting
6- Godoc only for exported functions that need explanation

1# This sometimes happens for legitimate security testing code
2
3claude > We're writing an integration test to verify SQL injection prevention.
4        This is an internal test to validate that the parameterized queries
5        we use in production are not vulnerable.
6        Implement this test case:
7        [describe what you need]

 1# A good pre-session setup:
 2alias claude-go='claude && go build ./... && go vet ./... && go test -race ./...'
 3
 4# Or make a script:
 5cat > scripts/ai-verify.sh << 'EOF'
 6#!/bin/bash
 7echo "=== Build Check ==="
 8go build ./... || exit 1
 9
10echo "=== Vet Check ==="
11go vet ./... || exit 1
12
13echo "=== Race Check ==="
14go test -race ./... || exit 1
15
16echo "=== Lint ==="
17golangci-lint run ./...
18
19echo "✅ All checks passed"
20EOF
21chmod +x scripts/ai-verify.sh
22
23# Run after every Claude Code session:
24./scripts/ai-verify.sh

 1# Update dependencies
 2claude
 3> go.mod shows pgx/v5 is v5.5.0 but the latest is v5.7.0.
 4> Update all pgx-related code to be compatible with v5.7.0.
 5> Check the changelog for breaking changes first.
 6
 7# Resolve a dependency conflict
 8claude
 9> go mod tidy produces:
10> [paste error]
11> Help resolve this.
12
13# Audit dependencies
14claude
15> Check go.sum and identify dependencies that might need updating
16> for security reasons based on your knowledge.

 1Metrics you can track:
 2
 31. Time per feature implementation
 4   Before AI: 4 hours average
 5   After AI: 2.5 hours average
 6   Improvement: 37.5%
 7
 82. PR review round trips
 9   Before: 2.3 round trips average
10   After: 1.4 round trips
11   Improvement: 39%
12
133. Test coverage
14   Before: 72% average
15   After: 88% average
16   Improvement: +16 percentage points
17
184. Error handling consistency
19   (via golangci-lint error handling rules)
20   Before: 8 violations per sprint
21   After: 1-2 violations per sprint
22
235. Time to onboard a new developer
24   Before: 2 weeks to first meaningful PR
25   After: 1 week
26   Improvement: 50%

1claude
2> Read CLAUDE.md and confirm you understand:
3> 1. Architecture rules
4> 2. Error handling pattern
5> 3. Monetary type rules

1# Experiment in a separate worktree without affecting the main working directory:
2git worktree add /tmp/experiment-cancel-order -b experiment/cancel-order
3cd /tmp/experiment-cancel-order
4claude > Try approach A for cancel order with the outbox pattern
5# If the approach is good: git cherry-pick or merge
6# If not: discard the worktree

1claude > Fix the bug on line 45 of cancel_order.go
2
3# Claude might not only fix the bug but also "refactor" other areas
4# Mitigation:
5claude > Fix ONLY the bug on line 45.
6        Don't change anything else.
7        If you see other improvements, just report them, don't implement them.

1# Less efficient:
2claude > [paste a 2000 line file]
3
4# More efficient:
5claude > The file order_repository.go has an issue in the GetByIDAndUserID implementation.
6        Relevant code (lines 145-180):
7        [paste only the relevant part]

1// Claude might generate:
2order.GetTotalWithTax()  // ← this method doesn't exist on your Order struct!
3
4// Prevention:
5// > Read entity.go first before implementing, so you know the existing methods.