同样的AI在个人项目里像开挂写接口、写脚本、补单元测试一套流程行云流水。可一旦把它放进一个几十万行代码的企业项目情况就完全不一样了——它新建的方法引用了一个不存在的Bean改完Controller顺手把Service接口的签名改了把项目里已有的工具类重新实现了一遍甚至会在没有数据库变更规范的情况下直接给你生成一条ALTER TABLE。很多人把这种情况归结为“AI水平不行”。但更接近真相的判断是AI的能力上限并没有突然下降而是它进入了一个“不适合正常工作”的工程环境。模型没有变变的是任务复杂度。让一个能力很强但对项目一无所知的新人直接上手大型项目也会出现同样的问题。AI也一样它需要一份“入职手册”、一套“任务拆解方式”、一个“验收流程”。这篇文章不讨论花哨的 Prompt 技巧而是讨论一个更实在的问题如何用工程化手段让 AI 在大型项目中稳定推进。你会了解 AI 在大型项目中翻车的根本原因学会用 AGENTS.md 这类文档给 AI 建立项目上下文学会把一个大需求拆成 AI 能执行的子任务并通过变更清单和自动化验证控制交付质量。1. 为什么同一个AI在小项目里惊艳在大项目里翻车在小型项目中AI 的表现确实惊艳。项目文件只有几十个依赖少业务逻辑直接AI 基本可以把所有相关代码放入上下文窗口一次看清全局。它“看得到”所以能做好。大型项目的复杂度完全不一样。几百个 Java 文件、几十张数据库表、一堆消息队列消费者、定时任务、配置中心哪怕是当前主流模型的最长上下文窗口也无法在一次对话中覆盖项目全貌。AI 在信息不足时只能根据概率去猜猜错了就表现为“翻车”。从工程视角看原因可以拆成四层上下文窗口有限。模型每次能看到的代码量是固定的大型项目的有效代码量远超窗口上限。项目导航缺失。AI 不知道应该先读哪些文件、不能改哪些文件、项目里已经有哪些约定和公共组件。长对话历史衰减。多个来回之后早期给出的约束容易被忽略越往后 AI 越容易跑偏。全局影响无法预判。改一个公共方法可能影响几十个调用方但 AI 只看到了它当前修改的那个文件。这四点如果不同时解决AI 就只能在“蒙眼编程”的状态下工作。真正稳定的 AI 辅助开发不是靠某一家的模型更聪明而是靠工程体系补足 AI 的短板。2. 让AI稳定推进的三个核心能力上下文、拆解、验证如果把 AI 比喻成程序员它比普通新人强的地方是知识量和生成速度弱的地方是对项目上下文的理解和对全局影响的判断。让 AI 在大型项目中稳定推进本质上是补足这两个短板。这里涉及三个核心能力。2.1 上下文给AI建一份“入职手册”新人入职第一天团队会给他架构文档、代码规范、目录说明、数据库说明。AI 同样需要这份东西。很多团队用 AI 编程时直接选中一个代码文件就开始对话AI 对项目整体完全不了解自然只能“就文件论文件”生成的结果很难适配业务约束。解决办法是为项目准备一份项目上下文文件。它的作用是每次 AI 开启新会话、开始新任务之前可以读取这份文件快速了解项目的基本信息、目录结构、编码规范和禁止事项。2.2 拆解不要让AI直接执行史诗级需求你不会把“重构核心交易模块”直接扔给刚入职的新人。让 AI 直接面对一个大而模糊的需求它会自己选择认知路径而那条路径不一定符合项目的技术约束。好的方式是先拆解把一个大型需求拆成“调研、设计、开发、验证”等多个环节每个环节只交付一个小目标。AI 的每一步都在明确边界内工作出错概率会大幅下降。2.3 验证让每次AI输出都经过低成本检查AI 生成的代码必须经过编译、测试和检查否则你只是在“信任生成结果”。大型项目里建立一条自动化验证链路非常关键。每当 AI 完成一个子任务就执行一次编译和测试问题能立刻暴露。我见过最典型的失败案例是给 AI 一个大任务后整个过程没有任何验证点AI 连续改了几十个文件最后工程根本无法编译。如果每一个子步骤都验证至少可以在前一个环节就发现方向错了。3. 搭建AI工作台用AGENTS.md给AI提供项目上下文AGENTS.md 是一种放在项目根目录的项目说明文件。它让 AI 编程工具在开始工作时可以先读取项目规则。不同 AI 编程工具可能有不同的文件约定但思路完全一致项目里放一份面向 AI 的“入职手册”。下面是一个电商中后台项目的 AGENTS.md 示例。这个项目是示例项目文件内容可以根据真实项目调整。# 项目代号shop-platform ## 项目简介 基于 Spring Boot 3 Vue 3 的电商中后台管理系统。 ## 技术栈与版本 - Java 17 - Spring Boot 3.2 - MyBatis-Plus 3.5 - MySQL 8.0 - Redis 7 - Vue 3 Vite Element Plus ## 目录地图AI必读 - backend/src/main/java/com/shop/controller —— 只放HTTP接口不写业务逻辑 - backend/src/main/java/com/shop/service —— 业务逻辑层 - backend/src/main/java/com/shop/mapper —— 数据库访问接口 - backend/src/main/resources/db/migration —— Flyway数据库脚本不允许手动改数据库 - frontend/src/views —— 页面组件 - frontend/src/api —— HTTP请求封装 ## 公共组件清单优先复用禁止重写 - StringUtils字符串工具 - PageResultT分页返回结构 - ResultT统一响应结构 - GlobalExceptionHandler全局异常处理 ## 编码约束 - 后端接口返回统一使用 ResultT - 所有接口入参必须做参数校验Validated - 新增数据库字段必须新增 Flyway 脚本 - 禁止修改其他业务模块的 Service 接口签名 - 业务逻辑禁止写在 Controller 中这份文件有什么价值AI 在开始任务前读取了这份文件就不会在 UserController 里写业务逻辑也不会绕开 Flyway 去改数据库。它知道了公共组件的位置就会优先复用而不是重写。AGENTS.md 必须放在项目根目录并保持更新。项目里每增加一个重要模块、一套新的规范都应该同步维护进去。它本质上是把团队沉淀的代码规范转换成了 AI 能读取的格式。4. 任务拆解把大型需求变成AI可执行的子任务AGENTS.md 解决的是“AI 知道项目长什么样”的问题。任务拆解解决的是“AI 这一轮应该做什么”的问题。很多人使用 AI 编程时习惯把整个需求一次性描述给 AI“帮我实现用户积分系统。”这个需求如果丢给 AI它会自己决定数据库怎么建、接口怎么设计、需不需要缓存、任务是同步还是异步……一旦决策和项目现有架构冲突后面就很难收拾。正确的拆解方式是把需求拆成多个子任务每个子任务只包含一个明确目标、涉及文件、输出物和验收方式。用户需求实现用户积分系统。 第1步上下文调研 - 阅读数据库初始化脚本backend/src/main/resources/db/migration/V1__init.sql - 阅读 ResultT 和 PageResultT 的 API - 阅读 OrderService 中用户表的使用方式 - 输出现有用户体系的技术要点不超过300字 第2步方案设计 - 在 docs/design/integral-system.md 输出设计文档 - 必须包含表结构、接口路径、Redis key 设计 - 本阶段不要写代码 第3步数据库变更 - 新建 Flyway 脚本backend/src/main/resources/db/migration/V2__integral.sql - 脚本执行前先在同环境验证备份 - 执行后运行mvn flyway:migrate 验证 第4步后端实现 - 新建 IntegralService 和 IntegralController - 只实现查询积分、增加积分、扣减积分三个方法 - 不要在这轮实现定时任务和消息推送 第5步单元测试 - 编写 IntegralServiceTest - 使用项目已有测试基类和 Mockito 风格为什么这样拆有效每个子任务都有明确边界AI 不需要自己猜测“要不要建定时任务”这类模糊问题。如果 AI 在第1步就发现表结构设计与自己预期不一致它会在这个阶段提出来而不是等代码写完了再返工。拆解时还要注意一个原则每一步的验收输出必须明确。做不到这点的拆解本质上和没有拆解没有区别。5. 用Definition of Done约束AI交付质量很多开发团队都有自己的 Definition of Done完成定义例如“必须通过编译”“必须有测试”“必须走完 Code Review”。AI 编程同样需要这套约束。在与 AI 协作时我建议在任务描述中固定要求 AI 输出一份变更清单。变更清单既是对 AI 工作的约束也是后续人工 Review 的依据。下面是一个可以直接套用的模板。请按以下格式输出本次变更清单 ## 修改文件清单 | 文件路径 | 变更类型新增/修改/删除 | 变更摘要 | 是否涉及接口签名 | | --- | --- | --- | --- | | backend/src/main/java/com/shop/service/IntegralService.java | 新增 | 积分查询、增加、扣减逻辑 | 否 | ## 新增加依赖 | 依赖 | 版本 | 原因 | | --- | --- | --- | | 无 | - | - | ## 验证方式 1. 编译mvn compile 2. 测试mvn test 3. 手工验证启动服务后调用 GET /api/user/{id}/integral 查看积分 ## 风险提示 本次改动会影响哪些模块是否涉及共享代码是否创建了数据库表为什么这个步骤重要第一它强制 AI 在修改前想清楚影响范围。第二它让你能在几分钟内完成人工Review而不是在一堆 Diff 中慢慢猜。第三如果 AI 的变更清单含糊不清你完全可以要求它重新输出。这条规则对大型项目尤其关键。大型项目中一个看似无关紧要的改动实际影响范围可能很大。AI 如果能列出“是否涉及接口签名”这一项就更容易发现问题。6. 自动化验证让AI每走一步都能低成本验证没有验证的手段AI 的稳定输出就是一句空话。大型项目里的自动化验证不一定要很复杂先跑通编译、单元测试和前端构建就足够覆盖绝大多数问题。下面是一个简易验证脚本。它适合在 Linux/macOS 环境下运行核心逻辑是每完成一个子任务执行一次后端编译、后端测试和前端构建任何一个环节失败都会中断并明确报错。#!/bin/bash # 文件路径scripts/verify.sh set -e echo [1/5] 检查未提交变更 git status --short echo [2/5] 后端编译 cd $(dirname $0)/../backend mvn compile -q echo [3/5] 后端单元测试 mvn test -q echo [4/5] 前端构建 cd ../frontend npm run build echo [5/5] 验证全部通过使用方式很简单把上述脚本保存到scripts/verify.sh然后执行下面的命令。chmod x scripts/verify.sh ./scripts/verify.sh如果脚本在执行中报错set -e会保证退出你需要在后台输入中查看具体哪一步失败。还有一个容易被忽略的点验证脚本必须让 AI 也知道。在很多 AI 编程工具中你可以把它写进 AGENTS.md 或者任务描述里“所有改动完成后先执行 scripts/verify.sh再输出变更清单。” 这会让 AI 把验证前置而不是只给你一段“看起来正确”的代码。7. 常见问题与排查方法AI 在大型项目中推进时会遇到很多重复出现的问题。下面按我的经验整理成一张排查表。问题现象可能原因排查方式解决方案AI 修改了一个方法其他调用方报错方法签名被改动调用方未同步更新搜索该方法所有引用查看 diff在任务约束中明确“禁止修改公共方法签名”如果必须修改则先列出调用方清单AI 使用了不存在的工具类/组件上下文文档缺少公共组件清单检查 AGENTS.md 是否更新搜索项目已有工具类在 AGENTS.md 中维护公共组件清单并让 AI 先搜索“是否存在”再决定是否新增多次对话后 AI 行为明显偏离最初需求对话历史过长早期约束被遗忘对比当前输出与最初任务描述重新开启会话并把关键约束和当前进展写入新任务描述AI 生成代码后编译不通过任务未要求先做编译验证查看编译错误日志在任务描述中加入“必须执行编译验证后才算完成”AI 新增了重复的依赖项目已有同类依赖AI 不知道检查 pom.xml / package.json在 AGENTS.md 中记录主要依赖版本并禁止重复引入AI 一条 SQL 直接改了生产库结构没有数据库变更规范确认变更是否经过 Flyway 脚本明确“所有数据库变更必须新增 Flyway 脚本禁止手动执行 SQL”这里需要特别强调大型项目里最容易出的问题永远不是 AI 不会写代码而是 AI 在错误的位置写代码、用错误的方式改代码。人工 Review 和规范约束是最后的防线不要全部交给 AI。8. 最佳实践与工程建议结合前面的内容这里汇总几条能在实际项目中直接落地的工程建议。第一把 AGENTS.md 当作一等工程产物来维护。它不该是一次性写完后放那不动的东西。每当项目新增技术栈、新模块、新规范都要同步更新。它需要像 README 一样被团队认可并成为 AI 编程的入口文件。第二让 AI 小步提交禁止一次性提交超大改动。如果一个任务让 AI 同时修改了 20 个文件这个改动已经超出了可 Review 的范围。把任务拆小让 AI 每完成一个小目标就提交一次并附上变更说明。第三数据库变更要守住安全底线。对于涉及数据库表结构变更的任务必须在测试库验证后再同步到生产环境。执行前确认备份、执行后确认回滚方案。在任务描述中写清楚“该脚本会创建 xxx 表执行前请确认测试库已备份”。第四对 AI 生成代码做 Code Review不要直接信任。AI 生成代码的效率很高但它没有能力和动力去验证代码在真实业务场景中的行为。业务逻辑边界、异常处理、事务边界这些仍然需要人工确认。第五多人协作时把 AI 的职责边界清晰化。如果多个开发者同时使用 AI 编程最好在 AGENTS.md 中约定每个人或者每个 AI 会话负责的模块避免两个会话同时修改同一段核心代码产生互相覆盖的问题。第六逐步引入 Agent 化工作流。如果团队已经能稳定使用“单次任务 验证 变更清单”的协作方式再进一步考虑更复杂的 Agent 编排。让一个 Agent 做调研另一个 Agent 做编码第三个 Agent 做测试每个 Agent 之间有明确交付物。这类探索是很有价值的下一步。9. 总结与后续学习方向大型项目中AI 稳定推进的关键并不在于哪个模型更强而在于是否建立了上下文、拆解、验证三件套。AGENTS.md 让 AI 第一次接触项目时就知道规则任务拆解让 AI 每一步都走在有效路径上变更清单和自动化验证让每个输出都可回看、可回滚。建议你先在自己的项目中写一份 AGENTS.md把一个常用需求拆成上面说的几步下次用 AI 写代码时只做一件事让 AI 按这个流程执行一遍。感受一下和直接抛一个大需求相比输出可控性的差异是很明显的。后续如果想把这件事做得更深可以研究三个方向一是结合 Spring AI 这类框架把 AGENTS.md 和项目文档变成可检索的知识库让 AI 能动态获取上下文二是深入使用 AI 编程工具的 Workflow 功能把任务拆解和验证脚本固化到工具流程里三是设计更复杂的多 Agent 协作场景调研 Agent、编码 Agent、测试 Agent 各司其职。建议先收藏这篇文章动手实践时按章节逐步对照。希望这篇文章能让你对“AI 写大型项目代码”这件事有一个更稳的判断不该指望 AI 做全知全能的独立开发者而该把它当作一个能力强但需要边界的新同事用工程化的方式让它稳定干活。
