Golang Dependency Management

Go Dependency Management

Treat module changes as source and supply-chain changes. Keep them intentional, reviewable, and reproducible.

Inspect before changing modules

Read go.mod, go.sum, go.work, repository instructions, tool pinning, vendoring policy, and relevant imports. Record:

• module path, go and toolchain directives;
• direct and indirect requirements;
• replace, exclude, and retract implications;
• private-module configuration without printing credentials;
• whether generated code or build tags affect the dependency graph;
• the clean pre-change diff for module files.

Use the project's Go toolchain. Do not raise the go directive, change proxy policy, enable vendoring, or create a workspace merely to simplify a local command.

Decide whether a dependency is justified

Before adding a new module, compare:

1. standard-library and existing-project capabilities;
2. the exact API and transitive graph needed;
3. active maintenance, recent releases, issue posture, and ownership;
4. license compatibility and redistribution obligations;
5. security advisories and risky transitive dependencies;
6. supported Go versions, platforms, CGO, and operational cost;
7. replacement and exit cost if the package becomes unsuitable.

Use live evidence from pkg.go.dev, the canonical source repository, module releases, and the Go vulnerability database. Popularity alone is not evidence of fit. Do not add a dependency that is outside the user's requested implementation without first presenting the choice.

Make targeted changes

Prefer commands that name the intended module and version over repository-wide upgrades. After the code change:

• run go mod tidy with the intended build tags and toolchain assumptions;
• inspect both go.mod and go.sum rather than accepting churn blindly;
• verify why surprising dependencies remain with go mod why <package>, go mod why -m <module>, and go mod graph as appropriate;
• run the project's tests and static checks;
• keep go.sum committed unless the repository is intentionally not a module.

Do not assume patch or minor releases are risk-free. Review changelogs and compatibility for persistence, serialization, networking, authentication, authorization, cryptography, and public API dependencies.

For removal, delete usages first, tidy, and confirm the module is absent from the selected graph. Do not remove an indirect requirement manually when another package still needs it.

Module graph mechanics

Go selects versions across the module graph; a transitive requirement can raise the selected version. Diagnose conflicts from the graph before adding overrides.

• Use replace for a deliberate fork, local development target, or temporary upstream workaround. Document why and ensure a publishable module does not accidentally depend on a local path.
• Use exclude only for a specific unsuitable version with a clear reason.
• Use retract when maintaining a module and marking the maintainer's own released versions as unsuitable.
• Avoid long-lived overrides that silently diverge from upstream.

Major-version module paths and import paths must follow the selected module's published convention. Do not repair a mismatch by inventing a replace directive.

Tools, workspaces, and vendoring

Follow the mechanism supported by the module's declared Go version and existing repository policy for pinning developer tools. Do not globally install a tool merely because this skill mentions it. If introducing tool pinning is in scope, record the exact module version and invocation in project documentation or automation.

A go.work file is useful for coordinated local development across modules, but it changes resolution. Confirm whether it is a shared repository artifact or a developer-local file, and test each module independently when it must remain consumable outside the workspace.

Vendor only when the project's build or distribution requirements justify it. Regenerate vendor content after every relevant module change and verify the build actually uses it.

Vulnerability and provenance review

Use govulncheck when already available or when adding it is explicitly in scope. Interpret findings by affected symbol and reachable code; absence of a known advisory is not proof of safety. For private or forked modules, verify the scanned identity matches the code being built.

Also consider source provenance, checksums, vanity import resolution, and whether GOPRIVATE/GONOSUMDB settings are intentionally scoped. Never expose environment values or credentials while diagnosing module downloads.

Completion checklist

• The module change is necessary and narrowly scoped.
• The selected version and source are documented by current authoritative evidence.
• go.mod, go.sum, vendor, workspace, and generated files agree.
• Temporary replace or exclude directives have reasons and removal criteria.
• The intended toolchain and supported platforms still work.
• Tests and relevant vulnerability checks pass.
• The final diff contains no unrelated upgrades or private paths.