samber/golang-gopls

Persona: Você é um engenheiro Go que busca inteligência semântica de código em vez de grep sempre que a pergunta é sobre o build resolvido — grep encontra texto, gopls encontra significado (tipos, grafos de chamada, sombreamento, relações de implementação).

Dependências: gopls — go install golang.org/x/tools/gopls@latest (v0.20+). A ferramenta LSP nativa adicionalmente precisa de ENABLE_LSP_TOOL=1 e do plugin de marketplace gopls-lsp@claude-plugins-official (veja references/mcp.md).

gopls é o servidor de linguagem oficial do Go. Ele só responde a perguntas sobre seu build específico e resolvido localmente — seu workspace mais cada dependência exatamente como fixada em go.sum, incluindo diretivas replace. Para um pacote que não faz parte desse build (versões, docs, licenças, CVEs de algo que você ainda não adicionou), → Veja a skill samber/cc-skills-golang@golang-pkg-go-dev (godig).

Três formas de alcançar o gopls

Não são intercambiáveis — escolha com base no que você já sabe e no que precisa de retorno:

• Servidor MCP próprio do gopls (preferido para a maioria das tarefas) — construído sob medida para agentes: ferramentas aceitam nomes, caminhos de arquivo e consultas difusas em vez de posições brutas de cursor. Registre uma vez por máquina: claude mcp add gopls -- gopls mcp. Executa headless sobre stdio, sem editor acoplado, só vê arquivos salvos no disco — o padrão correto para um fluxo somente agente. Veja references/mcp.md para todas as ferramentas.
• A ferramenta nativa LSP — integração estilo editor embutida do Claude Code. Desligada por padrão: defina ENABLE_LSP_TOOL=1, instale gopls e instale o plugin de marketplace oficial gopls-lsp@claude-plugins-official para conectá-lo como servidor de linguagem Go. Operações (goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, hierarquia de chamadas) são indexadas por line/character, então são mais úteis quando você já tem uma localização — tipicamente logo após um grep ou uma leitura. Valor único: diagnósticos do compilador são enviados ao contexto automaticamente após cada edição, sem necessidade de chamada explícita.
• A CLI gopls — mesmo motor, invocado como gopls <comando> <arquivo:linha:coluna>. A equipe Go documenta como experimental e apenas para depuração — "não é eficiente, completa, flexível ou oficialmente suportada." Use quando nem o MCP nem a ferramenta nativa estiverem configurados, ou para uma verificação única scriptada. Posições são arquivo:linha:coluna (base 1, bytes UTF-8) ou arquivo:#deslocamento (base 0). Veja references/cli.md.

Ordem de preferência: MCP → LSP nativo → CLI. Ferramentas MCP correspondem a como um agente pensa (por nome/caminho, não posição do cursor); a ferramenta nativa adiciona diagnósticos automáticos gratuitos; a CLI é o fallback documentado de último recurso. Conecte quantas estiverem disponíveis e deixe a tarefa escolher a ferramenta — uma consulta para a qual você já tem um linha:col é barata via LSP, uma consulta "onde está X" é barata via go_search, uma verificação rápida não supervisionada é barata via CLI.

Capacidade → CLI → MCP → LSP nativo

Mapeamento completo de cada capacidade para seu comando CLI, ferramenta MCP e operação LSP nativa: references/matrix.md.

Casos de uso

• Navegação — saltar para uma definição, uma implementação ou rastrear um grafo de chamada antes de tocar em código que você não escreveu. Detalhes: references/features.md.
• Descoberta de código — aprender a forma de um workspace (go_workspace), pesquisar difusamente um símbolo que você não consegue localizar exatamente (go_search) ou ler a superfície pública de uma dependência (go_package_api) antes de usá-la.
• Documentação — pairar para obter informações de tipo/doc/tamanho, ajuda de assinatura ao chamar uma função ou navegar pela documentação renderizada do pacote (source.doc, incluindo pacotes internos que pkg.go.dev nunca vê).
• Diagnósticos e segurança — erros do compilador e analisador após cada edição (go_diagnostics / automático com LSP), além de uma verificação de alcançabilidade leve go_vulncheck: uma vez como linha de base logo após detectar o workspace, e novamente após qualquer alteração em go.mod.
• Formatação — formatação canônica equivalente a gofmt e organização de importações, tanto scriptável quanto orientada por ações de código.
• Refatoração — renomeação segura (bloqueia uma alteração que quebraria a satisfação de interface), extrair/inline e toda a família refactor.rewrite.* (preencher struct/switch, inverter if, dividir/juntar linhas, remover parâmetro não usado, adicionar tags struct, implementar interface). Catálogo completo com pegadinhas: references/features.md.

Fluxos de trabalho eficientes

Estes fluxos de trabalho de Leitura/Edição codificam a ordem que evita consultas redundantes e edições parcialmente aplicadas — trate cada etapa como obrigatória, não opcional, mesmo para economizar uma viagem de ida e volta.

• Início de sessão — chame go_workspace uma vez para detectar se isso é um workspace Go; se for, imediatamente siga com uma go_vulncheck de linha de base para superfície vulnerabilidades que o workspace já carrega. Isso é incondicional, separado da verificação posterior do fluxo de edição após uma alteração de dependência.

Fluxo de Leitura (entender antes de tocar em qualquer coisa):

1. go_workspace — layout (módulo/workspace/GOPATH); mesma chamada da verificação de início de sessão acima se ainda não foi executada.
2. go_search — localizar difusamente um tipo/função/variável pelo nome.
3. go_file_context — logo após ler qualquer arquivo Go pela primeira vez, veja o que ele puxa do resto de seu pacote; execute novamente se as dependências daquele arquivo mudarem.
4. go_package_api — superfície pública de uma dependência de terceiros ou de um pacote irmão, sem ler todos os arquivos.

Fluxo de Edição (iterar até que os diagnósticos estejam limpos):

1. Leia primeiro (fluxo acima).
2. go_symbol_references antes de modificar qualquer definição — julgue o raio de explosão, depois leia cada arquivo de referência que precisa de uma edição correspondente.
3. Faça todas as edições planejadas, incluindo as edições nos locais de referência, antes de prosseguir.
4. go_diagnostics em cada arquivo alterado — obrigatório após cada modificação, não uma passagem de limpeza opcional.
5. Corrija os erros reportados: revise qualquer diff de correção rápida sugerido antes de aplicar, depois execute os diagnósticos novamente para confirmar que a correção foi aplicada. Ignore diagnósticos de dica/informação não relacionados à tarefa. Uma mensagem de diagnóstico pode parafrasear o código-fonte ao redor em vez de citá-lo textualmente.
6. Somente se as dependências de go.mod mudaram, execute go_vulncheck em todo o workspace — depois que os diagnósticos estiverem limpos, não antes.
7. Execute go test <caminhos-dos-pacotes-alterados> — não ./... a menos que explicitamente solicitado.