go-dev-guidelines

Original：🇺🇸 English

Translated

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.

1installs

Sourcejumppad-labs/jumppad

Added on2026-02-07

NPX Install

npx skill4agent add jumppad-labs/jumppad go-dev-guidelines

SKILL.md Content

View Translation Comparison →

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:

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

New Go Service/Package Checklist

When creating a new Go service or package from scratch:

Setup project structure - Use standard Go layout (
```
/cmd
```
,
```
/internal
```
,
```
/pkg
```
)
Initialize module - Run
```
go mod init
```
with appropriate module path
Define core interfaces - Start with small, focused interfaces
Write tests first - Follow TDD approach for all business logic
Implement with DI - Use dependency injection for testability
Add logging - Include structured logging for observability
Configure graceful shutdown - Implement proper cleanup for services
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

go

// 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.