go-semantic-tools

Go セマンティックツール

grep は文字列を見つけますが、ツールチェーンは意味を見つけます。メソッド名は型をまたいで繰り返され、インターフェースは暗黙的に満たされ、ドットインポートはテキスト検索を誤らせます。共有コードを変更する前に、型を理解するツールで正確な情報を確認しましょう。

必要に応じて読み込める詳細なリファレンス資料：

• references/mcp-and-code-actions.md — gopls mcp のセットアップとツール、読み取り／編集のループ、CLI コードアクション、ビルドタグに関する注意点。

以下の概要だけでは不十分な場合にのみ、リファレンスファイルを読んでください。

0. インターフェースを選ぶ

インターフェース	こちらを選ぶ場面
gopls MCP サーバー（gopls mcp、v0.20+）	エージェントとして作業する場合 — ツールにはカーソル位置ではなく、シンボル名とファイルパスを指定します
ハーネスに組み込まれた LSP 統合（有効な場合）	すでに位置がわかっていて、編集のたびに診断を受け取りたい場合
gopls CLI（以下を参照）	スクリプトや単発の確認に使う場合。Go チームはこれをデバッグ用インターフェースとして案内しています

MCP サーバーでは、次の手順で進めます。定義を変更する前に go_symbol_references を実行し、変更のたびに問題がなくなるまで go_diagnostics を実行し、go.mod の変更後に go_vulncheck を実行してから、変更したパッケージだけを対象に go test を実行します。セットアップとツール一覧については、references/mcp-and-code-actions.md を参照してください。

1. ツールを選ぶ

質問	コマンド
このシンボルはどこで使われていますか？	gopls references file.go:LINE:COL
どこで定義されていますか？	gopls definition file.go:LINE:COL
このインターフェースを実装しているのは何ですか？／この型が満たすインターフェースはどれですか？	gopls implementation file.go:LINE:COL
この関数を（間接的に）呼び出しているのは何ですか？	gopls call_hierarchy file.go:LINE:COL
このパッケージの API には何がありますか？	go doc ./internal/service / go doc pkg Symbol
どのパッケージが存在し、何に依存していますか？	go list ./...、go list -deps、go list -json
モジュール全体から名前でシンボルを探す	gopls workspace_symbol Name
1 つのファイル内のシンボル	gopls symbols file.go

位置は file.go:line:column（1 始まり）で指定します。先行する検索または gopls symbols から行番号と列番号を取得してください。すべての gopls コマンドはモジュール内から実行し、ビルドキャッシュが温まっている必要があります。まず go build ./... を一度実行してください。

2. 標準的な調査フロー

関数を変更する前に

gopls references internal/service/user.go:42:6   # every call site, typed
gopls call_hierarchy internal/service/user.go:42:6

Process( をテキスト検索すると、各型の Process がすべて見つかります。一方、references で返されるのは、この関数の呼び出し箇所だけです。grep では見つけられない、インターフェースや埋め込みを介した使用箇所も含まれます。

インターフェースを把握する

# On the interface name: all implementations
gopls implementation internal/store/store.go:15:6

# On a method of a concrete type: interfaces it satisfies
gopls implementation internal/store/postgres/user.go:30:18

インターフェースにメソッドを追加する前に実行してください。一覧にある実装はすべて壊れます。

依存関係グラフを理解する

go list ./...                                    # all packages
go list -f '{{.ImportPath}} -> {{join .Imports " "}}' ./... # direct edges
go list -deps ./cmd/api | grep myorg             # everything a binary pulls in
go list -json ./internal/service | jq .Imports   # machine-readable

ディレクトリ名を鵜呑みにせず、「domain は何もインポートしない」といったレイヤー構成の主張を検証するために使います。

慣れていない API を調べる

go doc ./internal/payments            # package overview
go doc ./internal/payments Gateway    # one symbol, with doc comment
go doc -all ./internal/payments       # full API surface

ファイルを開くよりこちらを使いましょう。実装のノイズを除いた、エクスポートされる契約を確認できます。

3. セマンティックな名前変更

gopls rename -w internal/service/user.go:42:6 ProcessOrder

インターフェース、埋め込み、テストパッケージを通じて、参照されている箇所すべてでシンボルの名前を変更します。識別子を検索と置換で名前変更しないでください。フィールドの UserID とローカル変数の UserID は、綴りが同じでも別のシンボルです。

4. エディターを使わずに診断する

gopls check ./internal/...   # type errors + analyzer findings per file
go vet ./...                 # the vet suite standalone

gopls check は IDE ユーザーに表示されるものと同じ診断を提示します。エディターで開いていないコードをレビューするときに実行してください。

5. リファクタリングのコードアクション

gopls codeaction internal/order/service.go:42:2-58:3                     # list
gopls codeaction -kind=refactor.extract.function -exec -diff \
    internal/order/service.go:42:2-58:3                                  # preview

抽出（関数、メソッド、変数、定数、新しいファイル）、呼び出しのインライン化、構造体や switch の補完、if の反転、すべての呼び出し箇所からの未使用パラメーターの削除が可能です。いずれも型を認識しており、手作業の編集とは異なります。書き込む前に差分を確認してください。抽出とインライン化はコメントについてベストエフォートです。

6. grep が今でも適している場合

• 文字列リテラル：ログメッセージ、SQL、設定キー、エラーテキスト。
• コメント、TODO、ドキュメント。
• まだコンパイルできないコード — gopls には型チェック可能なパッケージが必要ですが、grep は壊れたツリーでも使えます。
• 存在の簡単な確認（「この環境変数はどこかで参照されていますか？」など）。

目安：識別子には gopls、リテラルや文章には grep を使います。

検証チェックリスト

1. 共有シンボルを変更する前に、gopls references（grep ではなく）で呼び出し箇所を列挙します
2. インターフェースを変更する前に、そのインターフェースに対して gopls implementation を実行します
3. 名前の変更には gopls rename -w を使用し、テキストの置換は行いません
4. レイヤー構成に関する前提を go list のインポートデータで確認します
5. 不慣れなパッケージは、実装を読む前に go doc で調べます
6. エディターを使わずにレビューする場合は、gopls check / go vet を実行します
7. grep はリテラル、コメント、コンパイルされないコードに限定して使用します
8. 編集のたびに診断結果を確認します（MCP go_diagnostics または gopls check）
9. クロスプラットフォームのシンボルは、対応する GOOS / ビルドタグを指定して検索します