1. 从“能跑就行”到“意图对齐”AIcoding 落地内部项目的真实起点去年下半年开始团队里几乎每个人都在聊 AIcoding。一开始大家的兴奋点很朴素让模型帮我们写点样板代码、补几个单元测试、顺手把 lint 报错清一清。可真到了内部项目改造这种“老代码 老逻辑 老约定”的场景里问题立刻暴露出来——模型写出来的东西语法没错、测试也能过但就是“不是我们想要的那个东西”。它不知道这个模块为什么存在不知道哪些字段是历史包袱不能动更不知道我们内部那套隐性的命名约定和错误码规范。这就是我写这篇东西的起因。标题里的intent.md和持续评测不是两个时髦词而是我在把一个真实内部项目交给 AIcoding 流程改造时被逼出来的两个核心抓手。intent.md 解决的是“让模型知道我们要什么”持续评测解决的是“怎么证明它一直没跑偏”。而 CLAUDE.md、SDLC 这些词则是这套流程落地时绕不开的上下文文件和研发流程框架。这篇文章适合谁看如果你只是想让 AI 帮你写个爬虫脚本、生成个正则那没必要往下读。但如果你正准备把 AIcoding 引入到有历史包袱的内部系统改造里或者你正在准备 aicoding 相关的笔试题、想搞清楚 ai-native sdlc playbook 到底在讲什么那这篇从实战里抠出来的经验应该能帮你少踩几个坑。我会把 intent.md 怎么写、持续评测怎么搭、CLAUDE.md 和 intent.md 怎么分工、整个流程怎么嵌进 SDLC全部拆开讲清楚并且给出可以直接抄的模板和参数。先说结论性的判断AIcoding 在内部项目改造中的成败八成不取决于模型能力而取决于你有没有把“意图”显式化、把“验收”自动化。模型再强你给它一个模糊的“帮我重构这个模块”它只能猜你给它一份写清楚的 intent.md 加一套持续评测它就能稳定产出接近可合并的代码。下面我按实际落地的顺序一层层拆。2. intent.md 到底是什么和 CLAUDE.md 的分工与写法2.1 为什么光有 CLAUDE.md 不够很多人第一次接触 AIcoding 的上下文管理是从 CLAUDE.md 这类文件开始的。它的定位是“项目级长期约定”技术栈、目录结构、代码风格、常用命令、禁止事项。你可以把它理解成给模型看的《新员工入职手册》。这东西非常有用但它有个致命短板——它是静态的、跨任务的。内部项目改造往往是“一个任务一个样”。今天你要把订单模块的同步调用改成异步明天你要给用户中心加一层缓存后天你要把某个遗留的定时任务迁移到新调度框架。这些任务的意图、边界、验收标准完全不同但 CLAUDE.md 里不可能为每个任务都写一段。你如果硬往 CLAUDE.md 里塞它会迅速膨胀成几千行模型反而抓不住重点。所以我的做法是分层CLAUDE.md 管“这个项目长期怎么干活”intent.md 管“这一次改造到底要干什么”。前者是宪法后者是这一次的作战指令。两者配合模型既有稳定的背景知识又有明确的任务边界。2.2 intent.md 的六段式结构我试过很多版本最后稳定下来的 intent.md 是六段式。这个结构不是拍脑袋定的而是对应了模型在改造任务里最容易出错的六个地方。第一段是任务目标。用一句话说清楚这次改造要达成什么必须是可验证的结果不能是“优化一下”这种虚词。比如“把 OrderService 中同步调用 InventoryClient 的三处逻辑改为基于消息队列的异步扣减保证下单接口 P99 从 800ms 降到 300ms 以内”。第二段是范围边界。明确写出哪些文件、哪些模块在改动范围内哪些绝对不能碰。内部项目最怕的就是模型“顺手”改了不该改的地方。我一般会列出 allow list 和 deny listdeny list 里放那些历史包袱重、牵一发动全身的核心类。第三段是约束条件。包括不能引入的新依赖、必须保持兼容的接口签名、必须遵守的错误码规范、性能红线等。这一段是内部项目改造的灵魂因为内部系统的约束往往比开源项目多得多。第四段是验收标准。这是和持续评测直接挂钩的部分。每一条验收标准都要能被自动化检查不能自动化的也要写清楚人工检查的步骤。比如“所有新增异步逻辑必须有对应的幂等测试”“下单接口的集成测试全部通过”“不新增任何编译警告”。第五段是参考上下文。指向相关的设计文档、历史 issue、关键代码位置。模型不会自己去翻你的 wiki你得把入口给它。第六段是输出要求。规定它交付什么是直接改代码还是先给方案再改是分几个 commit还是一个大 patch要不要附带变更说明。2.3 一个可直接抄的 intent.md 模板下面这个模板是我在多个内部项目里迭代出来的你可以直接拿去改。注意里面的占位符要替换成你自己的内容。# Intent: [任务简称] ## 1. 任务目标 [一句话可验证目标含量化指标] ## 2. 范围边界 ### 允许改动 - path/to/moduleA/** - path/to/moduleB/ServiceX.java ### 禁止改动 - path/to/core/LegacyEngine.java - 任何数据库 schema 文件 ## 3. 约束条件 - 不新增第三方依赖 - 保持 public 方法签名不变 - 错误码遵循 docs/error-code.md - 新增逻辑必须幂等 ## 4. 验收标准 - [ ] 集成测试 suite: order-flow 全部通过 - [ ] 新增幂等测试覆盖 3 个异步分支 - [ ] 无新增编译警告 - [ ] P99 压测 300ms ## 5. 参考上下文 - 设计文档: docs/design/order-async.md - 相关 issue: #1234 - 关键代码: OrderService.java:120-180 ## 6. 输出要求 - 先输出改造方案确认后再改代码 - 按逻辑分 3 个 commit - 每个 commit 附带变更说明这个模板看起来简单但每一条都是踩坑换来的。比如“先输出方案再改代码”这一条是因为我早期直接让模型改结果它一口气改了十几个文件方向还错了回滚都费劲。加上这一条之后返工成本直接降了一个数量级。2.4 intent.md 和 CLAUDE.md 的协作方式实际使用时我会把 CLAUDE.md 放在项目根目录intent.md 放在一个专门的.ai/目录下按任务命名比如.ai/intent-order-async.md。每次让模型干活时在 prompt 里明确指向这两个文件。模型读 CLAUDE.md 获得项目背景读 intent.md 获得本次任务指令两者叠加输出的稳定性明显提升。这里有个细节CLAUDE.md 不要写太长控制在 200 行以内只放真正跨任务通用的内容。intent.md 可以详细但也要控制在 150 行以内太长了模型会漏读。我实测下来超过 200 行的上下文文件模型对后半部分的遵循度会明显下降。3. 持续评测体系让 AIcoding 的产出可量化、可回归3.1 为什么“跑一次测试”不叫持续评测很多人对评测的理解就是“改完跑一下测试”。这在 AIcoding 场景里远远不够。原因很简单AIcoding 的产出是不确定的。同一个 intent.md你今天跑和明天跑模型可能给你两个不同的实现。如果只跑一次测试你根本不知道这次通过是“真的对”还是“碰巧对”。持续评测的核心是把评测变成一套可重复执行、有基线、有趋势的体系。它要回答三个问题这次产出和上次比是变好了还是变差了这次产出有没有触碰红线这次产出在多大程度上满足了 intent.md 里的验收标准我在内部项目里搭的持续评测分三层静态检查层、测试回归层、意图对齐层。三层从快到慢、从机械到语义逐层过滤。3.2 静态检查层最快的一道闸静态检查层是成本最低、反馈最快的。它包含编译、lint、类型检查、依赖检查、格式检查。这一层的作用是挡住那些“一眼假”的产出。AIcoding 有时候会生成引用了不存在方法的代码或者引入了 intent.md 里明确禁止的依赖这些在静态层就能拦下来。我一般会把这层做成一个脚本模型每次产出后自动跑。脚本内容大致是先编译编译不过直接打回编译过了跑 lintlint 有新增错误打回再跑依赖分析对比改动前后的依赖树有新增未授权依赖打回。这一层跑完通常只要几十秒但能挡掉大概四成的低级问题。注意静态检查的基线很重要。你要记录改造前的 lint 警告数量、依赖列表评测时对比的是“增量”而不是绝对值。否则一个本来就有 50 个警告的老项目你永远过不了。3.3 测试回归层用测试套件锁住行为测试回归层是持续评测的主力。内部项目改造最怕的就是“改坏了没发现”所以测试覆盖是硬要求。但这里有个现实问题很多内部老项目的测试覆盖很差你不可能为了引入 AIcoding 先把测试补到 80%。我的做法是分两步走。第一步先圈定本次改造直接影响的模块把这些模块的现有测试跑通作为底线。第二步针对 intent.md 里的验收标准补一批“意图测试”。这些测试不一定追求覆盖率但必须精准覆盖本次改造的关键行为。比如改造异步扣减我就补三个测试正常扣减、重复消息幂等、库存不足回滚。测试回归层的关键是基线对比。我会在改造前跑一遍全量测试记录通过/失败清单改造后再跑一遍对比差异。只有“改造前失败、改造后通过”或者“两次都通过”才算合格“改造前通过、改造后失败”直接打回。这个对比逻辑写进脚本避免人工判断出错。3.4 意图对齐层最难但最有价值的一层前两层解决的是“代码对不对”意图对齐层解决的是“代码是不是我们要的”。这一层最难自动化但价值最高。我的做法是把 intent.md 里的验收标准逐条转成检查项能自动化的自动化不能自动化的做成检查清单。能自动化的比如性能指标我会跑一个轻量压测脚本对比 P99 是否达标。不能自动化的比如“错误码规范”我会写一个半自动的检查脚本扫描新增代码里的错误码输出一份报告让人工确认。还有一些更语义化的比如“异步逻辑是否真的解耦”我会让另一个模型实例来评审给它 intent.md 和 diff让它判断是否满足意图。这个“模型评审模型”的做法听起来有点玄但实测下来对明显偏离意图的产出识别率还不错可以作为人工评审前的预筛。3.5 持续评测的落地形态把这三层串起来我最终落地的形态是一个 CI 流水线。每次 AIcoding 产出提交后自动触发静态检查层先跑过了跑测试回归层再过了跑意图对齐层最后输出一份评测报告。报告里包含三层的结果、和基线的对比、以及是否建议合并的结论。这套东西搭起来大概花了我一周时间但后面每次改造都能复用边际成本极低。而且它带来的最大好处不是省时间而是让 AIcoding 的产出变得可信。团队里原本对 AI 改代码有顾虑的人看到这套评测报告后接受度明显提高。4. 把 AIcoding 嵌进 SDLC从需求到合并的完整流程4.1 ai-native sdlc playbook 到底在讲什么热词里有个“ai-native sdlc playbook”很多人问这是什么缩写。SDLC 是 Software Development Life Cycle软件开发生命周期。ai-native 的意思是“原生为 AI 设计的”playbook 就是操作手册。合起来它讲的是一套“把 AI 作为一等公民嵌入研发全流程”的方法论。传统 SDLC 是需求、设计、开发、测试、部署、运维。ai-native 的版本不是简单地在每个环节加个 AI 工具而是重新设计每个环节的输入输出让 AI 能稳定参与。比如需求环节要产出结构化的 intent.md开发环节要产出可评测的 diff测试环节要产出意图测试。这套东西的核心思想和我前面讲的分层评测、意图显式化是一脉相承的。4.2 需求阶段把模糊需求翻译成 intent.md内部项目改造的需求往往来自一句话“把这块改快一点”。这种需求直接丢给模型就是灾难。我的做法是在需求阶段就强制产出 intent.md。产品或者提需求的人不用自己写但必须参与确认。我会先根据需求草拟一版 intent.md然后拉着提需求的人过一遍重点确认验收标准那一段。这一步的产出物就是一份双方认可的 intent.md。它既是给模型的任务书也是后续评测的基准。很多改造失败根子就在这一步没做扎实验收标准含糊后面评测无从谈起。4.3 开发阶段方案先行分步交付开发阶段我坚持“方案先行”。模型读完 CLAUDE.md 和 intent.md 后先输出改造方案我确认后再让它改代码。改代码时要求分 commit每个 commit 对应一个逻辑单元。这样做的好处是如果某个 commit 的评测没过回滚范围小定位问题也快。这里有个实操技巧让模型在每个 commit 的说明里写清楚“这个 commit 对应 intent.md 的哪条验收标准”。这样评测时可以直接建立映射哪条标准没过一眼就知道是哪个 commit 的问题。4.4 测试与合并阶段评测报告作为合并门槛测试阶段就是跑前面那套持续评测。评测报告作为合并的硬门槛三层全过才允许合并。如果有层没过报告里会指出具体是哪条标准、哪个文件、哪一行。模型根据报告修复再跑一遍评测直到全过。这个流程跑顺之后我发现一个有意思的现象模型在“知道有评测”的情况下产出的质量会明显更高。因为 intent.md 里的验收标准它读到了评测的存在它也知道它会更倾向于写出符合标准的代码。这有点像考试有明确评分标准的时候答题方向会更准。4.5 一个完整的改造案例复盘我拿一个真实案例走一遍。需求是“用户中心的头像上传接口太慢要优化”。第一步我把它翻译成 intent.md目标是头像上传 P99 从 1.2s 降到 500ms 以内范围是 UserAvatarService 及其依赖的存储客户端约束是不改接口签名、不新增依赖验收标准是压测达标、上传成功率不降、无新增警告。第二步模型读 CLAUDE.md 和 intent.md输出方案把同步的图片压缩和存储上传改成并行压缩用线程池上传用异步客户端。我确认方案合理。第三步模型分三个 commit 改代码第一个 commit 抽离压缩逻辑第二个 commit 引入并行第三个 commit 改上传为异步。每个 commit 都标注了对应的验收标准。第四步跑持续评测。静态层过测试回归层过意图对齐层的压测显示 P99 降到 420ms达标。评测报告建议合并合并完成。整个过程从提需求到合并大概用了半天其中模型干活的时间不到一小时剩下都是我在确认方案和看评测报告。这个效率在以前是不可想象的。5. 常见问题与排查技巧实录5.1 模型不遵守 intent.md 怎么办这是最常见的问题。模型明明读了 intent.md还是改了禁止改动的文件或者引入了禁止的依赖。我的排查思路是分三步先确认 intent.md 是否真的被读进去了有时候是 prompt 里路径写错了再确认 intent.md 里的约束是否足够具体“不要改核心文件”这种表述太模糊要写成具体的文件路径最后确认约束是否放在了显眼位置我一般把禁止改动放在 intent.md 的前三分之一模型对前部内容的遵循度更高。如果都确认了还是不遵守我会在 prompt 里再强调一遍关键约束并且要求模型在输出方案时逐条复述约束。这个“复述”动作能显著提高遵循度。5.2 评测通过但代码质量差怎么办评测通过只代表满足了验收标准不代表代码写得好。我遇到过模型写出能过测试但可读性极差的代码。解决办法是在 intent.md 的输出要求里加上代码质量约束比如“新增方法不超过 50 行”“圈复杂度不超过 10”“必须有注释说明异步逻辑的幂等保证”。这些约束可以部分自动化检查部分靠人工评审。另外我会在 CLAUDE.md 里放一份代码风格示例让模型有具体的模仿对象。光说“写得好一点”没用给它看一段好代码它模仿得会好很多。5.3 评测太慢拖累迭代怎么办三层评测全跑一遍确实不快尤其是测试回归层。我的优化思路是分级触发静态层每次必跑测试回归层只跑受影响模块的测试意图对齐层只在准备合并时跑。这样日常迭代快合并前把关严。还有一个技巧是缓存。测试回归层里那些和本次改动无关的测试如果代码没变可以跳过。我用的是基于文件哈希的缓存改动文件对应的测试才跑其他跳过。这个优化让评测时间从十几分钟降到两三分钟。5.4 常见问题速查表问题现象可能原因排查方向解决技巧模型改了禁止文件约束不具体或位置靠后检查 intent.md 约束段用具体路径放前部要求复述评测通过但质量差缺质量约束检查输出要求段加行数/复杂度约束给风格示例评测太慢全量跑无缓存检查触发策略分级触发 哈希缓存产出不稳定上下文太长检查文件行数CLAUDE.md 200 行intent.md 150 行验收标准无法自动化标准太模糊检查验收标准段量化指标拆成可检查项模型漏读上下文路径错误或格式问题检查 prompt 路径用绝对路径确认文件可读5.5 几条踩坑换来的经验第一条intent.md 一定要版本化。每次改造的 intent.md 都存进 git这样出问题可以回溯当时到底给模型下了什么指令。我吃过亏有一次改造出问题想复盘却发现 intent.md 被覆盖了只能凭记忆。第二条评测基线要定期更新。项目在演进基线不能一成不变。我一般每个迭代更新一次基线确保评测对比的是当前的真实状态。第三条不要迷信模型评审。模型评审模型可以作为预筛但最终判断还是要人来做。我遇到过模型评审放过了明显偏离意图的产出也遇到过它误杀了合理的实现。把它当辅助别当裁判。第四条intent.md 里的验收标准宁少勿滥。我早期喜欢列十几条标准结果模型顾此失彼反而哪条都做不好。后来精简到三到五条核心标准完成度明显提升。标准太多等于没有重点。6. 关于 aicoding 笔试题的一点个人看法热词里有个“aicoding 笔试题怎么写”我顺带说几句。现在不少公司在招 AIcoding 相关岗位时会出笔试题常见的形式是给一个改造需求让你写 intent.md 或者设计评测方案。这类题考的不是你会不会用某个模型而是你有没有“把意图显式化、把验收自动化”的思维。我的建议是答题时先把需求拆成可验证的目标再写范围边界和约束最后落到验收标准。验收标准一定要具体到可检查别写“代码质量高”这种虚的。如果能附上一套评测思路比如静态检查加测试回归加意图对齐基本就能拿高分。这和我前面讲的落地方法是同一套逻辑笔试题本质上就是让你在纸上走一遍这个流程。7. 后续可以怎么扩展这套东西这套 intent.md 加持续评测的框架我现在还在往两个方向扩展。一个是多任务并行同时跑多个 intent.md每个任务独立评测互不干扰。另一个是评测数据的积累把每次评测的结果存下来形成趋势图这样能看出模型在某个类型任务上的表现是变好还是变差。还有个想法是把 intent.md 的生成也半自动化。根据需求描述和历史 intent.md让模型先草拟一版人工再改。这样能进一步降低使用门槛。不过这个还在试验阶段效果还不稳定等跑顺了再分享。我个人在实际操作中的体会是AIcoding 在内部项目改造里能不能落地技术只占三成剩下七成是流程和纪律。intent.md 写得清不清楚评测搭得扎不扎实决定了模型是帮你干活还是给你添乱。这套东西不复杂但需要你愿意在前期花时间把意图和验收想明白。想明白了后面就是流水线作业想不明白再强的模型也救不了。