golang-project-layout

Place all main packages under cmd/{name}/ with minimal logic, put private code in internal/, and use pkg/ only for code intended for external consumers. Add a Makefile, .gitignore, and .golangci.yml at the root, and right-size the structure to the project's actual scope.

The internal/ directory holds private code that Go's compiler prevents external modules from importing. The pkg/ directory is for public libraries genuinely useful to external consumers; default to internal/ for service and business logic.

Use go.work when developing multiple related Go modules that import each other, such as a monorepo with separate modules. Do not use workspaces for single-module projects, even ones with many packages.

Each main package belongs in its own subdirectory under cmd/, such as cmd/server/main.go. The main.go should only parse flags, wire dependencies, and call Run(); business logic belongs in internal/ or pkg/.

No. Sensitive values like database passwords, API keys, and JWT secrets must come from environment variables or a secret manager, never config files. Config files are acceptable only for non-sensitive values like ports and log levels.

Co-locate _test.go files in the same directory as the code they test, using either the same package for white-box tests or a _test package suffix for black-box tests. Use a testdata/ directory for fixtures, which Go ignores during builds.