这段代码为什么要这么改当时AI到底修的是什么bug——这话不是没有过。上个月我接手一个历史项目本来只是想清理一个过时的函数结果一查提交记录发现前两周AI已经悄悄改过一个关联逻辑还在一个if条件里塞了个看起来毫无来由的边界值。我盯着diff盯了十分钟还是没搞明白当时发生了什么。回翻对话窗口早就被新的对话挤没了。这正是AI改代码最容易埋雷的地方AI能改改了之后你自己说不上它的依据。你事后能看到的只是一个改完之后的结果所有中间判断、当时的需求背景、权衡过程全都留在那个不会主动说话的对话上下文里。等对话过期、模型上下文漂移这个依据就彻底没了。这篇文章就想聊聊这个问题怎么破适合那些已经开始用AI辅助开发、但还没有系统管理过AI变更依据的团队和个人。1. 问题解剖AI到底在哪些环节弄丢了依据想要解决一个问题得先搞清楚它是在哪个环节碎的。AI改代码这件事和传统程序员改代码有本质区别它的记忆机制决定了依据特别容易丢。1.1 AI修改代码的隐式判断机制传统程序员改代码脑子里有一条清晰的需求链路产品说要做A测试暴露了B我在C处修复。哪怕不写文档人脑的记忆多少能留个底。但AI不一样它拿到你的prompt之后是直接基于当前对话上下文、当前文件内容、当前仓库状态做一次隐式判断。这个判断通常包含以下内容你这个需求到底对应哪几处代码AI靠语义匹配猜的用哪种写法最符合项目现有风格AI靠模式识别猜的边界条件怎么处理AI靠训练语料里一般做法猜的关键就在这AI不会主动把它的猜测链条暴露给你。它直接输出diff你觉得看起来对就合了。然而一周之后你不会知道它当时为什么在这个边界值上做了1为什么用了Array.prototype.find而不是for循环为什么单独把这段逻辑抽成一个函数。我见过一个很典型的场景某个服务启动时偶尔报空指针有同事把这个报错信息发给AIAI定位到一段初始化逻辑建议在某个判断前加一个空值保护。两周后另一个同事重构这块逻辑看到那个空值保护就想删掉因为他找不到任何注释表明它是修什么的。结果一删生产报错立刻回来了。这就是依据丢失的代价——你不仅失去了为什么改还失去了能不能删的判断基础。1.2 依据丢失带来的连锁危害依据丢失不只是看不懂历史代码这么简单它的连锁反应比想象中大得多排查问题成本翻倍新bug出现时你无法判断是AI改出来的还是本来就有的只能靠git diff一遍遍考古回归测试抓瞎你不知道AI改了哪些边界条件回归用例自然覆盖不到代码评审流于形式reviewer看到diff也只能说看起来没问题根本不知道怎么评团队协作摩擦你和AI形成的心智模型只有你自己有别人接手时完全两眼一抹黑回滚失去依据真需要回滚时不知道是回滚到哪个commit、会不会把好消息也roll掉说句实话我自己在早期踩过最大的坑就是AI改完代码我一验功能通了就提交了什么都没留下。后来出了线上问题看代码时整个人傻在那里——我不记得那行判断是AI加的更不知道它为什么加。从那时起我开始认真琢磨怎么让AI把依据吐出来。这个问题的本质其实不是AI记性差而是我们没设计一套机制让依据沉淀下来。2. 第一步用提示词逼AI把决策过程写出来既然AI自带隐式判断那最简单粗暴的办法就是让它把判断理由显式化。调试一下你给AI的提示词让它不仅输出改完的代码还输出一份修改依据说明。这一步花不了几分钟效果立竿见影。2.1 一条实用的修改依据提示词模板我目前在自己项目里用的模板长这样分享出来供参考请帮我修改以下代码实现 [具体需求/修复目标]。 在输出diff之前先用列表形式说明 1. 你准备改哪几个文件、哪几个函数为什么是这些位置 2. 你判断这个需求涉及的关键边界条件有哪些 3. 你采用当前写法的依据是什么比如项目已有模式、性能考虑、兼容性考虑 4. 你预计这次修改会影响哪些现有功能可能引入什么风险 5. 如果未来要回滚或重构这段代码后人需要注意什么 只有在说明完以上5条后再输出代码diff。你可能会想怎么这么啰嗦确实平时自己写代码也没人这么要求你写备注。但恰恰是AI你不要求它它就真的只给你一个答案。把你和一个刚入职不了解业务的新人对比那个新人改代码时你至少还能问两句你怎么想的。AI呢你不问它就把想法留在黑盒里。用了这个模板之后我拿到的不再只是一段diff还有一个为什么的说明。这个说明可以直接粘到Git commit信息里或者粘到PR描述里。这样下一次任何人看到这次改动的代码都有了一串上下文线索不用再靠猜。2.2 让AI依据架构决策记录思路输出短条目如果你觉得上面这个模板还是太长每次都让AI写一大段受不了可以实践一种更轻的方法借鉴ADRArchitecture Decision Record架构决策记录的思路但不用写那么正式就让AI输出四条短条目Context现在遇到了什么问题Decision选择改哪几处怎么改Consequences改完会有什么影响风险在哪Rationale为什么是这个方案而不是其他方案我的实操是直接把答案格式写死在提示词里比如请你按这个格式输出修改说明 - Context: - Decision: - Consequences: - Rationale:这个格式天然适合填到PR描述里。而且短AI输出成本低你贴的意愿也高。别小看贴的意愿——再好的格式如果你每次都要手动整理半分钟坚持不了三次。格式越短你越愿意记录。关于为什么的解释我多说一句很多人觉得AI写的Rationale不一定准确它为了让你满意可能会编一个看起来合理的理由。这种情况确实存在所以你在提交前需要快速判断一下它说的依据是否合理。但至少它给了你一个可验证的假设而不是让你对着代码猜。这个价值已经远超它偶尔的虚构性。3. 实操落地把依据追踪嵌进日常开发流程方案有了怎么落地提示词模板再好如果你每次用的时候都要复制一遍坚持不了几次。我在自己团队里跑了两个月把整个流程简化成了三个可执行的环节现在基本不费力改之前定义目标改之后让AI出说明提交时把说明塞进git。下面拆开讲。3.1 一个可复用的AI辅助修改工作流我建议的流程分为五步每步都刻意留痕第一步定义修改目标。打开对话后不要直接说帮我改一下登录逻辑而是说清楚背景、现状、期望行为和约束条件。比如当前登录接口在token过期后返回401但前端没有处理导致用户被卡在页面上。请让后端在token过期时返回特定错误码并给出前端拦截方案。这一步的目标是让AI从一开始就在一个清晰上下文里工作。第二步让AI给出改造方案再动手。先不要让它出diff先让它说思路。除非是那种一行就能改完的修复否则这个前置思考阶段不能省。第三步确认变更范围。我会让AI列出一个清单这次改动会触及哪些文件哪些函数有没有可能影响到其他调用方确认完之后再放行它改。这一步能很大概率减少AI顺手改坏东西的风险。第四步应用前文那个模板让AI输出修改依据说明。在diff之后让它追加Context/Decision/Consequences/Rationale四条。第五步把说明沉淀到仓库。这一步见下小节。这五步走下来一次改动可能多花三到五分钟。但省下来的排查时间是按小时算的。账很好算。3.2 用代码注释给AI的修改打上依据标签如果你觉得把依据只写在commit message里还不够精细——因为代码里某个具体位置才是判断真正的落点——那就用注释把依据钉在那行代码旁边。我推荐一种轻量的标注手法在AI加的关键判断前一行加注释// AI-REF: 修xxx问题删除前确认xxx。这里的AI-REF就是一个显眼标签说明这行是AI改的且附带了依据。哪种情况值得写这个标记我的标准要么是边界条件要么是防御性代码要么是不直观的workaround。比如// AI-REF: 修复2024-06订单号为空导致的崩溃业务上订单号理论必填但历史脏数据存在空值 if (!orderId) { return createEmptyResult(INVALID_ORDER_ID); }这个注释的价值在于下次有人看到这行判空不会想这多余吧而是知道这是防护历史脏数据的。它把可以删还是不能删的决策依据留给了下一个读代码的人。但要注意不是所有AI改的代码都值得加注释。如果一个遍历从for改成map这种风格统一不需要注释一行命名调整也不需要。注释只给那些读者可能会产生疑惑、会想删、会想重构的地方贴。贴多了反而造成噪音后人看到一屏注释也懒得读。3.3 把依据链写进Git提交信息代码注释解决的是微观依据Git提交信息解决的是宏观依据。我推荐的提交信息格式是直接在常规提交信息后面挂一段AI依据说明fix(auth): 处理token过期场景 - 后端在token过期时返回4101错误码 - 前端拦截器捕获后跳转登录页 - 移除原401处理逻辑 AI依据: - Context: token过期后前端无提示用户被静默卡住 - Decision: 新增错误码前端跳转 - Consequences: 依赖4101的调用方需同步更新 - Rationale: 保持前后端错误码语义一致避免把所有401都当登录失效这段信息可以直接从AI的修改说明里复制出来改两笔。你要是嫌麻烦甚至可以写一条脚本让AI生成提交信息格式你复制粘贴就行。反正目标就一个让AI当时为什么这么改这件事躺在离代码最近的地方。3.4 为跨会话、长周期项目准备一份修改依据文档如果你做的是那种周期超过一个月的模块只靠注释和commit message还不够。对话窗口的上下文总会被冲掉AI对长期项目的记忆本来就弱依赖它记住所有历史决策根本不现实。这时候我建议在项目里放一个AI_CHANGES.md专门记录AI做过的重要修改。文档结构不用复杂就一个表格日期改动位置需求背景决策依据影响范围2025-XX-XXsrc/order.ts订单号为空时报错历史脏数据防护下单接口每次AI改完重要逻辑后把这一行填上。这个文档是给人看的更是给下一个AI对话看的——在新一轮对话里直接把这份文档丢给AI当上下文它就能快速理解项目里哪些地方是有意为之的避免重复踩坑或者把之前的防护逻辑当冗余代码删掉。这个喂文档的操作很关键。AI的上下文窗口是有限的但你可以在每次开新对话时把一个100行的变更记录丢进去。它看到这些背景理解项目时就不会把以前的决策重新发明一遍更不会把你已经踩过的坑再踩一遍。这是目前我在所有长期AI辅助项目里的必备操作。4. 常见问题与排查技巧实录这一个月里我观察下来即使有了上面那些机制还是会在实际落地时遇到各种问题。这里我把几个高频问题整理出来可能你能少走一些弯路。4.1 常见问题速查表症状可能原因处理方法AI不按模板要求输出说明提示词被对话历史冲淡或模型没严格遵循格式把模板放在对话最末尾并做一次示范输出AI生成的Rationale明显在编理由它基于语料猜测而非真实推理对关键依据做抽查不盲信可让AI提供参考来源提交信息里有说明但代码里找不到对应关系说明写得太宏观没落到具体行结合代码注释补一条AI-REF标签对话窗口关掉后发现没留存说明没形成复制粘贴习惯把说明输出直接引入到后续代码生成流程中要求它先给说明再给diff团队里别人不执行这个流程流程太繁琐没人愿意干简化模板甚至出台脚本让AI自动生成PR描述在这些问题里最难缠的其实是AI编Rationale这个问题。我发现的应对策略是让AI在Rationale里尽量引用项目中的真实代码或报错信息而不是空对空地说这是最佳实践。你可以追加一句请在Rationale中明确写出你参考了哪个已有函数、哪个报错堆栈或哪条业务约束。这样一来AI编造的空间就被压缩了它必须锚定具体事实才能给出理由。4.2 已经发生依据丢失怎么事后补救如果你现在翻代码发现几周前AI改过的东西已经一点依据都找不到别急还是有救的。我通常用三步来补救第一步死磕git diff。把那次改动的diff拉出来结合改动前后代码逻辑的对比尽量反推出改了会修什么。这一步的目标不是拿到100%准确的依据而是拿到一个可验证的假设。第二步让AI重新考古。把旧的diff作为一个独立的片段丢给AI不给任何背景只问按代码逻辑推断这次改动最可能解决什么问题AI基于diff的分析往往能给出几个候选场景你再去对照测试用例和线上现象通常能锁定真实原因。第三步快速补一层测试和注释。一旦你推断出了依据立刻在代码和测试里补上。让这次补救的成果沉淀下来而不是永远停留在大概知道的状态。说实话这一步比前两步都重要因为技术债就是在大概知道里累积出来的。4.3 更深一层的提醒依据追踪不是文档负担可能有人觉得让AI每改一次就要写一堆说明这不是加重负担吗我的体验恰好相反。真正的负担不是写说明而是出问题时对着不明不白的diff考古两小时。你只是把考古的时间提前花在了让AI说清楚上总耗费不增反降。另外一个容易忽略的好处是依据追踪对AI协作的提示起着反向约束作用——当你要求AI解释它在改什么时它自己也会更谨慎、更少瞎改。这就像学生写解题过程写着写着就会发现自己哪一步不太对。AI也一样当它需要把Context、Decision、Consequences和Rationale写清楚时它生成垃圾代码的概率明显降低。所以这不是一个纯记录动作它本身就在提高AI产出质量。我对这个问题的体会很简单AI改代码不恐怖恐怖的是改完之后这个世界没有任何一个地方记录它为什么这么改。哪怕只是“一行短注释 一条commit信息 一个表格行”都算给未来的自己和同事留了一条命。我现在的习惯是每次开新对话前先把上一轮的变更记录贴进去每次合代码前先确认AI的修改说明已经进了commit。这套流程跑顺之后AI在我项目里就不再是“改完就失忆的工具”而是一个“每次改完都交作业”的协作者。如果你也在用AI改生产代码建议从今天起给AI的下一次修改配一句“留痕”。真的花不了几秒钟省下来的是几天。