我第一次认真对待“让AI写代码”这件事是因为一个很丢人的经历。当时我让AI生成一个处理文件上传的函数它给我返回了一段看起来特别完整的代码类型标注、注释、异常处理全都有。我以为这就完事了结果一跑测试直接内存溢出。排查了半天才发现问题出在它用一个递归逻辑去读取大文件而那个递归有个隐藏的重复遍历分支数据量大一点就直接把内存打爆。代码看着很漂亮但本质上是一个高质量的错误。从那时候起我就意识到AI编程这件事真正的难点不在“让AI写”而在“怎么描述、怎么拆解、怎么验证”。标题里的“AI编程最佳实践”听起来像是一个工具使用教程但实际做下来你会发现它是一个关于判断力、工程习惯和沟通能力的问题。这篇文章我就围绕“怎么让AI写出高质量代码”这件事把我自己摸索出来的方法、踩过的坑、还有沉淀下来的提示词模板和工作流完整地分享出来。内容不挑工具主流的AI编程助手都适用适合下面这几类人被AI生成的“花架子代码”坑过但说不清问题在哪的开发者刚上手AI编程不知从哪下手的初级程序员以及正在团队里有意识地推广AI编程但担心代码质量失控的技术负责人。1. 先想清楚为什么“让AI写高质量代码”比“让AI写代码”难十倍这个事情得从根上说起。大多数人第一次用AI编程默认的用法是“我把需求丢给它它把代码吐出来我复制粘贴收工”。这个模式在写脚本、写一次性小工具的时候完全没问题但一旦进入真实项目几乎必然翻车。原因不复杂AI生成的代码质量天花板取决于你对问题的理解深度而不是它本身的能力上限。你自己对需求都只有模糊感觉的时候AI给你的东西只会更模糊。1.1 高质量代码到底意味着什么我评估代码质量从来不是看“能不能跑”而是看五个维度可读性、可维护性、正确性、性能和安全性。AI生成的代码前两个维度的表现其实不差——它非常擅长生成风格统一、加了详细注释、结构规整的代码因为训练数据里的优秀开源项目就是这样它模仿得很快。真正会出问题的是后三个维度。正确性问题最隐蔽。AI常常会“一本正经地胡说八道”比如推荐一个不存在的标准库函数、把某个方法的返回值类型搞错、或者对一个边界条件完全视而不见。性能和安全性有时候更糟它会为了追求代码简洁而选择一种优雅但性能很差的方案或者对用户输入完全没有过滤就直接拼进SQL。这几个维度不是AI能独立帮你兜底的必须有人的判断力在关键位置把关。1.2 AI不是程序员它更像一个“知识面广但没有常识”的实习生我后来想明白了一个类比AI编程助手本质上是一个知识面覆盖极广、速度极快、但对你项目一无所知的实习生。它不知道你们团队有什么代码规范不知道线上环境是什么版本不知道你项目里已经有哪些公共工具库更不知道那个谁离职前留下的“这函数千万别改”的诡异注释背后是什么故事。所以高质量代码不是AI写出来的是双方协作出来的。你的价值不在于手写每一行代码而在于提供上下文、设定约束、审查输出、纠正方向。一旦你心里接受这个定位你会发现跟AI协作的方式就变了——你不再是“提需求的人”而是“甲方中的监工”既要说明白“我要什么”也要能识别出来“这活儿干得不对”。1.3 我的工作法核心把AI“当人看”来提要求如果觉得AI是个实习生那么最好的协作方式就呼之欲出你需要像给一个聪明但没经验的实习生交代任务一样给它写清楚背景、目标、约束、验收标准以及常见坑。大多数人的提示词为什么效果不好就是因为只给了“目标”没给“背景”和“约束”。你自己想想如果有个实习生跑来问你“帮我写个函数把用户传的数据存一下。”你能直接给他写吗你肯定反问存哪里是MySQL还是Redis数据结构什么样要不要防重报错如何处理要不要考虑并发接口返回什么样的格式你问的每个问题都是“约束”和“上下文”。跟AI协作也是同样的道理只不过你需要在提示词里提前把这些约束准备好因为它不一定会主动问你。2. 上下文工程把项目背景讲清楚AI才能少犯蠢“上下文工程”是我认为的AI编程中最重要的概念但大多数人根本不重视。你以为的AI编程是“你给我写个函数”实际上的高质量AI编程是“我们项目是个什么结构、用的是哪个版本的技术栈、变量命名是什么风格、有哪些内部约束然后请在这个框架内帮我实现这个具体函数”。2.1 先在对话开头把项目背景一次性交代清楚我认真观察过很多人的用法绝大多数人AI对话的第一句就是“帮我实现一个xxx”完全没有背景。AI对你项目一无所知所以它会基于自己训练数据里的“通用情况”生成代码。但现实中的项目和“通用情况”之间的距离就是代码质量坍塌的地方。一个比较稳妥的做法是跟AI开启一段新对话时先花一点时间给它“介绍项目”之后再提具体需求。我会用下面这个结构我在做一个XXX系统技术栈是Spring Boot 3.x MyBatis-Plus Redis 某云OSS。 项目代码的位置在src/main/java下包名是com.xxx.project。 代码风格要求方法命名要清晰用动词开头禁止缩写命名Controller层只做参数校验和结果封装业务逻辑必须全放Service层异常统一用BizException抛出并由全局处理器拦截。 现有工具类中有ResultBody统一响应体、PageQuery分页参数和XxxUtil用户信息获取可以直接用不要在代码里写死任何用户信息。 请在此基础上帮我设计并实现用户积分变更功能。你看这一段话跟“帮我写一个积分变更功能”的唯一差别就是提供了上下文。但就是这个差别直接决定了AI返回的代码里依赖注入用的是AutoWired还是构造器返回值是ResultBody还是裸对象分页参数是从param里拿还是写死的页码。真实效果提升非常明显实测同一个需求有上下文和没有上下文生成的代码改动成本能差出至少一半以上。2.2 给AI“标准规范文档”而不是靠临时提醒团队里有代码规范的同学直接把规范文档发给AI效果比口头提醒一万遍都管用。不需要做任何特殊处理直接把你的代码规范、命名规范、接口设计规范、甚至.gitmessage提交规范粘贴进对话AI就会自动遵守。我每次在关键项目上都会维护一个“AI编码规范.md”文件内容大概几十行包含项目技术栈与版本目录结构与各层职责命名风格的强制约定代码注释的基本要求哪些必须有哪些禁止写日志打印规范异常处理方式SQL编写约定对话开始前把这份文档先发给AI再开始聊具体需求。这种做法的价值不仅仅是让代码风格统一更重要的是限制了AI的“自由发挥范围”。规范文档提供了一种结构化约束AI在这个框架里生成的东西怎么跑都不会偏得太远。2.3 让AI先“读”代码再“写”代码很多场景下项目的代码量不小不可能全部塞给AI。但这不代表AI不能“了解”你的项目。有个非常实用的技巧在需要AI修改现有模块或新增功能时先把相关的几个关键文件的内容发给AI让它先“读”完再给方案。举一个真实场景的例子。有一次我让AI实现一个导出Excel的功能开始直接告诉它“写个导出接口”它给我返回的方案是基于某个AI训练时学到的封装类而我们项目里明明有自己封装好的导出工具。代码能用但风格跟项目其他部分格格不入而且埋了一堆维护隐患。后来我把项目中现有的一个类似的导出Controller和Service文件直接丢给它再加上一句话“参考现有代码的风格和用到的工具类写一份新的导出Excel功能”。这次结果就完全不一样了导出的字段逻辑、文件名生成方式、错误提示风格全都和项目里的旧代码保持一致基本不需要再改。这里要说一个操作细节不是把整个项目都给AI而是有选择地给“和这个需求相关的文件”。AI的上下文窗口再大也是有限资源给太多无关代码会稀释它的注意力反而增加干扰。一般控制在两三个关键文件或者相关业务的四五个核心文件就足够了。3. 任务设计与提示词模板让AI一次写对的底层逻辑除了上下文第二重要的就是任务设计。上下文解决的是“AI知不知道你项目的情况”任务设计解决的是“AI知不知道它接下来要干什么”。很多人的提示词是那种一句话需求AI生成的代码质量自然不稳定。而高质量的任务设计是把一个复杂需求拆成一个一个小而清晰的任务并为每个任务给出明确的验收标准。3.1 任务拆小一次只让AI做一件事如果你让AI“写一个订单系统”它会给你生成一个大杂烩——Controller、Service、Mapper、实体类、XML、DTO全都来一通看着很全但每个类都不够细节而且所有东西混在一起你根本没法审查。这个思路是错的。正确做法是把大需求拆成小任务。比如订单系统就先拆成订单实体与表结构设计、创建订单接口、查询订单列表、订单状态流转、取消订单流程、支付回调处理。一次只做其中的一个任务。每一个任务里AI的注意力能完整集中它能考虑到这个模块的参数校验、异常分支、边界条件而不是着急忙慌把所有功能糊弄完。3.2 万能提示词模板任务描述五要素我自己在实践过程中总结了一套任务描述的标准结构管它叫“五要素”角色、任务、约束、验收标准、示例。下面是我最常用也最推荐的一个完整模板角色你是一名有10年经验的Java后端工程师特别擅长编写生产级别的高质量代码。 任务请设计并实现一个【用户积分变更】的功能。需求如下 1. 用户积分增加/扣减扣减后不允许为负数 2. 每次操作需要记录流水便于后续回溯和审计 3. 接口需要支持幂等避免重复提交造成重复扣减或增加。 约束 1. 使用项目现有的统一响应体ResultBody 2. 所有业务逻辑必须放在Service层Controller层只做参数校验和结果封装 3. 禁止使用任何未在项目中出现的第三方依赖 4. 方法命名必须动词开头禁止使用拼音缩写 5. 流水表的写入必须与积分变更处于同一个事务中。 验收标准 1. 积分变更后查询用户积分返回正确结果 2. 同一个幂等键重复请求多次积分只变更一次 3. 扣减时如果余额不足返回业务错误码10002。你看这段话每一行都在给AI划定边界。角色给了一个专业基准任务把要做什么说清楚约束把不能做什么限定死验收标准是判断“是否完成”的尺子。这个模板几乎可以用在任何编程场景里前端、后端、脚本都适用只需要替换里面的名词。3.3 几种常见的任务设计技巧除了上面这个完整模板还有几个小技巧特别好用。第一个是“让AI先问问题再写代码”。当需求本身比较模糊的时候不要让它直接生成代码而是先让AI把它的疑问说清楚然后你根据回答再补全上下文。我通常会加这么一句“先不要急着实现先列出你认为需求中不清楚或需要明确的点我回答你之后你再开始写。”第二个是“让AI给多方案对比”。技术选型类的问题比如“用户积分变更用事务消息还是本地事务加定时任务补偿”让AI直接写代码之前先让它说一下它的方案选型思路以及每个方案的优劣。这样你能在动手前就把方向定下来避免写完代码才发现方案不对再返工成本就大了。第三个是“交给AI之前先自己定义关键接口”。对于核心模块我会提前把接口签名、入参出参类型、返回结构定义好直接给AI让它在框架内填充逻辑。这样AI的自由发挥空间被约束在了“函数内部”而不是整个接口设计。第四个是“明确不让AI做什么”。很多人提示词只写“要做什么”不写“不要做什么”。但在真实项目里“不要”往往比“要”更重要。比如“不要引入新的工具类能用项目现成的就优先用”、“不要使用已废弃的方法”、“不要自己定义异常类型统一用BizException”。这些约束直接避免了最麻烦的事后返工。4. 实操全流程从需求到交付的完整工作流理论讲了很多现在我把一个比较典型的功能从需求到落地完整地展示一遍。以“用户积分新增功能”为例假设项目是一个电商系统已有代码结构和技术栈。4.1 第一步准备上下文让AI熟悉项目我不会一上来就让AI写代码。我会先给它发一段项目背景说明把技术栈、关键文件、代码风格规范都贴过去然后让它做一件事总结一下这个项目的技术栈和注意事项。这个“复述”的过程很重要——一方面确认它已经理解了我给的背景信息另一方面它会把注意力放在这些约束上后面生成代码时更可能遵守。实践下来这一步非常有效。很多时候跳过了“让AI复述”这一步AI虽然看到了规范但没有形成“显式记忆”写着写着就又回到自己的通用风格上去了。让它复述一遍相当于给它的显式记忆加深一次。4.2 第二步拆需求定义任务清单把积分功能拆成以下几个任务数据库表结构设计用户积分表、积分流水表积分变更Service接口与实现幂等处理逻辑Controller层接口设计与参数校验单元测试编写每个任务单独开一轮对话一个一个来。不要试图在同一个对话里让AI把所有任务一口气做完。理由很简单AI的输出质量会随着对话轮次增长而衰减任务越聚焦生成质量越稳定。而且分拆之后你每完成一个任务都可以人工审查一遍一旦发现AI理解偏差立刻就能纠正不至于等到全部生成完才发现设计思路整个走了样。4.3 第三步逐个任务实现与检查拿第一个任务举例。我会发这一段提示词请根据下面的需求设计积分模块的数据库表结构。 需求细节 1. 用户积分账户表 user_points字段至少要包含用户ID、总积分、版本号乐观锁用、更新时间 2. 积分流水表 points_log字段至少包含流水ID、用户ID、变更类型增加/扣减/冻结/解冻、变更数量、变更后余额、业务单号、幂等键、创建时间 3. 两个表都需要主键索引流水表需要按用户ID和时间建索引。 约束使用InnoDB引擎utf8mb4字符集字段类型要控制好长度和精度decimal不要用float。 请输出建表SQL并说明每个字段的设计理由。AI生成的建表SQL一看就是专业路子因为约束理得清楚。字段类型不会出现莫名的varchar(255)满天飞会给varchar(32)、varchar(64)这种恰好够用的长度存量字段会加注释索引会根据查询场景去建。每个任务完成之后我都会做一遍人工审查。我会重点检查三样东西一看字段是否覆盖全需求二看索引是否合理三看是否有遗漏的边界条件。审查发现的修改意见直接以追加指令的形式发给AI修改比如“流水表加一个 biz_type 字段用来区分是什么业务产生的积分变更”。这种方式比让AI一次性生成完美结果要可靠得多。4.4 第四步让AI自测人审终检在单测任务环节AI的能力其实被很多人低估了。让它写一个普通业务函数的单元测试它生成的用例质量相当高边界值、异常路径、正常路径都能覆盖到。但这里有一个前提你得像前面那样把被测函数的行为描述清楚。我会这样要求它请为下面的积分变更Service实现编写单元测试。要求 1. 使用JUnit5和Mockito 2. 覆盖正常增加积分、扣减成功、扣减余额不足、重复幂等请求、事务回滚这几条路径 3. 测试数据不要硬编码统一用常量和测试工具方法 4. 每个测试方法需要注明测的是什么场景。等它生成完我再人工跑一遍补一些它没测到的极端场景比如并发扣减、幂等键为空、积分变更数量为0然后合并进去。最终交付的代码质量完全经得起Code Review。4.5 “AI产出代码人负责烧水”的分工模型这个全流程走下来最大的感受就是AI把“从0到80分”的时间压缩得非常短而你作为工程师价值体现在“从80分到100分”这一段里。你不再是逐行写代码的人而是那个定方向、卡关键节点、审边界、补场景的人。有人担心工程师会因此被替代。我的看法恰恰相反AI淘汰的不是工程师是“不会跟AI协作的工程师”。在AI时代工程能力更像“判断力决策力质量意识”的综合体。那个能把需求拆成清清楚楚、把约束写明白、在AI输出里挑出问题的人单位时间产量大概率是闷头手写代码的同学的三倍以上而且代码质量还更稳。5. 常见问题与排查技巧实录AI编程避坑手册和AI协作的过程中不可能一帆风顺。我把实践里反复踩到的典型问题整理成一个排查手册每个问题都附上了触发原因和解决技巧希望对你有帮助。5.1 幻觉API与编造函数AI最坑的一类错误AI特别擅长一本正经地“发明”不存在的函数尤其是在一些冷门SDK的使用场景。比如让AI写某个第三方平台的文件上传功能它可能会编出来一个实际不存在的uploadWithV4方法。从方法名到参数设计看起来都完全合理但一编译才发现根本没有这个方法。排查技巧很简单AI给的所有涉及“外部SDK调用”的代码不要直接信任。先花10秒钟查一下官方文档确认方法的真实签名。如果你手头有官方文档的片段最好直接把片段发给AI作为参考再让它写调用逻辑。这基本能从根上消除幻觉API的问题。另外涉及版本敏感的方法一定要在提示词里写清楚版本比如“Spring Boot 3.2.5环境”和“Spring Boot 2.7.x环境”AI生成出来的依赖方法完全不同。版本不标明AI通常会默认用训练数据里占比最高的老版本知识这就是为什么很多人实际项目一编译全是废弃警告。5.2 代码风格“风格漂移”每次输出都像不同的人写的常出现的情况是这个函数是标准阿里Java规范风格下一个类又变成了Google风格换个对话窗口AI连命名习惯都变了。原因很简单AI的风格取决于你对话开头的“角色设定”和“风格描述”。解决方法是把风格约束写成一个固定模板每次都复制使用。如果你用的是带自定义指令功能的编程工具就直接把规范写进全局指令里让它覆盖所有会话。推荐在自己的全局配置里放这几个固定的风格条款代码注释不得超过一行复杂逻辑必须说明意图禁止使用拼音缩写命名所有方法必须包含入参校验新起方法必须说明边界场景5.3 AI过度设计杀鸡爱用牛刀AI训练数据里包含大量架构设计最佳实践所以它生成的代码往往带有强烈的“为了模式而模式”的毛病。明明只需要一个简单的函数它会给你搞出一个策略模式工厂模式模板方法模式的三层组装明明一个业务方法几十行就能写完它非要拆到四个类里让人维护的时候在类之间来回跳。这种情况下的修正方法很简单在你的提示词里补一句“保持实现简单不要过度设计优先用最直观的方案”。如果已经生成复杂代码了再追加一句“这个场景用不到策略模式请把它重构成一个直接实现的逻辑”。实测这一句话能把代码体积减掉一半以上可读性瞬间恢复。5.4 AI“假装测试通过”看着绿灯实际没测到东西AI在某些情况下生成的单元测试看起来测试用例很多、覆盖率很高但实际上它写的断言根本没测到关键逻辑。比如测试“扣减积分”只测了正常路径完全没有测“扣减到负数时抛异常”的情况比如测试数据准备不足导致断言无论实现成什么样都能通过。面对这种情况我一般会在人工审查测试用例时做两件事一是挑一个已知的错误实现跑一遍现有测试看能不能把它“测出来”——测不出来的测试就是废测试二是强制让它补边界条件专门写一行“补充以下边界场景的测试如果没有边界条件的请求不允许仅用正常路径凑数”。5.5 AI一次改不好迭代改写的艺术还有一种高频情况需要改一个已有函数AI改了三次改了这里坏了那里。这其实是它“改了但没完全理解”的表现。遇到这种场景正确姿势不是继续在原对话里改而是换一个思路操作把需要修改的函数原封不动地发给AI再给它加上那个函数的调用方代码、依赖的数据结构定义、以及相关的测试代码然后告诉它“这是这个函数所有相关的上下文请在理解完整后给出修改方案而不是直接给修改后的代码。”这里有个判断经验如果一个函数改了三轮都没改对那说明AI对这个函数的信息掌握不完整继续在原对话里改是没有意义的不如重新开一轮对话把更完整的上下文喂进去。这比反复折磨同一个对话框要高效得多。6. 团队协作与经验沉淀把AI编程变成团队的稳定能力自己摸透了AI编程的方法论之后你会面临一个新的问题怎么把这套方法复制给团队的同学如果每个人还是各自闷头用AI水平高低差异极大代码Review的时候就会变成一场灾难。我在团队里的做法是搭一套轻量的协作规范让AI编程从一个“个人技能”变成“团队基础设施”。6.1 建立团队的“AI编码规范”资产库第一步是把团队里所有跟代码质量相关的约定沉淀成一份文档就像第2.2节提到的“AI编码规范.md”。这份文档可以由经验最丰富的那位成员起草然后全员评审定稿后大家共用。内容不贪多覆盖几个关键约束就行必须遵守的命名风格、禁止使用的反模式、统一的技术栈版本、特殊业务的处理约定。之后每个人跟AI对话时第一步就是把这份文档发给AI作为“地基”再开始干活。好处很直接AI生成的东西天然是团队的“熟悉味道”不会出现张三的AI写出来的代码是这种风格、李四的AI写出来的是另一种风格的情况。6.2 把“好用的提示词”收集起来做成团队模板库每个人的实践过程中都会沉淀一些特别顺手的提示词片段比如任务描述五要素模板、“先问再写”的指令、“不要过度设计”的约束。这些都是宝贵资产建议直接收集到一个共享文档里按使用场景分类。新同学上手AI编程的时候不用自己从零摸索直接套用模板效果比自己裸写好得多。我见过很多团队一边抱怨AI写的代码不靠谱一边从来没有在团队内部共享过“什么样的提示词能让AI写出靠谱的代码”。这其实是一种巨大的浪费。分享好的提示词跟分享一个好的工程方案一样收益都是指数级的。6.3 合理利用AI把关代码审查形成双人复核机制除了让AI写代码还有一个特别实用的场景让AI当代码审查员。我自己的习惯是写完一轮代码后把代码贴给AI用下面这段指令让它做一轮“找茬”请以资深代码审查员的身份审查这段代码重点找以下几类问题潜在的空指针风险、并发安全问题、事务边界问题、异常被吃掉的场景、SQL性能隐患、命名不规范。不要客气列出你找到的所有问题并按严重程度排序。另外特别说明一下如果某个实现方式有更简洁安全的替代方案也指出来。这一步收获很大。AI能发现很多我自己看的时候因为“惯性思维”漏掉的问题尤其是空指针、事务回滚、并发竞态这些模式化问题。它给的建议不见得全部采纳但作为第二双眼睛价值极高。多一道AI审查环节我交付出去的代码质量明显比之前纯自己看要高了一个台阶。6.4 迭代式落地先小步试跑再全员推广如果你想在团队里推广AI编程实践不建议搞“一刀切”式的强制。更好的方式是选一个业务复杂度适中的模块让两个对AI编程比较感兴趣的同学先用这套方法来开发跑一个迭代周期之后把效果和踩坑记录复盘给团队。有了真实的数据其他同学的接受度和配合度都会高很多。这里我尤其想说的一点是AI编程在团队里真正的红利并不是“代码产量翻倍”而是把整个团队从低价值的重复编码劳动中解放出来让人更集中在需求理解、架构设计、代码审查、性能优化这些更高价值的环节。这一层收益比单纯“写得快”值钱得多。我个人实际使用中的一点体会这篇文章写到这里已经把我想分享的主要内容差不多讲完了。最后想聊聊我自己对“用AI写代码”这件事心态上的变化——因为我不觉得这是一个纯粹的技术技巧问题它更是一个工作方式的转变问题。最开始用AI编程的时候我跟大多数人一样总想着让它一下子把整个功能写完结果代码质量忽高忽低心里没底。后来把思路倒过来不急着让AI产出先把上下文讲清楚、把需求拆细、把约束定死、把验收标准列明白AI生成的东西反而越来越能“直接用了”。这个过程反复打磨之后我慢慢形成了一种新的工作直觉把AI当成一个“能力很强但不太知道前因后果”的结对伙伴而我自己的核心工作变成了背景说明、方向纠正和最终确认。顺带说一个我这两年养成的“小怪癖”每个AI会话开局的固定动作永远是先发一份上下文规范而不是直接丢需求。就这一个动作省下来的返工时间让我确信“人机协作的质量取决于人的定义能力”这句话是真的。如果这篇文章能让你在这个方向上少走两三个月的弯路那我的目的也就达到了。
