1. 从“能跑就行”到“意图对齐”AIcoding 落地中最容易被忽视的一环过去大半年我一直在团队内部推动 AIcoding 的落地。从最初让每个人装个插件、写几句 prompt 试试水到后来把 AI 生成代码正式纳入 SDLC 流程中间踩的坑比想象中多得多。最典型的一个现象是AI 生成的代码单测能过、编译能过但 review 的时候总觉得“哪里不对”——它实现的东西和需求文档里想表达的东西存在一层微妙的偏差。这种偏差在传统开发里靠口头沟通就能抹平但在 AIcoding 场景下因为生成速度太快、量太大反而被放大了。后来我们引入了一个叫intent.md的东西配合一套持续评测机制才算把这个问题按住。这篇文章就把我们内部项目改造的完整过程拆开讲包括intent.md到底该写什么、和CLAUDE.md这类上下文文件是什么关系、持续评测怎么搭、以及那些只有真正跑过一轮才会知道的坑。如果你正在团队里推 AIcoding或者正在准备 AIcoding 相关的笔试题、面试题这套东西应该能给你一个可复现的参考框架。先说清楚适用人群这篇文章不是给“刚听说 AIcoding”的人看的科普而是给已经动手、但发现效果不稳定、想把它工程化的人看的。你需要对 SDLC 有基本认知知道 CI/CD 大概怎么跑最好已经用过至少一种 AI 编码工具。至于intent.md这个命名它不是某个官方标准是我们内部约定的一种文件形态你可以叫它spec.md、task.md核心思想是一样的。2. intent.md 到底是什么和 CLAUDE.md、需求文档的边界在哪2.1 为什么已有的上下文文件不够用很多人第一反应是我已经有CLAUDE.md了里面写了项目结构、技术栈、编码规范为什么还要再搞一个intent.md这个问题我一开始也问过自己。实际用下来发现CLAUDE.md解决的是“这个项目长什么样”的问题它是一份长期稳定的项目上下文描述的是代码库的静态特征目录结构、依赖版本、命名约定、构建命令。它不会随着某个具体任务变化。而intent.md解决的是“这一次改动到底要达成什么”的问题它是任务级的意图声明。举个具体的例子CLAUDE.md里会写“本项目使用 TypeScript禁止使用 any”但intent.md里会写“本次改造要把订单查询接口的响应时间从 800ms 降到 200ms 以内允许引入缓存层但缓存失效策略必须保证最终一致性”。前者是约束后者是目标加取舍。需求文档PRD和intent.md的区别更微妙。PRD 是给人看的它允许模糊、允许留白因为人可以追问、可以脑补。但 AI 不会追问它只会按字面理解去生成。所以intent.md本质上是把 PRD 里那些“人默认懂、但没写出来”的部分显式地翻译成 AI 能消费的形式。我通常说intent.md是 PRD 的“可执行投影”。2.2 intent.md 的核心结构四段式写法经过几轮迭代我们把intent.md固定成了四个部分。这个结构不是拍脑袋定的每一段都对应一类 AI 容易跑偏的场景。第一段是目标声明Goal。用一句话说清楚这次改动要达成什么可验证的结果。注意是“可验证”不是“优化用户体验”这种没法测的表述。比如“将用户登录接口的 P99 延迟降低到 300ms 以下”就是可验证的“提升登录体验”就不是。第二段是约束条件Constraints。这里放那些“不能碰”的东西不能改数据库 schema、不能引入新的外部依赖、必须保持向后兼容。这一段是防止 AI“过度发挥”的关键。我见过太多次 AI 为了达成目标顺手把不相关的模块重构了结果引入一堆回归问题。第三段是验收标准Acceptance Criteria。用 checklist 的形式列出每条都要能被自动化测试覆盖。这一段直接决定了后面持续评测怎么写。第四段是上下文补充Context。放那些 AI 需要知道、但不适合写进CLAUDE.md的一次性信息比如“这个模块下周要迁移所以本次改动尽量局部化”。2.3 一个真实的 intent.md 示例光说结构太抽象直接上一个我们内部改造订单模块时的真实文件脱敏后# Intent: 订单查询接口性能优化 ## Goal 将 GET /api/orders/{id} 的 P99 响应时间从 800ms 降至 200ms 以下。 ## Constraints - 不得修改 orders 表的 schema - 不得引入新的外部服务依赖 - 必须保持现有 API 响应结构完全兼容 - 缓存层必须支持手动失效 ## Acceptance Criteria - [ ] P99 延迟 200ms压测脚本 bench/order_query.js - [ ] 现有 47 个集成测试全部通过 - [ ] 缓存命中率 85%基于生产流量回放 - [ ] 缓存失效后 5 秒内数据一致 ## Context - 该模块计划 Q3 迁移到新服务本次改动保持局部 - 现有 Redis 集群已有 30% 余量可直接复用这份文件大概 200 字但它把 AI 生成代码时的决策空间压缩到了一个很窄的范围内。实测下来有了这份文件AI 首次生成代码的可用率从大概 40% 提升到了 75% 左右。这个数字不是精确统计是 review 时“基本不用大改”的比例。3. 持续评测机制让 AIcoding 从“一次性生成”变成“可回归”3.1 为什么单次评测不够AIcoding 有个很反直觉的特点同一个 prompt今天生成的结果和明天生成的结果可能不一样。模型在更新、上下文在变化、甚至温度参数的微小差异都会导致输出漂移。所以如果你只在引入 AIcoding 的第一周做一次评测得出“效果不错”的结论那这个结论两周后就失效了。持续评测的核心思路是把 AI 生成代码的质量当成一个需要持续监控的指标而不是一次性的验收动作。这跟传统软件里“性能回归测试”的逻辑是一样的你不是测一次性能就完事而是每次改动都跑一遍确保没有退化。3.2 评测集的构建三层结构我们的评测集分三层从粗到细。第一层是冒烟评测Smoke Eval大概 20 个用例覆盖最常见的任务类型新增一个 CRUD 接口、修改一个已有函数、写一个单测、重构一段代码。这一层跑得很快几分钟出结果主要看 AI 有没有“基本能力退化”。第二层是意图对齐评测Intent Alignment Eval这是核心。针对每个intent.md我们准备 3 到 5 个变体测试 AI 在不同表述下是否能稳定理解意图。比如同一个性能优化目标分别用“降低延迟”“提升响应速度”“优化 P99”三种说法看生成结果是否一致。这一层能暴露 AI 对意图理解的稳定性问题。第三层是边界评测Edge Eval专门测那些容易出错的场景约束条件冲突时 AI 怎么取舍、验收标准里有互相矛盾的条目时 AI 怎么处理、上下文信息不完整时 AI 会不会瞎猜。这一层用例不多但每个都是踩过坑之后补上去的。3.3 评测的执行怎么和 CI 集成持续评测要真正“持续”必须进 CI。我们的做法是在 PR 流程里加一个ai-eval的 job触发条件是当 PR 里包含 AI 生成的代码标记时我们在 commit message 里约定了一个[ai-gen]前缀自动跑评测集。这里有个细节值得说评测不是跑一次就完而是跑两次。第一次用生成代码时的原始intent.md第二次用一个“扰动版”的intent.md把表述换一下、顺序调一下。两次结果如果差异超过阈值就标记为“意图理解不稳定”需要人工介入。这个双跑机制帮我们抓出了好几个隐蔽的问题。评测结果不阻塞合并但会作为一个 comment 自动贴到 PR 上包含通过率、失败用例、和上次评测的对比。我们内部有个约定如果意图对齐评测通过率低于 80%reviewer 必须重点看 AI 生成的部分。4. 内部项目改造实录从零搭起这套流程4.1 改造前的状态和痛点我们改造的是一个内部运营后台大概 15 万行 TypeScript 代码5 个开发维护。引入 AIcoding 之前大家的用法很随意有人直接在 IDE 里让 AI 补全有人把需求贴到对话框里让 AI 生成整个文件。问题集中在三个地方。第一是风格漂移。不同人用 AI 生成的代码风格差异很大有的用async/await有的用 Promise 链review 时经常要花时间统一。第二是意图偏差前面说过了AI 实现的东西和需求有微妙差异。第三是无法回归AI 生成的代码改完之后没人知道下次 AI 生成同样需求会不会又出问题因为根本没有评测基线。4.2 改造的三个阶段我们分三个阶段推。第一阶段是规范期大概两周。这个阶段不追求效率提升只做一件事让所有人按统一格式写intent.md。我们定了一个模板要求每个用 AI 生成代码的任务必须先写intent.md写完才能开始生成。这个阶段大家怨声载道觉得多了一道手续但两周后回头看正是这道手续把意图偏差问题压下去了。第二阶段是评测期大概一个月。这个阶段开始搭评测集、接 CI。一开始评测集只有 10 个用例跑起来经常误报我们花了不少时间调阈值、补用例。这个阶段的产出是一套能稳定跑的评测流程以及一份“AI 生成代码质量基线”。第三阶段是优化期持续进行。有了基线之后我们开始做针对性优化哪些任务类型 AI 表现好、哪些差差的就补intent.md模板、补评测用例、或者干脆规定这类任务不用 AI。这个阶段的核心是数据驱动不再凭感觉。4.3 改造后的量化变化说几个能拿出来的数字。AI 生成代码的首次可用率从 40% 左右提升到 75%。Review 时间平均缩短了 30%因为风格统一了、意图清晰了reviewer 不用再猜“这段代码想干嘛”。回归问题数量下降了大概一半因为持续评测把很多问题在合并前就拦住了。但也要说清楚代价写intent.md本身要花时间平均每个任务多花 10 到 15 分钟。评测集的维护也要投入我们大概每周花 2 小时补用例、调阈值。所以这套东西不是免费的它适合那些 AIcoding 用量已经比较大、问题已经开始显现的团队。如果只是偶尔用用可能不值得上这套。5. 踩过的坑和排查技巧5.1 intent.md 写太细反而效果差一开始我们觉得intent.md越详细越好有人写了 2000 字把每个函数签名都规定死了。结果 AI 生成出来的代码确实符合要求但完全没有发挥 AI 的优势——它变成了一个“按模板填空”的工具遇到intent.md没覆盖的边界情况就卡住。后来我们定了个经验值intent.md控制在 300 到 500 字只写目标、约束、验收标准、关键上下文具体实现留给 AI。这个长度下AI 有足够的决策空间同时意图又足够清晰。5.2 评测用例的“过拟合”问题评测集跑久了会出现一种情况AI 生成的代码越来越“擅长”通过评测但实际质量没提升。这是因为评测用例本身被 AI“记住”了——如果评测用例和训练数据有重叠或者用例太固定AI 会针对性地优化。我们的解法是定期轮换评测用例大概每两个月换掉 30%。同时保留一部分“隐藏用例”不放在公开的评测集里只在最终验收时跑。这样能测出 AI 的真实泛化能力而不是“应试能力”。5.3 常见问题速查表问题现象可能原因排查方向AI 生成代码风格不一致CLAUDE.md 约束不够具体补充命名、格式、依赖使用的硬性规定意图对齐评测通过率骤降模型版本更新或 prompt 模板改动对比评测日志定位变化点评测误报率高阈值设置过严或用例本身有歧义放宽阈值重写有歧义的用例AI 忽略约束条件约束写在 intent.md 靠后位置把硬约束前置用加粗强调生成代码过度重构目标描述太宽泛收窄 Goal增加“保持局部”类约束5.4 一个容易被忽视的细节intent.md 的版本管理intent.md必须进版本库和代码一起管理。我们一开始有人把intent.md放在本地不提交结果出了问题回溯时找不到当时的意图声明没法判断是 AI 理解错了还是意图本身写错了。现在我们的规矩是intent.md和对应的代码改动在同一个 commit 里commit message 里引用intent.md的路径。这个细节看起来小但在排查“为什么 AI 生成了这段奇怪的代码”时能直接看到当时的意图省掉大量猜测。6. 关于 AI-native SDLC 的一点个人理解最近“AI-native SDLC playbook”这个词被提得很多我理解它的核心不是“用 AI 替代 SDLC 的某个环节”而是“把 AI 当成 SDLC 里的一等公民来对待”。传统 SDLC 里人是唯一的执行者流程是为人设计的。AI-native 的意思是流程要同时考虑人和 AI 的协作方式。intent.md和持续评测本质上就是在 SDLC 里给 AI 加的两个“接口”一个负责输入意图一个负责输出质量。这两个接口建好了AI 才能真正融入流程而不是作为一个外挂工具存在。我在实际推这套东西的过程中最大的体会是不要指望一步到位。先从一个任务类型开始把intent.md写起来把评测跑起来跑顺了再扩到其他类型。那些一上来就想搞“全流程 AI 化”的往往在第二周就推不动了。小步快跑用数据说话比什么方法论都管用。