golang-gopls

ペルソナ： ビルド結果に関する質問では、grep よりもセマンティックなコードインテリジェンスを活用する Go エンジニアです。grep で見つかるのはテキストですが、gopls なら意味（型、呼び出しグラフ、シャドーイング、実装関係）が分かります。

依存関係： gopls — go install golang.org/x/tools/gopls@latest（v0.20 以降）。ネイティブの LSP ツールには、ENABLE_LSP_TOOL=1 と gopls-lsp@claude-plugins-official マーケットプレイスプラグインも必要です（references/mcp.md を参照）。

gopls は Go の公式言語サーバーです。ローカルで解決された特定のビルド（ワークスペースと、replace ディレクティブも含めて go.sum で固定されたすべての依存関係）についてのみ質問に答えます。まだ追加していないパッケージのバージョン、ドキュメント、ライセンス、CVE など、そのビルドに含まれないパッケージについては、代わりに samber/cc-skills-golang@golang-pkg-go-dev スキル（godig）を参照してください。

gopls を利用する 3 つの方法

互換性はありません。すでに分かっていることと、必要な出力に応じて選んでください。

• gopls 独自の MCP サーバー（ほとんどのタスクで推奨） — エージェント向けに設計されています。ツールでは生のカーソル位置ではなく、名前、ファイルパス、あいまい検索クエリを指定します。マシンごとに一度登録します：claude mcp add gopls -- gopls mcp。エディターを接続せず、stdio 経由でヘッドレス実行され、ディスクに保存されたファイルだけを参照します。エージェントのみで使うワークフローには、これが適切なデフォルトです。各ツールについては references/mcp.md を参照してください。
• ネイティブの LSP ツール — Claude Code に組み込まれた、エディター形式の統合です。デフォルトでは無効です。ENABLE_LSP_TOOL=1 を設定し、gopls をインストールしてから、公式の gopls-lsp@claude-plugins-official マーケットプレイスプラグインをインストールし、Go 言語サーバーとして接続してください。操作（goToDefinition、findReferences、hover、documentSymbol、workspaceSymbol、goToImplementation、呼び出し階層）は line／character を指定するため、位置がすでに分かっている場合に最も役立ちます。通常は grep や読み込みの直後です。独自の利点として、編集のたびにコンパイラー診断が自動的にコンテキストに追加され、明示的な呼び出しが不要です。
• gopls CLI — 同じエンジンを gopls <command> <file:line:col> として実行します。Go チームはこれを実験的でデバッグ専用と位置付けており、「効率的でも、完全でも、柔軟でもなく、公式にサポートされてもいない」としています。MCP もネイティブツールも接続されていない場合や、一度だけスクリプトで確認する場合に使ってください。位置は file:line:col（1 始まり、UTF-8 バイト単位）または file:#offset（0 始まり）で指定します。references/cli.md を参照してください。

優先順位：MCP → ネイティブの LSP → CLI。 MCP ツールは、エージェントの考え方（カーソル位置ではなく名前やパスを基準にする方法）に合っています。ネイティブツールでは診断が自動で追加され、CLI は公式ドキュメントに記載された最終手段です。利用可能なものはできるだけ接続し、タスクに応じて使い分けてください。すでに line:col が分かっているクエリは LSP で簡単に処理でき、「X はどこにあるか」というクエリは go_search で簡単に処理でき、手早く無人で確認する場合は CLI が便利です。

機能 → CLI → MCP → ネイティブ LSP

すべての機能と、それぞれに対応する CLI コマンド、MCP ツール、ネイティブ LSP 操作の完全な対応表は、references/matrix.md を参照してください。

ユースケース

• ナビゲーション — 自分が書いていないコードに手を加える前に、定義や実装へジャンプしたり、呼び出しグラフをたどったりできます。詳細：references/features.md。
• コードの探索 — ワークスペースの構造（go_workspace）を把握したり、正確な場所が分からないシンボルをあいまい検索（go_search）したり、依存関係の公開 API（go_package_api）を使用前に確認したりできます。
• ドキュメント — ホバーで型、ドキュメント、サイズに関する情報を確認したり、関数の呼び出し中にシグネチャのヘルプを表示したり、レンダリングされたパッケージドキュメント（内部パッケージを含み、pkg.go.dev では確認できないものも含む）を閲覧したりできます（source.doc）。
• 診断と安全性 — 編集のたびにコンパイラーとアナライザーのエラーを確認できます（go_diagnostics／LSP 使用時は自動）。さらに、軽量な go_vulncheck 到達可能性チェックも利用できます。ワークスペースの検出直後にベースラインとして一度実行し、go.mod の変更後にも再実行します。
• フォーマット — gofmt と同等の標準フォーマットとインポートの整理を利用できます。スクリプトからもコードアクションからも実行できます。
• リファクタリング — 安全な名前変更（インターフェースの実装を壊す変更はブロック）、抽出／インライン化に加え、refactor.rewrite.* ファミリー全体（構造体／switch の補完、if の反転、行の分割／結合、未使用パラメーターの削除、構造体タグの追加、インターフェースの実装）を利用できます。注意点を含む全カタログ：references/features.md。

効率的なワークフロー

これらの読み取り／編集ワークフローでは、重複した問い合わせや中途半端な編集を避けるための順序を定めています。往復を減らすためであっても、各ステップは任意ではなく必須として扱ってください。

• セッション開始時 — go_workspace を一度呼び出して、そもそも Go ワークスペースかどうかを検出します。Go ワークスペースであれば、直ちにベースラインの go_vulncheck を実行し、ワークスペースにすでに存在する脆弱性を明らかにします。これは無条件で実行し、依存関係の変更後に編集ワークフローで行うチェックとは別に実施します。

読み取りワークフロー（何かに手を加える前に把握する）：

1. go_workspace — レイアウト（モジュール／ワークスペース／GOPATH）を確認します。まだ実行していない場合は、上記のセッション開始時のチェックと同じ呼び出しを使います。
2. go_search — 型／関数／変数を名前であいまい検索します。
3. go_file_context — Go ファイルを初めて読んだ直後に、そのファイルがパッケージの他の部分から何を取り込んでいるかを確認します。そのファイルの依存関係が変わった場合は再実行します。
4. go_package_api — サードパーティ依存関係または兄弟パッケージの公開 API を確認します。すべてのファイルを読む必要はありません。

編集ワークフロー（診断がクリーンになるまで繰り返す）：

1. まず読み取ります（上記のワークフローを参照）。
2. 定義を変更する前に go_symbol_references を実行し、影響範囲を判断してから、対応する編集が必要な参照元のファイルをすべて読み取ります。
3. 次に進む前に、参照箇所の編集も含め、計画した編集をすべて行います。
4. 変更したファイルすべてに対して go_diagnostics を実行します。各変更後に必ず実行し、任意の仕上げ作業として扱わないでください。
5. 報告されたエラーを修正します。提案されたクイックフィックスを適用する前に差分を確認し、修正が反映されたことを確認するため、診断を再実行します。タスクと無関係なヒント／情報の診断は無視します。診断メッセージは、周辺のソースを逐語的に引用するのではなく、言い換えることがあります。
6. go.mod の依存関係が変更された場合に限り、診断がクリーンになった後で、ワークスペース全体に対して go_vulncheck を実行します。診断がクリーンになる前には実行しません。
7. go test <changed-package-paths> を実行します。明示的に求められない限り ./... は実行しません。リポジトリ全体を実行すると反復のサイクルが遅くなるためです。

結果を利用する前に知っておくべき注意点：

• references の結果には、問い合わせたファイルのビルド設定のみが反映されます。foo_windows.go への問い合わせでは、bar_linux.go の一致箇所は表示されません。クロスプラットフォームの結果が欠けている場合は、該当する GOOS／ビルドタグで再実行してください。
• call_hierarchy に表示されるのは静的な呼び出しのみです。関数値やインターフェースメソッドを介した呼び出しは表示されないため、呼び出し箇所が重要な場合は references で裏付けてください。
• 抽出／インライン化リファクタリングは名前変更ほど厳密ではありません。コメントが削除されることがあり、DO NOT EDIT とマークされた生成ファイルにはコードアクションがまったく適用されません。
• refactor.rewrite.fillStruct はカーソルより上にある現在のファイルのみを検索し、構造体のパッケージがすでにインポートされている必要があります。型を入力したばかりの場合は、先に source.organizeImports を実行してください。

gopls、godig、Context7、govulncheck の比較

gopls が推論できるのは、ローカルビルド内に存在し解決可能なコードに限られます。

• そのビルドに結び付かない情報（バージョン履歴、ライセンス、エコシステム全体でのインポート元、まだ追加していないパッケージの CVE など）には、samber/cc-skills-golang@golang-pkg-go-dev スキル（godig）を参照してください。ローカルチェックアウトは不要で、pkg.go.dev に直接問い合わせます。
• gopls の軽量なオンデマンド go_vulncheck ではなく、ツリー全体を対象とする包括的な脆弱性監査（CI のゲート、定期的なスキャンなど）には、samber/cc-skills-golang@golang-security スキル（govulncheck）を参照してください。
• Go 以外のドキュメント、または pkg.go.dev にインデックスされていない Go モジュールには、Context7 をフォールバックとして利用できます。

タスクとツールの完全な対応表は、samber/cc-skills-golang@golang-how-to スキルの「godig vs gopls vs Context7 vs govulncheck」セクションにあります。