Dependency notes for Go

go.mod records which modules a build requires and at which version. It does not record why a module was chosen, which of its APIs the code is built around, or what to run before moving it — and go get -u ./... moves everything at once.

Pacmon keeps a note for each module in .pacmon/go/DEPENDENCY-NOTES.md, beside go.mod, and shows it on the module's require line.

What Pacmon reads

• Manifest: go.mod
• Notes file: .pacmon/go/DEPENDENCY-NOTES.md
• Section heading: the module path: ## github.com/spf13/cobra, ## github.com/jackc/pgx/v5

Pacmon reads module paths in require directives of go.mod, including // indirect ones, shown with their own scope. A tool directive points at the required module that provides it. replace, exclude, retract, go.work and vendor/ are not read as dependencies.

Pacmon never runs the go command, so it needs no Go toolchain.

Example

module example.com/billing

go 1.24

require (
	github.com/jackc/pgx/v5 v5.7.1
	github.com/spf13/cobra v1.8.1
	golang.org/x/sync v0.10.0 // indirect
)

.pacmon/go/DEPENDENCY-NOTES.md:

## github.com/jackc/pgx/v5

Postgres driver. Use it through internal/db only.

### Agent notes

- purpose: PostgreSQL driver and connection pool for the billing service
- usage: only through internal/db, which wraps the pool and the transaction helpers
- verify: `go test ./internal/db/...` against the Postgres in docker-compose.yml
- verified: v5.7.1

The heading is the module path as require spells it, major-version suffix included. A new major version of a Go module is a new module path, so moving from /v5 to /v6 starts a new section, and the old one stays with - status: removed <YYYY-MM> — <reason>.

For AI coding agents

An agent reads a module's section before it adds, upgrades or removes the module, runs what verify: says, and records the version it checked in verified:. See the rules agents follow.