AI代码上线就炸？从SKILL.md到agent的完整避坑指南

1. 那个让所有AI编程工具都尴尬的瞬间你有没有经历过这种场景让AI帮你写了一段代码本地跑得飞起测试全绿你信心满满地推到线上结果不到十分钟监控告警就炸了。日志里全是空指针、超时、内存溢出甚至更离谱的——数据被写坏了。这不是段子这是过去一年里我见过最多的真实事故。标题里那句“AI写的代码能跑一上线就炸”几乎成了所有用AI辅助编程的团队绕不开的坎。关键词里提到的Codex、CLI、SKILL.md、agent其实都指向同一个问题域我们到底该怎么把AI生成的代码安全地从“能跑”推进到“能上线”。这篇文章不打算给你灌鸡汤也不打算复述那些“AI编程要小心”的废话。我想做的是把这件事拆开揉碎从根因、排查链路、修复方案到预防机制完整地讲一遍。适合谁看如果你正在用Codex CLI、Claude CLI、Trae CLI这类工具做日常开发或者你在搭自己的agent框架、写SKILL.md来约束AI行为那这篇内容就是给你准备的。哪怕你只是刚装完Codex CLI、还在研究codex使用教程的新手也能从里面拿到能直接抄的检查清单。先说一个反直觉的结论AI写的代码上线就炸绝大多数时候不是AI的锅而是我们给它的上下文和约束不够。你让它写一个函数它写得漂漂亮亮但你没告诉它这个函数会在什么并发量下跑、依赖的数据库连接池有多大、上游传过来的字段有没有可能为空。它当然只能按“理想情况”写。上线之后真实世界的脏数据、并发、网络抖动一上来代码就原形毕露。所以这篇文章的核心不是教你“怎么让AI写出完美代码”而是教你怎么建立一套从AI生成到上线的安全网。这套安全网包括怎么在SKILL.md里写约束、怎么用agent做自动化检查、怎么在CLI工作流里插入验证环节、以及上线前必须人工过一遍的几件事。2. 为什么本地能跑、线上就炸根因不在代码本身2.1 环境差异只是表象真正的问题是“假设缺失”很多人第一反应是环境不一致本地是Node 18线上是Node 16本地用SQLite线上用PostgreSQL。这些确实是问题但只是表象。真正让AI代码崩溃的是它在生成时做了一堆没有写出来的假设。举个例子。你让AI写一个“从订单列表里筛选出未支付订单”的函数。它可能会写def get_unpaid_orders(orders): return [o for o in orders if o.status unpaid]本地测试你传了一个干净的列表跑通了。上线之后orders里混进了None或者某个订单对象根本没有status字段直接抛AttributeError。AI没有错它只是假设了“所有订单都有status字段”。这个假设在本地成立在线上不成立。这类问题在AI生成的代码里极其常见因为AI的训练数据里大量代码示例都是“理想路径”。它不会主动帮你加防御性检查除非你在提示词里明确要求。2.2 AI代码的“三高”特征高自信、高耦合、高隐式依赖我总结过AI生成代码的几个典型特征我称之为“三高”高自信AI写代码时语气非常确定变量命名、函数结构都很“标准”让你觉得它很靠谱。但这种自信往往掩盖了它对边界条件的无知。高耦合AI倾向于把逻辑写在一个大函数里因为它要“一次性解决问题”。结果就是一个函数里混了数据获取、业务判断、格式转换、异常处理上线后任何一环出问题整个函数都挂。高隐式依赖AI会默认一些库已经安装、一些配置已经就绪、一些中间件已经可用。它不会在代码里写try-except去处理“Redis连不上”的情况因为它假设Redis永远在线。这三个特征叠加起来就是“本地能跑、线上就炸”的完美配方。本地环境是你精心准备的所有依赖都在数据都是干净的线上环境是混沌的什么意外都可能发生。2.3 一个真实案例Codex CLI生成的支付回调处理我拿一个真实案例来说。团队里有个同学用Codex CLI生成了一段支付回调的处理逻辑。需求是收到支付平台的回调后更新订单状态并给用户发通知。AI生成的代码大概长这样def handle_payment_callback(request): data request.json() order_id data[order_id] status data[status] order db.query(Order).filter(Order.id order_id).first() order.status status db.commit() send_notification(order.user_id, f订单{order_id}状态更新为{status}) return {code: 0}本地测试传一个正常的JSON跑通了。上线之后问题一个接一个支付平台偶尔会发重复回调导致send_notification被调用多次用户收到一堆重复通知。某个回调的order_id在数据库里查不到order是None直接AttributeError。send_notification内部调用了第三方服务网络超时导致整个回调接口卡住支付平台重试又触发更多重复处理。这三个问题AI在生成时一个都没考虑。不是它能力不够而是它不知道“支付回调可能重复”“订单可能不存在”“通知服务可能超时”。这些信息你不写进提示词或SKILL.md它永远不会主动加。3. 从SKILL.md到agent把约束写进AI的工作流3.1 SKILL.md到底该写什么不是文档是契约很多人把SKILL.md当成一个“说明文档”写一堆“本项目使用Python 3.10”“数据库是PostgreSQL”之类的信息。这没错但远远不够。SKILL.md的真正价值是给AI立规矩。我自己的SKILL.md里会强制包含以下几类内容边界条件清单所有外部输入必须做空值检查、类型检查、范围检查。比如“所有来自HTTP请求的字段必须用get()而不是[]访问”。幂等性要求所有可能被重复调用的接口必须实现幂等。比如“支付回调必须用order_id status做去重”。超时与重试策略所有外部调用必须设置超时并且明确重试次数和退避策略。日志与监控埋点关键路径必须有日志异常必须打错误日志并带上上下文。禁止事项比如“禁止在循环里查数据库”“禁止在事务里做网络调用”。这些规则写进SKILL.md之后AI在生成代码时会主动遵守。我实测下来加了这些约束之后AI代码的上线事故率至少降了七成。3.2 用agent做自动化检查让机器审机器光靠SKILL.md还不够因为AI有时候会“忘记”规则。这时候就需要agent出场。你可以搭一个简单的检查agent在AI生成代码之后、提交之前自动跑一遍检查。这个agent不需要多复杂用CLI工具就能做。比如# 检查是否有未处理的空值访问 grep -rn \[.*\] --include*.py | grep -v get( # 检查是否有未设置超时的外部调用 grep -rn requests\.\(get\|post\) --include*.py | grep -v timeout # 检查是否有循环内数据库查询 grep -rn for .*: --include*.py -A 5 | grep db.query这些简单的grep规则能抓住大部分低级问题。更高级一点你可以写一个agent用AST解析代码检查函数复杂度、嵌套深度、异常处理覆盖率。我见过一个团队他们的agent会在每次AI生成代码后自动跑一遍单元测试、静态检查、安全扫描任何一项不过代码就打回去重写。3.3 CLI工作流里的“人工闸门”哪些必须人看Agent再强也有盲区。有些东西必须人工过一遍。我在CLI工作流里设了三个“人工闸门”数据模型变更任何涉及数据库schema变更的代码必须人工review。AI很容易写出“删掉一个字段”这种危险操作。权限与鉴权逻辑AI对权限的理解往往很粗糙它可能写出“只要登录就能访问”的代码而实际需求是“只有管理员才能访问”。资金与状态流转任何涉及钱、订单状态、库存扣减的代码必须人工确认幂等性和事务边界。这三个闸门是我用血泪换来的。曾经有一次AI生成的代码把“退款”逻辑写成了“先加钱再减钱”本地测试没问题上线后并发一上来用户余额直接翻倍。4. 上线前的最后一道防线我必做的五项检查4.1 空值与边界检查用“脏数据”跑一遍AI代码最怕干净数据。上线前我一定会用“脏数据”跑一遍。什么是脏数据就是那些你在本地测试时永远不会传的值None、空字符串、空列表超长字符串比如10万个字符负数、零、极大值格式错误的日期、邮箱、手机号并发重复请求我通常会写一个简单的脚本把这些脏数据灌进接口看代码会不会崩。这个步骤花不了多少时间但能抓住大部分空指针和类型错误。4.2 幂等性验证重复调用会不会出事对于任何可能被重复调用的接口我会手动调用两次看结果是否一致。比如支付回调、消息消费、定时任务。如果第二次调用产生了额外副作用比如又发了一次通知、又扣了一次库存那就是幂等性没做好。AI生成的代码幂等性往往是最薄弱的环节。因为它默认“这个接口只会被调用一次”。但线上环境里重试、重复消息、用户狂点按钮都会导致重复调用。4.3 超时与降级外部依赖挂了会怎样AI代码对外部依赖的假设是“永远可用”。上线前我会模拟外部依赖挂掉的情况把数据库连接断开、把Redis停掉、把第三方API的域名指向一个不存在的地址。然后看代码会怎样。如果代码直接抛异常、整个接口500那说明没有降级逻辑。正确的做法是外部依赖挂了接口应该返回一个合理的默认值或者至少返回一个友好的错误提示而不是让整个服务雪崩。4.4 日志与可观测性出事了能不能查到AI生成的代码日志往往很少。它不会主动打日志因为它觉得“代码逻辑很清楚不需要日志”。但线上出问题的时候没有日志你根本不知道发生了什么。我会检查关键路径是否有日志请求入口、数据库操作前后、外部调用前后、异常分支。日志里要带上足够的上下文请求ID、用户ID、订单ID、关键参数。这样出问题的时候你能快速定位。4.5 回滚方案炸了能不能快速恢复最后一项也是最重要的一项回滚方案。AI代码上线炸了你能不能在一分钟内回滚如果不能那说明你的发布流程有问题。我自己的做法是任何AI生成的代码上线时必须带上回滚脚本。回滚脚本要经过测试确保能真正恢复。另外我会用灰度发布先放1%的流量观察十分钟没问题再逐步放大。这样即使炸了影响面也可控。5. 那些AI不会告诉你、但你必须知道的坑5.1 坑一AI会“发明”不存在的APIAI在生成代码时有时会调用一些根本不存在的函数或方法。比如它可能写db.query(Order).filter_by_status(unpaid)但你的ORM里根本没有filter_by_status这个方法。本地测试时你可能没跑到这行上线后一跑就报AttributeError。这个坑的解法是所有AI生成的代码必须跑一遍完整的单元测试覆盖所有分支。不要只测主路径异常路径也要测。5.2 坑二AI对并发一无所知AI生成的代码几乎从不考虑并发。它写的“查一下、改一下、存一下”逻辑在并发场景下就是灾难。两个请求同时查到同一个订单同时改成不同状态后写的覆盖先写的数据就乱了。解法是所有涉及状态变更的操作必须用数据库的原子操作或乐观锁。比如用UPDATE orders SET status paid WHERE id ? AND status unpaid而不是先查再改。5.3 坑三AI会忽略事务边界AI经常把多个数据库操作写在一起但不加事务。比如“扣库存、创建订单、扣余额”三个操作如果中间任何一个失败前面的操作不会回滚数据就不一致了。解法是所有多步数据库操作必须包在事务里。并且要确认事务的隔离级别和传播行为符合预期。5.4 坑四AI生成的错误处理是“假”的AI会写try-except但它的except里往往只是pass或者print(e)。这种错误处理等于没有因为它把异常吞掉了上层根本不知道出了问题。解法是检查所有except块确保异常被正确记录和向上传递。不要吞异常除非你有明确的理由。5.5 坑五AI对性能的假设过于乐观AI生成的代码在本地小数据量下跑得很快但线上数据量一大就慢成狗。比如它可能写一个循环里查数据库的代码本地10条数据没问题线上10万条数据直接把数据库打挂。解法是所有涉及循环、批量操作的代码必须做性能评估。用生产级别的数据量跑一遍看响应时间和资源消耗。6. 把AI代码当“实习生代码”来管最后分享一个我自己的心态转变。刚开始用AI编程的时候我把它当“高级工程师”觉得它写的代码应该没问题。结果被现实反复教育。后来我换了个心态把AI当成一个刚入职的实习生。它基础不错写代码很快但对业务不熟、对线上环境没概念、对边界条件不敏感。你会让实习生写的代码直接上线吗不会。你会让他写完你review一遍跑一遍测试确认没问题再上线。对AI代码也应该这样。具体来说我的流程是AI生成代码后先跑静态检查lint、类型检查。然后跑单元测试覆盖主路径和异常路径。人工review关键逻辑特别是数据模型、权限、资金相关的部分。用脏数据和并发场景做一次集成测试。灰度发布观察监控指标。准备好回滚方案。这套流程跑下来AI代码的上线事故率能降到和人工代码差不多的水平。而且因为AI写得快整体效率还是提升了很多。提示不要因为AI代码出过事故就放弃用它。问题不在AI而在我们怎么用它。把约束写清楚、把检查做扎实、把闸门设好AI代码完全可以安全上线。还有一个实用技巧我会把每次AI代码出的事故记录下来整理成“事故模式库”。比如“空值未检查”“幂等性缺失”“事务边界错误”“超时未设置”。然后把这些模式写进SKILL.md让AI下次生成时主动规避。这个库越丰富AI代码的质量就越高。说到底AI编程不是“让AI替你写代码”而是“你带着AI一起写代码”。你的经验、你的判断、你的约束才是代码能上线的真正保障。AI只是加速器方向盘还得你自己握。