---

name: golang-backend description: Go backend development best practices and performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring Go backend code including APIs, services, concurrent systems, and database interactions. Triggers on tasks involving Go handlers, middleware, goroutines, channels, error handling, or performance improvements. license: MIT metadata: author: freepeak version: "1.0.0"

Go Backend Best Practices

Comprehensive best practices guide for Go backend development, optimized for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Go services, APIs, or handlers
• Implementing concurrent patterns with goroutines and channels
• Reviewing code for performance issues or bugs
• Refactoring existing Go backend code
• Optimizing database queries and connections
• Implementing error handling and logging
• Writing tests for Go code

Rule Categories by Priority

Quick Reference

1. Error Handling (CRITICAL)

• error-wrap-context - Wrap errors with context using fmt.Errorf %w
• error-check-always - Never ignore returned errors
• error-sentinel - Use sentinel errors for expected conditions
• error-custom-types - Define custom error types for complex errors
• error-early-return - Return early on errors, avoid deep nesting

2. Concurrency Safety (CRITICAL)

• concurrency-goroutine-leak - Prevent goroutine leaks with context cancellation
• concurrency-race-condition - Protect shared state with mutex or channels
• concurrency-channel-close - Only sender should close channels
• concurrency-waitgroup - Use WaitGroup for goroutine synchronization
• concurrency-context-propagation - Propagate context through call chain

3. Performance (HIGH)

• perf-preallocate-slices - Preallocate slices when size is known
• perf-string-builder - Use strings.Builder for string concatenation
• perf-sync-pool - Use sync.Pool for frequently allocated objects
• perf-avoid-reflection - Avoid reflection in hot paths
• perf-buffer-channels - Use buffered channels appropriately

4. API Design (HIGH)

• api-accept-interfaces - Accept interfaces, return concrete types
• api-functional-options - Use functional options for configuration
• api-context-first - Context should be first parameter
• api-naming-conventions - Follow Go naming conventions
• api-package-design - Design packages by responsibility

5. Database Patterns (MEDIUM-HIGH)

• db-connection-pool - Configure connection pool properly
• db-prepared-statements - Use prepared statements for repeated queries
• db-transaction-scope - Keep transactions short and focused
• db-scan-struct - Use struct scanning for type safety
• db-context-timeout - Always use context with timeouts for queries

6. Testing (MEDIUM)

• test-table-driven - Use table-driven tests
• test-parallel - Run independent tests in parallel
• test-mock-interfaces - Mock at interface boundaries
• test-golden-files - Use golden files for complex outputs
• test-cleanup - Use t.Cleanup for test resource cleanup

7. Security (CRITICAL)

• security-sql-injection - Use parameterized queries
• security-input-validation - Validate and sanitize all inputs
• security-secrets-env - Load secrets from environment
• security-rate-limiting - Implement rate limiting for APIs
• security-timeout-config - Configure timeouts for all operations

8. Code Organization (LOW-MEDIUM)

• org-flat-structure - Prefer flat package structure
• org-internal-packages - Use internal packages for private code
• org-dependency-injection - Use dependency injection for testability
• org-config-struct - Group configuration in typed structs
• org-graceful-shutdown - Implement graceful shutdown

How to Use

Read individual rule files for detailed explanations and code examples:

Copyrules/error-wrap-context.md
rules/concurrency-goroutine-leak.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md