参与go-modern-guidelines社区：Issue、PR与生态扩展全指南

参与go-modern-guidelines社区：Issue、PR与生态扩展全指南

【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelines

go-modern-guidelines 是一个帮助 AI 编程智能体（AI Coding Agent）写出现代化 Go 代码的开源项目。本完整指南面向新手，带你从零开始学会三件事：如何提交能快速得到响应的 Issue、如何贡献你的第一个现代 Go 编码指南 PR，以及如何把这个指南生态扩展到你自己的 AI 开发工具中。

先认识项目：为什么 AI 需要"现代 Go 指南"

很多 AI 编程助手写出的 Go 代码偏"老派"：明明项目用 Go 1.24，它却还在写for i := 0; i < n; i++，而不是for i := range n。原因有两个：训练数据滞后（模型不知道新特性）和频率偏差（旧写法在语料里更多）。

go-modern-guidelines 的解法是给 AI 一份显式参考清单，覆盖 Go 1.0 到 1.27 的实用特性。它以一个小 CLI 运行，核心只有两个命令（见 internal/cli/cli.go）：

• list：解析项目的 Go 版本后，返回该版本可用的现代写法清单（新特性优先排序）
• explain：按指南 ID 返回详细说明和 Before/After 代码示例

版本解析的优先级是：显式指定 →go.mod/go.work→ 本地工具链，实现见 internal/goversion/goversion.go。

核心模块速览

本地开发环境快速配置：一条命令跑通全部测试

🔧 参与贡献前，先把本地环境搭好，只需三步：

1️⃣ 克隆仓库并初始化：

git clone https://gitcode.com/GitHub_Trending/go/go-modern-guidelines cd go-modern-guidelines

2️⃣ 运行全部测试（等价于go test ./...）：

make test

3️⃣ 熟悉 Makefile 提供的四个维护命令：

💡 环境要求：Go 工具链需在 PATH 中；CLI 面向 Go 1.25 及以上，老版本在GOTOOLCHAIN=auto（默认值）下可自动切换工具链。

如何提交能快速得到响应的 Issue

📌 这个项目的合并门槛并不高，社区贡献者的小改动都在 CHANGELOG.md 里有名有姓：

• #2：修正time.Tick在 Go 1.23 的表述
• #8：新增 skills.sh 安装支持
• #23：修正strings_clone指南的可用版本（Go 1.18 起）

提交 Issue 时，建议按以下结构组织，维护者能更快定位：

1. 环境信息：你的 Go 版本（go env GOVERSION）、项目go.mod中声明的版本
2. 复现命令：list或explain的完整调用方式与输出
3. 预期 vs 实际：例如"Go 1.24 的项目用list时没看到某条指南"

🎯 适合新手认领的 Issue 类型：

• 文档勘误：FEATURES.md 中某条指南的版本号、描述或示例有误
• 补充示例：某条指南缺少典型 Before/After 对比
• 版本覆盖：新版 Go 发布后，跟进新特性的指南条目

你的第一个 PR：新增一条现代 Go 指南

这是本项目最核心的贡献方式。指南数据是"单一事实来源"，流程固定且可验证：

第一步：编辑 guidelines.json

在文件顶部按新特性优先顺序插入新条目。schema.go 会做严格校验，PR 不满足以下规则会直接失败：

• id：只能用小写字母、数字、下划线，且全局唯一
• since_version：必须是major.minor格式，且整份文件按版本从新到旧排序
• impact：只能是Critical、High、Medium、Low四档
• 每条指南必须包含guideline（一句话规则）、details（详细说明）和至少一组非空的 Before/After 示例

第二步：重新生成文档并测试

make generate-features # 由 featuresgen 重新生成 FEATURES.md make test # 确保数据与文档一致

⚠️ FEATURES.md 首行注明了"由 JSON 生成，勿手改"，请一定通过生成器更新它。

第三步：本地预览效果（强烈推荐）

在提 PR 前，你可以让本地构建替代正式发布版本，直接在 AI 智能体里体验你的改动（见 README.md 的 Local development 章节）：

make dev-install export GO_MODERN_GUIDELINES_DEV=1 # 启动智能体前导出此变量

之后任意安装了该插件的智能体（Claude Code、Codex、Cursor 均可）都会运行你的本地构建。改完代码再跑一次make dev-install即可热更新；make dev-uninstall可还原。Windows 或无make的环境可直接执行 scripts/dev-install.ps1 / scripts/dev-install.sh。

第四步：更新 CHANGELOG 并提交

按 CHANGELOG.md 的现有格式，在Unreleased下补一行### Added或### Fixed，即可提交 PR。

生态扩展：把指南接入你常用的 AI 智能体

🌱 不想改代码、只想扩展生态？这个项目天然支持多智能体接入，插件清单见 plugin/extension.json，技能定义见 plugin/skills/use-modern-go/SKILL.md。官方已内置四类集成：

完整的安装与更新命令都写在 README.md 中，照着执行即可。

技能是如何驱动智能体的

SKILL.md 定义了明确的工作流：智能体在改 Go 代码前先调用list（优先传入要编辑的文件路径），读完完整清单后再针对拿不准的条目调用explain。命令封装脚本为 run-tool.sh 与 run-tool.ps1，首次运行时会自动把 CLI 安装到本地缓存目录，不污染项目本身。如果你想给自己的智能体接入同类能力，直接参考这套"先 list 后 explain"的调用约定即可。

贡献者流程：从 Fork 到合并的完整清单

✅ 提交流程速查：

1. 克隆仓库，make test确认基线通过
2. 修改 guidelines.json（数据）或其他模块
3. make generate-features同步 FEATURES.md
4. make dev-install+ 设置GO_MODERN_GUIDELINES_DEV=1在真实智能体里验证
5. make test全部通过
6. 更新 CHANGELOG.md
7. 提交 PR，附上改动动机与验证结果

🚀 从修正一个版本号，到新增一条 Go 1.27 新特性指南，再到为新的 AI 智能体写适配——go-modern-guidelines 为每种参与深度都留了位置。选一个最适合你的切入点，今天就发出你的第一个 Issue 吧。

【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelines