你有没有过这种体验？
兴冲冲用上 Claude Code、Codex 这些 AI 编程助手，想着终于能解放双手，让它帮我改 bug、做功能，结果发现 —— 这哪是帮手，分明是个添乱的！
让它改个小问题，它改完给你搞出一堆新报错；换个 AI 助手，之前教的规矩全忘了，又要重新教一遍怎么启动项目、哪些东西不能改；改完代码它自己也不知道对不对，还得我人工测一遍……
就像请了个钟点工来打扫，第一次来你家，不知道哪个抽屉不能碰，不知道你家的扫地机器人怎么开，擦完桌子也不知道有没有擦干净，最后你还得自己再收拾一遍烂摊子。
我最近就踩了这么个坑，花了一周时间，把我那个 400 万 + 下载的 Grafana 开源插件，从 “对 AI 极不友好” 改造成了 “AI 能独立干活” 的状态，今天就把这套改造经验分享给你，看完你也能把你家的 AI 助手调教好。
1. 刚升完级，我用了两年的插件直接罢工了
事情的起因很简单，我有个用了快两年的 Grafana 插件，叫 CompareQueries，解决的是 Grafana 原生没法给每条曲线单独设时间偏移的问题 —— 简单说就是你想同时看本月和上月的销售数据对比，不用来回切换时间，这个插件能帮你直接把两条线画在一张图里。
这个插件稳定跑了两年，社区里 400 多万人下载使用，本来相安无事，结果 Grafana 13 一更新，我突然收到用户的反馈：升级完插件，面板直接显示No data，彻底罢工了！
翻了更新日志才搞明白，Grafana 13 把我们插件依赖的 mixed 数据源功能给改成内部的了，第三方插件用不了了，这不就等于你开了个小餐馆，用了两年的配菜工具，平台突然更新把这个工具的入口给封了，你之前的配菜全用不了，客人点单直接出不了餐。
没办法，只能改代码适配，顺便把社区攒了好久的需求一起做了：比如支持告警、支持前后端混合模式，还要兼容从 8.4 到 13 所有的老版本。
本来想着用 Codex 辅助开发，能快点，结果越用越不对劲：这个 AI 怎么这么不靠谱？
改完后端代码，它不知道对不对，还得我自己跑一遍构建测一下；它还乱改东西，把我之前留的兼容性字段给改了，要不是我盯着，差点把老用户的面板搞崩了；换 Claude Code 来写，之前教 Codex 的规则全没用了，又要重新教一遍怎么启动环境、哪些不能改……
合着我不是雇了个帮手，是雇了个啥都不懂的学徒，还得我手把手教，教完一个换一个又要重新教？
2. 原来我的代码仓库，对 AI 来说就是个盲盒
折腾了两天我才反应过来：不是 AI 不行，是我的仓库，对 AI 来说根本就是个盲盒！
以前我们写代码，仓库是给人看的，README 写个大概，剩下的规矩都在老开发者的脑子里：哪个目录不能动、哪个字段改了会崩、怎么启动本地环境、改完要测什么…… 这些东西人来了慢慢学能学会，可 AI 不行啊！
AI 干活的逻辑很简单：它在有限的上下文里循环，读代码→规划→改代码→看结果→继续。可如果你的仓库没给它说清楚这些事，它进来就是盲人摸象：
它不知道哪个目录不能碰，随手就把配置文件给改了
它不知道改完要怎么验证，改完就提交，结果 CI 爆了
它不知道怎么启动本地环境，改完代码也不知道实际效果好不好
换个 AI，之前的上下文全丢了，又要重新教一遍所有规矩
就像那个钟点工，你没给她说家里的规矩，她不知道你家那个抽屉里有贵重物品不能碰，不知道你家的扫地机器人要按这个按钮才能开，擦完桌子也不知道要检查有没有擦干净，最后只能瞎忙活，越帮越乱。
既然要改，干脆一步到位：把这个仓库改造成 AI 能独立接手的状态，让它自己就能跑完 “读代码→改→测→提交 PR” 整个流程，不用我再盯着。
3. 第一步：给 AI 装个自动质检机，改完立刻验对错
改造的第一步，先解决 “改完不知道对不对” 的问题。
之前我的项目只有前端的单测，改了后端的 Go 代码，根本没有自动检查，AI 改完，我得自己拉下来跑一遍构建、测一遍功能，不然根本不知道它有没有搞坏东西。
这不就像外卖店，打包完餐，没有自动检查，骑手拿了就走，送到客人手里才发现漏了菜、放错了餐，那时候再改就晚了。
所以我第一件事就是把 CI 流水线补全了，做了一条完整的验证链：
不管你改的是前端的 React 组件，还是后端的 Go 代码，只要你提交了 PR，流水线自动帮你跑：
前端的 lint、单测、构建
后端的 lint、单测、构建
产物的打包校验
所有步骤跑完，绿了就是没问题，红了就是哪里错了。
这样一来，AI 改完代码，自己看 CI 的结果就知道有没有搞坏东西了，不用我再人工测一遍，就像外卖打包完，自动过一遍质检机，有没有漏菜、有没有放错，一眼就知道，AI 自己就能判断，不用我再盯着。
4. 第二步：给 AI 立好规矩，再也不怕它乱改东西
CI 能解决 “这步编译过没过” 的问题，但解决不了 “这个东西你不能改” 的问题。
比如我们的 plugin.json，里面的 ID、type 这些字段，改了 Grafana 就找不到插件了，直接罢工；还有 .config 目录，里面是构建的配置，改了整个项目就崩了。
这些都是潜规则啊，我脑子里知道，可 AI 不知道啊，它之前就差点把 plugin.json 的 ID 给改了，要不是我拦着，整个插件就废了。
所以我把这些所有的潜规则，全都写成了明文，放在\.config/AGENTS/instructions\.md里，就 50 行，不多，刚好 AI 能看完：
\.config目录绝对不能改
plugin.json 的 ID、type 绝对不能改
改 query 字段必须同时改前端和后端的文件
Grafana 的 API 要以官方文档为准，你脑子里的旧数据不准
你以为这就完了？不对，不同的 AI，认的入口文件不一样啊！
Claude Code 认CLAUDE\.md，Codex 认AGENTS\.md，Gemini 认GEMINI\.md，要是我给每个都写一份规则，那以后改规则我得改三份，不得累死？
我就想了个招，跟 robots.txt 一样：根目录的这些入口文件，啥都不用干，就指向我那一份统一的规则文件！
比如AGENTS\.md就三行字：
## Project knowledge This repository contains a **Grafana plugin**. You must read @./.config/AGENTS/instructions.md
CLAUDE\.md、GEMINI\.md也一样，全都指向同一份规则。
这样不管是哪个 AI 来，Claude 也好，Codex 也好，Gemini 也好，进来读的都是同一份规矩，不用我重新教一遍，新的 AI 平台出来了，我加个软链接就行，不用复制一遍规则，太省心了。
5. 第三步：一键搭好试验台，AI 改完就能自己看效果
规矩立好了，质检也有了，还有个问题：AI 改完代码，怎么看实际效果？
之前我要手动启 Grafana 的容器，挂载插件目录，配好数据源，还要改一堆配置才能让插件加载上，每次换个 AI，我都要跟它说一遍：你要先跑这个命令，再跑那个，端口是 3000，账号密码是 admin……
每次都要重新说一遍，烦都烦死了，就像钟点工来打扫，你每次都要跟她说一遍：扫地机器人在柜子里，要按这个按钮，拖布要泡这个水…… 说一次两次还行，每次都要说谁受得了？
所以我把这些全都打包成了一键脚本！
我写了个 docker-compose.yaml，把 Grafana 的环境、插件的挂载、数据源的配置全都写好了，然后在 package.json 里包了一层命令：
你要启动环境？不用记一堆命令，就运：
npm run server
就这一条，自动帮你拉起 Grafana 容器，挂载好插件，配好数据源，打开浏览器就能用，AI 改完代码，自己跑个 build，然后启动环境，就能看到实际效果了，不用我再教一遍。
甚至我还做了多版本的启动命令，一条命令就能同时拉起 Grafana 11、12、13 三个版本的容器，AI 改完代码，直接在三个版本里都测一遍，不用等 PR 合并了才发现某个版本炸了。
除此之外，我还把所有的操作经验，都写成了 AI 能直接执行的 skill：
怎么构建插件，每一步要跑什么命令
怎么调试后端，断点怎么配
新人怎么从 0 到提交第一个 PR
出了问题要怎么排查
每一步都是能直接跑的 bash 脚本，AI 不用理解为什么，按步骤走就行，就像钟点工的操作手册，第一步做什么，第二步做什么，照着做就不会错。
6. 双栈项目的噩梦：AI 最爱 “改一半忘一半”
通用的改造做完了，我们这个 Grafana 插件还有个专属的坑：前后端双栈。
我们的插件，前端是 TypeScript，写界面、处理用户输入；后端是 Go，处理数据查询、告警执行。一个完整的功能，经常要前后端一起改才行。
可 AI 最擅长的就是啥？改一半忘一半！
比如我让它给查询加个别名字段，它把前端的 types.ts 改了，把界面的输入框加了，结果后端的 Go 代码忘了改解析，结果前端传过去的字段，后端根本不收，运行的时候直接崩了。
这不就像做蛋糕，你让它做个奶油蛋糕，它把蛋糕胚做好了，装饰也做好了，结果忘了抹奶油，端上来一半是胚，一半是奶油，看着就离谱，吃也没法吃。
之前就踩过这个坑，后来我干脆在规则里写死了：
任何 query model 的字段变更，必须同时改 src/types\.ts 和 pkg/plugin/query\.go，少一个都不行！
然后我还加了个测试，检查前端的 JSON schema 和后端的 Go 结构体是不是对齐的，CI 里同时跑前端和后端的测试，只要有一个没过，整个 PR 就过不了，直接把 AI “改一半” 的毛病给治了。
7. 解决 AI 的“记忆过期”：给它补一份最新说明书
还有个很有意思的坑，AI的“记忆过期”。
你想啊，Claude 4.6 的训练数据，截止到 2024 年中，可 Grafana 的 API 更新多快啊，每个月都有新的东西，AI 脑子里的 Grafana API，还是半年前的，它写代码的时候，经常就用了旧的 API，甚至编出来一些根本不存在的 API，结果跑的时候直接报错。
这就像什么？你家的菜谱，去年改了新版的做法，可钟点工记得还是去年的旧菜谱，她按旧的做法给你做，做出来根本不是你要的味道，你跟她说了新的做法，她下次来又忘了，又按旧的来。
那怎么解决？我用了llms\.txt这个东西。
Grafana 官方专门给 AI 做了一份文档索引，就是llms\.txt，里面把所有最新的插件开发文档都列好了，AI 能直接读。
我就在规则里加了一条：
你脑子里的 Grafana API 是旧的，不准用你自己的训练数据，要写代码，去看我给你的官方最新文档！
就这么一句话，AI 就不会再用那些过期的旧 API 了，就像给钟点工一份最新的菜谱，她再也不会按旧的做法来做了，做出来的东西就对了。
现在很多大厂都做了自己的llms\.txt，比如 Vercel、Tailwind，其实就是给 AI 的最新说明书，花半小时做一份，性价比超高。
8. 同时开3个版本测，再也不怕顾此失彼
最后还有个 Grafana 插件专属的问题：多版本兼容。
我们的插件要兼容从 Grafana 8.4 到 13 所有的版本，同一份代码，在不同的版本里，行为可能不一样，之前就是 Grafana 13 升级才出的问题，之前测试的时候只测了旧版本，没测新版本，结果用户升级完直接炸了。
那怎么解决？我写了个小脚本，一条命令就能同时拉起 3 个 Grafana 容器，分别是 11、12、13 三个版本，每个都挂载我的插件代码，前端热更新。
AI 改完代码，跑个 build，然后就能同时在三个版本里测，看看是不是都能正常使用，不用等 PR 合进去，跑完 CI 才发现某个版本出了，也不用我自己一个个装版本测，省了大把时间。
就像你做了个新菜，同时给三个不同口味的客人试吃，咸的、淡的、辣的都试过了，都满意了，你再端给所有客人，就不会有人说不对味了。
改造完，AI 终于能独立干活了
花了一周时间，把这些改造做完，你猜怎么着？
之前那个动不动就翻车、要我手把手教的 AI，现在能独立接任务了！
社区提了个 issue，说某个场景下告警不生效，我把 issue 丢给 AI，它自己：
读代码，找到问题在哪
改前后端的代码
跑单测、跑 CI
启动本地环境，自己验证效果
写完 PR，自己写好描述
全程我啥都没干，就等它把 PR 提给我，我 review 一下就合了！
原来那个帮倒忙的 AI，现在真的能 carry 了，一个人就能搞定从改 bug 到提 PR 的全流程，我终于能腾出手来做更重要的事了。
最后聊聊
其实不止是代码仓库，现在很多人用 AI，都遇到过这个问题：不是 AI 不行，是你没给它准备好合适的环境，没给它立好规矩，没给它配好工具。
就像请钟点工，你不能指望她第一次来你家，就知道你家的所有规矩，就知道怎么用你家的所有工具，你得给她准备好，她才能帮你把活干好。
AI 也是一样，你把仓库改造成 AI 友好的，它就能帮你干更多的活，帮你省更多的时间。
最后问你个问题：
你平时用 AI 写代码的时候，遇到过最离谱的翻车是什么样的？评论区聊聊！
