golang-project-layout

To structure a Golang project effectively, match the directory layout to your project's size and goals, applying right-sized guidelines for CLI tools, libraries, services, or monorepos to prevent over-engineering.

The best way to organize multiple main packages is by using the cmd/ directory layout, placing each executable in its own subdirectory to maintain clear entry points and simplify build management.

You need to use go.work for a multi-module Go setup when managing a monorepo with interdependent modules, allowing local development workflows to resolve module dependencies without pushing changes.

A Go project layout often needs dependency injection and 12-factor considerations for services to cleanly separate configuration, environment variables, and internal dependencies from the core business logic.

You can use the internal/ directory to restrict package visibility and pkg/ for public reusable code, applying both to Go libraries and CLI tools to enforce proper encapsulation and dependency boundaries.

You should co-locate tests with source code in a Go project directory structure to maintain proximity between implementation and test files, simplifying navigation and ensuring cohesive module testing practices.