1. 从能跑就行到改得动内部项目AI化改造的真实起点接手一个已经跑了两年多的内部运营系统代码量不算夸张大概四万多行技术栈是典型的能跑就行组合——后端Python Flask前端早期用jQuery堆出来的页面数据库MySQL部署靠一台内部服务器加手工脚本。团队三个人平时维护靠口口相传的这块别动那个接口有坑。这种项目在AIcoding落地时反而是最有代表性的样本它不像新项目可以从零设计规范也不像大型系统有完善的文档和测试覆盖它就是大多数公司里真实存在的那种祖传代码。我决定拿它做AIcoding改造的试验田目标很明确不是让AI把整个项目重写一遍而是让AI能在这个项目里持续、稳定地帮我做增量修改和局部重构。这个目标听起来简单但实际操作下来最大的障碍不是模型能力而是上下文管理和质量验证这两件事。前者决定了AI能不能理解这个函数为什么长这样后者决定了AI改完之后你敢不敢合并。围绕这两个障碍我最终沉淀出两个核心实践用intent.md承载项目意图用持续评测机制守住质量底线。这两个东西不是拍脑袋想出来的而是在反复踩坑之后被逼出来的方案。下面我会把整个改造过程拆开讲包括为什么选这个方案、具体怎么落地、中间遇到哪些坑、以及最终跑通之后的实际效果。这篇文章适合两类人看一类是正在考虑把AIcoding引入内部项目的开发者另一类是已经在用AI写代码但发现改着改着就失控的团队。如果你只是想让AI帮你写个独立脚本那这篇内容可能偏重了但如果你要让AI在一个有历史包袱的项目里持续干活那接下来的内容应该能帮你少走不少弯路。2. intent.md 到底解决什么问题不是文档是AI的项目记忆2.1 为什么 CLAUDE.md 不够用一开始我也是按主流做法在项目根目录放了一个CLAUDE.md把技术栈、目录结构、启动命令这些信息写进去。用了两周之后发现一个问题CLAUDE.md更像是一份项目说明书它告诉AI这个项目是什么但没法告诉AI这个项目为什么是这样。举个例子项目里有一个sync_user_data()函数逻辑写得非常绕里面有三层嵌套判断和一个看起来毫无必要的重试循环。我在CLAUDE.md里写了用户数据同步模块但AI每次改这个函数都会把重试逻辑删掉因为它看起来冗余。实际上那个重试是因为上游接口在特定时段会返回空数据不加重试会导致同步任务静默失败。这种信息CLAUDE.md的静态描述根本承载不了。intent.md的核心思路就是把为什么和不能动什么显式写出来作为AI每次修改前的必读上下文。它不是替代CLAUDE.md而是在其之上增加一层意图约束。CLAUDE.md回答项目长什么样intent.md回答改的时候要守住什么。2.2 intent.md 的四个核心区块我最终把intent.md固定成四个区块每个区块解决一类问题第一块业务意图锚点。用三五句话说明这个模块存在的业务目的以及它服务的核心流程。比如用户数据同步模块的唯一目的是保证内部CRM和运营后台的用户状态一致任何修改都不能改变最终一致性这个目标。这句话看起来废话但它能有效阻止AI把同步逻辑改成异步队列——因为异步队列虽然更优雅但会破坏最终一致性的时间窗口。第二块不可变约束。列出那些看起来可以优化但绝对不能动的点。比如重试循环必须保留因为上游接口存在时段性空返回这个字段的默认值不能改历史数据依赖它。这一块是踩坑重灾区后面我会专门讲怎么积累这些约束。第三块修改边界。明确告诉AI哪些文件、哪些函数是可以改的哪些是只读的。内部项目经常有一些碰了就出事的核心文件与其让AI猜不如直接划红线。第四块验证方式。说明改完之后怎么验证。这一块和持续评测机制直接挂钩后面会展开。2.3 一个真实的 intent.md 片段下面是我在项目里实际使用的一个片段脱敏之后大概长这样## 模块用户数据同步 ### 业务意图 保证内部CRM与运营后台的用户状态最终一致同步延迟容忍上限为15分钟。 ### 不可变约束 - 重试循环必须保留上游接口在每日02:00-04:00存在空返回 - status字段映射关系不可更改历史数据依赖当前映射 - 同步任务必须保持串行执行不可改为并发 ### 修改边界 - 可修改sync_user_data()内部逻辑、日志输出 - 只读config/sync_config.py、数据库表结构 ### 验证方式 - 运行 pytest tests/test_sync.py - 手动触发一次全量同步检查日志中无空返回告警这个文件不长大概几十行但它对AIcoding的效果提升非常明显。之前AI改这个模块十次有三次会破坏约束加上intent.md之后破坏约束的情况基本消失。原因很简单AI不是不懂这些道理而是它不知道这些道理在这个项目里成立。你把约束显式写出来它就会遵守。2.4 intent.md 的维护节奏这里有个容易被忽略的点intent.md不是写完就完事的它需要跟着项目一起演进。我的做法是每次AI改完代码之后如果发现某个约束被违反了就把这个约束补进intent.md。相当于把每次踩坑都转化成一条显式规则让AI下次不再犯同样的错。这个过程听起来很笨但实际跑下来大概经过三四个迭代周期intent.md就能覆盖住项目里80%以上的隐性知识。到那个时候AIcoding的稳定性会有质的提升。我个人的体会是intent.md的价值不在于它写得多完美而在于它持续积累——每一条约束都是从真实问题里长出来的比任何凭空设计的规范都管用。3. 持续评测机制让AI改完的代码敢合并3.1 为什么单次评测不够AIcoding刚落地的时候我的做法是每次让AI改完代码手动跑一遍测试没问题就合并。这个做法在小改动上还行但一旦改动涉及多个文件、多个模块手动评测就变得非常吃力。更麻烦的是AI有时候会顺手改一些你没让它改的地方这些改动单看没问题但组合起来可能引入回归。持续评测机制的核心思路是把评测从改完再跑变成改的过程中持续跑并且把评测结果作为AI下一步修改的输入。这样AI不仅能知道自己改得对不对还能根据评测反馈自我修正。3.2 评测体系的三层结构我把评测体系分成三层每层解决不同粒度的问题层级评测内容触发时机工具单元层函数级正确性每次AI修改后pytest集成层模块间交互每轮对话结束后pytest 自定义脚本意图层约束是否被违反合并前自定义检查脚本单元层是最基础的用pytest跑一遍现有测试用例。这里有个前提项目里得有测试。内部项目经常测试覆盖很低我的做法是先用AI把核心路径的测试补上再开始AIcoding改造。这个顺序很重要没有测试兜底AIcoding就是裸奔。集成层解决的是单测都过但组合起来出问题的情况。我写了一个简单的脚本模拟几个核心业务流程跑完之后检查关键数据状态。这个脚本不追求覆盖率只覆盖最核心的三五条路径。意图层是最有特色的一层它直接检查intent.md里的约束有没有被违反。比如重试循环必须保留这条约束我就写一个脚本检查sync_user_data()函数里是否存在重试逻辑。这个检查很粗糙但非常有效。3.3 评测结果如何反馈给AI持续评测的关键不在于跑评测而在于把评测结果结构化地反馈给AI。我的做法是每次评测跑完把失败信息整理成一段简短的文本直接作为下一轮对话的输入。比如上一轮修改后评测结果 - 单元测试test_sync.py::test_retry_logic 失败 - 意图检查重试循环约束被违反 请根据以上反馈修正代码注意不要删除重试逻辑。这种反馈方式比让AI自己猜要高效得多。实测下来加上评测反馈之后AI自我修正的成功率从大概六成提升到九成以上。原因也很简单AI看不到运行结果你不告诉它哪里错了它就只能靠猜。3.4 评测脚本的落地细节评测脚本本身不复杂但有几个细节值得注意。第一评测要快。如果每次评测要跑五分钟那持续评测就变成了负担。我的做法是把单元测试控制在30秒以内集成测试控制在2分钟以内意图检查控制在10秒以内。第二评测要稳定。内部项目经常有一些偶发失败的测试这些测试会干扰AI的判断。我的做法是先把这些不稳定测试标记出来暂时排除在评测之外等稳定了再加回来。第三评测结果要可读。AI看不懂复杂的测试报告所以我会把结果整理成通过/失败失败原因的简单格式。这个整理工作可以写个脚本自动完成不需要手动做。4. 改造过程中的三个真实坑与排查链路4.1 坑一AI把冗余代码优化掉了这是最早遇到、也最典型的一个坑。项目里有个函数里面有一段看起来完全多余的边界判断if user_id is None or user_id 0: return NoneAI第一次改这个函数的时候直接把这段删了理由是user_id在上游已经做了非空校验这里重复判断是冗余的。结果上线之后某个边缘路径传入了user_id0导致后续逻辑把0当成了有效ID写入了错误数据。排查过程是这样的先看日志发现异常数据都集中在user_id0的记录上然后回溯代码发现边界判断被删了再查上游确认上游只校验了None没校验0。整个排查花了大概两个小时但根因其实很简单。修复方案是把判断加回去同时在intent.md里补了一条约束user_id0是无效值边界判断必须保留。这个坑给我的教训是AI判断冗余的标准是代码逻辑但项目里的冗余往往是业务约束的体现。你不把业务约束写出来AI就会按代码逻辑去优化。4.2 坑二评测通过但业务出错第二个坑更隐蔽。有一次AI改了一个数据导出模块单元测试全过集成测试也过但上线之后用户反馈导出的数据少了大概百分之五。排查下来发现AI把导出逻辑里的一个过滤条件改了从排除已删除用户改成了只导出活跃用户。单测和集成测试都没覆盖这个过滤条件所以评测全绿但业务逻辑已经偏了。这个坑的排查链路比较长先对比导出前后的数据量确认少了然后逐条对比导出记录发现少的是已删除但仍有历史订单的用户再查代码发现过滤条件被改了。整个过程花了半天。修复方案是把过滤条件改回去同时在intent.md里补了一条导出逻辑的过滤条件不可更改历史订单依赖已删除用户的数据。另外我在集成测试里补了一条针对导出数据量的断言防止类似问题再次发生。这个坑的教训是评测覆盖不到的地方就是AIcoding的风险区。你不能指望评测覆盖所有业务逻辑但你可以通过intent.md把关键业务约束显式写出来让AI在修改时有所顾忌。4.3 坑三多轮对话中的上下文漂移第三个坑和上下文管理有关。有一次我让AI连续改了三个相关模块改到第三个的时候AI已经忘记了第一个模块的约束把一个原本不能改的字段改了。这个问题的根因是多轮对话中早期的上下文会被逐渐稀释AI的注意力会集中在最近的对话上。排查过程相对简单对比三轮修改的diff发现第三轮修改违反了第一轮建立的约束。但修复起来比较麻烦因为不能简单回滚第三轮的修改本身是对的只是附带改了一个不该改的地方。修复方案有两个一是把intent.md作为每轮对话的固定输入确保约束始终在上下文中二是在每轮修改前让AI先复述一遍当前模块的约束确认它记得。第二个做法看起来有点笨但实测下来非常有效能显著降低上下文漂移的概率。这个坑的教训是多轮AIcoding对话中约束需要反复强化。你不能指望AI记住十轮之前说过的话你得把关键约束放在它每轮都能看到的地方。5. 跑通之后的实际效果与团队协作变化5.1 效率提升的量化观察改造跑通之后我做了个简单的统计。在引入intent.md和持续评测之前AIcoding的改动大概有30%需要人工返工平均每个改动从提出到合并需要两到三轮对话。引入之后返工率降到10%以下平均对话轮次降到1.5轮左右。这个提升主要来自两个方面一是intent.md减少了AI改错方向的概率二是持续评测让AI能自我修正减少了人工介入。当然这个数据是基于我们团队的实际使用情况不同项目、不同团队可能会有差异但趋势应该是类似的。5.2 团队协作方式的变化更有意思的变化在团队协作层面。以前代码评审的时候评审人需要花大量时间理解这个改动为什么这么做现在intent.md里已经写清楚了业务意图和约束评审人可以更快地判断改动是否合理。另外新成员加入项目的时候intent.md也成了一份很好的项目隐性知识入口比读代码快得多。还有一个变化是团队开始有意识地积累intent.md。以前大家觉得写文档是负担现在发现写intent.md能直接减少AI改错的情况反而愿意写了。这个正向循环一旦建立起来项目的可维护性会有明显提升。5.3 什么情况下这套方案不适用说了这么多好处也得说说边界。这套方案在以下情况下效果会打折扣一是项目本身没有测试补测试的成本可能比收益还高二是项目改动非常频繁intent.md的维护跟不上代码变化三是项目业务逻辑极其复杂intent.md很难覆盖全。我的建议是如果你的项目符合前两种情况可以先从一个小模块试点跑通之后再逐步推广。不要一上来就全项目铺开那样很容易因为维护成本过高而放弃。6. 把 intent.md 和持续评测串成工作流6.1 一次完整的AIcoding改造流程把前面讲的东西串起来一次完整的AIcoding改造流程大概是这样准备阶段确认目标模块有基本测试覆盖没有的话先补核心路径测试。意图梳理为目标模块写intent.md至少覆盖业务意图、不可变约束、修改边界、验证方式四块。首轮修改把intent.md作为上下文输入让AI执行修改。持续评测修改完成后自动跑三层评测整理结果。反馈修正把评测结果反馈给AI让它自我修正直到评测全绿。人工复核评测全绿之后人工复核一遍diff确认没有评测覆盖不到的问题。约束沉淀如果复核中发现新问题把对应约束补进intent.md。这个流程跑顺之后单次改造的时间大概在半小时到一小时之间比纯手工改快不少而且质量更稳定。6.2 几个提升效率的小技巧第一个技巧是把intent.md拆成模块级文件。项目大了之后一个intent.md会变得很长AI读起来效率低。我的做法是按模块拆成多个文件比如intent_sync.md、intent_export.md每次只加载相关模块的意图文件。第二个技巧是评测脚本参数化。不同模块的评测内容不一样与其写多个脚本不如写一个脚本通过参数指定要跑哪些评测。这样维护成本低扩展也方便。第三个技巧是把常见约束做成模板。比如不可变约束这一块很多模块都有类似的约束可以做成模板写的时候直接套用减少重复劳动。6.3 关于 intent.md 的一个常见误解最后说一个常见误解有人觉得intent.md是写给AI看的所以要用AI能理解的格式。实际上intent.md首先是写给人看的其次才是给AI看的。它的价值在于把项目里的隐性知识显式化这个过程本身就是对项目的一次梳理。如果你写出来的intent.md人看不懂那AI大概率也理解不好。所以我的建议是写intent.md的时候先假设读者是一个刚加入项目的新人用他能理解的语言把意图和约束讲清楚。这样写出来的内容AI用起来效果也最好。7. 从 intent.md 到 AI-native SDLC 的延伸思考7.1 这套实践在更大范围内的位置把intent.md和持续评测放在一起看它们其实是在做一件事把AIcoding从单次对话变成可持续的工程流程。单次对话的问题是每次都要重新建立上下文质量不稳定而工程流程的核心是把上下文、约束、验证这些要素固化下来让每次AIcoding都在一个稳定的框架里进行。这个思路和最近常被提到的AI-native SDLCAI原生的软件开发生命周期是相通的。所谓AI-native不是简单地把AI塞进现有流程而是围绕AI的能力和限制重新设计流程。intent.md解决的是AI理解项目的问题持续评测解决的是AI改动可信的问题这两个问题解决了AIcoding才有可能真正融入日常开发。7.2 后续可以扩展的方向如果这套实践要继续深化我觉得有几个方向值得尝试。一是把intent.md和代码仓库的CI流程打通让约束检查自动化二是把评测结果和代码评审系统集成让评审人直接看到评测状态三是积累一套intent.md的编写规范让团队里不同人写出来的意图文件风格一致。还有一个方向是把intent.md作为项目交接的一部分。内部项目经常面临人员流动intent.md如果能持续维护就能在很大程度上缓解人走了项目就没人懂的问题。这个价值可能比AIcoding本身还大。7.3 一点个人体会最后分享一点个人体会。AIcoding落地这件事技术层面的难点其实不多真正的难点在于愿不愿意把项目里的隐性知识显式化。很多团队习惯了代码即文档觉得写intent.md是额外负担。但从我的实际经验看这个负担是值得的——它不仅让AIcoding更稳定也让项目本身变得更可维护。我在这个项目上前后花了大概三周时间做改造其中写intent.md和搭评测体系占了大概一半时间。这个投入不算小但跑通之后后续每次AIcoding改动的效率提升和质量稳定性很快就把这部分投入赚回来了。如果你也在考虑类似的事情我的建议是先从一个小模块开始跑通一个完整流程再决定要不要推广。