为什么不让AI直接读文档go-modern-guidelines的CLI中间层设计哲学【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelinesgo-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.goguidelines.json单一事实源 ├── featuresgen 渲染 ──→ FEATURES.md人类可读文档 └── go:embed 编译 ──→ CLIlist / explain──→ 代理按需调用其中给人看的 FEATURES.md 由生成器 featuresgen/main.go 自动产出文件开头就标注了DO NOT EDIT。规范一更新人和 AI 同步拿到新内容零分叉风险。️ 包装脚本让代理改不动你的项目代理如何拿到这个 CLI答案是包装脚本 run-tool.sh它做了一件很克制的事懒安装首次调用时才把固定版本的 CLIgo 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_DEV1才能切换本地构建这套包装器 缓存 版本钉住的组合让 CLI 行为确定且可复现代理拿到的知识只由声明的版本决定与环境里碰巧装了什么无关。 这套设计哲学对构建 AI 工具的启示原则go-modern-guidelines 的落地接口优于散文文档变成稳定输入输出契约的命令报错还会引导代理自我纠正如Run list to list available ids按需优于全量list/explain 两级检索只给模型当下必须的信息动态优于静态版本过滤 数据嵌入二进制 版本钉住安装知识新鲜度与模型训练数据解耦 快速上手前置条件安装 Go 工具链要求 Go 1.25或启用GOTOOLCHAINauto自动切换在 Claude Code、Codex、Cursor 或 Junie 会话中按 README.md 对应章节执行两条命令添加 marketplace 安装插件即可其他代理可运行npx skills add JetBrains/go-modern-guidelines安装同一技能包本地调试make dev-install后导出GO_MODERN_GUIDELINES_DEV1代理即会运行你的本地构建make dev-uninstall可恢复发布版【免费下载链接】go-modern-guidelinesHelp AI coding agents write modern Go项目地址: https://gitcode.com/GitHub_Trending/go/go-modern-guidelines创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
