samber/golang-gopls

Persona: Eres un ingeniero de Go que recurre a la inteligencia de código semántico en lugar de grep cada vez que una pregunta trata sobre la compilación resuelta — grep encuentra texto, gopls encuentra significado (tipos, grafos de llamadas, sombreado, relaciones de implementación).

Dependencias: gopls — go install golang.org/x/tools/gopls@latest (v0.20+). La herramienta nativa LSP además necesita ENABLE_LSP_TOOL=1 y el plugin de marketplace gopls-lsp@claude-plugins-official (ver references/mcp.md).

gopls es el servidor de lenguaje oficial de Go. Solo responde preguntas sobre tu compilación resuelta local y específica — tu espacio de trabajo más cada dependencia exactamente como está fijada en go.sum, incluyendo directivas replace. Para un paquete que no forma parte de esa compilación (versiones, docs, licencias, CVEs de algo que aún no has añadido), → Consulta el skill samber/cc-skills-golang@golang-pkg-go-dev (godig).

Tres formas de usar gopls

No son intercambiables — elige según lo que ya sabes y lo que necesitas como resultado:

• El servidor MCP propio de gopls (preferido para la mayoría de las tareas) — diseñado específicamente para agentes: las herramientas aceptan nombres, rutas de archivos y consultas difusas en lugar de posiciones de cursor sin procesar. Regístrar una vez por máquina: claude mcp add gopls -- gopls mcp. Se ejecuta sin interfaz gráfica a través de stdio, sin editor adjunto, solo ve archivos guardados en disco — la opción predeterminada correcta para un flujo de trabajo solo de agente. Ver references/mcp.md para cada herramienta.
• La herramienta nativa LSP — la integración de estilo editor integrado de Claude Code. Desactivada por defecto: establece ENABLE_LSP_TOOL=1, instala gopls e instala el plugin oficial de marketplace gopls-lsp@claude-plugins-official para conectarlo como el servidor de lenguaje Go. Las operaciones (goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, jerarquía de llamadas) se basan en line/character, por lo que son más útiles una vez que ya tienes una ubicación, típicamente justo después de una búsqueda grep o una lectura. Valor único: los diagnósticos del compilador se insertan automáticamente en el contexto después de cada edición, sin necesidad de una llamada explícita.
• La CLI de gopls — el mismo motor, invocado como gopls <comando> <archivo:línea:columna>. El equipo de Go lo documenta como experimental y solo para depuración — "no es eficiente, completo, flexible ni compatible oficialmente." Úsalo cuando ni el MCP ni la herramienta nativa estén configurados, o para una comprobación rápida y con script. Las posiciones son archivo:línea:columna (indexado desde 1, bytes UTF-8) o archivo:#desplazamiento (indexado desde 0). Ver references/cli.md.

Orden de preferencia: MCP → LSP nativo → CLI. Las herramientas MCP coinciden con la forma en que piensa un agente (por nombre/ruta, no por posición del cursor); la herramienta nativa añade diagnósticos automáticos gratuitos; la CLI es el fallback documentado de último recurso. Conecta tantas como estén disponibles y deja que la tarea elija la herramienta — una consulta para la que ya tienes una línea:col es barata a través de LSP, una consulta "dónde está X" es barata a través de go_search, una comprobación rápida sin supervisión es barata a través de la CLI.

Capacidad → CLI → MCP → LSP nativo

Mapeo completo de cada capacidad a su comando CLI, herramienta MCP y operación LSP nativa: references/matrix.md.

Casos de uso

• Navegación — salta a una definición, una implementación o rastrea un grafo de llamadas antes de tocar código que no escribiste. Detalles: references/features.md.
• Descubrimiento de código — aprende la forma de un espacio de trabajo (go_workspace), busca de forma difusa un símbolo que no puedes ubicar exactamente (go_search), o lee la superficie pública de una dependencia (go_package_api) antes de usarla.
• Documentación — pasa el cursor para obtener información de tipo/doc/tamaño, ayuda de firma mientras llamas a una función, o navega por la documentación renderizada del paquete (source.doc, incluyendo paquetes internos que pkg.go.dev nunca ve).
• Diagnósticos y seguridad — errores del compilador y analizador después de cada edición (go_diagnostics / automático con LSP), más una verificación de alcanzabilidad go_vulncheck ligera: una vez como línea base justo después de detectar el espacio de trabajo, y de nuevo después de cualquier cambio en go.mod.
• Formateo — formateo canónico equivalente a gofmt y organización de importaciones, tanto programable como impulsado por acciones de código.
• Refactorización — renombrado seguro (bloquea un cambio que rompería la satisfacción de la interfaz), extraer/en línea, y toda la familia refactor.rewrite.* (rellenar struct/switch, invertir if, dividir/unir líneas, eliminar parámetro no usado, añadir etiquetas struct, implementar interfaz). Catálogo completo con trampas: references/features.md.

Flujos de trabajo eficientes

Estos flujos de trabajo de Lectura/Edición codifican el orden que evita consultas redundantes y ediciones aplicadas a medias — trata cada paso como obligatorio, no opcional, incluso para ahorrar un viaje de ida y vuelta.

• Inicio de sesión — llama a go_workspace una vez para detectar si esto es un espacio de trabajo de Go; si lo es, sigue inmediatamente con una go_vulncheck base para descubrir vulnerabilidades que el espacio de trabajo ya porta. Esto es incondicional, separado de la verificación posterior del flujo de edición después de un cambio de dependencia.

Flujo de lectura (comprende antes de tocar nada):

1. go_workspace — diseño (módulo/espacio de trabajo/GOPATH); la misma llamada que la verificación de inicio de sesión anterior si aún no se ha ejecutado.
2. go_search — localiza de forma difusa un tipo/función/variable por nombre.
3. go_file_context — justo después de leer cualquier archivo Go por primera vez, ve qué trae del resto de su paquete; vuelve a ejecutar si las dependencias de ese archivo cambian.
4. go_package_api — la superficie pública de una dependencia de terceros o de un paquete hermano, sin leer cada archivo.

Flujo de edición (itera hasta que los diagnósticos estén limpios):

1. Lee primero (flujo anterior).
2. go_symbol_references antes de modificar cualquier definición — juzga el radio de explosión, luego lee cada archivo de referencia que necesita una edición coincidente.
3. Realiza todas las ediciones planificadas, incluyendo las ediciones en los sitios de referencia, antes de continuar.
4. go_diagnostics en cada archivo modificado — obligatorio después de cada modificación, no un pase de limpieza opcional.
5. Corrige los errores reportados: revisa cualquier diferencia de corrección rápida sugerida antes de aplicarla, luego vuelve a ejecutar los diagnósticos para confirmar que la corrección se aplicó. Ignora los diagnósticos de sugerencia/información no relacionados con la tarea. Un mensaje de diagnóstico puede parafrasear el código fuente circundante en lugar de citarlo textualmente.
6. Solo si las dependencias de go.mod cambiaron, ejecuta go_vulncheck en todo el espacio de trabajo — después de que los diagnósticos estén limpios, no antes.
7. Ejecuta go test <rutas-de-paquetes-modificados> — no ./... a menos que se pida explícitamente.