# Golang Project Layout

Golang project layout and workspace setup, cmd/internal/pkg directory conventions...

- Repository: https://github.com/samber/cc-skills-golang (3750 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add samber/cc-skills-golang --skill golang-project-layout -g -a claude-code -y`
Codex: `npx skills add samber/cc-skills-golang --skill golang-project-layout -g -a codex -y`
Cursor: `npx skills add samber/cc-skills-golang --skill golang-project-layout -g -a cursor -y`
Gemini CLI: `npx skills add samber/cc-skills-golang --skill golang-project-layout -g -a gemini-cli -y`

## Description

Golang project layout and workspace setup, cmd/internal/pkg directory conventions, module and package naming, go.work workspaces, and essential configuration files. Use when starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, or discussing package restructuring, package splits, or module splits. Not for restructuring existing code without a layout change (→ See `samber/cc-skills-golang@golang-refactoring` skill).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

**Questions:** Ask the user through the environment's question tool, never as plain-text prose. Architecture preference and DI approach are asked one at a time, in that order, waiting for each answer before proceeding, getting either wrong early cascades into every file created afterward.

# 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.). Avoid over-structuring 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](https://12factor.net/) 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

The rest: https://github.com/samber/cc-skills-golang/blob/HEAD/skills/golang-project-layout/SKILL.md