过去大半年，我在一个模拟项目X上做了一次比较彻底的试验：把AI编程工具从"偶尔问两句"的玩具，变成覆盖日常开发全环节的工作台。这个项目大概有40万行Java代码，历史包袱很重——模块边界模糊、测试覆盖率不到三成、线上还有几个常年没人敢动的老文件。团队规模控制在5人左右，没有专职架构师。就在这种条件下，我们把一个原计划六周的迭代压缩到三周半，过程中AI编程工具贡献了大概四成代码量，剩下六成还是人工写的，但这六成里有一部分是在AI草稿基础上修改出来的。
这篇文章不打算做成工具功能介绍，我想分享的是更实际的东西：在真实项目里，AI编程工具应该怎么选、怎么让它读懂你的代码库、怎么把任务拆到AI能接得住、怎么把"问一句答一句"变成"交付闭环"，以及我在这个过程中踩过的坑。适合两类人看：一类是团队里准备引入AI辅助开发，但不知道怎么落地的技术负责人；另一类是自己写代码，想让AI从"玩具"变成"生产力"的独立开发者。
1. 选型不是选最火的，而是选最省心的：AI编程工具的三种形态与我的搭配方案
先说结论：我最终保留了两个工具——一个编辑器内的代码补全插件，一个支持自主代理模式的IDE扩展。前者负责日常的"填鸭式"编码，后者负责重构和批量修改。没有上那种终端里流式对话的代理工具，虽然它在某些场景下特别强，但对这个项目的存量代码来说，它的工作方式风险大于收益。
1.1 三类工具形态的实际差异
市面上AI编程工具看着五花八门，本质上只有三条路线：补全型、对话型、代理型。
补全型就是那种你在编辑器里写注释，它帮你补下一行的工具。核心价值是"少敲键盘"，对上下文要求不高，适合处理模板代码、单元测试骨架、配置文件的重复片段。这类工具最大的优点是侵入感低，不改变你原有的编码节奏，缺点是只能做"局部聪明"，整个模块的设计它完全插不上手。
对话型是指那种在侧边栏或终端里一问一答的工具。它能理解你粘贴进去的代码片段，解释报错、生成示例、做重构建议。这类工具对单次对话的处理能力还行，但一旦涉及多个文件的跨模块改动，它就力不从心了，因为它没有完整看到你的项目结构。
代理型是最近一年发展最猛的方向。你给它一个任务，它能主动读取项目目录、打开文件、编辑代码、运行测试，甚至根据报错自行修正。理论上它是唯一能承担"从需求到代码"完整链路的形态。问题也出在这个"主动"上——它在一个你可能并不完全理解的老项目里自己做决策，一旦读完错误文件、在错误的层改了代码，返工成本比人工写还要高。
1.2 我的选型逻辑
我最终保留了补全型和代理型各一个，原因是它们的配合方式刚好互补。日常写新代码时，补全型负责把已经想清楚的逻辑快速落地，我只需要在关键分支上手动调整；遇到重构任务，我就切到代理型，让它在限定的模块范围内做"指定动作"——提取方法、改签名、移动文件。限制是关键：我不会给它"优化这个模块"这种开放式指令，而是给"把UserService里的validate方法拆成三个独立方法，保持外部调用不变"这种封闭式指令。
终端流式代理工具我试用过两周，结论是：它适合那种代码量很小、结构清晰的绿地项目。在历史包袱重的存量项目里，它会因为读文件太慢导致耐心下降，然后开始做一些激进的猜测性改动。有一次它把我一个工具类的import区域全部重排，顺手"修正"了一个实际上有意的重名方法调用，差点引发线上故障。从那之后，我把这类工具彻底移出了工作流。
经验：选型前先问团队一个问题——你们的代码库是"历史遗产"还是"新建工程"？前者以代理型为主，后者可以尝试终端流式代理。不要在遗产库上做激进的自动化尝试。
2. 让AI读得懂"带病"的代码库：上下文工程是怎么做的
把AI工具装好只解决了"有没有"的问题，真正让AI在项目里发挥价值，取决于它能不能理解你的代码库。这个理解不是靠把整个仓库塞进上下文窗口实现的——那是很多人的误区。大项目全量塞进去，上下文窗口再大也是一次性烟花，聊两轮就丢。
2.1 项目术语表是第一步
我在项目根目录建了一个AGENTS.md文件，作用相当于给AI一份"项目说明书"。里面写了三块内容：项目技术栈和目录结构、核心业务域的术语定义、编码规范与约定。比如说"订单域"在代码里对应order包，接口统一以OrderResult类型返回；比如所有对外接口的异常必须包装成BizException，不允许裸抛RuntimeException；比如数据库访问层的命名必须是XxxMapper，且必须继承基类BaseMapper。
这份说明文件的效果立竿见影。在加这份文件之前，我让代理工具生成一个"查询用户订单列表"的接口，它给出的是标准的三层架构代码，Controller直接调用Service，Service直接调用Mapper——没有异常包装、没有统一返回结构、没有权限校验注解。加上这份文件之后，同样的问题，生成代码的第一版就已经符合项目80%的规范。
不要小看这件事，它其实是在给AI建立"项目记忆"。人类新成员入职还要看新人文档呢，AI凭什么不看你就能猜对？很多人抱怨AI生成代码"水土不服"，往往是这个文档缺失导致的。
2.2 用"索引拆分"代替"全库索引"
真正让AI理解大型代码库，不能靠一次性读入，要靠分片加载。我的做法是：按业务域把项目拆成若干个domain文件夹，每个域内维护一份DOMAIN.md，描述这个域的核心模型、关键接口、常用依赖。代理工具在开始某个任务前，我会先让它读取对应的DOMAIN.md，而不是让它自己满仓库翻文件——这样既省token，又避免了误读无关模块后产生幻觉。
2.3 给AI配一个"检索器"
代理工具能自己翻文件，但它翻文件的方式是"按文件名猜测+逐个打开"，效率极低。更靠谱的做法是给AI配一套检索命令：项目的util目录下加了一个小脚本search_by_symbol.py，传入类名或方法名就能返回文件路径和代码片段摘要。这个脚本会精确匹配符号定义，比AI自己glob加打开文件的方式快一个数量级。实测下来，AI在一个新任务里平均少打开四五个无关文件，生成的代码也更少跑偏。
提示：上下文工程的核心不是"喂得更多"，而是"喂得更准"。一个清晰的
AGENTS.md、一份分域的DOMAIN.md、一个快速的符号检索工具，这三件套足够让AI在一个中型项目里达到"可用"的聪明程度。
3. 从"问一句答一句"到"交付闭环"：需求、实现、验证的分层方法论
很多开发者的AI使用姿势停留在"让它写一段代码"，这使得AI的产出永远是碎片化的——你拿到一个函数，但函数放哪里、接口怎么对齐、异常怎么处理，全得自己操心。我的体会是，AI编程真正爆发的起点，是开始用"任务"而非"问题"来驱动它。
3.1 任务分层是AI协作的第一原则
我把团队里所有开发任务按体量分成四档：
| 层级 | 耗时 | 典型场景 | AI参与方式 |
|---|---|---|---|
| S档 | 5分钟以内 | 改一个判断条件、修一个字段名、补一个日志 | 补全型工具直接搞定 |
| M档 | 半小时以内 | 写一个独立的小函数、生成单元测试 | 对话型工具+人工修改 |
| L档 | 半天到一天 | 重构一个核心类、新增一个service | 代理型工具+人工设计+自动/手动测试 |
| XL档 | 一整天以上 | 模块拆分、接口协议变更 | 只让AI做局部机械改动，架构决策由人负责 |
关键心得：越往上，AI的自主权越要收缩，人工的设计参与越要加大。XL档任务如果直接丢给AI做全量改动，几乎必然产生大范围的技术债——它会把本来清晰的边界改成一团乱麻。
3.2 把需求拆成AI能执行的"原子任务"
进入L档任务时，我要求在动手前先做任务拆解。例如"给订单导出功能增加筛选条件"这个大需求，我会拆成：新增查询参数对象、修改Mapper查询SQL、修改Service过滤逻辑、调整导出模板、补充单元测试、更新接口文档。每个原子任务都有明确的验收条件，比如"Mapper的SQL必须使用#{param}占位符，不能拼接字符串"。
这种拆解对AI是友好的：它不需要自己决定"任务范围有多大"，只需要执行我指定的范围。实操中我用对话型工具开新会话，把原子任务描述+验收条件粘贴进去，让它直接出代码。一条任务一个会话，做完即关，绝不混用。
3.3 "红绿灯"验证机制：让测试定义行为
这个方法是这个项目里最有效的一个改动。以前是"AI写完代码，我们一起看"，现在是"先写测试，再让AI实现"。对每个需要AI实现的函数，我先用测试用例描述它的输入输出、边界条件、异常路径，然后让AI对着测试写实现——测试是红灯，AI的任务是让红灯变绿。
这个机制解决了一个核心问题：AI对需求的理解偏差。以前AI生成的代码可能功能正确但路径处理不完善，比如没考虑空指针、没校验边界。测试先行的条件下，AI的产出会被约束在测试定义的范围内，偏差被限制在极小范围内。
当然，测试是由人写的，写测试这部分的精力省不掉。但它省的恰恰是更昂贵的精力——反复review AI代码的时间。测试一跑，对错一目了然，不用逐行抠实现细节。
3.4 三条绝不放开给AI的红线
测试可以做，边界可以碰，但有三类操作我在这个项目中绝对不允许AI直接修改：数据库迁移脚本、权限校验逻辑、敏感数据脱敏规则。这三类内容是系统安全的底线，AI一旦产生幻觉，影响的不只是代码正确性，而是数据安全。任何涉及这三类的改动，我都要求AI只输出"建议代码"，由人工确认后手动应用。
4. 把AI嵌进流水线：CI审查、重构辅助与增量落地的编排细节
工具选好了、上下文喂到位、任务能拆了，下一步是把这些东西串成一条稳定的工作流，让AI不是"偶尔用一下"，而是成为项目节奏的一部分。这一节讲我实际落地时用的编排细节。
4.1 新功能开发的五步链路
在模拟项目X里，一次完整的新功能开发是这样的流程：
- 需求文档转技术方案：我先写好技术方案（包括改动涉及的文件、新增的接口、数据变更），这一步纯人工。
- 方案转任务列表：把技术方案拆成原子任务（前文的分层方法论）。
- 逐任务AI实现：每个原子任务单独开会话，附带
AGENTS.md和对应DOMAIN.md的摘要，以及该任务的测试定义。 - 人工代码审查：AI产出的代码合并之前，必须经过一次diff review。重点看整体设计有没有走偏，不逐行审——测试已经跑过了。
- 集成环境自动回归：合并后触发自动化测试流水线，全部绿了才算完成。
这个流程跑通之后，开发速度的提升不是线性的，而是结构性的——以前需要大量时间写"胶水代码"（DTO转换、配置拼接、模板填充），现在AI把这些都消化了，人可以专注在真正的业务判断上。
4.2 存量代码重构的特殊编排
重构老代码比写新代码更考验AI，因为它需要先看懂一段可能没人看得懂的历史代码。我给代理工具布置重构任务时，会强制它先输出一份"现状摘要"再做改动：这个类有哪些公共方法？方法之间的调用关系？数据流向是什么？这份摘要我会先看一遍，确认AI的理解没有偏差，才会允许它继续。
有个典型案例：LegacyOrderMapper是一个七百多行的老文件，既有数据查询逻辑，又混了两段Excel导出模板的拼接代码。我给AI的任务是"把导出相关的两段代码提取到独立的OrderExportUtil类中，保持LegacyOrderMapper的公共接口不变"。AI先输出的摘要准确指出了两类代码的边界，我才放行。最终改动涉及4个文件，测试次日补完，没有回退问题。
4.3 CI流程中的"AI审查小助手"
除了开发阶段，我在CI流程里加了一个自定义脚本，每次代码合并前自动做三层检查：检查新增/修改的代码里是否包含常见漏洞模式（如日志打印敏感字段、直接拼接SQL、缺少参数校验）；检查是否引入了AGENTS.md里列出的禁止模式（如裸抛RuntimeException）；检查新增的public方法是否都对应了测试断言。这三层检查不追求全面，只防守高危问题。
这个"小助手"本质上就是把AGENTS.md里的规范文本转化成可执行的静态检查规则。项目规范越清晰，这个检查器越有用。如果你接手的项目没有规范文档，那AI审查也无从下手——所以还是回到"上下文工程"那一节：规范先行，工具才有用武之地。
5. 幻觉不是bug，是特性：我在实际项目里踩过的和绕过的坑
最后这部分我想认真说说踩坑经历。网上大量的AI编程帖子都在晒"AI生成的炫酷代码"，但落地时真正的难点是：AI会一本正经地编造不存在的依赖、生成看似正确但实际完全跑不通的代码，甚至"热心"地帮你重构掉那些牵一发动全身的细节。
5.1 最常见的三类幻觉与应对方案
第一类是"虚构API幻觉"。AI在生成代码时，会调用一个项目里根本不存在的工具方法，比如FileStorageUtils这个类在这个项目里压根没出现过。应对方案其实非常简单——在任务描述里明确写到"只允许使用AGENTS.md中罗列的公共工具类，不得自行创造工具类"。加了这一条后，虚构API的情况从每三四个任务一次降到了几乎没有。
第二类是"过度抽象幻觉"。代理工具在做重构时，特别喜欢把页面上搜到的相似代码抽象成公共方法。表面看是"优化代码结构"，实际上它根本不理解业务差异——两个看似一样的逻辑，可能因为一个字段的来源不同，压根不能合并。这种抽象一旦被采纳，后面排查问题会非常痛苦。我的做法是，重构任务一律限定"最小改动"，明确要求"不提取公共方法，不合并重复代码，只做指定的结构变更"。重构的抽象决策由人来做，AI只负责机械执行。
第三类是"上下文漂移"。在一个长对话里，AI前面聊得好好的，到第二十轮它突然忘了项目规范，开始用一套全新的代码风格。我发现它的记忆衰减曲线跟人有点像——一开始遵守规范，聊着聊着就放飞了。应对方案是"任务会话隔离"：一个会话只做一个原子任务，做完就关，不反复追问，不跨任务复用。
5.2 关于成本控制
提到token成本，可能有人觉得这是小事，但在长任务里它不是。一件比较肉疼的案例：我让代理工具做一个模块级重构，它反复读文件、反复跑测试、反复自行修正，一个下午消耗了大约相当于旧版大模型全量上下文40倍以上的token数量，花费足够我买一个月所有付费AI工具了。
后来定了两条铁律：其一，大任务必须拆小，禁止把"整个模块重构"一次性丢给AI；其次，给代理工具设置最大轮次限制，代码修改超过4轮仍未通过测试就停手，手动介入排查——AI在一个坑里反复绕圈的时间成本远高于人工看一眼。还有就是尽量让AI只读取DOMAIN.md和核心文件，而不是全目录递归扫描，这个对token的节省非常明显。
5.3 真正危险的坑：AI带偏技术栈决策
这是我个人最警惕的一个坑。AI会倾向于使用它训练数据里最常见的方案，而不是你这个项目最合适的方案。比如项目里做异步任务，团队的现有储备是自研的AsyncRunner，但AI在生成代码时总会试图往Spring的@Async注解上靠——因为它的训练数据里那个方案出现次数更多。如果不加控制，AI会在不知不觉间把项目的技术栈往它“熟悉”的方向拉，造成严重的标准分裂。
应对方案是在AGENTS.md里写明"技术选型清单"：哪些库是项目标准、哪些场景禁止引入新依赖、哪些替代方案可以用但必须先经过技术评审。把选择权前置到文档里，AI在代码生成时就不是自由发挥了，而是在一个受限的选项空间里选择——这个思路，其实和给AI设定行为边界是一回事。
5.4 一个经过验证的"AI协作收尾动作"
每做完一个原子任务，我会做一次固定的收尾动作：关掉AI会话，重新打开相关文件，手动通读一遍AI的改动，然后用一个三行的脚本跑一遍相关的测试用例集。这三步都不耗时，但能有效拦截大多数幻觉。这套收尾动作基本成为了项目的规定动作，不允许跳过。
从我个人的实际体会来说，AI编程工具真正的价值不是替你写代码，而是替你写那些你不想写的代码——重复的、机械的、说明文档式的、测试骨架类的。而它最大的风险，则是会让你在轻松的"看起来正确的代码"面前失去警惕。这两种特质加在一起，得出的工作流只能是人机互相制衡，而不是谁替代谁。
如果你正准备把一个历史遗留项目迁移到AI辅助开发的模式，我的建议是：先从最小的一个模块开始，先建好AGENTS.md和分域文档，先封死上面说的三条红线，再逐渐扩大AI的参与范围。不要上来就把整个项目铺开交给AI——那只会让你同时收获AI的效率和它制造的混乱。最后再分享一个不起眼的技巧：在AGENTS.md里加一条"任务完成后，请用不超过50字总结你完成的工作和遗留风险"。这条强制总结让我在多少个大意时刻保持了清醒，已经数不过来了。
