AI 生成的 Go 代码能编译却常需重写的原因

你让 Claude Code、Cursor 或任何你正在用的 AI 编程工具"添加一个商品管理模块"。大多数时候它生成的东西能编译通过。接口能正常响应。甚至可以用 Postman 调用。

然后你打开前端，菜单项不见了。或者说有了，点击进去却得到 403。或者代码能跑，但风格跟项目里其他部分完全不同，两周后你根本分不清哪些是 AI 写的、哪些不是。

模型不是问题所在。它只是完全不了解你的项目此刻长什么样。

为什么"直接问模型"会失败

以 go-admin 为例，这是一个开源的 Gin + Vue 3 后台管理框架。已经公开好几年了。在早期版本中，每个业务模块都需要手写 Api 和 Service 文件——每个 Api 至少七个函数。这种风格在 GitHub 上占很大比例，也几乎肯定在模型的训练数据中过度 representation。

不过当前代码库推荐的是一种基于 Actions 的单表 CRUD 模式：一个模块只需要三个文件——model、dto、router——参数绑定、数据范围过滤和分页都由框架内置的 Actions 处理。

两种风格都能编译通过。模型两种都不会警告你，你也不会立刻注意到。等到两种风格混在一个真实代码库中时，再统一回来需要实实在在的工程时间。

而这还只是后端代码风格。容易忽略且静默失败的部分完全不同：要使一个模块在 UI 中真正可用，还需要在四张表中写入正确的种子数据：sys_api、sys_menu、sys_menu_api_rule 和 casbin_rule——路由注册、菜单挂载、菜单与 API 的关联关系，以及实际的权限策略。漏掉任何一个，症状都一样：一切看起来正常，但菜单不出现，或者按钮没有任何反应。没有任何报错。

第一层是 AGENTS.md——一份专门为 AI 编程工具编写的约定文件，放在 go-admin 和 go-admin-ui（前端）根目录各一份。它刻意保持简短：只有忽略后会导致实际失败的规则。栈版本和命令由 go.mod 和 package.json 自行管理，这样文件就不会跟代码不同步。

第二层是一个参考实现，真正能编译、有测试、在 CI 中运行（app/demo/）。文字会过时。而 CI 持续锻炼的代码不会——它比任何规格文档都更可靠。

这两层能解决风格对齐问题，但仅靠它们还不够。代码可以很 idiomatic，但权限仍然可能出错，用户仍然只能盯着一个空空的侧边栏。所以我们把"添加一个新的业务模块"从一段文字描述变成了一个结构化的、可调用的 Skill——一个端到端的过程，覆盖表设计、迁移、Actions 模式脚手架，以及最容易忽略的菜单/权限种子数据步骤，每一步都指向一个真实的、可运行的参考文件，而不是让模型凭记忆重建。前端侧有一个配套的 Skill 用于脚手架化标准的列表+表单页面，两者通过一个共享字符串——权限标识符——保持同步。

即使不用 go-admin，也有值得借鉴的部分

不是每个项目都需要立即建立一个正式的 Skill，但其背后的分层思路可以推广：

写下哪些是真正的硬规则——一个 AGENTS.md 风格的文件，限定在"忽略它就会出问题"的范围。保持简短。

指向一个真实的、可运行的参考实现，而不是用文字描述模式。文字最终会撒谎；被 CI 持续锻炼的代码不会。

点出那个容易跳过且静默失败的步骤。对 go-admin 来说是权限种子数据。大多数 nontrivial 的系统都有等效的隐藏依赖。

只在真正重复的工作流上建立 Skill。一次性任务用文档更好；不是所有事情都需要工具化。

内置的代码生成器处理确定性的、可复现的部分——根据表定义生成标准 CRUD。AI 生成覆盖生成器做不到的部分：业务逻辑、重构、测试。它们不是竞争关系，用哪个取决于任务本身。

如果你想看细节

go-admin 是一个基于 Gin 和 Vue 3 构建的开源后台管理框架。文档中有完整的攻略，讲述如何为它提示 AI 生成代码——一份好的提示需要哪三样东西，还有添加模块、跨表业务逻辑、重构现有代码、补写测试、编写迁移的复制粘贴模板。

仓库：go-admin（后端）、go-admin-ui（前端，Element Plus 版）。欢迎对 AGENTS.md 文件或 Skill 本身提出反馈。