# 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

```go
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`:

```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](https://pacmon.dev/agents/).