Golang Project Layout

Persona: You are a Go project architect. You right-size structure to the problem — a script stays flat, a service gets layers only when justified by actual complexity.

Go Project Layout

Architecture Decision: Ask First

When starting a new project, ask the developer what software architecture they prefer (clean architecture, hexagonal, DDD, flat structure, etc.). NEVER over-structure small projects — a 100-line CLI tool does not need layers of abstractions or dependency injection.

→ See samber/cc-skills-golang@golang-design-patterns skill for detailed architecture guides with file trees and code examples.

Dependency Injection: Ask Next

After settling on the architecture, ask the developer which dependency injection approach they want: manual constructor injection, or a DI library (samber/do, google/wire, uber-go/dig+fx), or none at all. The choice affects how services are wired, how lifecycle (health checks, graceful shutdown) is managed, and how the project is structured. See the samber/cc-skills-golang@golang-dependency-injection skill for a full comparison and decision table.

12-Factor App

For applications (services, APIs, workers), follow 12-Factor App conventions: config via environment variables, logs to stdout, stateless processes, graceful shutdown, backing services as attached resources, and admin tasks as one-off commands (e.g., cmd/migrate/).

Quick Start: Choose Your Project Type

Module Naming Conventions

Module Name (go.mod)

Your module path in go.mod should:

• MUST match your repository URL: github.com/username/project-name
• Use lowercase only: github.com/you/my-app (not MyApp)
• Use hyphens for multi-word: user-auth not user_auth or userAuth
• Be semantic: Name should clearly express purpose

Examples:

// ✅ Good
module github.com/jdoe/payment-processor
module github.com/company/cli-tool

// ❌ Bad
module myproject
module github.com/jdoe/MyProject
module utils

Package Naming

Packages MUST be lowercase, singular, and match their directory name. → See samber/cc-skills-golang@golang-naming skill for complete package naming conventions and examples.

Directory Layout

All main packages must reside in cmd/ with minimal logic — parse flags, wire dependencies, call Run(). Business logic belongs in internal/ or pkg/. Use internal/ for non-exported packages, pkg/ only when code is useful to external consumers.

See directory layout examples for universal, small project, and library layouts, plus common mistakes.

Essential Configuration Files

Every Go project should include at the root:

• Makefile — build automation. See Makefile template
• .gitignore — git ignore patterns. See .gitignore template
• .golangci.yml — linter config. See the samber/cc-skills-golang@golang-lint skill for the recommended configuration

For application configuration with Cobra + Viper, see config reference.

Tests, Benchmarks, and Examples

Co-locate _test.go files with the code they test. Use testdata/ for fixtures. See testing layout for file naming, placement, and organization details.

Go Workspaces

Use go.work when developing multiple related modules in a monorepo. See workspaces for setup, structure, and commands.

Initialization Checklist

When starting a new Go project:

• [ ] Ask the developer their preferred software architecture (clean, hexagonal, DDD, flat, etc.)
• [ ] Ask the developer their preferred DI approach — see samber/cc-skills-golang@golang-dependency-injection skill
• [ ] Decide project type (CLI, library, service, monorepo)
• [ ] Right-size the structure to the project scope
• [ ] Choose module name (matches repo URL, lowercase, hyphens)
• [ ] Run go version to detect the current go version
• [ ] Run go mod init github.com/user/project-name
• [ ] Create cmd/{name}/main.go for entry point
• [ ] Create internal/ for private code
• [ ] Create pkg/ only if you have public libraries
• [ ] For monorepos: Initialize go work and add modules
• [ ] Run gofmt -s -w . to ensure formatting
• [ ] Add .gitignore with /vendor/ and binary patterns

Related Skills

→ See samber/cc-skills-golang@golang-cli skill for CLI tool structure and Cobra/Viper patterns. → See samber/cc-skills-golang@golang-dependency-injection skill for DI approach comparison and wiring. → See samber/cc-skills-golang@golang-lint skill for golangci-lint configuration. → See samber/cc-skills-golang@golang-continuous-integration skill for CI/CD pipeline setup. → See samber/cc-skills-golang@golang-design-patterns skill for architectural patterns.

Application Configuration with Cobra + Viper

→ See samber/cc-skills-golang@golang-cli skill for complete Cobra+Viper setup, flag binding, precedence rules, and configuration layering.

Where Config Lives

myapp/
├── cmd/myapp/
│   ├── main.go                # Entry point
│   ├── root.go                # Root command + Viper init
│   ├── serve.go               # Subcommand with flags
│   └── config.go              # Config struct + loader
└── configs/
    └── config.yaml            # Default config file

Config Struct

Define configuration as a struct with mapstructure tags matching your YAML keys:

// cmd/myapp/config.go
package main

import (
    "fmt"

    "github.com/spf13/viper"
)

type Config struct {
    Port     int    `mapstructure:"port"`
    Host     string `mapstructure:"host"`
    LogLevel string `mapstructure:"log-level"`
    Database struct {
        DSN     string `mapstructure:"dsn"`
        MaxConn int    `mapstructure:"max-conn"`
    } `mapstructure:"database"`
}

func loadConfig() (Config, error) {
    var cfg Config
    if err := viper.Unmarshal(&cfg); err != nil {
        return Config{}, fmt.Errorf("unmarshaling config: %w", err)
    }
    return cfg, nil
}

Configuration MUST be loaded from env vars, files, or flags — NEVER hardcoded. Sensitive values MUST come from env vars or secret managers, NEVER config files.

Directory Layouts

Universal Layout (Most Projects)

project/
├── cmd/                    # Entry points - ONE subdirectory per main package
│   ├── server/            # Main application #1
│   │   └── main.go
│   ├── client/            # Main application #2
│   │   └── main.go
│   └── migrate/           # Main application #3
│       └── main.go
│   └── cli/               # Main application #4
│       └── main.go
│   └── worker/            # Main application #5
│       └── main.go
├── internal/              # Private application code (`internal/` MUST be used for non-exported packages)
│   ├── app/              # Application initialization
│   ├── config/           # Configuration loading
│   ├── handler/          # HTTP/request handlers
│   ├── model/            # Data models/domain
│   └── service/          # Business logic
├── pkg/                   # Public libraries (optional - only if useful to others)
│   └── logger/
│       └── logger.go
├── api/                   # API definitions (optional)
│   └── openapi.yaml
├── configs/               # Configuration files (optional)
│   └── config.yaml
├── scripts/               # Build/deployment scripts (optional)
├── go.mod
├── go.sum
├── Makefile               # Build automation
├── .gitignore             # Git ignore patterns
├── .golangci.yml          # Linter configuration
├── LICENSE                # License file
└── README.md

Small Projects (Single Binary)

For simple tools, keep it minimal:

my-tool/
├── cmd/
│   └── my-tool/
│       └── main.go        # Single main package
├── internal/
│   └── core.go            # Application logic
├── go.mod
├── Makefile               # Build automation (optional but recommended)
├── .gitignore             # Git ignore patterns
├── .golangci.yml          # Linter configuration (optional)
├── LICENSE                # License file (recommended)
└── README.md

Libraries (Reusable Code)

my-library/
├── example/               # Example
├── logger/                # Public package
│   ├── logger.go
│   └── logger_test.go
├── internal/
│   └── impl/              # Private implementation details
│       └── core.go
├── go.mod
├── go.sum
├── Makefile               # Build automation
├── .gitignore             # Git ignore patterns
├── .golangci.yml          # Linter configuration
├── LICENSE                # License file
└── README.md

Key points for libraries:

• Put public API in root-level directories (e.g., logger/)
• Use internal/ for private implementation
• Don't use cmd/ (unless you have example binaries)

The cmd/ Directory Convention

CRITICAL: All main packages must reside in cmd/. cmd/ MUST contain only main.go with minimal logic — parse flags, wire dependencies, call Run(). NEVER put business logic in cmd/ — it belongs in internal/ or pkg/.

Single Application

cmd/
└── myapp/
    └── main.go    // package main

Multiple Applications

When you need multiple binaries (e.g., server, CLI tool, migration utility):

cmd/
├── server/
│   └── main.go        // Runs the API server
├── client/
│   └── main.go        // CLI client tool
├── worker/
│   └── main.go        // Background worker
└── migrate/
    └── main.go        // Database migration utility

Each main.go:

• Declares package main
• Has its own func main()
• Can be built independently: go build ./cmd/...

Building all binaries:

go build ./cmd/...        # Build all main packages
go build ./cmd/server     # Build specific binary

Common Mistakes to Avoid

Don't Do This

myproject/
├── src/              # Go doesn't use /src (Java pattern)
├── main.go           # Don't put main at root
├── utils/            # Generic package name
├── helpers/          # Generic package name
└── common/           # Generic package name

Do This Instead

myproject/
├── cmd/
│   └── myapp/
│       └── main.go   # Main in cmd/
├── internal/
│   ├── util/         # Specific utility names
│   └── format/       # Or domain-specific names
└── pkg/              # Only if useful to others

Tests, Benchmarks, and Examples

File Naming Conventions

Go uses suffix-based naming for test-related files:

Where to Place Tests

Co-locate tests with the code they test:

internal/
├── handler/
│   ├── handler.go          # Production code
│   ├── handler_test.go     # Tests for handler
│   └── handler_bench_test.go  # Benchmarks (optional)
├── service/
│   ├── service.go
│   └── service_test.go
└── model/
    ├── user.go
    └── user_test.go

pkg/
└── logger/
    ├── logger.go
    └── logger_test.go

Key principles:

• Tests live in the same package as the code (e.g., package handler)
• Test files are in the same directory as the code they test
• Use _test.go suffix for all test files

Test Package Options

When writing tests, you have two options for the package declaration:

Option 1: Same package (white-box testing)

package handler  // Same package, can access unexported

import "testing"

func TestHandler(t *testing.T) {
    // Can access unexported functions and types
    internalFunction()
}

Option 2: Package with `_test` suffix (black-box testing)

package handler_test  // Different package, only exported API

import "testing"

func TestHandler(t *testing.T) {
    // Can only access exported functions and types
    handler.PublicMethod()
}

When to use each:

• Use same package for unit tests that need to test internals
• Use `_test` suffix for integration/behavioral tests

Benchmarks

Benchmarks use the _bench_test.go suffix and contain functions with the Benchmark prefix.

Examples

Examples serve two purposes: documentation and verification.

In libraries - use *_example_test.go files:

pkg/
└── logger/
    ├── logger.go
    ├── logger_test.go
    └── logger_example_test.go     # Examples

Example function format:

package logger

import "fmt"

func ExampleLogger_Info() {
    log := New()
    log.Info("processing started")
    log.Info("processing complete")
    // Output:
    // INFO: processing started
    // INFO: processing complete
}

Key points:

• Example functions must start with Example
• The // Output: comment verifies the output
• Examples are runnable tests: go test will fail if output doesn't match
• godoc displays examples as documentation
• File name format: {package}_example_test.go (e.g., logger_example_test.go)

For executable examples (standalone demo programs):

examples/
└── basic-usage/
    └── main.go                    # Executable example

Test Utilities

When you have shared test helpers, use a dedicated package:

test/
└── testutils/
    ├── mock.go
    └── fixtures.go

Or use the internal/testutil pattern:

internal/
└── testutil/
    ├── mock.go
    └── fixtures.go

Test Fixtures

Fixtures are test data files used across multiple tests. Use one of these patterns:

Option 1: Local testdata directory (package-specific fixtures)

internal/
└── handler/
    ├── handler.go
    ├── handler_test.go
    └── testdata/
        ├── users.json
        ├── request_valid.json
        └── request_invalid.json

Option 2: Global test directory (shared across packages)

test/
└── fixtures/
    ├── users.json
    ├── products.json
    └── responses/
        ├── success.json
        └── error.json

Option 3: Embedded fixtures (Go 1.16+, use //go:embed)

internal/
└── handler/
    ├── handler.go
    ├── handler_test.go
    └── testdata/
        └── users.json

Important notes:

• Go ignores the testdata directory when building regular packages
• Use testdata/ for package-specific test data
• Use test/fixtures/ for cross-package shared fixtures
• Don't put .go files in testdata/ - they will be ignored

Running Tests

go test ./...                    # Run all tests
go test ./internal/handler       # Test specific package
go test -v ./...                 # Verbose output
go test -race ./...              # Race detection
go test -cover ./...             # Coverage report
go test -short ./...             # Skip long-running tests

Test File Summary

<!-- markdownlint-disable ol-prefix -->

Go Workspaces for Multi-Package Repositories

When to Use Workspaces

Use Go workspaces (go.work) when:

• Developing multiple related modules that import each other
• Building a monorepo with separate Go modules
• Testing local changes across module boundaries
• Avoiding replace directives in every module

Don't use workspaces for:

• Single-module projects
• Projects that only use external dependencies
• Simple applications

Workspace Structure

Example monorepo with multiple modules:

my-monorepo/
├── go.work                    # Workspace file (see below)
├── pkg/
│   ├── auth/                 # Module 1: github.com/user/my-monorepo/pkg/auth
│   │   ├── go.mod
│   │   ├── cmd/
│   │   │   └── auth-server/
│   │   │       └── main.go
│   │   └── internal/
│   │       └── handler/
│   │           └── auth.go
│   └── user/                 # Module 2: github.com/user/my-monorepo/pkg/user
│       ├── go.mod
│       ├── cmd/
│       │   └── user-server/
│       │       └── main.go
│       └── internal/
│           └── handler/
│               └── user.go
├── cmd/
│   └── api/                 # Module 3: github.com/user/my-monorepo/cmd/api
│       ├── go.mod
│       └── main.go
└── tools/
    └── cli/                  # Module 4: github.com/user/my-monorepo/tools/cli
        ├── go.mod
        └── cmd/
            └── mycli/
                └── main.go

Creating a Workspace

1. Initialize the workspace:

go work init

This creates go.work:

go 1.21

use (
    ./services/auth
    ./services/user
    ./shared/libs
    ./tools/cli
)

2. Add modules to workspace:

go work use ./services/auth
go work use ./services/user
go work use ./shared/libs

3. Use modules without replace directives:

In services/user/go.mod:

module github.com/user/my-monorepo/services/user

go 1.21

require github.com/user/my-monorepo/shared/libs v0.0.0

The workspace automatically resolves shared/libs to the local directory.

Workspace Commands

go work init              # Initialize new workspace
go work use ./path/to/mod # Add module to workspace
go work use -rm ./path    # Remove module from workspace
go work sync              # Sync workspace with module changes