# Golang Rules > Comprehensive Go coding rules covering style, patterns, testing, and security Use when this capability is needed. - Skill: `tomevault-io/golang-rules` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/golang-rules` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/golang-rules/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/golang-rules --- # Go Coding Rules ## Coding Style ### Immutability (CRITICAL) ALWAYS create new objects, NEVER mutate existing ones: ``` // Pseudocode WRONG: modify(original, field, value) -> changes original in-place CORRECT: update(original, field, value) -> returns new copy with change ``` Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency. ### File Organization MANY SMALL FILES > FEW LARGE FILES: - High cohesion, low coupling - 200-400 lines typical, 800 max - Extract utilities from large modules - Organize by feature/domain, not by type ### Formatting - **gofmt** and **goimports** are mandatory -- no style debates ### Design Principles - Accept interfaces, return structs - Keep interfaces small (1-3 methods) ### Error Handling ALWAYS handle errors comprehensively: - Handle errors explicitly at every level - Provide user-friendly error messages in UI-facing code - Log detailed error context on the server side - Never silently swallow errors Always wrap errors with context: ```go if err != nil { return fmt.Errorf("failed to create user: %w", err) } ``` ### Input Validation ALWAYS validate at system boundaries: - Validate all user input before processing - Use schema-based validation where available - Fail fast with clear error messages - Never trust external data (API responses, user input, file content) ### Code Quality Checklist Before marking work complete: - [ ] Code is readable and well-named - [ ] Functions are small (<50 lines) - [ ] Files are focused (<800 lines) - [ ] No deep nesting (>4 levels) - [ ] Proper error handling - [ ] No hardcoded values (use constants or config) - [ ] No mutation (immutable patterns used) ## Patterns ### Skeleton Projects When implementing new functionality: 1. Search for battle-tested skeleton projects 2. Evaluate options for security, extensibility, relevance 3. Clone best match as foundation 4. Iterate within proven structure ### Repository Pattern Encapsulate data access behind a consistent interface: - Define standard operations: findAll, findById, create, update, delete - Concrete implementations handle storage details (database, API, file, etc.) - Business logic depends on the abstract interface, not the storage mechanism - Enables easy swapping of data sources and simplifies testing with mocks ### API Response Format Use a consistent envelope for all API responses: - Include a success/status indicator - Include the data payload (nullable on error) - Include an error message field (nullable on success) - Include metadata for paginated responses (total, page, limit) ### Functional Options ```go type Option func(*Server) func WithPort(port int) Option { return func(s *Server) { s.port = port } } func NewServer(opts ...Option) *Server { s := &Server{port: 8080} for _, opt := range opts { opt(s) } return s } ``` ### Small Interfaces Define interfaces where they are used, not where they are implemented. ### Dependency Injection Use constructor functions to inject dependencies: ```go func NewUserService(repo UserRepository, logger Logger) *UserService { return &UserService{repo: repo, logger: logger} } ``` ## Testing ### Minimum Test Coverage: 80% Test Types (ALL required): 1. **Unit Tests** - Individual functions, utilities, components 2. **Integration Tests** - API endpoints, database operations 3. **E2E Tests** - Critical user flows ### Test-Driven Development MANDATORY workflow: 1. Write test first (RED) 2. Run test - it should FAIL 3. Write minimal implementation (GREEN) 4. Run test - it should PASS 5. Refactor (IMPROVE) 6. Verify coverage (80%+) ### Troubleshooting Test Failures 1. Check test isolation 2. Verify mocks are correct 3. Fix implementation, not tests (unless tests are wrong) ### Framework Use the standard `go test` with **table-driven tests**. ### Race Detection Always run with the `-race` flag: ```bash go test -race ./... ``` ### Coverage ```bash go test -cover ./... ``` ## Security ### Mandatory Security Checks Before ANY commit: - [ ] No hardcoded secrets (API keys, passwords, tokens) - [ ] All user inputs validated - [ ] SQL injection prevention (parameterized queries) - [ ] XSS prevention (sanitized HTML) - [ ] CSRF protection enabled - [ ] Authentication/authorization verified - [ ] Rate limiting on all endpoints - [ ] Error messages don't leak sensitive data ### Secret Management - NEVER hardcode secrets in source code - ALWAYS use environment variables or a secret manager - Validate that required secrets are present at startup - Rotate any secrets that may have been exposed ```go apiKey := os.Getenv("OPENAI_API_KEY") if apiKey == "" { log.Fatal("OPENAI_API_KEY not configured") } ``` ### Security Scanning - Use **gosec** for static security analysis: ```bash gosec ./... ``` ### Context & Timeouts Always use `context.Context` for timeout control: ```go ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel() ``` ### Security Response Protocol If security issue found: 1. STOP immediately 2. Fix CRITICAL issues before continuing 3. Rotate any exposed secrets 4. Review entire codebase for similar issues --- > Source: [Luohaothu/everything-codex](https://github.com/Luohaothu/everything-codex) — distributed by [TomeVault](https://tomevault.io).