---

name: go-dev-guidelines description: This skill should be used when writing, refactoring, or testing Go code. It provides idiomatic Go development patterns, TDD-based workflows, project structure conventions, and testing best practices using testify/require and mockery. Activate this skill when creating new Go features, services, packages, tests, or when setting up new Go projects.

Go Development Guidelines

Overview

This skill provides comprehensive guidelines for idiomatic Go development with a Test-Driven Development (TDD) approach. Follow these patterns when writing Go code, creating tests, organizing projects, or refactoring existing code.

Quick Start Checklists

New Go Feature Checklist

When implementing a new feature in an existing Go project:

1. Define interface - Create small, focused interface in appropriate package
2. Write tests first - Create *_test.go file with testify/require tests
3. Generate mocks - Use mockery to generate mocks in mocks/ subfolder
4. Implement logic - Write the implementation to satisfy tests
5. Handle errors - Ensure all errors are explicitly handled
6. Add integration tests - Test the feature end-to-end if applicable
7. Run go vet & gofmt - Ensure code meets Go standards
8. Update documentation - Add godoc comments for exported types/functions

New Go Service/Package Checklist

When creating a new Go service or package from scratch:

1. Setup project structure - Use standard Go layout (/cmd, /internal, /pkg)
2. Initialize module - Run go mod init with appropriate module path
3. Define core interfaces - Start with small, focused interfaces
4. Write tests first - Follow TDD approach for all business logic
5. Implement with DI - Use dependency injection for testability
6. Add logging - Include structured logging for observability
7. Configure graceful shutdown - Implement proper cleanup for services
8. Document package - Add package-level godoc and README

Core Principles

Follow these seven core principles for all Go development:

1. Follow Test-Driven Development (TDD)

Write tests before implementation. Tests should be easy to read and favor verbosity over abstraction.

2. Use testify/require for Unit Tests

All unit tests must use github.com/stretchr/testify/require for assertions.

3. Use Mockery for Mocks

Generate mocks using mockery. Mocks must be localized in a mocks/ subfolder next to the interface being mocked.

4. Never Use Table-Driven Tests

Avoid table-driven tests. Write explicit test functions for each scenario.

5. Never Mix Positive and Negative Tests

Keep positive (success) and negative (error) test cases in separate test functions.

6. Handle All Errors Explicitly

Never ignore errors. Always handle them explicitly or return them to the caller.

7. Prefer Small, Focused Interfaces

Design interfaces with few methods. Use composition over large interfaces.

8. Use any Instead of interface{}

For generic types, prefer any over interface{} (Go 1.18+).

Standard Go Directory Structure

project-root/
├── cmd/                  # Main applications
│   └── myapp/
│       └── main.go
├── internal/             # Private application code
│   ├── handler/          # HTTP handlers
│   │   ├── handler.go
│   │   ├── handler_test.go
│   │   └── mocks/        # Mocks for handler interfaces
│   ├── service/          # Business logic
│   │   ├── service.go
│   │   ├── service_test.go
│   │   └── mocks/
│   └── repository/       # Data access
│       ├── repository.go
│       ├── repository_test.go
│       └── mocks/
├── pkg/                  # Public library code
│   └── client/
│       ├── client.go
│       ├── client_test.go
│       └── mocks/
├── api/                  # API definitions (OpenAPI, protobuf)
├── configs/              # Configuration files
├── go.mod
├── go.sum
└── README.md

Quick Reference

Common Test Patterns

// Unit test with mock
func TestServiceCreate(t *testing.T) {
    mockRepo := mocks.NewRepository(t)
    mockRepo.On("Save", mock.Anything).Return(nil)

    svc := NewService(mockRepo)
    err := svc.Create(context.Background(), data)

    require.NoError(t, err)
    mockRepo.AssertExpectations(t)
}

// Separate negative test
func TestServiceCreate_RepoError(t *testing.T) {
    mockRepo := mocks.NewRepository(t)
    mockRepo.On("Save", mock.Anything).Return(errors.New("db error"))

    svc := NewService(mockRepo)
    err := svc.Create(context.Background(), data)

    require.Error(t, err)
    require.Contains(t, err.Error(), "db error")
}

Naming Conventions

• Packages: Short, lowercase, no underscores (handler, service)
• Files: Lowercase with underscores (user_service.go, user_service_test.go)
• Types: PascalCase (UserService, HTTPHandler)
• Functions/Methods: PascalCase for exported, camelCase for unexported
• Interfaces: Often end with -er suffix (Reader, Writer, UserRepository)

Navigation Table

Use this table to find detailed guidance for specific tasks:

If You Need To...	See This Resource
Set up a new Go project structure	Project Structure
Understand Go naming conventions	Naming Conventions
Write tests with TDD, testify/require, and mockery	Testing Guide
Organize packages, interfaces, and dependencies	Code Organization
Handle errors idiomatically	Error Handling
Work with goroutines, channels, and context	Concurrency Patterns
Manage dependencies and go.mod	Dependencies
See complete working examples	Complete Examples

Resources

This skill includes detailed reference documentation in the references/ directory. Claude will load these resources as needed when working on specific tasks.