go-modern-guidelines

现代 Go 编码指南

本仓库包含为代码智能体编写的指南，帮助它们编写现代 Go 代码。

例如，遵循这些指南的智能体会使用 max(a, b) 而不是 if-else 块，使用 slices.Contains 而不是手动循环，使用 cmp.Or(a, b, c) 而不是一连串 nil 检查。它也知道一些新增特性，比如用 new(42) 获取指向值的指针，以及用 errors.AsType[T](err) 进行类型安全的错误匹配——两者都来自 Go 1.26。

这些指南涵盖了从 Go 1.0 到 Go 1.27 之间最有用的特性，包括 modernize 分析器所针对的所有内容。智能体将会：

• 从 go.mod 检测项目的 Go 版本
• 使用该版本及之前版本中可用的语言特性和标准库新增功能
• 更倾向于采用现代惯用法，而不是旧模式

动机

所有编码智能体都倾向于生成过时的 Go 代码。原因有二：

1. 训练数据滞后。 模型不知道训练截止日期之后新增的特性。如果模型从未见过 errors.AsType[T]（Go 1.26），它就无法使用它。

2. 频率偏差。 即使模型知道某些特性，它也常常选择旧模式。训练数据中 for i := 0; i < n; i++ 比 for i := range n 出现得更多，所以输出结果往往也是前者。

这些指南通过为智能体提供明确的参考，解决了这两个问题。

这与 Go 团队的方向一致。modernize 分析器用于自动更新已有代码，使其使用更新的惯用法（参见 Go 团队的这个演讲）。这些指南对于新代码也有同样的目标：智能体从一开始就编写现代 Go，以后需要修复的内容就更少。

要求

这些市场集成首次使用时，会通过 go install 安装一个小型 CLI。因此，必须安装 Go 工具链，并将其加入你的 PATH。

CLI 会安装到本地缓存（例如 ~/.cache/go-modern-guidelines），并且永远不会修改你的项目。它面向 Go 1.25 或更高版本；在更旧的 Go 上，只要启用了自动工具链切换（GOTOOLCHAIN=auto，默认开启）仍可工作，Go 会在首次运行时获取兼容的工具链。

使用说明

这些指南适用于 Junie、Claude Code、Codex 和 Cursor，并可通过 skills.sh 用于其他智能体。

Junie

Junie CLI

在 Junie CLI 会话中运行以下命令。

1. 将此仓库添加为市场：

/extensions marketplace add JetBrains/go-modern-guidelines

1. 安装扩展：

/extensions install modern-go-guidelines

当与 Go 任务相关时，Junie 会自动调用该技能。

更新

在 Junie CLI 会话中更新已安装的扩展：

/extensions update modern-go-guidelines

Claude Code

安装

在 Claude Code 会话中运行以下命令。

1. 将此仓库添加为市场：

/plugin marketplace add JetBrains/go-modern-guidelines

1. 安装插件：

/plugin install modern-go-guidelines@goland-claude-marketplace

使用方法

当与 Go 任务相关时，Claude Code 会自动调用该技能。

要显式调用它：

/modern-go-guidelines:use-modern-go

更新

Claude Code 可以在启动时自动更新市场和已安装的插件。对于第三方市场，自动更新默认是关闭的，所以请启用一次：

1. 运行 /plugin。
2. 打开 Marketplaces，选择 goland-claude-marketplace。
3. 选择 Enable auto-update。

当 Claude Code 提示插件已更新时，使用以下命令将新版本应用到当前会话：

/reload-plugins

若要改为手动更新，请在终端中运行以下命令：

claude plugin marketplace update goland-claude-marketplace
claude plugin update modern-go-guidelines@goland-claude-marketplace

Codex

安装

在终端中运行以下命令。

1. 将此仓库添加为市场：

codex plugin marketplace add JetBrains/go-modern-guidelines

1. 安装插件：

codex plugin add modern-go-guidelines@goland-codex-marketplace

更新

刷新市场并重新安装插件，以便 Codex 替换其缓存的副本：

codex plugin marketplace upgrade goland-codex-marketplace
codex plugin remove modern-go-guidelines@goland-codex-marketplace
codex plugin add modern-go-guidelines@goland-codex-marketplace

Cursor

为方便起见，这些指南以 Cursor 插件的形式分发。

安装

1. 通过在终端中运行以下命令，将此仓库添加为市场：

cursor-agent plugin marketplace add https://github.com/JetBrains/go-modern-guidelines

1. 在 Cursor 会话中使用 /plugins 命令安装插件。

更新

从 Git 刷新市场，然后重新打开 Cursor，以便它获取新的插件版本：

cursor-agent plugin marketplace update goland-cursor-marketplace

如果已安装的插件仍然停留在旧版本，请使用 /plugins 命令重新安装。Cursor 目前不提供用于更新已安装插件的非交互式 CLI 命令。

其他智能体（通过 skills.sh）

同一个技能包也适用于其他智能体，例如 OpenCode。使用以下命令安装：

npx skills add JetBrains/go-modern-guidelines

（--skill use-modern-go 仅安装此技能。）

更新

使用以下命令更新项目级安装的技能：

npx skills update use-modern-go -p -y

对于全局安装的技能，将 -p 替换为 -g。

本地开发

要在你的智能体中试用 CLI 的改动，请将此工作副本构建到工具的缓存中：

make dev-install

然后在智能体运行的环境中设置 GO_MODERN_GUIDELINES_DEV=1。设置后，任何使用该插件的智能体都会运行你的本地构建，而不是发布版本，在 Claude Code、Codex 和 Cursor 中的方式相同。请在启动智能体之前导出它，以便智能体进程继承该变量：

export GO_MODERN_GUIDELINES_DEV=1

编辑 CLI 后，再次运行 make dev-install 进行重建；下一次调用会使用新构建。要恢复到发布版本，请取消设置该变量（或运行 make dev-uninstall 删除该构建）：

make dev-uninstall

这需要 Go 工具链。开发构建存储在工具的缓存目录中（$XDG_CACHE_HOME/go-modern-guidelines 或 ~/.cache/go-modern-guidelines）。

构建由 scripts/dev-install.sh 驱动，它特意与面向智能体的包装器分开，因此智能体永远无法触发构建。在没有 make 的情况下（例如在 Windows 上），你可以直接运行它：

sh scripts/dev-install.sh install       # or: uninstall
pwsh scripts/dev-install.ps1 install    # PowerShell equivalent