golang-project-layout

$27

Project Type

Use When

Key Directories

CLI Tool

Building a command-line application

cmd/{name}/, internal/, optional pkg/

Library

Creating reusable code for others

pkg/{name}/, internal/ for private code

Service

HTTP API, microservice, or web app

cmd/{service}/, internal/, api/, web/

Monorepo

Multiple related packages/modules

go.work, separate modules per package

Workspace

Developing multiple local modules

go.work, replace directives

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.