Standard Go Project Layout

What it is

Standard Go Project Layout is a repository with an example Go project structure. It became popular because Go itself keeps directory rules light, while teams still need shared language for commands, internal code, public packages, and deployment files.

Its status matters: it is not a Go specification and not a compiler requirement. It is a set of practices for discussing structure before a repository grows messy.

What is inside

The repository explains directories such as cmd, internal, pkg, api, web, configs, scripts, deployments, and test. Each directory has a short explanation and notes on when it may be unnecessary.

The point is not to copy the whole tree. A good use is to keep only the parts that match the real product.

How it is used

Teams use it as a starting point for Go services, especially when a project is expected to grow beyond its first few months. It helps agree where executable commands, domain code, helper scripts, and environment files belong.

For a tiny utility, this layout can be too much. If the whole project fits in a few files, starting smaller is usually better.

Strengths and limits

The strength is a clear map for architecture conversations. It reduces chaos when several developers add packages and commands at the same time.

The limitation is cargo-cult copying. Empty directories do not make a project mature; in Go, structure should stay short until code needs stronger boundaries.

A good way to use this repository is to start with responsibility boundaries. If internal separates application code from public packages, it helps. If pkg exists only because the example has it, the structure starts getting in the way.

In Go, it is easy to add architecture too early. This layout is more useful as a menu of options than as a fixed instruction. It helps a team name things, but the final structure should follow the real code.

Example

myservice/
  cmd/api/main.go
  internal/orders/service.go
  internal/http/routes.go
  configs/local.yaml
  go.mod