你有没有过这种体验兴冲冲用上 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\.mdCodex 认AGENTS\.mdGemini 认GEMINI\.md要是我给每个都写一份规则那以后改规则我得改三份不得累死我就想了个招跟 robots.txt 一样根目录的这些入口文件啥都不用干就指向我那一份统一的规则文件比如AGENTS\.md就三行字## Project knowledge This repository contains a **Grafana plugin**. You must read ./.config/AGENTS/instructions.mdCLAUDE\.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 写代码的时候遇到过最离谱的翻车是什么样的评论区聊聊
让AI助手从翻车到carry的实战指南
你有没有过这种体验兴冲冲用上 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\.mdCodex 认AGENTS\.mdGemini 认GEMINI\.md要是我给每个都写一份规则那以后改规则我得改三份不得累死我就想了个招跟 robots.txt 一样根目录的这些入口文件啥都不用干就指向我那一份统一的规则文件比如AGENTS\.md就三行字## Project knowledge This repository contains a **Grafana plugin**. You must read ./.config/AGENTS/instructions.mdCLAUDE\.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 写代码的时候遇到过最离谱的翻车是什么样的评论区聊聊
