让 AI 写 go-admin 代码，为什么十次有八次要返工？我们把踩过的坑写成了 Skill
一个很多人都遇到过的场景
把"帮我加一个商品管理模块"丢给 Claude Code、Cursor 或者随便哪个 AI 编程工具，十有八九能跑出一版代码——能编译，接口能通，你甚至能在 Postman 里调通。
然后你打开前端界面，侧边栏没有这个菜单。或者菜单有了，点进去接口报 403。或者代码是能用，但和项目里其他模块的写法完全是两套风格，过两周你自己都分不清哪个是 AI 写的、哪个是手写的。
问题不在模型笨。是它压根不知道你的项目现在长什么样。
为什么"直接让模型写"会失败
以 go-admin 为例，这是个横跨好几年的开源后台框架。早期版本里，每个业务模块都要手写 Api 和 Service，一个 Api 至少七个函数。这套写法在 GitHub 上留存量巨大，模型训练时看到的大概率就是这套。
但项目现在对单表增删改查推荐的是 Actions 模式——一个模块只要 model、dto、router 三个文件，参数绑定、数据权限过滤、分页这些都交给框架内置的通用 Action。
两种写法都能跑，模型不会报错，你短期内也发现不了。等项目里两套风格混在一起，再统一就是真金白银的返工成本。
这还只是后端代码风格。真正容易被忽略、而且错了也不会报错的，是另一件事：一个模块要在界面上真正可用，除了代码，还需要往 sys_api、sys_menu、sys_menu_api_rule、casbin_rule 四张表里写正确的种子数据——接口注册、菜单挂载、菜单和接口的关联、实际生效的权限策略。漏了任何一步，现象都是"看起来一切正常，但界面上要么没有菜单，要么按钮点不动"，没有任何报错提示。
我们怎么解决
第一层是 AGENTS.md。这是专门写给 AI 编码工具看的约定文件，go-admin 和它的前端仓库 go-admin-ui 根目录各有一份。它刻意做得很短，只写"不遵守就会出错"的规则，技术栈版本、命令这些交给 go.mod、package.json 自己说话，避免文档和代码脱节。
第二层是一份可编译、有测试、CI 会跑的参照实现（app/demo/）。文字描述会过时，但被 CI 持续验证的代码不会——这比任何规范文档都可靠。
这两层已经能让 AI 生成的代码风格对齐了，但还不够。风格对了，权限没配对，用户还是会卡在"界面上看不到菜单"这一步。于是我们把"新建一个业务模块"这件事，从一段散文式的操作说明，改写成了一个结构化、可以直接调用的 Skill——把表设计、迁移、Actions 模式代码生成、以及最容易漏掉的菜单/权限种子数据，串成一条端到端的流程，每一步都指向真实存在、可运行的参照文件，而不是让模型凭记忆现编。前端这边同理，做了一个对应的 Skill，负责生成标准的列表+表单页面，两边靠同一个权限标识字符串对齐。
这套思路值得抄的地方
不是所有项目都需要立刻上 Skill，但这个分层思路是通用的：
- 先写清楚"哪些是死规则"（AGENTS.md 式的文件），不遵守就会出编译错误或者运行时问题的那种，越短越好；
- 指向一个真实可跑的参照实现，而不是在文档里复述代码——文字会骗人，CI 跑过的代码不会；
- 把"容易漏、错了也不报错"的步骤单独拎出来讲清楚——go-admin 这里就是权限种子数据，几乎每个项目都有类似的"隐性依赖"；
- 重复性高的流程才值得写成 Skill，一次性的活儿写文档就够了，没必要为每件事都上工具化。
代码生成器解决的是"确定性、可复现"的标准 CRUD；AI 生成解决的是生成器覆盖不到的部分——业务逻辑、改造既有代码、补测试。两者不是竞争关系，选哪个看场景。
想看具体怎么做的
go-admin 是基于 Gin + Vue 3 的开源中后台框架，文档站上有完整的 用 AI 生成代码 这篇，讲了提示词该包含哪三个要素、以及新增模块、跨表业务、改造代码、补测试、写迁移这几种场景的可复制模板。
仓库地址：https://github.com/go-admin-team/go-admin（后端）、https://github.com/go-admin-team/go-admin-ui（前端，Element Plus 版）。欢迎 star，也欢迎在 AGENTS.md 或者 Skill 上提意见。
