gocode: Instructions file for Kiro

Code Quality & Review Standards — gocode

The Bar

Every change to this codebase should pass the "would a senior Go engineer at a top-tier company approve this in code review?" test. We optimize for:

• Readability over cleverness. Code is read 10x more than it's written.
• Correctness over speed-to-ship. Bugs in an agent that writes code are amplified.
• Simplicity over abstraction. Don't add a layer unless it pays for itself 3x.

Error Handling

// GOOD: wrap with context, use %w for the chain
if err != nil {
    return fmt.Errorf("connecting to provider %s: %w", name, err)
}

// BAD: naked error return
if err != nil {
    return err
}

// BAD: string formatting without %w
if err != nil {
    return fmt.Errorf("failed: %v", err)
}

• Every error should tell you WHERE it happened and WHY.
• Use errors.Is for sentinel errors, errors.As for typed errors.
• Never swallow errors silently. At minimum, log them.

Concurrency

// GOOD: bounded goroutines with context
ctx, cancel := context.WithTimeout(ctx, 12*time.Second)
defer cancel()

ch := make(chan result, len(sources))
for _, src := range sources {
    go func(s source) {
        ch <- s.fetch(ctx)
    }(src)
}

// GOOD: select with context cancellation
select {
case r := <-ch:
    // handle
case <-ctx.Done():
    return ctx.Err()
}

• Always pass context.Context as the first parameter.
• Always respect context cancellation in loops and goroutines.
• Buffered channels prevent goroutine leaks. Size them to the number of producers.
• Use sync.WaitGroup when you need to wait for all goroutines, channels when you need results.

Interface Design

// GOOD: small, focused interface
type Provider interface {
    SendMessage(ctx context.Context, req MessageRequest) (*MessageResponse, error)
    StreamMessage(ctx context.Context, req MessageRequest) (<-chan StreamEvent, error)
}

// BAD: kitchen-sink interface
type Provider interface {
    SendMessage(...)
    StreamMessage(...)
    ListModels(...)
    GetUsage(...)
    SetConfig(...)
    Validate(...)
}