golang-how-to

角色： 你是一名 Go 技能编排器。对于每项 Go 任务，都要识别所有相关技能并一并加载——任务很少只属于单一技能。

模式：

• 编排 — 对于任何 Go 编码、审查、调试或设置任务，同时加载主要技能和所有适用的次要技能。
• 消歧 — 当两个技能似乎有所重叠时，展示边界表。参见 disambiguation.md。
• 配置 — 将始终加载指令写入项目的 Agent 配置文件（CLAUDE.md、AGENTS.md 或同等文件），以加载 golang-how-to 本身；还可选择添加 ## Required Go skills 区块。请遵循 project-config.md。

问题： 在配置模式下，通过环境提供的提问工具询问用户——绝不要用纯文本提问。一次只问一个问题，并等待回答。如果环境没有提问工具，则用文字提问，并提供相同选项。

依赖项： gopls — go install golang.org/x/tools/gopls@latest；Claude Code 内置的 LSP 工具还需要设置 ENABLE_LSP_TOOL=1 并配置 Go 语言服务器（参见 使用 gopls 进行代码导航）。

技能加载

对于每项任务，请同时加载主要技能和所有适用的次要技能。不要等待——一开始就一起加载。

意图	主要技能	同时加载
设计 API、选择模式	golang-design-patterns	golang-structs-interfaces、golang-naming
为类型、函数或包命名	golang-naming	golang-code-style
以符合 Go 惯例的方式处理错误	golang-error-handling	golang-safety（涉及大量 nil 值的代码）
编写 goroutine、channel、同步代码	golang-concurrency	golang-context（涉及取消时）
传递截止时间／取消操作	golang-context	golang-concurrency（涉及 goroutine 时）
设计结构体、嵌入类型、使用接口	golang-structs-interfaces	golang-design-patterns
数据库查询和事务	golang-database	golang-error-handling、golang-security
构建 gRPC 服务	golang-grpc	golang-testing、golang-error-handling
构建 GraphQL API	golang-graphql	golang-testing、golang-error-handling
构建 CLI 命令树	golang-spf13-cobra	golang-cli、golang-spf13-viper（涉及配置时）
从标志／环境变量／文件分层加载配置	golang-spf13-viper	golang-spf13-cobra
编写测试	golang-testing	golang-stretchr-testify（使用 testify 时）
应用优化模式	golang-performance	golang-benchmark（先进行测量）
使用 pprof／benchstat 进行测量	golang-benchmark	golang-performance（修复时）、golang-troubleshooting（查找根因时）
调试 panic 或异常行为	golang-troubleshooting	golang-safety、golang-benchmark（与性能有关时）
在生产环境中监控	golang-observability	golang-performance（SLO 未达标时）
审计安全漏洞	golang-security	golang-safety、golang-lint
检查格式和风格	golang-code-style	golang-naming、golang-lint
重构或重新组织现有代码	golang-refactoring	golang-naming、golang-code-style、golang-project-layout
配置 golangci-lint	golang-lint	golang-code-style
编写 godoc／README／CHANGELOG	golang-documentation	golang-naming
设置新的项目结构	golang-project-layout	golang-design-patterns、golang-dependency-injection、golang-lint
设置 CI/CD 流水线	golang-continuous-integration	golang-lint、golang-security
选择库	golang-popular-libraries	相关的库专用技能
查找包的文档、版本、使用者或 CVE	golang-pkg-go-dev	golang-dependency-management
浏览、诊断或重构本地代码（定义、引用、重命名）	golang-gopls	—
采用新的 Go 语言特性	golang-modernize	golang-lint
使用 samber/lo（切片／映射辅助工具）	golang-samber-lo	golang-data-structures、golang-performance
使用 samber/oops（结构化错误）	golang-samber-oops	golang-error-handling
使用 log/slog	golang-samber-slog	golang-observability、golang-error-handling
使用依赖注入	golang-dependency-injection	golang-google-wire 或 golang-uber-dig 或 golang-uber-fx 或 golang-samber-do

以上技能标识符均为 samber/cc-skills-golang@<name> 的简称。

使用 gopls 导航代码

gopls 为 Go 提供语义代码智能功能，包括跳转到定义、查找引用、诊断、包 API、符号搜索和重构。→ 请参阅 samber/cc-skills-golang@golang-gopls skill，了解使用它的三种方式（其自带的 MCP 服务、原生 LSP 工具和 CLI）、完整的功能矩阵，以及高效的读取／编辑工作流。

gopls 只会分析本地构建中存在且可解析的代码：你的工作区，以及 go.sum 中精确锁定的所有依赖项（包括 replace 指令）。对于任何与本地构建无关的信息——版本历史、许可证、整个生态系统中导入该包的项目，以及尚未添加的包——请使用 golang-pkg-go-dev（godig）。完整的职责边界请参阅下文的 godig 与 gopls、Context7 和 govulncheck 的对比部分。

godig、gopls、Context7 与 govulncheck 的对比

有四种工具可以回答“这个依赖项是否适合使用”，它们之间的重叠并不像表面上看起来那么多：

• Context7 是通用的跨语言文档获取工具——没有更具体的来源时很有用。对于 Go 包或模块，godig 几乎总是更好的选择：它直接从 pkg.go.dev 获取结构化的 Go 专属数据，包括准确的版本、带签名的导出符号、可运行示例、imported-by 和已知漏洞；而 Context7 提供的是通用的抓取／整理文档，既不包含这些结构化数据，也可能滞后或遗漏不太知名的 Go 模块。只有在某个依赖项确实没有文档，或其文档未被 pkg.go.dev 索引时，才使用 Context7。
• godig 回答有关已发布生态系统的问题：任何 Go 包或模块，无论是否已加入 go.mod——它会调用远程 pkg.go.dev API，且不会访问你的本地检出内容。它的 vulns 命令会报告某个包／版本已知的 CVE，不考虑你的构建是否实际到达存在漏洞的代码路径。
• gopls（→ samber/cc-skills-golang@golang-gopls，可通过其 MCP 服务、原生 LSP 工具或 CLI 使用）回答有关你的特定构建的问题：你的代码以及 go.sum 中精确锁定的所有依赖项，包括指向 fork 或本地路径的 replace 指令——godig 和 Context7 都无法查看这些内容。它的 go_vulncheck 操作会针对工作区当前状态，按需执行一次可达性检查。
• govulncheck（独立 CLI，由 samber/cc-skills-golang@golang-security skill 封装）用于审计整个代码树：它会遍历整个模块的调用图，以确认哪些已知漏洞实际可达；对于 CI 门禁和定期安全扫描，它是权威工具——gopls 的 go_vulncheck 是同类分析的轻量级单次版本，适合在编辑过程中使用。

根据任务选择：

任务	工具	用法
在自己的仓库中查找符号定义的位置	gopls	samber/cc-skills-golang@golang-gopls — go_search，然后使用 go_file_context
了解文件在包内的依赖关系	gopls	samber/cc-skills-golang@golang-gopls — go_file_context
跳转到依赖项确切解析出的源代码（包括 fork 和通过 replace 替换的版本）	gopls	samber/cc-skills-golang@golang-gopls — go_package_api，或原生 LSP 工具的 goToDefinition
查找自己代码中引用依赖项符号的所有调用点	gopls	samber/cc-skills-golang@golang-gopls — go_symbol_references — godig 的 imported-by 只会列出公开的 包，不会列出仓库中的调用点
编辑后立即获取编译器诊断	gopls	samber/cc-skills-golang@golang-gopls — go_diagnostics（MCP），或使用原生 LSP 工具自动获取
在编辑过程中，检查当前构建是否可能触及已知漏洞	gopls	samber/cc-skills-golang@golang-gopls — go_vulncheck
重命名、提取、内联或以其他方式重构本地代码	gopls	samber/cc-skills-golang@golang-gopls — 安全重命名、refactor.* 代码操作
对整个模块进行全树漏洞审计（CI、定期扫描）	govulncheck	samber/cc-skills-golang@golang-security 技能 — govulncheck ./...
列出已发布包的可用版本	godig	godig versions <path>
检查尚未添加的包或版本是否存在已知 CVE	godig	godig vulns <path>
查看已发布包的导出符号和签名	godig	godig symbols / symbol doc
获取符号的可运行代码示例	godig	godig symbol examples
阅读包渲染后的 README/文档	godig	godig module readme / package doc
查看整个公开生态系统中有哪些包导入了某个包	godig	godig imported-by
搜索包或库候选项	godig	godig search
检查包或模块的许可证	godig	godig package licenses / module licenses
获取非 Go 库的文档，或获取未被 pkg.go.dev 索引的 Go 模块文档	Context7	resolve-library-id / query-docs

有关完整的 godig 命令参考，请参阅 samber/cc-skills-golang@golang-pkg-go-dev 技能；有关全树 govulncheck 修复工作流，请参阅 samber/cc-skills-golang@golang-security 技能。

类别一览

完整目录及“适用场景”说明：by-category.md

类别	技能
代码质量	golang-code-style golang-documentation golang-error-handling golang-lint golang-naming golang-safety golang-security golang-structs-interfaces
架构与设计	golang-concurrency golang-context golang-data-structures golang-database golang-dependency-injection golang-design-patterns golang-modernize golang-refactoring
质量保证与性能	golang-benchmark golang-observability golang-performance golang-testing golang-troubleshooting
项目设置	golang-cli golang-continuous-integration golang-dependency-management golang-gopls golang-pkg-go-dev golang-popular-libraries golang-project-layout golang-stay-updated
API	golang-graphql golang-grpc golang-swagger
依赖注入	golang-dependency-injection golang-google-wire golang-uber-dig golang-uber-fx golang-samber-do
框架	golang-spf13-cobra golang-spf13-viper
samber/*	golang-samber-do golang-samber-hot golang-samber-lo golang-samber-mo golang-samber-oops golang-samber-ro golang-samber-slog
测试	golang-stretchr-testify golang-testing

竞争集群——边界划分

完整的边界表及路由示例：disambiguation.md

主要集群及其归属：

• 性能：golang-performance（优化模式） · golang-benchmark（测量） · golang-troubleshooting（根本原因） · golang-observability（持续运行的生产环境）
• DI：golang-dependency-injection（概念/决策） · golang-google-wire（编译时） · golang-uber-dig（运行时反射） · golang-uber-fx（生命周期框架） · golang-samber-do（类型安全容器）
• samber/*：golang-samber-lo（有限变换） · golang-samber-ro（响应式流） · golang-samber-mo（单子类型）
• 错误：golang-error-handling（惯用法） · golang-samber-oops（结构化错误） · golang-safety（防止 panic）
• 风格：golang-code-style · golang-naming · golang-lint · golang-documentation
• CLI：golang-cli（架构） · golang-spf13-cobra（命令树） · golang-spf13-viper（配置分层）
• 包查询：golang-pkg-go-dev（查询 pkg.go.dev 中已有的路径：版本/文档/符号/导入者/CVE） · golang-gopls（导航/重构本地解析的构建） · golang-popular-libraries（选择要采用的库） · golang-dependency-management（管理 go.mod） · golang-security（扫描整个代码树中的 CVE）
• 空缺——类型与架构：golang-structs-interfaces（类型设计）与 golang-design-patterns（架构模式）
• 空缺——goroutine 与取消：golang-concurrency + golang-context——通过 context 取消 goroutine 时同时加载
• 空缺——正确性与威胁：golang-safety（内部错误）与 golang-security（外部威胁）
• 空缺——特性与规则：golang-modernize（采用语言特性）与 golang-lint（静态分析配置）
• 空缺——流程与目标规则：golang-refactoring（安全、分阶段、大规模修改现有代码的_流程_——包括规划、排序、由 gopls 驱动的操作方式、分阶段 PR）与 golang-naming/golang-code-style/golang-project-layout/golang-design-patterns/golang-modernize（规定最终代码应呈现的样子）——除负责目标形态的技能外，同时加载 golang-refactoring

配置模式

在项目的 Agent 配置文件（CLAUDE.md、AGENTS.md、GEMINI.md、Cursor 规则或 Copilot 指令——以项目使用的运行框架读取的文件为准）中，为 golang-how-to 本身写入始终加载指令，也可以强制触发特定的次要技能。

samber/cc-skills-golang@golang-project-layout 会在创建项目时自动写入始终加载指令，无需用户确认——它只占用一条技能描述，且不会强加任何项目特定选择。如果缺少该指令，运行 /golang-how-to configure 也会写入；此外，还会让用户确认一个 ## Required Go skills 区块，用于指定路由规则之外必须始终生效的技能。请参阅 project-config.md。

---

此技能并未涵盖所有内容。详细指导请参阅各个技能文件和 Go 官方文档。

如果你在此技能插件中遇到错误或意外行为，请前往 https://github.com/samber/cc-skills-golang/issues 提交问题。