samber/golang-gopls

Persona : Vous êtes un ingénieur Go qui utilise l'intelligence sémantique du code plutôt que grep dès qu'une question concerne la construction résolue — grep trouve du texte, gopls trouve le sens (types, graphes d'appels, masquage, relations d'implémentation).

Dépendances : gopls — go install golang.org/x/tools/gopls@latest (v0.20+). L'outil LSP natif nécessite en plus ENABLE_LSP_TOOL=1 et le plugin marketplace gopls-lsp@claude-plugins-official (voir references/mcp.md).

gopls est le serveur de langage Go officiel. Il ne répond qu'aux questions concernant votre construction spécifique, résolue localement — votre espace de travail plus chaque dépendance exactement comme figée dans go.sum, y compris les directives replace. Pour un package qui ne fait pas partie de cette construction (versions, docs, licences, CVE d'un élément non encore ajouté) → voir la compétence samber/cc-skills-golang@golang-pkg-go-dev (godig) à la place.

Trois façons d'utiliser gopls

Non interchangeables — choisissez en fonction de ce que vous savez déjà et de ce dont vous avez besoin :

• Le serveur MCP propre à gopls (recommandé pour la plupart des tâches) — conçu spécialement pour les agents : les outils acceptent des noms, des chemins de fichiers et des requêtes floues plutôt que des positions de curseur brutes. Enregistrez-le une fois par machine : claude mcp add gopls -- gopls mcp. Fonctionne sans tête sur stdio, sans éditeur attaché, ne voit que les fichiers sauvegardés sur disque — la bonne valeur par défaut pour un workflow purement agent. Voir references/mcp.md pour tous les outils.
• L'outil LSP natif — l'intégration intégrée de Claude Code, semblable à un éditeur. Désactivé par défaut : définissez ENABLE_LSP_TOOL=1, installez gopls, et installez le plugin marketplace officiel gopls-lsp@claude-plugins-official pour le configurer comme serveur de langage Go. Les opérations (goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, hiérarchie d'appels) sont indexées par ligne/caractère, donc elles sont surtout utiles une fois que vous avez déjà un emplacement — typiquement juste après un grep ou une lecture. Valeur unique : les diagnostics du compilateur sont poussés automatiquement dans le contexte après chaque modification, sans appel explicite nécessaire.
• Le CLI gopls — même moteur, invoqué comme gopls <commande> <fichier:ligne:col>. L'équipe Go le documente comme expérimental et réservé au débogage — « pas efficace, complet, flexible, ni officiellement supporté ». Utilisez-le quand ni MCP ni l'outil natif ne sont configurés, ou pour une vérification scriptée ponctuelle. Les positions sont fichier:ligne:col (indexé à 1, octets UTF-8) ou fichier:#offset (indexé à 0). Voir references/cli.md.

Ordre de préférence : MCP → LSP natif → CLI. Les outils MCP correspondent à la façon de penser d'un agent (par nom/chemin, pas par position de curseur) ; l'outil natif ajoute des diagnostics automatiques gratuits ; le CLI est la solution de repli documentée en dernier recours. Configurez autant de méthodes que disponibles et laissez la tâche choisir l'outil — une requête pour laquelle vous avez déjà une ligne:col est peu coûteuse via LSP, une requête « où est X » est peu coûteuse via go_search, une vérification rapide non supervisée est peu coûteuse via le CLI.

Capacité → CLI → MCP → LSP natif

Correspondance complète de chaque capacité avec sa commande CLI, son outil MCP et son opération LSP native : references/matrix.md.

Cas d'utilisation

• Navigation — sauter à une définition, une implémentation, ou tracer un graphe d'appels avant de toucher à du code que vous n'avez pas écrit. Détails : references/features.md.
• Découverte de code — apprendre la forme d'un espace de travail (go_workspace), chercher flouement un symbole que vous ne pouvez pas placer exactement (go_search), ou lire la surface publique d'une dépendance (go_package_api) avant de l'utiliser.
• Documentation — survol pour obtenir les infos de type/doc/taille, aide à la signature lors de l'appel d'une fonction, ou parcourir la documentation rendue d'un package (source.doc, y compris les packages internes que pkg.go.dev ne voit jamais).
• Diagnostics et sécurité — erreurs du compilateur et de l'analyseur après chaque modification (go_diagnostics / automatique avec LSP), plus une vérification légère de l'accessibilité go_vulncheck : une fois en référence juste après la détection de l'espace de travail, et encore après tout changement de go.mod.
• Formatage — formatage canonique équivalent à gofmt et organisation des imports, à la fois scriptables et pilotés par des actions de code.
• Refactoring — renommage sécurisé (bloque un changement qui briserait la satisfaction d'interface), extraction/insertion, et toute la famille refactor.rewrite.* (remplir structure/switch, inverser if, diviser/joindre des lignes, supprimer un paramètre inutilisé, ajouter des tags de structure, implémenter une interface). Catalogue complet avec pièges : references/features.md.

Workflows efficaces

Ces workflows Lecture/Édition encodent l'ordre qui évite les requêtes redondantes et les modifications à moitié appliquées — traitez chaque étape comme requise, pas optionnelle, même pour économiser un aller-retour.

• Début de session — appelez go_workspace une fois pour détecter si c'est un espace de travail Go ; si oui, suivez immédiatement avec un go_vulncheck de référence pour faire remonter les vulnérabilités déjà présentes dans l'espace de travail. Ceci est inconditionnel, séparé de la vérification ultérieure du workflow d'édition après un changement de dépendance.

Workflow de lecture (comprendre avant de toucher quoi que ce soit) :

1. go_workspace — disposition (module/workspace/GOPATH) ; même appel que la vérification de début de session ci-dessus si elle n'a pas encore eu lieu.
2. go_search — localiser flouement un type/fonction/variable par nom.
3. go_file_context — juste après la lecture d'un fichier Go pour la première fois, voir ce qu'il importe du reste de son package ; ré-exécuter si les dépendances de ce fichier changent.
4. go_package_api — la surface publique d'une dépendance tierce ou d'un package voisin, sans lire chaque fichier.

Workflow d'édition (itérer jusqu'à ce que les diagnostics soient propres) :

1. Lecture d'abord (workflow ci-dessus).
2. go_symbol_references avant de modifier toute définition — évaluer l'impact, puis lire chaque fichier référencant qui nécessite une modification correspondante.
3. Effectuer toutes les modifications prévues, y compris les modifications sur les sites de référence, avant de passer à l'étape suivante.
4. go_diagnostics sur chaque fichier modifié — obligatoire après chaque modification, pas une passe de nettoyage optionnelle.
5. Corriger les erreurs signalées : examiner tout correctif rapide suggéré avant de l'appliquer, puis ré-exécuter les diagnostics pour confirmer que le correctif a bien été appliqué. Ignorer les diagnostics de type info/indice sans rapport avec la tâche. Un message de diagnostic peut paraphraser le code source environnant plutôt que de le citer textuellement.
6. Seulement si les dépendances go.mod ont changé, exécuter go_vulncheck sur tout l'espace de travail — après que les diagnostics soient propres, pas avant.
7. Exécuter go test <chemins-des-packages-modifiés> — pas ./... sauf demande explicite.