前两年大家聊 AI 编程焦点还在“AI 一天能写多少行代码”。今年我的体感已经完全变了——问题不再是“能不能写”而是“怎么让 AI 写出来的东西在一个正经软件项目里真正活下来”。带着这个疑问我们组把 Anthropic 公开的那套 AI 原生 SDLC 六阶段重构手册搬进了真实项目用 intent.md 做全流程的上下文锚点用持续评测把 AI 编码的质量从“感觉还行”变成“可量化、可回归”。这篇文章就是把我们这几个月落地过程中踩过的坑、验证过的方案、最后留下来的东西一次说清楚。重点拆两块intent.md 到底怎么写才有用持续评测到底怎么搭才不会沦为摆设。适合正在把 AI Agent 引入研发流程、但对质量和稳定性心里没底的团队参考。1. 先搞清楚AI 原生 SDLC 到底在重构什么1.1 传统研发流程在 AI 协作下的三个失效点先说结论传统 SDLC软件开发生命周期不是不好而是它默认“写代码的人”和“知道为什么写代码的人”是同一个或者至少能通过会议、文档、口头沟通保持同步。但 AI 编程工具进场以后这个默认前提被打破了。第一个失效点是上下文断层。AI 每次对话都是“失忆”的它不记得你昨天在架构评审会上定的技术选型不记得你上周跟产品争论后砍掉的边界 case。传统项目里的需求文档、设计文档、PRD 往往是给“人”看的写得再详细AI 也不会主动去翻。结果就是 AI 生成一堆“语法完全正确、语义完全跑偏”的代码。第二个失效点是验收标准模糊。人写代码代码审查靠人看reviewer 脑子里有一整套隐含的验收标准。AI 写代码代码量会成倍放大靠人逐行 review 根本不现实。这时候如果项目没有一个明确的“什么样算完成、什么样算好”的定义AI 生成代码的质量就完全取决于模型心情和 prompt 运气。第三个失效点是反馈回路断裂。传统流程里测试挂了、代码 review 被拒这些信号最终会回到开发者手里。但 AI 编码场景下如果 AI 生成完代码人就走了测试失败、线上问题、性能回退这些信息根本不会反馈到“下一次生成”里。没有反馈闭环AI 就永远是同一个水平不会越用越聪明。1.2 Anthropic 六阶段手册的骨架计划、规格、实现、测试、重构、文档Anthropic 那套 AI 原生 SDLC 思路核心是把软件开发重新拆成六个阶段Plan计划、Spec规格设计、Implement实现、Test测试、Refactor重构、Document文档。表面看和传统瀑布没什么区别但关键差异在于每个阶段都明确设计了“AI 参与方式”和“阶段产物”。比如 Plan 阶段不是让 AI 直接写代码而是先让 AI 参与问题拆解产出任务清单和风险点。Spec 阶段核心产物就是 intent.md——一份描述“这段代码为什么存在”的活文档。Implement 阶段AI 按 spec 执行而不是凭 prompt 自由发挥。Test 阶段强调测试先行、AI 负责补齐测试矩阵。Refactor 阶段专门处理技术债和重复代码。Document 阶段要求把实现过程中学到的东西回写进 intent.md。这六个阶段的顺序本身不是重点重点是两个贯穿始终的机制intent.md 作为“单一事实来源”贯穿所有阶段持续评测作为“质量闸门”卡住每个阶段的出口。我后面会分别展开。1.3 我们落地前的三个判断把手册搬进项目之前我们做了三个判断现在回头看都挺关键。第一这套东西不是为了“炫技”而是为了应对真实的项目痛。我们的项目是一个中型业务系统模块多、依赖复杂、历史代码质量参差不齐团队人力长期不够。AI 编程对我们来说是刚需不是尝鲜。第二intent.md 和持续评测要一起上缺一个都不行。只写 intent.md 不评测文档会慢慢腐烂只评测不写 intent.md评测只能测出“代码写得对不对”测不出“方向对不对”。第三落地节奏必须渐进。我们没有一上来就全流程 AI 接管而是先挑一个边缘模块试点跑通之后再往核心模块推。这个决策帮我们少踩了很多雷。2. intent.md把“为什么”焊进代码库2.1 intent.md 到底解决什么问题intent.md 字面意思是“意图文件”但它不是需求文档的另一个名字。需求文档描述“要做什么”设计文档描述“怎么做”intent.md 描述的是“为什么做、做到什么程度算成功、做的时候有哪些约束不能碰”。为什么需要单独搞这么个东西因为 AI 编码最大的问题是“缺乏判断力”。人写代码的时候面对一个模糊决策会调用项目背景知识用户是谁、老板想要什么、隔壁模块老张的代码有什么坑、线上跑的是什么版本。AI 没有这些背景你给它一个任务它只会从训练数据里找最相似的模式然后套上去。intent.md 就是把人的判断力提前结构化喂给 AI。它让 AI 在做决策时有一个“锚”不会飘。我们的实测经验是有 intent.md 的项目AI 生成代码的一次性通过率比没有的时候高出三到四倍而且代码风格的一致性明显更好。2.2 一份可落地的 intent.md 模板拆解网上流传的 intent.md 模板很多我自己整理了一套经过项目验证的结构分成七个区块每个区块都有明确的作用。这里直接给出我们的模板骨架# Intent: 模块/功能名 ## 1. 背景与动机 - 这个模块解决什么业务问题 - 为什么现在要做不做的代价 ## 2. 目标与成功标准 - 可量化的目标性能指标、功能覆盖率 - 非目标明确不做什么防止 AI 过度设计 ## 3. 用户与场景 - 主要用户角色 - 核心使用场景含边界 case ## 4. 约束条件 - 技术栈与版本限制 - 兼容性要求 - 禁止使用的模式/依赖这是重点 ## 5. 架构决策 - 关键设计决策ADR 摘要 - 为什么选这个方案放弃什么方案 ## 6. 模块间接口 - 对外 API 约定 - 数据结构定义 - 与其他模块的依赖关系 ## 7. 验收清单 - 功能验收点 - 质量验收点测试覆盖、性能阈值这七个区块不是拍脑袋定的。背景与动机解决“AI 理解上下文”的问题目标与成功标准解决“AI 判断何时停止”的问题约束条件解决“AI 别乱造轮子”的问题架构决策解决“AI 别选错方案”的问题接口约定解决“AI 别破坏边界”的问题验收清单解决“AI 交付完成后如何被评估”的问题。需要注意intent.md 不是写一次就完事的。它是活文档每个迭代都要更新。我们约定任何导致架构决策变化、接口变化、约束调整的改动都必须同步更新 intent.md否则视为流程违规。2.3 编写 intent.md 的三个经验第一个经验是“约束条件”要写得足够具体越具体越好。“不要使用过时的库”这种话等于没说AI 会继续用。“禁止引入新的 ORM 依赖数据库访问统一走现有 DAO 层”这才是 AI 能执行的信息。第二个经验是“非目标”一定要写。这是最容易忽略、也最值钱的部分。AI 有过度设计的天性你让它实现一个列表页它可能顺手给你加了一个缓存层、一个消息队列、三个设计模式。写清楚“本模块不做权限控制权限前置到网关”“本模块不做异步化先同步实现”之类的非目标能省掉大量返工。第三个经验是意图文件要“短而准”不要“长而全”。我们一开始把 intent.md 写成了一本二十页的设计书结果 AI 根本读不进去人也懒得维护。后来砍到一页到两页反而变成了真正每天有人看的东西。核心信息提炼到最简细节留在代码注释和 ADR 里。2.4 intent.md 如何驱动 AI 编码intent.md 不是给人看的摆设它要真正进入 AI 的工作上下文。我们的做法是把它作为每次编码任务的“system prompt 附加材料”启动一个编码任务时先把对应的 intent.md 和任务描述一起发给 AI要求 AI 先复述它从 intent.md 中理解到的目标、约束和验收标准经过确认无误后再开始写代码。这个“先复述后动工”的步骤非常重要。它相当于让 AI 做一次阅读理解测试你从它的复述里就能看出它有没有理解错方向。有一次 AI 复述的时候把“兼容旧版本数据格式”理解成了“把新数据格式转成旧格式”方向完全反了但正是在写代码之前就被发现挽回了一天的工作量。另外intent.md 也应该作为代码审查的参照物。我们 review AI 生成的代码时第一件事不是看代码细节而是对照 intent.md 的验收清单一项项打勾。先确认做的是不是对的事再确认做的事对不对。3. 六阶段流水线实战从拆需求到文档回传3.1 阶段一问题定义与范围收敛这一阶段的核心是把模糊的业务诉求拆成 AI 能执行的任务。传统做法是产品经理写 PRD开发看 PRD 估点。在 AI 原生流程里我们让 AI 先参与拆解把需求描述喂给模型让它列出任务清单、识别依赖、标记风险点。这个环节我们验证下来最有用的是“让 AI 提问题”。拿到需求后先不让 AI 给方案而是要求它列出所有它觉得信息不足、存在歧义的地方。AI 列的清单往往会超出人的预期有些细节业务方自己都没想过。把这些问题的答案补进需求描述之后任务拆解才会真正靠谱。阶段出口的验收标准是产出一份任务清单每个任务都有明确的输入、输出、验收标准并且已经归类到对应的 intent.md 区块。达不到这个标准不进入下一阶段。3.2 阶段二方案设计与 intent.md 成型方案设计阶段是六阶段里对人的能力要求最高的因为 AI 可以帮你写代码、写测试、写文档但做技术决策和权衡这件事短期内还得靠人。这个阶段的产出包括技术方案、架构决策、以及我们前面花了大篇幅讲的 intent.md。我们的实操节奏是先由架构师或资深工程师出方案初稿然后用 AI 做反向质询——让模型站在反对者的角度挑方案的毛病找方案的薄弱点。这一步非常值钱AI 往往能指出一些你习以为常但细想确实有问题的假设比如“这个接口的幂等性依赖了调用方的顺序保证但调用方其实是并发的”。方案定稿后同步生成 intent.md。注意这里不是“写文档”而是“把决策固化下来”。每个关键决策后面都要写“为什么这么选”因为这就是 AI 后续真正需要的东西。3.3 阶段三AI 辅助实现实现阶段是我们和 AI 协作最密集的部分。我们的协作模式分三层第一层AI 按任务清单逐个实现每个任务完成时要求它同步更新模块内的单元测试第二层AI 生成代码后先自测——我们要求它在交付前自己跑一遍相关测试把失败 case 修掉再提交第三层人做增量审查——不逐行看而是看关键路径和 intent.md 的约束是否被遵守。这一层最容易翻车的是“AI 自说自话”。AI 会倾向于把自己的代码写得“看起来很完整”比如补了一堆它觉得“应该需要”的 helper 方法但这些方法其他地方根本没人用。我们的对策是在任务清单里写明“禁止新增与任务无关的公共方法”并且在 review 时用脚本检查 diff 中超出任务范围的文件变更。3.4 阶段四自动化测试测试阶段的核心原则是“测试先行”。我们不为 AI 写测试代码这件事感到兴奋——AI 写测试代码确实快但它更倾向于写“能通过”的测试而不是“能发现 bug”的测试。所以我们的策略是核心业务逻辑的测试由人写AI 负责补边界 case 矩阵和集成测试场景。AI 补边界 case 的效果出乎意料地好。比如一个解析用户输入的函数我们人只写了正常输入和空输入的测试AI 补上了超长输入、特殊字符、Unicode 溢出这些我们没想到的 case。原因是模型的训练数据里见过太多这类边界模式它的“想象力”在枚举异常输入这件事上比大多数人有优势。测试阶段的出口标准是全量测试通过、覆盖率达到模块既定阈值、并且把新增测试纳入回归集。注意一轮迭代产生的测试必须全部沉淀进项目的测试套件里这是持续评测能跑起来的基础。3.5 阶段五重构与质量加固重构阶段处理的是实现阶段留下的技术债。AI 写代码速度快代价是代码质量会呈“偏平分布”——就是没有明显的烂代码但也没有高质量代码到处都是中不溜的实现。重复代码、魔法数字、缺少抽象这些都是重构阶段的重点。这个阶段我们建议让 AI 做“小步重构”不要让它一口气重构大模块。理由很简单重构的破坏力与代码改动量成正比AI 对既有行为的保持能力在小范围内可靠范围一大就容易“顺手改坏”。我们给 AI 定的重构约束是每次重构必须保证测试全部通过且重构 diff 中不包含行为变更。另外重构阶段一定要回头看 intent.md 的“非目标”。AI 在重构时特别容易“顺手优化”——明明任务只是消除重复代码它却把相关模块的数据结构也给换了。这种设计变更直接违反了我们“决策先于实现”的原则必须打回。3.6 阶段六文档沉淀与经验回传最后一个阶段经常被团队忽略但它在 AI 原生流程里的价值会被放大很多倍。原因很简单AI 没有记忆项目知识唯一可靠的载体就是文档和测试。这一阶段要做三件事更新 intent.md、沉淀 ADR、把实现过程中发现的问题回传给团队知识库。我们团队的做法是每次迭代结束用 AI 生成一份“迭代回顾草稿”内容包括哪些任务顺利完成、哪些出了问题、问题根因是什么、下一轮应该注意什么。然后人工删减修订保留真正有价值的部分合并进 intent.md 或团队 wiki。坚持三个迭代之后这份积累起来的知识库对 AI 编码质量的提升非常明显——相当于你把自己团队的项目经验也喂给了 AI。4. 持续评测让 AI 编码的效果可量化4.1 评测什么从代码质量到过程质量持续评测最忌讳的是“什么都想测”最后什么都测不准。我们落地时把评测对象分成三类每类用不同的指标第一类是代码质量评测关注 AI 产出的代码本身。指标包括静态检查通过率、测试覆盖率、重复代码率、复杂度超标函数数量。这些指标可以直接用现有工具链SonarQube、eslint、覆盖率平台采集不需要额外开发。第二类是任务质量评测关注 AI 是否真正完成了任务意图。指标包括需求验收通过率、单次生成合格率、平均返工次数。这个需要人参与打分但可以做得很轻量——每次 review 结束reviewer 顺手打一个分、填一个失败原因分类即可。第三类是过程质量评测关注整个流水线运转得健不健康。指标包括阶段流转时间、等待时间、intent.md 更新及时率、测试沉淀量。这一类容易被忽略但它往往是最早暴露问题的intent.md 不及时更新两轮迭代后 AI 编码质量会肉眼可见地下降。4.2 评测数据集构建 golden set 的实操持续评测尤其是针对 AI Agent 行为的评测必须有一组稳定的“黄金样本”作为基准。我们的做法是从历史迭代中挑选一批“典型任务”每个任务配上标准的 intent.md 摘要、代码仓库状态、期望产出以及人工确认过的“合格”和“不合格”参考答案。这批 golden set 的构建没有什么捷径就是靠前两三个迭代的积累。每完成一个任务如果验收通过我们就把它收入 golden set如果验收失败也把失败样本存下来标注失败原因。两个月下来我们积累了大约四十个样本这些样本足够后续每次流程调整时做一次“回归评测”。实测下来golden set 最大的价值是防回归。当我们调整了 system prompt、换了一个更强的模型、改了 intent.md 模板之后先跑一遍 golden set马上就能看出改动是正向还是负向。这比让开发凭感觉判断“新模型好像好用一点”靠谱得多。4.3 评测流水线把评测嵌入 CI评测要成为习惯必须自动化不能靠人工。我们把评测拆成两个层次日常评测在每次代码提交时自动触发运行静态检查、单元测试和性能回归迭代评测在每次迭代结束时触发运行 golden set 任务、汇总过程质量指标。日常评测的触发很简单就是在 CI 脚本里加一个 job对本次迭代内 AI 生成的所有代码做统计和检查。关键是要把“AI 生成的代码”和“人写的代码”打上标记这样才能单独追踪 AI 产出的质量趋势。我们的做法是要求 AI 任务的提交信息统一带上[ai-gen]前缀CI 里通过提交信息筛出来单独统计。迭代评测则要生成一份质量报告格式固定各类指标的当前值、环比变化、是否触发阈值告警。这个报告不需要花哨但必须每周发到团队群里让大家看到趋势。质量这个东西看不见就不会被重视。4.4 指标解读与迭代闭环评测跑起来之后最重要的事是“解读指标并驱动行动”而不是盯着数字自嗨。我们遇到过几个典型的指标误读这里展开讲讲。第一个是“测试覆盖率提升但线上 bug 率没降”。后来查下来是 AI 补的测试大量是重复断言、无效断言覆盖率的数字涨了但实际断言深度没变。对策在覆盖率指标之外额外统计“每个被覆盖函数的断言数量中位数”低于阈值视为无效覆盖。第二个是“单次生成合格率从 70% 掉到 40%”。排查后发现不是模型变笨了而是我们改了一批历史任务的 intent.md把一些约束写得更具体了AI 频繁触碰到新约束需要更多轮次修正。这其实是正向变化——约束变严意味着质量天花板变高但如果你只盯合格率很容易误判成倒退。正确做法是把“首次合格率”和“最终合格率”分开统计。第三个是“重构阶段耗时越来越长”。查下来的根因是前一个阶段的测试沉淀不足导致重构时回归成本很高。这个问题的信号其实在过程指标里早就出现了——测试沉淀量的趋势一直在下滑只是我们当时没有把两个指标联动起来看。现在我们把“重构耗时”和“新增测试数”放进同一张趋势图互相印证。5. 踩坑实录与落地建议5.1 高频问题速查表下面这张表是我们内部知识库里最常被翻的一页整理了一段时间内出现频率最高的问题和对应的处置办法供参考。现象可能原因处置办法AI 频繁修改与任务无关的代码任务边界不清晰任务清单必须写明涉及的文件列表禁止越界修改intent.md 写了但 AI 不遵守意图文件未进入模型上下文或文件过长被截断把最关键的约束提取到任务描述中不要把整个文件丢给模型单次生成合格率低但最终交付正常初始 prompt 缺少关键细节建立 prompt 模板复用机制把成功案例沉淀为标准模板测试都通过但功能行为不对测试与实现互相印证缺少独立参照引入 golden set 中的独立用例做行为对照代码能用但风格和现有体系不一致未提供项目代码风格规范在 intent.md 中明确风格和模式约定示例优先API 调用报错提示模型路由或网关配置异常网关路由配置错误或模型权限配置不对优先检查 API key 对应模型权限、网关路由映射再确认网络连通性同一任务多次执行结果差异大模型采样参数或上下文不稳定固定 temperature 和随机种子关键任务增加确定性校验5.2 团队协作方式的三个改变落地 AI 原生 SDLC 之后团队协作方式有几个显著变化提前有预期会从容很多。第一个改变是“写文档变成了核心工作而不是收尾工作”。以前工程师最讨厌写文档现在 intent.md 直接决定了 AI 产出质量写好意图文件本身就是生产力。我们把 intent.md 的编写纳入了工作量评估不再当作附带任务。第二个改变是“代码审查从查错变成查意图”。以前 review 是看代码逻辑有没有 bug现在更关键的是看代码实现是否偏离了 intent.md 的约束和边界。有人不习惯这种变化觉得“不写代码光写文档”不是工程师该干的事。实际上在 AI 原生流程里对人最有价值的能力恰恰是“定义清楚问题和判断方案好坏”。第三个改变是“质量指标变成了团队共同语言”。以前质量是 QA 的事开发只关心功能上线。现在有了持续评测看板覆盖率、合格率、返工率成了迭代回顾会上必聊的话题。这个变化是良性的因为它把模糊的“代码质量”变成了可讨论、可改进的对象。5.3 给正在尝试的团队一份落地路线图如果你所在的团队正准备尝试这套流程我的建议是从最小闭环开始不要想着一口吃成胖子。参考我们的路线先选一个两周内能完成的边缘模块搭出 intent.md 模板、定义基础指标、把 CI 上的评测 job 跑通然后完整走一轮六阶段。第一轮的目标不是“提升效率”而是“跑通流程、收集数据”。哪怕效果比传统方式还慢也别急着下结论——你是在为后续所有迭代打地基。第一轮结束后花半天时间做一次复盘哪些步骤是累赘、哪些检查是重复、哪个环节最耗时然后针对性调整。第二轮开始增加 golden set 的积累并且尝试让 AI 更深度地参与实现和测试。到第三轮基本就能看出这套流程对团队的真正价值了。我们自己的数据是第三轮之后AI 生成代码的最终合格率稳定在 85% 以上边缘模块的开发周期压缩了约四成而且这还是在我们没有换更大模型的前提下达成的。最后分享一个个人的实操心得不要把 AI 原生 SDLC 当成一个“工具链改造项目”它本质上是一次“研发协作方式的改革”。工具可以一天换完但人的习惯、文档的规范、质量的意识需要几个迭代才能固化。我们踩过最大的坑就是第一轮就追求完美流程结果大家疲于应付文档和评审反而忽略了真正要交付的业务价值。想清楚这一点你就能理解为什么手册把 intent.md 和持续评测放在最核心的位置——它们一个管住方向一个管住结果这两件事立住了AI 编码这件事的长期价值才真正立得住。
