go-project-layout
Guide for setting up Golang project layouts and workspaces. Covers CLI tools, libraries, services, and monorepos.
SKILL.mdskills/go/go-project-layout/SKILL.md
GitHubDirectory Structure Best Practices
- cmd/ — Entry points (main packages). Each binary gets its own subdirectory:
cmd/myapp/main.go. - internal/ — Private library code. Code in this directory cannot be imported by other projects. This is where most business logic should live.
- pkg/ — Public library code. Only use this if you want others to import these packages.
- api/ — OpenAPI/Swagger specs, JSON schema files, protocol definition files.
- web/ — Web static assets, server-side templates, SPAs.
- configs/ — Configuration file templates or default configs.
- init/ — System init (systemd, upstart) and process manager (runit, supervisord) configs.
- scripts/ — Scripts for build, install, analysis, etc.
- build/ — Packaging and Continuous Integration.
- test/ — Additional external test apps and test data.
- docs/ — Design and user documents.
Project Types
| Project Type | Key Directories |
|---|---|
| CLI Tool | cmd/{name}/, internal/, optional pkg/ |
| Library | pkg/{name}/, internal/ |
| Service (API) | cmd/{service}/, internal/, api/ |
| Monorepo | go.work, separate modules in subdirectories |
Module Naming (go.mod)
- Must match repository URL:
github.com/username/project-name. - Lowercase only:
github.com/user/my-app. - Hyphens for multi-word:
payment-processor.
Package Naming
- Lowercase and singular:
user,auth,http. - Match directory name.
- Avoid "util" or "common" — Be specific (e.g.,
jsonutil,stringset).
Checklist for New Projects
- Run
go mod init github.com/user/repo. - Create
cmd/app-name/main.go. - Create
internal/for business logic. - Add
.gitignore(ignoring binaries and vendor if not used). - Add
golangci-lintconfiguration. - Initialize
gitand make initial commit.
Anti-patterns
- ❌ Massive
main.go— Keepmainsmall, only for wiring and flag parsing. - ❌ Circular dependencies — Result of poor package boundaries.
- ❌ Deeply nested packages — Go prefers a flatter structure.
- ❌ Using
pkg/for everything — Most code should be ininternal/. - ❌ Generic package names —
logic,models,interfacesare too vague.