go-semantic-tools

Files (2)

• SKILL.md
• mcp-and-code-actions.md · references/

SKILL.md (first lines)

# Go Semantic Tools

grep finds strings; the toolchain finds meaning. Method names repeat
across types, interfaces are satisfied implicitly, and dot-imports lie
to text search. Before changing shared code, get the truth from tools
that understand types.

Detailed reference material, loaded on demand:

- `references/mcp-and-code-actions.md` — `gopls mcp` setup and tools, the
  read/edit loop, CLI code actions, build-tag gotchas.

Read a reference file only when the summary below is not enough.

## 0. Pick the Interface

| Interface | Prefer it when |
|---|---|
| gopls MCP server (`gopls mcp`, v0.20+) | Working as an agent — tools take symbol names and file paths, not cursor positions |
| The harness's built-in LSP integration, if enabled | You already have a position, and want diagnostics pushed after every edit |
| `gopls` CLI (below) | Scripts and one-off checks; the Go team documents it as a debugging interface |

With the MCP server, follow its loop: `go_symbol_references` before
changing a definition, `go_diagnostics` after every edit until clean,
`go_vulncheck` after `go.mod` changes, then `go test` on the changed
packages only. Setup and the tool list: `references/mcp-and-code-actions.md`.

## 1. Choose the Tool

| Question | Command |
|---|---|
| Where is this symbol used? | `gopls references file.go:LINE:COL` |
| Where is it defined? | `gopls definition file.go:LINE:COL` |
| Who implements this interface? / which interfaces does this type satisfy? | `gopls implementation file.go:LINE:COL` |
| Who calls this function (transitively)? | `gopls call_hierarchy file.go:LINE:COL` |
| What's in this package's API? | `go doc ./internal/service` / `go doc pkg Symbol` |
| Which packages exist / depend on what? | `go list ./...`, `go list -deps`, `go list -json` |
| Find a symbol by name across the module | `gopls workspace_symbol Name` |
| Symbols in one file | `gopls symbols file.go` |

Positions are `file.go:line:column` (1-based). Get line/column from a
prior search or `gopls symbols`. All gopls commands run from within the
module and need a warm build cache — run `go build ./...` once first.

## 2. Standard Investigation Flows

### Before changing a function

```bash
gopls references internal/service/user.go:42:6   # every call site, typed
gopls call_hierarchy internal/service/user.go:42:6
```

Text search for `Process(` would surface every type's `Process`;
`references` returns only this one's call sites — including usages via
interfaces and embeddings that grep cannot see.

### Mapping an interface

```bash
# On the interface name: all implementations
gopls implementation internal/store/store.go:15:6

# On a method of a concrete type: interfaces it satisfies
gopls implementation internal/store/postgres/user.go:30:18
```

Run this before adding a method to an interface — every implementation
listed will break.

### Understanding the dependency graph

```bash
go list ./...                                    # all packages
go list -f '{{.ImportPath}} -> {{join .Imports " "}}' ./... # direct edges
go list -deps ./cmd/api | grep myorg             # everything a binary pulls in
go list -json ./internal/service | jq .Imports   # machine-readable
```

Use this to verify layering claims ("domain imports nothing") instead
of trusting directory names.

### Exploring an unfamiliar API

```bash
go doc ./internal/payments            # package overview
go doc ./internal/payments Gateway    # one symbol, with doc comment
go doc -all ./internal/payments       # full API surface
```

Prefer this to opening files: it shows the exported contract without
implementation noise.

## 3. Semantic Rename

```bash
gopls rename -w internal/service/user.go:42:6 ProcessOrder
```

Renames the symbol everywhere it's referenced — through interfaces,
embedding, and test packages. Never rename an identifier with
find-and-replace; `UserID` the field and `UserID` the local variable
are different symbols with the same spelling.

## 4. Diagnostics Without an Editor

```bash
gopls check ./internal/...   # type errors + analyzer findings per file
go vet ./...                 # the vet suite standalone
```

`gopls check` surfaces the same diagnostics an IDE user sees — run it
when reviewing code you haven't opened in an editor.

## 5. Refactoring Code Actions

```bash
gopls codeaction internal/order/service.go:42:2-58:3                     # list
gopls codeaction -kind=refactor.extract.function -exec -diff \

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills