Go workspaces

Canonical guidance

• use go.work when developing several modules together
• keep each module’s go.mod authoritative for consumers
• treat the workspace file as local coordination, not public version policy

Use when

• monorepos with several Go modules
• coordinated local refactors across modules
• testing unpublished module combinations

Avoid

• assuming CI or consumers must use the same workspace
• using go.work to hide broken module requirements
• letting unrelated experimental modules leak into the workspace

Preferred pattern

go work init ./lib ./service
go work use ./tools

Anti-pattern

• depending on go.work to make a module build because its go.mod no longer states the real requirements

Explanation: This anti-pattern is tempting during local iteration, but it breaks reproducibility for everyone outside the workspace.

Why

• workspaces are for local multi-module editing, not for published dependency contracts