为什么不让AI直接读文档？go-modern-guidelines的CLI中间层设计哲学
【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelines
go-modern-guidelines是一个面向 AI 编程代理的 Go 现代编码规范项目，它让 Claude Code、Codex、Cursor、Junie 等 AI 绕过"知识截止日期"，写出始终跟上 Go 语言演进的现代代码。这个项目最有意思的，不是它内置的 50 多条现代 Go 规范，而是它的CLI 中间层设计——为什么偏偏不让 AI 直接读文档？
🤔 "直接喂文档给AI"的三个坑
项目团队在 README.md 的 Motivation 部分点出了 AI 写出"老式 Go"的两个根因：
- 训练数据滞后：模型不知道训练截止后发布的新特性——它可能从未见过 Go 1.26 的
errors.AsType[T] - 频率偏差：训练语料里
for i := 0; i < n; i++远比for i := range n多，于是模型总倾向选旧写法
最朴素的解法是把规范文档塞进上下文让 AI 读。但静态文档有三个硬伤：
| 问题 | 后果 |
|---|---|
| 文档过长 | 挤占整个上下文窗口，稀释 AI 对真正任务的注意力 |
| 无版本感知 | AI 可能在 Go 1.21 项目里写 Go 1.24 特性，直接编译失败 |
| 知识易过时 | 文档要单独维护，且无法保证代理"读完全文" |
所以项目把"文档"变成了"工具"：AI 不再读文档，而是调用命令。
⚙️ CLI 中间层：三个核心职责
中间层的入口是 internal/cli/cli.go 中的list与explain两个子命令，配合指导代理调用行为的技能说明 SKILL.md。
① 版本闸门：自动探测项目 Go 版本并过滤
这是中间层最精妙的地方——同一份知识，不同项目看到不同内容。list命令调用 goversion.Resolve 按三级回退策略探测版本：
--go-version（显式指定）→ 向上查找 go.mod / go.work → go env GOVERSION（本地工具链）拿到版本后，supportedGuidelines 只返回"引入版本 ≤ 项目版本"的规范，并按"最新优先"排序。AI 因此永远不会收到当前项目里编译不过的规范——这种动态过滤是静态文档做不到的。
② 两级检索：先 list 后 explain，省 token 预算
中间层把文档拆成了两级粒度：
list --file-path path/to/file.go：每条规范一行，轻量"索引"explain sync_waitgroup_go：按需取回某条规范的详解与 Before/After 示例
SKILL.md 明确要求代理"先调 list 并读完全部输出，只在需要时才对具体 ID 调 explain"。这本质是渐进式披露：模型先扫索引再定点深入，而不是一次性吞下所有规范的完整示例。
③ 单一事实源，双重渲染：人和 AI 读同一份数据
所有规范数据只存在于 guidelines.json 这一个文件，并通过go:embed编译期嵌入二进制（见 guidelines.go）：
guidelines.json（单一事实源） ├── featuresgen 渲染 ──→ FEATURES.md（人类可读文档） └── go:embed 编译 ──→ CLI（list / explain）──→ 代理按需调用其中给人看的 FEATURES.md 由生成器 featuresgen/main.go 自动产出，文件开头就标注了"DO NOT EDIT"。规范一更新，人和 AI 同步拿到新内容，零分叉风险。
🛡️ 包装脚本：让代理"改不动"你的项目
代理如何拿到这个 CLI？答案是包装脚本 run-tool.sh，它做了一件很克制的事：
- 懒安装：首次调用时才把固定版本的 CLI
go install进本地缓存（如~/.cache/go-modern-guidelines），并校验安装后的版本号与声明一致 - 零侵入：全程只读取项目的
go.mod等文件，从不修改项目 - 防越权：本地开发构建脚本 dev-install.sh 刻意与代理可见的包装器分离——README 明确说这是"so an agent can never trigger a build"，只有开发者手动
make dev-install并设置GO_MODERN_GUIDELINES_DEV=1才能切换本地构建
这套"包装器 + 缓存 + 版本钉住"的组合，让 CLI 行为确定且可复现：代理拿到的知识只由声明的版本决定，与环境里碰巧装了什么无关。
💡 这套设计哲学对构建 AI 工具的启示
| 原则 | go-modern-guidelines 的落地 |
|---|---|
| 接口优于散文 | 文档变成稳定输入输出契约的命令，报错还会引导代理自我纠正（如"Run list to list available ids"） |
| 按需优于全量 | list/explain 两级检索，只给模型当下必须的信息 |
| 动态优于静态 | 版本过滤 + 数据嵌入二进制 + 版本钉住安装，知识新鲜度与模型训练数据解耦 |
🚀 快速上手
- 前置条件：安装 Go 工具链（要求 Go 1.25+，或启用
GOTOOLCHAIN=auto自动切换） - 在 Claude Code、Codex、Cursor 或 Junie 会话中，按 README.md 对应章节执行两条命令（添加 marketplace + 安装插件）即可
- 其他代理可运行
npx skills add JetBrains/go-modern-guidelines安装同一技能包 - 本地调试：
make dev-install后导出GO_MODERN_GUIDELINES_DEV=1，代理即会运行你的本地构建，make dev-uninstall可恢复发布版
【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelines
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
