★ FEATURED ARTICLE 三个月前我们内部项目组做了一次特别的工作流改造把 AIcoding 从“偶尔用一下的辅助工具”变成“日常开发的固定环节”。改造完成之后我最大的感受不是代码写得更快了而是 AI 写的代码终于“懂事”了。而这一切的转折点是一份叫 intent.md 的文件外加一套持续评测机制。这篇内容就围绕这次改造展开讲清楚什么是 intent.md、它解决什么问题、持续评测怎么搭以及我们踩过的那些坑。如果你是正在做内部 AIcoding 落地、或者想把手头的 AI 编码工作流做得更稳的人这篇文章应该能给你一些可以直接抄作业的思路。先说明一下我理解的 AIcoding它不是让 AI 完全替代人写代码而是把“编码任务”变成“意图表达 结果验证”的工作流。传统开发是人写需求、人写代码、人测试AIcoding 则是人写意图、AI 出代码、人去验证。这个转变里最大的难点不是模型选型而是怎么把“意图”这件事做得足够扎实。我们最初试过直接让大模型基于需求文档干活也试过在聊天窗口里反复调试提示词结果都不理想。最后沉淀下来的方案就是现在要聊的 intent.md 和持续评测。1. 为什么 AIcoding 落地卡在了“意图传递”而不是“模型能力”我们内部项目的代码主要跑在订单、支付、供应链这条线上。团队很早就开始用 AI 辅助编码Copilot、ChatGPT 都用过但效果一直飘忽不定。有时候让 AI 写一个工具函数写得干净利落有时候让它改一个业务方法它能给你整出个逻辑漏洞。最开始大家都觉得是模型不行后来复盘多了才发现真正的问题出在“任务意图”根本没被完整表达出来。1.1 从“提示词工程”到“意图工程”一次认知转变大部分团队用 AIcoding 的方式本质上还是把大模型当成一个“高级搜索框”需求来了把零散的文字往对话框里一丢然后等结果。需求文档、聊天记录、代码注释、口头交代这些东西混在一起模型能看到的只是一堆碎片。举个最典型的例子。我们有个同事让 AI 重构一个订单查询接口提示词里写的是“优化一下这个函数的性能注意幂等”。AI 确实优化了性能还把方法签名改了结果下游两个调用方直接编译报错。为什么因为“注意幂等”这句话在业务里的真实含义是“同一个订单多次请求时不要重复创建支付流水”但 AI 理解的“幂等”可能只是“重复调用时返回缓存结果”。这种偏差靠堆提示词是解决不了的。这就是为什么我们要从“提示词工程”转向“意图工程”。提示词是一段随口的描述而意图是一份文件。这份文件把任务的背景、目标、边界、验收标准、禁止事项全部写清楚让 AI 在动手之前就对齐所有上下文。用管理学的说法提示词是“口头布置”intent.md 是“书面任务书”。对一个稍微复杂点的编码任务来说没有书面任务书翻车是大概率事件。1.2 选一个“小而痛”的模块做突破想一步到位把整个项目改造完是不现实的。我们挑了一个边界清晰、痛点明显、改动范围可控的模块来做试点订单服务的错误处理模块。这个模块的问题肉眼可见错误码定义混乱同一个错误在不同的接口里返回不同状态码日志信息割裂排查一个问题要翻好几个服务部分异常被静默吞掉线上出了故障都定位不到根因。选这个模块的原因很简单。第一它的痛点足够具体团队内部有共识改造的收益一眼就能看到。第二它的边界足够清晰主要影响订单查询、订单状态变更和支付回调几个入口改造失败也不会把整个系统搞瘫。第三它适合做评测错误处理的行为是可验证的——输入什么参数、返回什么错误码、写不写日志这些都是可以写成测试用例的硬指标。实践下来我强烈建议做类似改造的人也按这个思路来不要一上来就搞“全项目 AIcoding 转型”而是找一个边界清晰、反馈直接的小模块把意图文件、生成、评审、评测这一整套流程跑通。小模块跑通了方法论才能有说服力后面推广才推得动。2. intent.md 的设计把任务意图写成“可被 AI 执行的文件”intent.md 这个名字字面意思就是“意图文件”。它不是需求文档的替代品而是专门给 AI 看并用于约束其编码行为的任务说明。它解决的问题是AI 在生成代码前需要一份足够清晰、足够结构化、又足够简洁的上下文。2.1 一个意图文件最少包含哪些字段我们经过多轮迭代把 intent.md 固定为十个字段。大家刚开始可能觉得字段多但用熟了之后会发现每一个字段都在特定场景下救过命。下面这个表格是我目前比较推荐的版本。字段作用必填background业务背景与改动动机必填goal本次改动的核心目标一句话说清必填scope明确改动范围哪些文件/模块可以动必填inputs输入数据的来源与格式按需outputs输出结果、返回值、落库内容必填success-criteria验收标准尽量量化必填constraints技术约束、性能要求、兼容性要求必填anti-goals明确禁止做的事防止 AI 发散必填terminology术语定义表统一概念含义按需related-files关联代码路径与依赖说明必填乍一看这很像平时写需求文档的要素。关键区别在于intent.md 是写给模型执行用的所以每个字段都要写得“可运行”——AI 拿到之后能直接映射到代码逻辑而不是还要它自己去做业务推理。像“注意幂等”这种话就不合格应该写成“同一订单号在五分钟内重复请求支付回调时只允许创建一条支付流水记录”。2.2 订单错误处理改造的 intent.md 实例直接看我们实际用的文件会更有感觉。下面是订单错误处理模块一次改造任务的 intent.md 简化版保留核心结构。# Intent: 订单错误处理模块重构 ## background 订单服务当前错误处理逻辑分散在多个 Controller 和 Service 中错误码定义不一致 部分异常被吞掉日志缺失严重线上排障依赖人工 review。 ## goal 统一订单服务的错误码体系补齐日志输出确保所有外部接口异常都能返回标准化错误结构。 ## scope - 可改动order-service 下的 controller、service、error-handler 目录 - 不可改动支付网关对接层、数据库访问层、下游库存服务接口 ## inputs - 外部请求OrderRequestDTO 对象包含 orderId, userId, amount, channel - 内部依赖OrderRepository, PaymentClient, InventoryClient ## outputs - 统一返回结构{ code, message, requestId, data } - 错误日志包含 requestId、orderId、错误类型、堆栈摘要按 ERROR 级别输出 ## success-criteria 1. 所有 Controller 接口不再返回裸异常统一走 ResultWrapper 2. 错误码收敛到错误码表中的 27 个枚举值删除自定义魔法数字 3. 单测覆盖新增改动的分支核心错误路径覆盖率达到 85% 以上 ## constraints - 保持接口兼容已有客户端依赖的字段不能改名 - 响应时间不得因新增日志逻辑增加超过 2ms - 不引入新的第三方依赖 ## anti-goals - 不要重构 Controller 层的 URL 路由结构 - 不要修改订单状态机的流转逻辑 - 不要为兼容旧错误码而保留 Deprecated 状态 ## terminology - requestId网关层传入的全局追踪 ID格式为 UUID - 幂等同一 orderId 的业务请求在重复提交时只生效一次 ## related-files - order-service/src/main/java/.../OrderController.java - order-service/src/main/java/.../OrderErrorHandler.java - order-service/src/main/resources/error-code.json这个文件看起来不复杂但它解决了一个很关键的问题AI 不用再猜了。它知道哪些文件能碰、哪些不能碰知道成功标准是“错误码收敛到 27 个枚举值”而不是“优化一下代码结构”。我们第一次拿着这种完整意图文件去跑 AIcoding 任务生成的代码质量直接提升了一个档次。2.3 三条写作原则克制、具体、可验证写 intent.md 写过一段时间之后我总结出三条原则。第一条克制。字段别贪多一个任务写清楚十个字段就足够了不要试图把整个业务规则都塞进去。AI 处理长文本时照样有注意力漂移的问题文件超过一定篇幅它的执行度反而下降。我们的经验是正文控制在 80 到 120 行之间超过这个范围就要考虑拆任务了。第二条具体。写 background 的时候不要写“系统存在性能问题”而是写“订单查询接口在 10 万单量级下平均响应 800ms其中 60% 耗时花在 N1 查询上”。AI 对具体数字的敏感度远高于模糊形容词。这一条在写 success-criteria 的时候尤其重要。第三条可验证。每个字段都应该能映射到测试动作。比如 success-criteria 里的“错误码收敛到 27 个枚举值”这是可以写脚本统计的而“代码更加健壮”这种话就是无效信息AI 和人都不知道它到底该做什么。我们后来还把 intent.md 的通过率纳入了持续评测体系这就引出了下一个章节。3. 持续评测让每一次 AIcoding 改动都有“数字账本”intent.md 是输入持续评测是保障。只有 intent.md 没有评测你永远不知道 AI 生成的代码到底行不行。评测这个东西听起来像是正规软件团队才做的事但做 AIcoding 落地时它比传统开发场景还要重要——因为你面对的是一个每次输出都可能不一样的“非确定性开发者”。3.1 评测集怎么建从真实任务里沉淀样例持续评测的第一步是建评测集。我们当时的做法是把过去三个月实际交给 AI 做的编码任务整理出来加上改造订单模块过程中产生的典型任务一共沉淀了 20 个固定评测任务。每个任务包含三部分任务描述、intent.md 模板、预期行为。预期的行为我们用一组可执行的规则来描述。比如对于错误处理任务预期行为是“入参 orderId 不存在时返回 code404001同时日志中必须包含 requestId 和 orderId”。这些规则不是泛泛的“代码要优雅”而是可以直接用脚本或单元测试校验的硬断言。评测结果分三档全部断言通过记为 PASS部分断言通过记为 PARTIAL核心断言失败记为 FAIL。评测集建好之后最忌讳的事情就是把它锁在抽屉里不更新。我建议每两到四周根据真实任务补充一次把生产环境里新发现的问题类型转化成新的评测样例。评测集的质量直接决定了这套机制能帮你挡住多少问题所以宁可在建集的时候多花时间。3.2 评测流程与轻量级工具链我们在项目里的评测流程分为五步。首先是任务分发拿到一个内部需求后人工写好 intent.md然后提交到任务池。第二步是 AI 生成AI 读取 intent.md生成代码变更。第三步是自动化校验跑一遍评测集里对应的测试用例同时用脚本检查代码风格、错误码收敛情况、日志格式等静态规则。第四步是人工评审自动化通过之后仍然要有资深工程师做代码走查重点看 AI 生成的逻辑有没有业务语义上的坑。第五步是回归评分每次 intent.md 或评测集有变更时把历史任务全部重新跑一遍确保没有出现“修好一个任务、弄坏另一个任务”的回归。工具链方面我们没有引入特别复杂的东西。评测脚本用 Python 写测试用例用项目现有的单测框架任务池就是一个简单的 Git 分支加 Issue 列表。整套流程不需要平台化先把流程跑起来比什么都重要。如果一上来就想着做平台很容易陷入工具建设的无底洞。这里有一个我们必须接受的现实AIcoding 的产出不能只看通过率还要看返工率。我们统计过第一版跑完评测后大约 40% 的任务需要二次修正经过 intent.md 持续优化后这个比例降到了 15% 左右。所以与其期待 AI 一次生成完美代码不如把流程设计成“快速生成、快速验证、快速修正”的闭环。3.3 评测结果反哺意图文件的方法持续评测最有价值的地方不是打分本身而是通过分数变化反推 intent.md 哪里写得不够好。举个我们亲历的例子。订单错误处理模块第一次跑评测时有几个任务反复在“超时处理”上翻车。AI 生成的代码要么没做超时判断要么超时后返回了错误的错误码。我们一开始以为是模型能力问题后来翻了一下 intent.md发现 constraints 字段里压根没提超时阈值和超时后的处理策略。这就是意图文件的信息缺口。把“超时阈值 500ms超时后返回 code408001并记录 timeout 标签日志”补进去之后相关评测任务的通过率直接从 55% 升到了 95%。评测不是目的改意图文件才是目的。每一次评测暴露的问题都要能回溯到 intent.md 的某个缺失信息上。如果一个问题连续出现两次就说明它不是偶发现象要不要把它写进 anti-goals 或 constraints 就得认真考虑了。我在实际操作中的体会是每个 intent.md 都需要版本管理。文件变更之后最好把涉及到的评测任务重新跑一遍。因为 AIcoding 的产出具有随机性你今天改了意图文件下一次生成结果可能就好转也可能反而变差没有持续评测你判断不了到底是不是文件改对了。4. 内部改造踩过的坑从术语混乱到评测集过拟合光讲顺利的部分不叫分享。下面这些坑都是我们内部这次改造中真实踩过的每一个都付出了不少时间和返工成本。4.1 意图文件写太长AI 反而抓不住重点第一次正经写 intent.md 的时候我犯了一个典型错误想把所有业务细节都写进去。文件写到了三百多行背景、历史、每个接口的演进过程事无巨细。结果 AI 生成的代码表现得非常“犹豫”该改的没改不该动的还动了不少。后来我意识到意图文件的核心信息密度才是关键不是在写技术方案文档。现在的做法是把“背景”压缩到三四句把“约束”提炼成可检查的规则把“禁止事项”写得像红灯一样明确。如果一个意图文件超过一百二十行我会直接拆成两个任务。AIcoding 和带团队是一样的逻辑一次交代太多事做出来肯定有偏差。4.2 术语表必须全局统一否则 AI 会“自以为懂”“幂等”这个坑我们踩得最狠。不同模块对这个词的理解不一致订单模块认为幂等是“同一订单不重复创建支付流水”而库存模块认为幂等是“同一 SKU 的库存扣减请求只生效一次”。当任务同时涉及两个模块时AI 会随机选择一种理解而你根本不知道它选了哪一种。现在的强制要求是只要 intent.md 中的关键词可能产生歧义就必须在 terminology 字段里给出项目内的定义。这个原则不仅对 AI 有效对团队内部沟通同样有效。术语统一之后人工评审的压力也小了很多因为大家沟通的基础一致了。有趣的是我们在做 aicoding 笔试题设计的时候也沿用了这个思路——要求候选人在写代码前先定义术语这一步直接刷掉了相当一部分只会“能跑就行”的人。4.3 意图漂移代码改了文件没跟着改意图漂移是隐蔽性最强的一个坑。开发节奏一快工程师改完代码顺手就提交了intent.md 还停在改之前的状态。过了两周AI 再基于这个过期文件生成新代码时就会做出和已有代码逻辑冲突的改动。我们在推行一个硬性约定任何 AIcoding 产生的代码变更都必须在同一个 PR 里包含对应的 intent.md 变更记录。如果代码改动扩大了原有范围必须更新 scope 或 anti-goals 字段并重新跑一遍评测。这个约定听起来很小但执行之后AI 生成代码和实际代码仓库的“上下文漂移”问题大幅度减少。4.4 评测集过拟合跑分很高真刀真枪就垮持续评测做了一段时间后我们遇到了一个特别讽刺的问题评测集里的任务通过率越来越高但真实开发里 AI 的表现却没有同步提升。后来排查原因发现问题出在评测集本身——我们的任务样例太固定了AI 在迭代过程中相当于“背题”了。只要任务的表述稍微变化它的表现就回到原形。解决方法是给评测集引入动态变换。同一道核心任务每次生成时的描述方式、字段名、参数顺序都会做一些微调确保 AI 真正理解的是任务本质而不是特定字符串。另外我们还规定评测集中 30% 的任务应该是最近两周新增的真实案例防止评测体系变成一套封闭的“模拟题”。这个调整完成之后评测分数才慢慢变得能代表真实水平。4.5 顺便说说 aicoding 笔试题怎么设计因为我们内部在做 AIcoding 工作流改造团队自然要招一些具备这方面能力的人。后来我们发现传统的算法笔试根本考察不出候选人的 AIcoding 水平因为 AIcoding 的核心能力不是写代码本身而是“把任务意图表达清楚”和“验证 AI 产出”的能力。于是我们设计了一套新的笔试题。给定一个业务场景和一堆零散需求描述要求候选人先写一份 intent.md再借助 AI 工具生成代码最后提交一份评测说明。评分时重点看三块意图文件是否结构完整、边界和约束是否清晰AI 生成的代码是否严格匹配 intent.md 的验收标准候选人是否能看出 AI 代码里的问题并修正。这套题的背后逻辑其实和持续评测是同构的——都是看一个人能不能建立“意图输入、产出验证、反馈修正”的闭环。对想要内部推 AIcoding 的团队来说用同样的标准去选人和去评测代码是一个值得考虑的连招。5. 最后分享一点个人体会这套方案在项目里跑通之后新成员接入的速度明显变快了。以前新人了解一个模块要看半天代码和文档现在直接把相关 intent.md 拉出来看一遍再加上一轮评测集基本就能在自己脑子里建立完整的模块认知图。我个人最大的体会是AIcoding 不是把“写代码”变成“说需求”而是把“写代码”变成“写意图 验证结果”。intent.md 和持续评测本质上不是新工具而是把以前藏在资深工程师脑子里的隐性知识显性化成团队可以共享、迭代、评测的资产。这份资产一旦沉淀下来价值远超某一次 AI 生成的高质量代码。如果你也准备在内部项目里做类似的改造我的建议很直接别先买工具别先建平台先找一个小而痛的模块把第一份 intent.md 写出来把第一轮评测跑起来。等这个闭环转起来了你自然知道下一步该优化哪里。
阅读完成 · 觉得有帮助？
