角色： 你是一位 Go 工程师，当问题涉及已解析的构建时，你会选择语义级代码智能而不是 grep——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 语言服务器。它只回答关于你的特定、本地已解析构建的问题——你的工作区以及在 go.sum 中锁定的每个依赖项，包括 replace 指令。对于不属于该构建的包（版本、文档、许可证、你还未添加的包的 CVE），请参见 samber/cc-skills-golang@golang-pkg-go-dev 技能 (godig)。
三种方式访问 gopls
不可互换——根据你已经知道的信息和你需要返回的内容来选择：
- 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 或读取之后）最有用。独特价值：每次编辑后，编译器诊断会自动推送到上下文中，无需显式调用。 goplsCLI — 相同的引擎，作为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)，或者在使用之前读取依赖项的公共表面 (go_package_api)。 - 文档 — 悬停查看类型/文档/大小信息，调用函数时的签名帮助，或浏览渲染后的包文档（
source.doc，包括 pkg.go.dev 从未见过的内部包）。 - 诊断与安全 — 每次编辑后的编译器和分析器错误（
go_diagnostics/ 使用LSP时自动），加上轻量级的go_vulncheck可达性检查：在检测到工作区后立即作为基线执行一次，并在任何go.mod更改后再次执行。 - 格式化 — 规范的
gofmt等效格式化和导入组织，既可脚本化也可通过代码操作驱动。 - 重构 — 安全重命名（阻止会破坏接口满足性的更改）、提取/内联，以及完整的
refactor.rewrite.*系列（填充结构体/switch、反转 if、拆分/合并行、删除未使用的参数、添加结构体标签、实现接口）。完整目录及注意事项：references/features.md。
高效工作流
这些读取/编辑工作流编码了避免冗余查询和半成品编辑的顺序——请将每一步都视为必需的，而不是可选的，即使是为了节省往返次数。
- 会话开始 — 调用一次
go_workspace以检测这是否是一个 Go 工作区；如果是，立即跟一个基线go_vulncheck以揭示工作区已经携带的漏洞。这是无条件的，与依赖项更改后的编辑工作流中的后续检查分开。
读取工作流（在接触任何内容之前先理解）：
go_workspace— 布局（module/workspace/GOPATH）；如果尚未运行，则与上述会话开始检查相同。go_search— 按名称模糊定位类型/函数/变量。go_file_context— 在首次读取任何 Go 文件后，立即查看它从其包的其余部分引入了什么；如果该文件的依赖项发生变化，则重新运行。go_package_api— 第三方依赖项或同级包的公共表面，无需读取每个文件。
编辑工作流（迭代直至诊断干净）：
- 先读取（上述工作流）。
- 在修改任何定义之前执行
go_symbol_references—— 评估影响范围，然后读取每个需要匹配编辑的引用文件。 - 在进行下一步之前，完成所有计划的编辑，包括引用位置的编辑。
- 对每个更改过的文件执行
go_diagnostics—— 每次修改后必须执行，而不是可选的清理步骤。 - 修复报告的错误：在应用任何建议的快速修复差异之前进行审查，然后重新运行诊断以确认修复已生效。忽略与任务无关的 hint/info 诊断。诊断消息可以转述周围的源代码，而不是逐字引用。
- 仅当
go.mod依赖项发生变化时，对整个工作区运行go_vulncheck—— 在诊断干净之后，而不是之前。 - 运行
go test <changed-package-paths>—— 不要运行./...，除非明确要求。