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

| 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](references/directory-layouts.md) 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](assets/Makefile)
• .gitignore — git ignore patterns. See [.gitignore template](assets/.gitignore)
• .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](references/config.md).

Tests, Benchmarks, and Examples

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

Go Workspaces

Use go.work when developing multiple related modules in a monorepo. See [workspaces](references/workspaces.md) 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samber
• Source: samber/cc-skills-golang
• License: MIT
• Homepage: https://skills.sh/samber/cc-skills-golang

Install and usage instructions live in the source repository linked above.