从Plan模式到工程制度：构建高效AI编程协作的四大核心要素

1. 从“Plan模式”到“工程制度”AI协作的范式转变最近在团队里推动AI工具落地时我反复听到一个词“Plan模式”。很多开发者包括一些技术管理者把AI当成了一个“超级实习生”——扔给它一个模糊的需求比如“帮我写个用户登录功能”然后期待它吐出一套完整、可运行、符合规范的代码。结果往往是AI确实能生成一大段代码但要么是“玩具级”的Demo要么充斥着安全漏洞、性能问题或者与现有工程架构格格不入。这种“给个指令坐等结果”的用法我称之为“Plan模式”我们只负责下达一个宏观的“计划”剩下的交给AI自由发挥。这听起来很美好但实际产出却常常令人失望甚至需要花费更多时间去“擦屁股”。问题的根源在于我们混淆了“指令”和“制度”。让AI进入“Plan模式”就像让一个没有经过任何岗前培训、不了解公司任何规章制度的新员工直接去负责一个核心模块的开发。他可能个人能力很强比如AI模型本身很强大但因为没有上下文、没有规范、没有协作流程他的产出大概率是无法直接使用的。Claude Code、Cursor、GitHub Copilot这些工具的出现标志着AI从“聊天伙伴”进化成了“编码协作者”。但如果我们不改变与之协作的方式就相当于给F1赛车手配了一条乡间土路再强的性能也发挥不出来。因此我的核心观点是不要只让AI进入“Plan模式”要先给AI一套“工程制度”。这套“制度”就是一套清晰、可执行、与团队现有流程无缝集成的规则、规范、上下文和协作框架。它的目的不是限制AI的创造力而是为它的创造力划定一个高质量、高效率、可协作的“发挥空间”。这不仅仅是技术问题更是工程管理和团队协作理念的升级。接下来我将结合具体的工具实践以Claude Code为例但其思想普适拆解如何为你的AI协作者建立这套“工程制度”。2. “工程制度”的核心四要素上下文、规范、流程与反馈一套有效的AI工程制度必须包含四个相互关联的要素丰富的上下文Context、明确的编码规范Specification、清晰的协作流程Workflow和持续的反馈机制Feedback。缺少任何一个AI的产出都会大打折扣。2.1 上下文Context给AI装上团队的“集体记忆”AI模型是“健忘”的尤其是在单次对话中。它不知道你的项目用了什么技术栈、目录结构如何、有哪些内部工具库、业务领域的专有名词是什么。在“Plan模式”下你需要像挤牙膏一样在每次对话中反复提供这些信息效率极低且容易遗漏。建立上下文制度就是要系统化地、自动化地将这些信息“喂”给AI。1. 项目级上下文代码库索引与架构图这是最基础的上下文。以VSCode配置Claude Code为例你不能仅仅打开一个文件就让AI修改。正确做法是打开整个项目根目录让Claude Code能够索引整个代码库。它会自动分析项目结构理解模块间的依赖关系。提供架构文档如果项目有ARCHITECTURE.md或README.md确保这些文件在项目中。AI在回答问题时会优先参考这些文档。你可以直接对AI说“请参考项目根目录下的ARCHITECTURE.md文件来理解我们的微服务划分。”关键配置文件将docker-compose.yml、package.json、pom.xml、.env.example等文件保持在可访问状态。当AI建议安装一个依赖或配置环境时它能基于现有配置给出更准确的建议比如“我看到项目使用Spring Boot 2.7.x建议的依赖版本需要与之兼容。”2. 团队级上下文开发规范与共享知识编码规范文件在项目根目录放置.eslintrc.js、.prettierrc、checkstyle.xml等配置文件。更有效的是创建一个DEVELOPMENT_GUIDE.md或AI_CODING_GUIDE.md文件用自然语言写明团队的约定例如“所有API响应必须使用统一的ApiResponse包装类”、“错误日志必须使用ERROR级别并包含requestId”、“DTO类字段命名使用小驼峰数据库字段名使用下划线”。内部工具与SDK文档如果公司有内部的工具库、SDK或平台将它们的API文档即使是Markdown格式的放入项目的docs/目录。AI在建议调用某个内部服务时就能参考正确的接口签名和示例。业务术语表创建一个GLOSSARY.md定义项目中的核心领域概念。例如在你的电商项目中明确“SPU”、“SKU”、“履约单”、“寻源”的具体含义。这能极大提升AI生成业务逻辑代码的准确性。实操心得我习惯在项目初始化时就建立一个/docs/for_ai目录把上述所有针对AI的上下文文档都放进去。然后在第一次使用Claude Code时我会直接把这个目录的路径贴给它并说“这是我们项目的AI协作上下文文档请在后续所有代码生成和建议中严格遵守其中定义的规范。” 这相当于一次性的“岗前培训”。2.2 规范Specification从模糊需求到精确“施工图”“写一个登录接口”是“Plan模式”的指令。“写一个登录接口”加上清晰的规范才是“工程制度”下的任务。规范越精确AI的产出越可用。1. 输入输出规范API Contract First不要只说“实现登录”。要给出细节需求实现用户手机号验证码登录接口。 规范 - 路径POST /api/v1/auth/login-by-sms - 请求体{ “phoneNumber”: “string”, “verificationCode”: “string” } - 响应体成功时返回 { “code”: 200, “message”: “success”, “data”: { “token”: “jwt-string”, “userInfo”: { … } } }失败时返回对应的错误码和信息。 - 校验手机号格式校验验证码非空且为6位数字。 - 安全验证码需在服务端校验有效期5分钟和正确性接口需具备防重放攻击能力建议使用请求唯一标识。当你把这样的规范描述给AI时它生成的Controller、Service代码会直接符合你的API设计甚至能提示你创建对应的请求/响应DTO类。2. 代码质量与安全规范在上下文中提供了规范文件后在具体任务中仍需强调“生成的代码必须通过ESLint规则见配置文件和SonarQube基础检查。”“所有数据库查询必须使用MyBatis-Plus的QueryWrapper禁止字符串拼接SQL。”“用户密码必须使用BCrypt加密存储密钥等敏感信息必须从配置中心读取。”“需要添加完整的Javadoc/TSDoc注释特别是公共方法。”3. 测试规范“工程制度”要求AI的产出必须是可测试的。给你的指令加上测试要求“请为上述登录服务生成单元测试使用JUnit 5和Mockito覆盖率要求达到80%以上。”“生成集成测试测试验证码发送和登录的全流程。” AI如Claude Code可以根据已有的Spring Boot测试结构生成非常贴近实际的测试类大大减轻了测试代码的编写负担。踩坑记录我曾让AI生成一个文件上传接口但没有明确规范文件大小限制和类型白名单。AI生成了一个功能上“能用”的接口但缺乏任何安全限制。上线前幸亏进行了代码审查否则就是潜在的安全漏洞。从此我明白安全规范必须作为“制度”的一部分在每一次AI协作中明确重申。2.3 流程Workflow将AI嵌入开发流水线AI不应该是一个独立的“黑盒”而应该融入现有的开发流程。这意味着AI参与的工作也需要经过代码审查、静态检查、CI/CD流水线。1. 需求拆解与任务分配流程面对一个中型需求如“优化商品详情页的加载速度”不要直接把这个大问题扔给AI。第一步人工拆解。开发者或技术负责人先将需求拆解为具体任务1) 分析慢查询日志2) 为商品主表添加缓存3) 图片资源懒加载4) 异步加载评论数据。第二步分步交给AI。将每个小任务结合具体的上下文和规范交给AI完成。例如任务2的指令可以是“基于我们现有的Redis配置配置项见application-redis.yml为Product实体类路径xxx实现一个缓存管理器遵循CacheTemplate模式参考UserCacheService缓存过期时间设为30分钟。”第三步人工组装与联调。将AI生成的各个模块组装起来进行集成测试和调优。2. 代码审查Code Review流程AI生成的代码必须经过严格的人工审查这一点绝不能因为“是AI写的”而放松。审查重点包括逻辑正确性生成的业务逻辑是否符合需求有没有边界条件遗漏安全性是否有SQL注入、XSS、CSRF等漏洞敏感信息处理是否得当性能循环是否高效数据库查询是否有N1问题缓存使用是否合理一致性代码风格是否与项目其他部分一致是否遵循了团队规范 在Pull Request描述中应该注明哪些部分由AI辅助生成并简要说明使用的指令和上下文方便审查者理解代码的来龙去脉。3. CI/CD集成流程在CI流水线中可以加入针对AI生成代码的特定检查虽然目前工具不完善但可以变通代码指纹检查使用一些工具检测大段重复的、可能来自公开训练集的代码片段避免潜在的版权问题。规范符合度增强检查除了常规的Lint可以运行自定义脚本检查AI容易出错的地方比如是否使用了被禁用的API是否添加了必要的日志点。将AI提示词纳入文档对于由AI生成的核心模块可以将生成该模块所使用的精确提示词Prompt保存在代码旁的AI_GENERATION.md中。这既是文档也方便后续维护和迭代。2.4 反馈Feedback训练你的专属“AI同事”AI模型不是一次性的工具通过反馈你可以让它越来越贴合你团队的习惯。这就是“制度”中的持续改进环节。1. 会话内的即时纠正当AI生成的代码不符合预期时不要直接废弃重来。应该像指导同事一样给出明确的反馈错误示例“不对这里不能用ArrayList我们项目规定统一用List接口声明。”正确示例“这个查询方法需要加上Transactional(readOnly true)注解因为这是一个只读操作。请修改。” AI特别是Claude Code这类具有较强对话能力的工具能够理解你的反馈并在后续的修改中应用这一规则。这个过程就是在单次会话中“微调”AI的行为。2. 建立团队知识库与优质Prompt库将那些被验证过“好用”的、能产生高质量代码的提示词收集起来形成团队的“AI最佳实践库”。例如“生成标准CRUD服务”提示词模板包含了对实体类、Mapper、Service、Controller、单元测试的完整规范要求。“修复特定类型Bug”提示词如“如何修复Spring循环依赖”、“解决MyBatis结果映射字段丢失问题”。“代码重构”提示词如“将这段代码重构为策略模式需符合我们项目中的策略模式实现惯例参考xxx包下的例子”。 新成员加入后首先学习这个Prompt库能极大降低AI协作的学习成本并保证输出质量的一致性。3. 评估与迭代定期比如每两周回顾AI协作的效果。可以问几个问题AI生成的代码一次通过审查的比例是多少哪些类型的任务AI完成得特别好比如生成样板代码、数据转换、写单元测试哪些特别差比如复杂的算法设计、高度创新的架构团队常用的提示词有哪些需要优化 根据回顾结果更新你们的上下文文档、规范文件和Prompt库让这套“工程制度”不断进化。3. 实战以Claude Code为例搭建你的AI工程制度理论说再多不如看一次实战。我们假设一个场景在一个Spring Boot MyBatis-Plus Redis的微服务项目中使用Claude Code完成“为订单服务添加一个查询用户历史订单列表的接口”这个任务。3.1 环境准备与上下文注入首先确保Claude Code正确安装并配置在VSCode中。打开你的订单服务项目order-service。关键一步提供初始上下文。我不会直接开始写代码而是先给AI一个“项目简报”我现在在order-service项目中这是一个Spring Boot 2.7.15微服务使用MyBatis-Plus 3.5.4作为ORM框架连接MySQL数据库。项目采用了分层架构controller, service, service.impl, mapper, entity, dto。 项目已经集成了Redis使用RedisTemplate进行缓存操作配置文件在application.yml中。 我们有一个统一的响应包装类RT位于com.xxx.common.core.domain.R。 数据库订单表名为t_order对应的实体类是Order包含字段id, order_no, user_id, amount, status, create_time等。 请先理解以上上下文后续所有代码生成请严格遵循此技术栈和项目结构。这个开场白一次性注入了技术栈、架构、关键类的位置等核心上下文将AI从“通用编程助手”拉入了你的“专属项目环境”。3.2 执行分步任务与规范细化现在开始拆解任务。我不会说“写一个查询历史订单的接口”。我会分步进行每一步都附带详细规范。第一步生成查询用的DTO和VO。基于上述上下文请完成以下任务 1. 在com.xxx.order.dto包下创建OrderQueryDTO类用于接收查询请求。字段要求userId (Long, 必须), pageNum (Integer, 默认1), pageSize (Integer, 默认10), startTime (LocalDateTime, 可选), endTime (LocalDateTime, 可选)。所有字段需添加Swagger注解ApiModelProperty说明。 2. 在com.xxx.order.vo包下创建OrderListVO类用于返回订单列表信息。字段从Order实体中选取orderNo, amount, status (请使用枚举名称而非数字), createTime。同样添加Swagger注解。 要求使用Lombok的Data注解并为所有日期字段添加JsonFormat(pattern yyyy-MM-dd HH:mm:ss)注解。这个指令明确了包路径、类名、字段细节、使用的工具注解Lombok, Swagger, Jackson以及数据转换要求状态枚举名。AI生成的代码几乎可以拿来即用。第二步生成Mapper层查询方法。接下来在OrderMapper接口假设已存在中添加一个根据OrderQueryDTO进行分页查询的方法。 要求 1. 方法名selectOrderListByPage 2. 参数Param(query) OrderQueryDTO query 3. 返回类型IPageOrderListVO 4. 请编写对应的Mapper XML在OrderMapper.xml中实现动态SQL查询。条件包括user_id #{query.userId}以及当startTime和endTime不为空时create_time BETWEEN #{query.startTime} AND #{query.endTime}。结果按create_time DESC排序。 注意XML中请使用if test\...\标签实现动态条件并注意防止SQL注入。这一步将数据持久层的规范定义得非常清楚包括MyBatis-Plus的分页对象IPage的使用、Param注解、XML动态SQL的写法以及排序要求。第三步生成Service层。现在生成Service层接口和实现。 1. 在OrderService接口中增加方法RIPageOrderListVO getHistoryOrder(OrderQueryDTO query); 2. 在OrderServiceImpl中实现该方法。 实现逻辑 - 参数校验userId不能为空。 - 调用第2步中生成的selectOrderListByPage方法进行查询。 - 考虑缓存查询前先尝试从Redis获取Key格式为order:list:${userId}:${pageNum}。如果缓存命中直接返回。如果未命中查询数据库并将结果序列化后存入Redis设置过期时间300秒。 - 返回结果包装成R.ok(pageData)。 注意请使用项目已有的RedisTemplate bean并处理可能的序列化异常。这里引入了业务逻辑参数校验、缓存策略包括Key设计、序列化、过期时间、以及统一的响应封装。AI需要理解并串联起之前步骤生成的组件。第四步生成Controller层。最后在OrderController中创建对应的RESTful接口。 要求 1. 路径GET /order/history 2. 使用Validated注解对OrderQueryDTO参数进行校验。 3. 在方法上添加Swagger注解ApiOperation(value “查询用户历史订单列表”)。 4. 调用orderService.getHistoryOrder方法并返回结果。至此一个完整的、符合规范的功能模块指令链完成。AI在每个步骤中都有明确的输入上下文规范从而能输出高质量、可直接整合的代码片段。3.3 代码审查与反馈循环AI生成代码后进入人工审查阶段。审查时我重点关注缓存逻辑AI生成的Redis Key是否唯一序列化方式是否与项目其他部分一致我们项目使用Jackson序列化AI不能自己用JDK序列化。异常处理Service层是否捕获了缓存或数据库操作的异常并做了适当处理或日志记录XML SQL检查生成的动态SQL确保if test中的条件判断正确特别是对LocalDateTime的判断要防止OGNL表达式错误。依赖注入OrderServiceImpl中RedisTemplate的注入方式是否正确我们项目习惯用Resource按名称注入。如果发现有问题比如缓存Key设计不合理我会直接给出反馈 “这里生成的Redis Keyorder:list:${userId}:${pageNum}在用户分页查询时是合理的。但考虑到订单列表可能根据时间筛选Key中应该加入startTime和endTime的哈希值否则不同的时间条件查询会错误命中缓存。请参考UserService中的generateCacheKey方法进行重构。”Claude Code能够理解这个反馈并基于你指明的参考方法进行修改。这个过程就是一次高效的“现场培训”。4. 制度之上的进阶AI Agent与自主工作流当我们为AI建立了扎实的“工程制度”后就可以展望更高级的协作模式——AI Agent。AI Agent不是简单的代码补全工具而是能够理解复杂目标、自主拆解任务、调用工具、并执行工作流的智能体。Claude Code Skill与自定义工作流Claude Code的“Skill”功能可以看作是对“工程制度”的封装和自动化。你可以创建一个“生成Spring Boot CRUD模块”的Skill这个Skill里封装了读取项目架构上下文的步骤。依次生成Entity、DTO、VO、Mapper、Service、Controller、单元测试的系列指令模板。每一步指令所关联的代码规范和质量要求。当你启动这个Skill输入“实体类名Product字段id, name, price, categoryId”它就能自动执行一整套流程生成完全符合你团队制度的标准代码。这相当于将“规范”和“流程”固化成了可重复执行的脚本。面向AI Agent的工程制度设计未来当AI Agent能力更强时我们的“工程制度”需要升级为“Agent工作手册”。这本手册可能需要定义权限边界Agent可以访问哪些系统如Git、JIRA、测试环境、执行哪些操作创建分支、提交代码、部署到开发环境。决策流程遇到模糊需求时Agent是应该直接询问人类还是根据某种规则自行决策验收标准如何定义一个任务被“完成”是代码通过CI流水线还是通过了自动化测试套件回滚机制如果Agent的操作导致了问题如何快速回滚例如你可以设计一个Agent工作流“每天早上自动检查未关闭的Bug对于标记为‘简单修复’的Bug尝试自动生成修复代码提交Pull Request并通知对应的负责人审查。” 这个工作流要能运行起来前提就是Bug的定义、代码规范、提交流程、通知规则都已经被清晰地定义在了“制度”中。个人体会从“Plan模式”到“工程制度”本质上是一种思维转变。我们不再把AI当作一个神秘的“许愿机”而是把它视为一个能力超强但需要严格指导和约束的新团队成员。制定制度的过程也是倒逼我们团队自身将隐性知识显性化、将模糊流程标准化的过程。最终这套制度不仅提升了AI的产出效率和质量也让团队新人 onboarding 更快让代码库更加一致和健壮。给AI一套好的工程制度最终受益的是我们整个工程团队。