https://godvvvzzz.github.io/tags/guidelines/Recent content in Guidelines on VvVzzz BlogHugo -- gohugo.iozh-cnWed, 09 Sep 2026 20:30:00 +0800https://godvvvzzz.github.io/p/go-modern-guidelines/Wed, 09 Sep 2026 20:30:00 +0800https://godvvvzzz.github.io/p/go-modern-guidelines/ <blockquote> <p>收录于：<a class="link" href="https://godvvvzzz.github.io/p/awesome-open-source-repos/" >开源仓库收藏夹</a></p> </blockquote> <p><strong>仓库</strong>：<a class="link" href="https://github.com/JetBrains/go-modern-guidelines" target="_blank" rel="noopener" >github.com/JetBrains/go-modern-guidelines</a> · <strong>许可</strong>：Apache-2.0 · <strong>来源</strong>：JetBrains 官方项目</p> <h2 id="它是什么"><a href="#%e5%ae%83%e6%98%af%e4%bb%80%e4%b9%88" class="header-anchor"></a>它是什么 </h2><p>给<strong>编码 Agent</strong> 用的现代 Go 写法指南。装上之后，Agent 会：</p> <ul> <li>用 <code>max(a, b)</code> 而不是 if-else 取大</li> <li>用 <code>slices.Contains</code> 而不是手写循环</li> <li>用 <code>cmp.Or(a, b, c)</code> 而不是一串 nil 检查</li> <li>知道 <code>new(42)</code> 取值指针、<code>errors.AsType[T](err)</code> 类型安全错误匹配（Go 1.26）</li> </ul> <p>覆盖 <strong>Go 1.0 → 1.27</strong> 最有用的特性，包括 Go 官方 <code>modernize</code> analyzer 的全部目标。完整清单在 <a class="link" href="https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md" target="_blank" rel="noopener" >FEATURES.md</a>。</p> <p>Agent 行为约定：</p> <ol> <li>从 <code>go.mod</code> <strong>检测项目 Go 版本</strong></li> <li>只用 ≤ 该版本的语言/标准库特性</li> <li><strong>优先现代惯用法</strong>，而不是老写法</li> </ol> <h2 id="动机写得很准"><a href="#%e5%8a%a8%e6%9c%ba%e5%86%99%e5%be%97%e5%be%88%e5%87%86" class="header-anchor"></a>动机写得很准 </h2><p>Agent 生成「过时 Go」几乎必然，原因只有两个：</p> <table> <thead> <tr> <th>问题</th> <th>含义</th> </tr> </thead> <tbody> <tr> <td><strong>训练数据滞后</strong></td> <td>训练截止后加的 API（如 <code>errors.AsType[T]</code>）模型根本没见过</td> </tr> <tr> <td><strong>频率偏置</strong></td> <td>见过也不一定用：语料里 <code>for i := 0; i &lt; n; i++</code> 远多于 <code>for i := range n</code></td> </tr> </tbody> </table> <p>指南的解法很直接：<strong>给 Agent 一份显式参考</strong>，而不是指望模型「自己想起来」。</p> <p>这也和 Go 团队方向对齐：<code>modernize</code> 负责把旧代码改新，这份指南负责让<strong>新代码一开始就新</strong>。</p> <h2 id="形态小-cli--多端插件"><a href="#%e5%bd%a2%e6%80%81%e5%b0%8f-cli--%e5%a4%9a%e7%ab%af%e6%8f%92%e4%bb%b6" class="header-anchor"></a>形态：小 CLI + 多端插件 </h2><p>不是纯 Markdown 甩给模型——各 market 集成会在首次使用时 <code>go install</code> 一个小 CLI，装进本地缓存（如 <code>~/.cache/go-modern-guidelines</code>），<strong>不改动你的项目</strong>。</p> <p>要求：PATH 上有 Go toolchain，目标 <strong>Go 1.25+</strong>；更旧版本在 <code>GOTOOLCHAIN=auto</code>（默认）下也能拉兼容 toolchain。</p> <p>支持面：</p> <table> <thead> <tr> <th>客户端</th> <th>方式</th> </tr> </thead> <tbody> <tr> <td>Junie</td> <td><code>/extensions marketplace add JetBrains/go-modern-guidelines</code></td> </tr> <tr> <td>Claude Code</td> <td><code>/plugin marketplace add</code> + <code>modern-go-guidelines@goland-claude-marketplace</code></td> </tr> <tr> <td>Codex</td> <td><code>codex plugin marketplace add</code> + <code>goland-codex-marketplace</code></td> </tr> <tr> <td>Cursor</td> <td><code>cursor-agent plugin marketplace add …</code></td> </tr> <tr> <td>其他（OpenCode 等）</td> <td><code>npx skills add JetBrains/go-modern-guidelines</code></td> </tr> </tbody> </table> <p>Claude Code 装完后 Go 任务会<strong>自动触发</strong>；也可显式 <code>/modern-go-guidelines:use-modern-go</code>。</p> <h2 id="值得学的两个工程细节"><a href="#%e5%80%bc%e5%be%97%e5%ad%a6%e7%9a%84%e4%b8%a4%e4%b8%aa%e5%b7%a5%e7%a8%8b%e7%bb%86%e8%8a%82" class="header-anchor"></a>值得学的两个工程细节 </h2><p><strong>1. 按 <code>go.mod</code> 探测版本</strong><br> 避免 Agent 在 Go 1.21 项目里写出 1.26 才有的 API——这是「知识」和「项目约束」分开的干净做法。</p> <p><strong>2. 构建脚本与 Agent 隔离</strong><br> <code>scripts/dev-install.sh</code> 故意和面向 Agent 的 wrapper 分开：<strong>Agent 永远不能触发本地构建</strong>。本地调试靠 <code>make dev-install</code> + <code>GO_MODERN_GUIDELINES_DEV=1</code>，与 Claude Code / Codex / Cursor 走同一套缓存路径。</p> <h2 id="上手claude-code-示例"><a href="#%e4%b8%8a%e6%89%8bclaude-code-%e7%a4%ba%e4%be%8b" class="header-anchor"></a>上手（Claude Code 示例） </h2><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">/plugin marketplace add JetBrains/go-modern-guidelines </span></span><span class="line"><span class="cl">/plugin install modern-go-guidelines@goland-claude-marketplace </span></span></code></pre></div><p>其他客户端安装与更新见 <a class="link" href="https://github.com/JetBrains/go-modern-guidelines#instructions" target="_blank" rel="noopener" >仓库 README</a>。</p> <h2 id="适合谁"><a href="#%e9%80%82%e5%90%88%e8%b0%81" class="header-anchor"></a>适合谁 </h2><ul> <li>用 Agent 写 Go，不想再 review「上古写法」</li> <li>团队想统一「新项目直接用新惯用法」，而不是事后 <code>modernize</code> 改</li> <li>在做 <strong>language-specific Agent guideline</strong> 时，可当范本看：动机、版本门控、多端分发、CLI 与 agent 隔离</li> </ul> <h2 id="和收藏夹里其他项目的关系"><a href="#%e5%92%8c%e6%94%b6%e8%97%8f%e5%a4%b9%e9%87%8c%e5%85%b6%e4%bb%96%e9%a1%b9%e7%9b%ae%e7%9a%84%e5%85%b3%e7%b3%bb" class="header-anchor"></a>和收藏夹里其他项目的关系 </h2><ul> <li>同为「给 Agent 的技能/指南」→ <a class="link" href="https://godvvvzzz.github.io/p/pptx-generator/" >pptx-generator</a>（产物向）vs 本文（语言向）</li> <li>跑在各种 Harness 里 → <a class="link" href="https://godvvvzzz.github.io/p/pi/" >Pi</a>、Claude Code、Codex 等</li> <li>指南/技能沉淀与检索 → <a class="link" href="https://godvvvzzz.github.io/p/openviking/" >OpenViking</a></li> </ul> <hr> <p><em>最后更新：2026-09-09。信息基于公开 README 与仓库状态，使用前请以官方文档为准。</em></p>