Golang Gopls

Working with gopls

Use gopls for semantic Go information that text search cannot reliably provide. Treat its command line and settings as versioned interfaces: inspect the installed version and built-in help before relying on a particular command or option.

Diagnose workspace context first

Read go.mod, go.work, build tags, generated-code instructions, editor settings, and the relevant package layout. Then determine:

• which directory is the intended workspace root;
• whether the file belongs to a loaded module;
• the active Go toolchain, GOOS, GOARCH, and build tags;
• whether generated files or missing private modules prevent loading;
• whether the host already exposes gopls-backed definition, reference, diagnostic, or rename operations.

Many apparent language-server failures are module-loading failures. Reproduce with the repository's ordinary Go commands before changing gopls configuration.

Choose the narrowest semantic operation

Use the semantic surface already exposed by the host. If more than one is available, choose by input and result shape:

• host LSP operations fit questions that already have a file position;
• gopls MCP operations, when exposed, fit name-, package-, or file-oriented queries;
• the gopls CLI is useful for one-shot checks and scripted fallbacks.

Read references/capability-matrix.md for concrete mappings. Inspect gopls version, gopls help, and the host's actual tool list before relying on a command or MCP operation.

Use text search for literal strings, generated artifacts, configuration, and non-Go files. Do not interpret text matches as semantic references when shadowing, aliases, build tags, or generated code matter.

Before a rename or other edit-producing refactor:

1. Confirm the target symbol and package.
2. Inspect exported API and cross-module impact.
3. Exclude generated or vendored files from direct edits while accounting for their API impact.
4. Preview the workspace edit or diff when supported.
5. Apply the returned workspace edit and inspect the resulting diff.
6. Run formatting, compilation, and focused tests.

Do not manually reproduce a semantic rename with global search-and-replace.

Troubleshoot diagnostics

When editor and command-line results differ, compare:

• workspace folder and module selection;
• installed gopls and Go versions;
• environment inherited by the editor;
• build tags and test variants;
• unsaved overlays;
• private-module access;
• generated files;
• stale processes or caches.

Prefer fixing project or environment facts over suppressing diagnostics. Change a gopls setting only when it is documented for the installed version and reflects the intended workspace build; avoid committing machine-specific editor state as a project fix.

Report evidence clearly

For navigation or diagnosis, report:

• the symbol or file queried;
• the workspace and build assumptions;
• the relevant definitions, callers, implementations, or diagnostics;
• whether results may exclude inactive build variants;
• the smallest next action.

A successful gopls response does not replace compilation or tests. After an edit, run the repository's normal Go verification. If gopls is absent or incompatible, explain which semantic guarantees are missing and continue with the safest available navigation method.