> For the complete documentation index, see [llms.txt](https://shike.gitbook.io/ai-coding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shike.gitbook.io/ai-coding/13-chapter.md). # 第13章 AI 生成代码的失序:四类工程问题与系统化治理 **本章导读**:AI 编程的副作用不是孤立的 bug,而是四类反复发作的工程问题:代码质量下滑、上下文失效、文档与代码不一致、架构渐进腐化。本章逐一分析四类问题,每类按"症状—实证数据—根本原因—解法与配套工具"的结构展开,章末提供四类问题的总表、实证数据汇总表、20 条仓库健康自检清单。本章是问题线的一次集中收束,为后续章节的工程化工具讨论提供问题侧的基础。 **本章关键词**:代码质量、上下文管理、文档一致性、架构腐化、系统化治理 ## 13.1 一类反复发作的工程问题 **现场还原**:某次季度复盘会上,某 SaaS 公司的工程主管打开一个 6 个月的项目做体检。原计划 4 个月完工,实际用了 7 个月,原因被归到"AI 不给力"。工程主管读了一段 600 行的核心模块,逐条标注:第一处,异常处理把日期格式解析失败"容错"成了空数组(代码质量);第二处,模块顶部有一句"本项目统一用 pnpm"写在对话记录里,代码里却同时存在 pnpm 和 npm 的 lockfile(上下文);第三处,README 里的"快速开始"写着 `npm install`,实际 `package.json` 已经移除了对 `npm` 的支持(文档);第四处,业务层直接 import 了第三方 SDK 的内部函数,跨了三层抽象(架构)。一次复盘里,四类问题全部到齐。 这次复盘的结论不是"这个项目用 AI 用错了",而是"四类问题在每个项目里都在发生,只是这个项目把它们都暴露到了同一个模块里"。**教训**:四类问题不是孤立的偶发 bug,而是同一根因在不同侧面的表现——关键信息没落在 AI 能读到的文件里,AI 就在每个侧面上自行补救,补救的结果就是四类问题。 ### 13.1.1 案例篇的"暗线" 本书前 12 章记录了若干"AI 干得不对"的事件:第 2 章中 AI 煞有介事地编造了并不存在的方法签名,第 3 章中长任务跑了一半忘了开头定的规矩,第 5 章中数据管道出错时难以定位原因,第 9 章中自我迭代使系统越改越乱。这些不是孤立的偶发事件,其背后是四类反复发作的工程问题。 四类问题的共同根源是:**关键信息没有落在 AI 能读到的文件里**。AI 不知道不该改什么(代码质量)、记不住早前说好的(上下文)、看到过时的说明书(文档)、按局部最优而非全局最优修改(架构)。把规格、约束、验收标准、章程全部写进仓库里,AI 才有"约束记忆"的持久载体。 ### 13.1.2 本章的方法论 本章对四类问题逐一展开,每类按以下结构: * **症状**:问题在仓库中表现为什么 * **实证数据**:公开数据如何描述这类问题 * **根本原因**:为什么会反复发作 * **解法与配套工具**:具体的工程化解决方案 章末提供可立即落地的资产:四类问题总表、实证数据汇总表、20 条仓库健康自检清单。 ## 13.2 问题一:代码质量下滑 ### 13.2.1 症状 代码质量下滑的早期不表现为故障,而表现为仓库的形态慢慢变形:同一功能的函数出现多个版本(参数顺序不一致),异常处理大量出现但只打日志不解决。代码可以跑、测试可以过,但团队成员逐渐不敢改任何一处——因为没人能确定,改了一处会不会让别处出问题。 一个典型事故:某对账任务连续两周少结算四笔小额订单,单笔金额只有几十元,差额低于报警阈值,没有任何告警。追查发现,问题出在一段 AI 写的解析逻辑里:解析失败时,代码返回一个空数组,注释写"容错处理,避免中断主流程"。上游接口把日期格式调整后,所有新格式的记录都被这个"容错"逻辑悄悄丢掉。从变更上线到发现问题,间隔十四天。 这个案例暴露了这类问题最危险的特征:**被吞掉的异常不会报错,只会持续产生错误的结果**。 **现场细节**:对账任务的事故,具体是这样的:某电商公司的对账系统每天凌晨 2 点跑一次,核对当天订单与第三方支付平台的流水,差异超过 100 元时报警。事故前两周,某 AI 助手按"统一异常处理"模式重写了解析逻辑——把"日期格式解析失败"这个 catch 块的逻辑改成"返回空数组",注释写"避免中断主流程"。改完后,新的日期格式上线(原系统用 YYYY-MM-DD,新格式升级到 RFC 3339),所有新格式的记录都被这个 catch 块静默吞掉,空数组流到对账逻辑,被解释为"当天没有新订单"。两周内损失了 4 笔订单(每笔几十元),金额低于报警阈值,无人察觉。两周后财务对账时才发现。这个事故的关键教训:**"避免中断主流程"是合理的工程直觉,但它把"显式失败"变成"静默成功",代价是延迟两周才发现**。对账、支付、计费这类场景,容错不是"返回空",而是"显式告警"。 ### 13.2.2 实证数据 2026 年 4 月发表于 arXiv 的一项研究分析了 6,299 个 GitHub 仓库中的 30.26 万个 AI 署名提交,结论是:五种主流 AI 编程工具无一例外,超过 15% 的提交引入了至少一个可检测的问题\[^60^]。GitClear 对 2.11 亿行变更代码的分析显示,AI 生成时代下,代码克隆量增长 4 倍、重构活动下降 60%、函数调用率下降 35%\[^63^]。这些数据共同指向同一行为模式:AI 更倾向于复制现有代码,更少抽取公共函数,更少整理旧代码——生成速度越快,仓库里堆下来的维护欠账就越多。 ### 13.2.3 根本原因 AI 写代码倾向于吞掉异常,原因可以从它的优化目标理解:"让程序运行起来"是默认成功标准。抛出异常是显式失败,静默捕获并返回默认值可以让程序继续跑——从"任务完成度"这个指标看,后者是更优解。GitClear 报告背后有一段机制分析,把这个默认策略概括成一句话:永远不要抛出错误\[^63^]。 重复代码是同一机制的另一面。AI 每次只能看到局部上下文,不知道仓库另一处已经存在可复用的实现,于是在当前位置重新写一遍。这不是模型能力不足,而是它的视野在结构上受限——全局信息只能靠工程手段补给它。 ![上下文失效三类型判别](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-dbdbf79c1a897f3e2c959017c256d3e182738f57%2Fsec13_context_triage.svg?alt=media) ### 13.2.4 解法:质量左移 **现场细节**:某次项目,工程师按 13.2.5 的方法让 AI 用自然语言生成触发器配置,挂到仓库里,让 AI 改一个无关紧要的测试文件演示一遍。演示结果:触发器没把"测试失败"这个事件回传到会话窗口,AI 报告"修改完成",但 CI 流水线里一片红。工程主管在飞书里回了一段话: > 工程师:这个配置可能没生效,我看 CI 是红的但 AI 不知道。 主管:那就还没配好,不要往后走。 工程师:我周三卡在这里一整个下午,反复改了三版配置,最后才发现是事件订阅的路径写错了一个字母。 这次卡点的代价是周三整个下午——但更危险的代价是:如果团队没要求"现场演示一遍",触发器未生效这件事会潜伏到某次真正的 bug 出现,彼时 AI 已经自信地把测试漏掉合入。**判断标准**:治理手段配完后,必须由"故意触发一次失败"来证明它真的拦得住,不能只读一遍配置就认为"应该能跑"。 治理分三层,逐层加码。 **第一层:测试先行**。先写一个必然会失败的测试,再写恰好让这个测试通过的最少代码。这条规则对人类开发者是自律要求,对 AI 则是硬约束——有测试作基线,吞掉异常、擅自改变行为等操作会立刻暴露。 **第二层:质量左移**。传统流程里质量检查发生在评审环节,发现问题时代码已经写完;左移是把测试与静态检查提前到保存与提交的瞬时自动执行,使问题产生后立刻报警。配合 CI 流水线:每次提交自动构建并跑测试,未全部通过则禁止合入。 **第三层:评审留痕**。AI 生成的修改不应只附"修改前后对比",而须把每一处修改映射回任务与验收标准;无法完成映射的修改,即为尚未准备好合入。评审留痕让审查行为从"靠自觉"变成"靠证据"。 ### 13.2.5 配套工具 针对代码质量问题,可挂载"改完代码自动跑测试"的触发器。配置由 AI 用自然语言生成,挂到代码仓库中。配置完成后,让 AI 现场改一个文件演示一遍,确认测试失败时它能自己收到报错——能收到,配置才算生效。这套机制的意义在于:不依赖 AI"记得"跑测试,而由触发器替你执行。 ![三重债务模型](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-de5cea52486124fe4da0b3b2a3976d487cb65b92%2Fsec13_triple_debt.svg?alt=media) ## 13.3 问题二:上下文失效 ### 13.3.1 症状 **现场还原**:某次接入支付网关的项目,客户在第 80 轮验收时发现一个隐蔽的 bug——退款接口调用时,日志里记录的字段是订单 ID(`order_id`),但下游账务系统收到的字段却是订单号(`order_no`)。两份接口文档在对话前部都给过,字段名只差一个字母。测试通过的原因是 mock 数据里 `order_id` 和 `order_no` 都被赋了同一个值。客户的原话: > 客户:这个退款能跑通吗?我看到日志里写的字段和账务那边收到的对不上。 工程师(打开会话窗口往回翻):对话第 4 轮和第 6 轮各贴过一份接口文档,两份的字段名差一个字,AI 把它们记混了。 客户:那它为什么不报错? 工程师:mock 数据里两个字段都填了同一个值,测试看不出来。 这个案例同时呈现"漂移"和"腐烂"两种类型——约束在窗口里仍然存在(两份文档都还在对话前部),但模型在第 80 轮召回时把两份文档的字段对应错了。事后排查发现,这种"差一字"的张冠李戴在前 50 轮对话里就发生过 3 次,只是都因为测试覆盖或人工抽查被挡住了,没有被发现。**教训**:上下文失效最危险的不是"AI 忘了第 3 轮说过什么",而是"AI 记得这件事,但记错了细节"——后者和正确版本之间只差一个字母,人眼很难在评审时识别。 上下文失效在工程现场呈现为三种类型: * **溢出**:对话过长导致历史被截断,开头立的规矩在物理意义上从窗口中消失。AI 在第 80 轮询问"项目用什么包管理器",而该信息在第 3 轮就给了。 * **漂移**:约束还在窗口里,但 AI 的行为慢慢跑偏——命名风格变了,约定的目录结构不再被遵守。 * **腐烂**:信息完整保留在窗口里,但模型回忆不准确,张冠李戴。这是三种类型里最难察觉的一种。 腐烂的特征:AI 在第 80 轮把订单接口的字段写进了退款接口——两份接口文档都在对话前部,字段名只差一字,模型产生了混淆。测试没抓住这个错,是因为 mock 数据里两个字段都恰好被赋值。 ### 13.3.2 实证数据 向量数据库公司 Chroma 开展的 Context Rot 研究测试了 18 个前沿模型,覆盖 GPT、Claude、Gemini、Qwen、Llama 全系列,结论一致:所有模型的表现均随输入变长而持续退化,无一幸免\[^75^]。工程界据此形成一条经验法则:生产环境中的有效上下文约为标称窗口的 25% 至 30%。以标称 1M 的窗口为例,硬性任务建议按 250K 至 350K 规划;超出该范围后,模型进入"无法准确回忆已读内容"的区间。 ### 13.3.3 根本原因 上下文失效的根源是"注意力资源的物理约束"——上下文中的 token 数量越多,模型准确回忆信息的能力越低,这一特性存在于所有模型之中\[^74^]。期望通过"换窗口更大的模型"解决上下文问题,在方法论上不成立——病灶不在单个模型,而在架构本身。 ### 13.3.4 解法:四类对策 **现场细节**:某次接入三方 SDK 的项目,主对话到第 60 轮时,工程师发现"读 SDK 源码"这件事已经吞掉了 4 万 token——主对话里塞满了 API 文档的粘贴、字段定义的来回比对、版本号的反复确认。客户在飞书里催"什么时候能出第一版",工程师回话: > 工程师:我让 AI 去读 SDK 源码,主对话已经被污染了。 客户:什么叫"污染"? 工程师:意思是,主对话里现在有一半是 SDK 文档,我们后面要写的业务逻辑只占另一半,AI 接下来的回答会偏向 SDK 风格而不是我们项目的风格。 当天工程师把"读 SDK 源码"这件事派给一个子 Agent,子 Agent 在独立窗口里消耗了 5.8 万 token,向主对话返回 1,400 个 token 的蒸馏摘要——主对话重新变得干净,业务讨论能正常推进。这次切换的代价是 token 成本上升了约 1.4 倍,收益是主对话的有效上下文比例从约 35% 回到 70% 以上。**判断标准**:当主对话里"探索性输出"占比超过 40% 时,该把这类工作派给子 Agent——主对话的有效空间不应被消耗性任务挤占。 生产环境里经过验证的对策有四类。 **第一类:对话压缩**。上下文快到容量上限时,把此前的对话历史摘要化,带着摘要开新窗口继续。手动执行压缩比等自动触发更可控——可以在压缩前补一句"压缩时务必保留这三条约束"。 **第二类:观测遮罩**。把早期的工具输出从上下文里藏起来。一次安装可能输出几千行日志,这些信息在执行当下有用,三小时后只是占窗口的噪声。遮罩机制定期清理,只保留最近的高信号输出。 **第三类:即时检索**。不预先把仓库内容一次性灌进上下文,而是维护一份轻量索引,在需要某份文件时现场去查。 **第四类:子代理隔离**。把"探索"这种最消耗上下文的工作派给子代理。子代理可以在独立窗口里消耗几万 token,最后只向主会话返回 1,000—2,000 个 token 的蒸馏摘要。主会话的上下文因此保持清洁,代价是 token 成本上升。 四类对策不是并列关系。启用的顺序:先开即时检索与遮罩(成本为零);任务变长后启用压缩;探索规模扩大后再启用子代理(成本最高,收益也最大)。 ## 13.4 问题三:文档与代码不一致 ### 13.4.1 症状 **现场还原**:某次交付前夜,客户打开仓库的 README,按"快速开始"那节的命令跑了一次,前 4 步都报错。第 4 步是 `npm install`,客户原话: > 客户:你们这个 README 是不是三个月前写的? 工程师(对照 git log):三个月零 8 天前。 客户:那文档算不算交付的一部分? 工程师:算。 客户:那这份交付不算完成。 这份 README 是项目第二周由一位工程师手写的,之后代码部分切换到 pnpm,删除了 npm 脚本,但 README 没有同步更新。三周后这份文档被另一位工程师重新看了一遍,他/她以为这是"参考资料",没有作为交付内容检查。**教训**:文档在团队内部的优先级普遍低于代码,但在客户视角里它和代码是同一种交付物——交付检查清单里应同时有"代码能跑"和"文档能跑"两项,缺一不可。 这类问题的典型症状是仓库里同时存在"两个项目":一个存在于代码中,每日变化;另一个存在于文档中,停留在三个月之前。README 里的"快速开始"跑不起来,因为依赖安装命令半年前已经换了;架构图上有两个模块实际已经合并。人类开发者对过时文档具备免疫力,对照代码就能识别文档失真;AI 不具备这种免疫力,它把文档当成事实来源,并基于一个已经不存在的世界写出逻辑自洽的错误代码。 ### 13.4.2 根本原因 文档与代码不一致的根源是"约束的缺失而非遗忘"——约束从未被书面记录,只分散于聊天记录、已关闭的 Issue、评审评论与离职员工的记忆中。AI 之所以看不到那条契约,是因为契约从未被书面记录。 ### 13.4.3 解法:文档即代码 **现场细节**:某团队在引入"文档即代码"流程时,运营岗位一度反对"定期删除文档"这条纪律。反对的理由是:"这份 onboarding 文档我花了 3 天写,删了多可惜。"项目负责人当时的回复是: > 负责人:这份文档最后一次更新是 4 个月前,里面提到的接口有 2 个已经下线,有 1 个换了版本号。 运营:但新人可能还要看。 负责人:新人按这份文档跑不通,他们下次会去找别的文档,这份文档就再也没人看——但 AI 还会读它。 这位负责人后来执行了一条更具体的纪律:任何超过 90 天没被引用、也没被更新的文档,默认删除,不需讨论。三个月下来,仓库里被删除的"过期但舍不得删"的文档有 23 份,留下的文档总量没有显著减少(因为同期新增了 18 份活跃文档),但 AI 引用文档时的错误率从约 12% 降到 3% 以下。**原则**:过时文档的害处是"让 AI 误以为不必查代码",这条害处只有在文档被删除时才能根除。 解法可以概括为一句话:**把文档从"代码的附属品"升级为"代码的输入"**。 具体落实为三条纪律: * **规格进 git**:需求、设计决策与验收标准全部落实到仓库内的文件里,不在聊天窗口里确定需求 * **同 PR 更新**:改变行为的 PR 必须同步修改对应文档 * **同评审**:文档变更与代码变更走同一评审流程,任何一方不得单独合入 此外还有一条反直觉的纪律:**定期删除文档**。过时文档的危害大于没有文档——缺少文档时,人与 AI 都知道应当查阅代码;过时文档则让双方都误以为不必查。 ## 13.5 问题四:架构渐进腐化 ### 13.5.1 症状 **现场还原**:某次半年回顾,某团队技术主管打开仓库的依赖图看了一晚上。图上有 47 个模块,理论上应该分成 4 层(domain / application / infrastructure / interface),但实际的依赖关系是"网状"——domain 层的某个聚合根直接 import 了 infrastructure 层的具体实现,application 层则跳过 interface 直接调用了 domain 的私有方法。他/她翻看过去 6 个月的提交记录,发现这种"跨层引用"最早出现于第 3 个月,当时是 AI 给某次紧急需求写的"快速方案",注释写着"临时的,后面再重构"。这个"后面再重构"在后续 47 次提交中没有被任何一次处理,反而被另 11 处类似注释的"临时代码"模仿。技术主管在内部邮件里写了一句话: > 主管:这半年提交都没让 build 失败,所以我们都没注意——但每次都"可以运行"的代价,是把分层秩序一点点换成了网状依赖。 这个案例最危险的地方是"没人能指出哪次提交是错的"——每次提交都让测试通过、都让功能上线,但每一次都在原有问题上叠加新问题。**判断标准**:架构腐化的早期信号不是"测试失败",而是"PR 评论里开始频繁出现'这个为什么不放在 X 层'这类问题"——这个信号出现时,问题已经累积 3—6 个月。 架构腐化没有引言事故那种显性爆发点,它表现为长期、缓慢、每次幅度都很小的劣化。代码量在持续增长,结构在持续离散。每次提交都"可以运行",半年后回看则会发现:分层秩序被打乱,本该复用的逻辑散落各处,模块之间的依赖关系失去清晰的层次。 ### 13.5.2 实证数据 回到 GitClear 的数据:重构活动下降 60%、函数调用率下降 35%\[^63^]。两项指标合在一起的含义是:AI 生成的代码在"代码量"层面持续增长,在"结构"层面持续离散。三重债务模型(技术债 + 认知债 + 意图债)描述了这类问题的累积效应:当 AI 生成代码的速度超过团队理解代码的速度时,团队欠下的不只是技术债,还包括认知债和意图债\[^62^]。 ### 13.5.3 解法:架构约束的强制化 **现场细节**:某次项目,运营在某次紧急需求里让 AI 直接改了一个"受保护路径"下的文件——这个路径下是数据库迁移脚本,章程明确禁止 AI 修改。受保护路径由 PreToolUse 钩子通电,AI 每次尝试写入时,钩子立即拒绝并把原因返回给会话。AI 在会话里看到拒绝信息后,自动改去走人工流程:开 PR、@ 工程师审批,而不是绕过。运营最初在飞书里抱怨了一句: > 运营:为什么不让我直接改? 工程师:上次直接改的那次,我们线上回滚了 40 分钟。 运营:那 AI 改不一样吗? 工程师:不一样,AI 改也会被拦——被拦的意思是,它不能自己改完就上线,得有人看到。 这次拦截发生在第一次上线之前——相比之下,之前那次直接改的迁移脚本,问题在生产环境暴露 3 小时后才被定位。**解法**:`CLAUDE.md` 里的规则,AI "读到"后仍可能不遵守(它可能在压力下"权衡");PreToolUse 钩子里的规则,AI 在物理层面无法绕过——两种约束的差距,正是"被读到"和"被拦住"的差距,后者在生产事故的代价上便宜得多。 针对这类问题,采用三件工具,约束强度递增。 **第一件:constitution(章程)**。项目的根本约束文件,记录"不可协商原则",对人与 AI 具有同等最高约束力。章程高于具体业务规则,且不因单次决策的方便而变更。 **第二件:PreToolUse 拦截**。给纸面规则赋予强制力。AI 每次修改文件之前先经过一道检查,命中禁区即被拒绝。关键在于拦截是确定性代码,而非提示词——CLAUDE.md 里的规则,AI"读到"后仍可能不遵守;PreToolUse 钩子里的规则,AI 在物理层面无法绕过。 **第三件:架构守护测试**。把架构规则编码为可执行的测试,扫描依赖关系,越界即测试失败。该检查与 CI 门禁共同运行,任何提交越界都会触发红灯。 三件工具的分工:constitution 解决"AI 知道规则",PreToolUse 解决"AI 无法违反规则",架构守护测试解决"任何漏网行为都会报警"。三层各管一段,冗余是刻意设计。 ## 13.6 治理的工程化 ### 13.6.1 感知偏差:AI 时代的认知陷阱 **现场案例**:某团队在 2025 年下半年做过一次内部对照实验,方法很简单——挑 12 个中等复杂度的需求(每个需求 2—5 天工作量),把工程师随机分成两组,一组可以用 AI 工具,一组不用。实验结束后的数字: * 周期时间(从开工到合入):用 AI 组平均 4.2 天,不用组 3.6 天 * 修改平均评审轮次:用 AI 组 3.1 轮,不用组 2.4 轮 * 合入后两周内返工修改占比:用 AI 组 18%,不用组 7% 实验结束后的匿名问卷里,12 位"用 AI 组"工程师里,9 位认为自己"明显变快"或"略变快",只有 1 位认为"略变慢"。实际数据显示他们的平均周期时间多了 16%。**现场细节**在于,这位唯一认为变慢的工程师,在实验结束后私下说: > 工程师:我周三下午盯了一个 PR 两个半小时,看 AI 写的代码但不敢合,得自己一行行对照规格。最后我重写了关键路径——如果我自己从零写,半小时就完事。 这个案例与 METR 研究的发现一致:感知与实测之间存在结构性偏差。偏差的方向是系统性的(偏向"我变快了"),偏差的幅度不容忽视(本案例约 35 个百分点,与 METR 报告的 39 个百分点量级一致)。**原则**:不应以"我感觉变快了"为由跳过评审与测试——感觉是最先被 AI 改变的变量,真实账要靠指标看。 在讨论治理之前,需要先处理一个前提问题:上述治理手段是否值得投入,取决于 AI 编程究竟有没有提升效率。METR 2025 年的随机对照实验是这一议题最常被引用的研究:16 名资深开源维护者、246 个真实任务,使用 AI 的组完成任务平均慢了 19%。更具方法论意义的发现:开发者事前预测自己会快 24%,实测变慢之后仍自认快了 20%——预测与实测之间存在 39 个百分点的感知偏差\[^61^]。 39 个百分点的感知偏差意味着:不应以"我感觉变快了"为由跳过评审与测试——感觉是最先被 AI 改变的变量。要了解本团队的真实效率账,应测量三个指标:任务从开工到合入的周期时间、修改平均评审轮次、合入后两周内的返工修改占比。三个指标在引入 AI 前后各测量一个月,结论比任何行业调研都更贴近实际。 ### 13.6.2 治理的瓶颈下移 **现场案例**:某团队统计了引入 AI 工具前后 6 个月的 PR 数据,样本量 312 个 PR。结果与 Harding GitClear 的发现方向一致: * 单 PR 平均评审轮次:引入前 1.8 轮,引入后 3.0 轮(增加 67%,约等于多 1.2 轮) * 单 PR 平均评论数:引入前 4.5 条,引入后 5.4 条(增加 20%) * 评审者单 PR 平均耗时:引入前 22 分钟,引入后 31 分钟 更值得注意的是"评论类型"的分布变化:引入 AI 之前,评论里 80% 是"逻辑/边界"类问题;引入 AI 之后,逻辑/边界类评论占比降到 55%,其余 45% 是"代码风格/重复实现/遗漏测试/约束理解错误"——这些是 AI 特有的问题类型。工程主管在月会上指着一张柱状图说: > 主管:我们以前评审是"看 AI 写的代码对不对",现在变成了"看 AI 写的代码有没有漏掉我们说过的规矩"。前者 5 分钟,后者 25 分钟。 这个案例说明:生成端节省的时间,在评审端被放大消耗——因为 AI 写的代码"看上去对",但要确认它"完全按规格做"反而更费时。**原则**:治理投入的最佳位置不是"减少 AI 写的代码",而是"减少评审者检查 AI 代码的时间"——具体方法见 13.2.4 的"评审留痕"、13.5.3 的"PreToolUse 拦截"、13.4.3 的"同评审"。 可验证的效率变化集中体现在评审端。含 AI 代码的修改平均多 1.3 轮评审、多 15% 的评论\[^64^]。生成端节省的时间,有一部分被转移到了评审端消耗——瓶颈发生了下移,但并未消失。这正是本章全部解法都在评审与检查环节加码的原因:那里是新的瓶颈所在,也是治理投入应当配置的位置。 ## 13.7 方法论提炼与可复用资产 ![治理组合分阶段实施阶梯](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-b361b8b181d2751d92f6a6da07ddc10c660d90fc%2Fsec13_ladder.svg?alt=media) ![四类问题全景对照](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-70c028f4d1698055ea36bf6fec6712d3f065cd10%2Fsec13_four_diseases.svg?alt=media) ### 13.7.1 四类问题总表 | 问题 | 典型症状 | 关键实证 | 病根 | 解法 | 配套工具 | | -------- | --------------------- | ------------------------------------ | ----------------- | ------------------------------------- | ----------------------------- | | 代码质量下滑 | 重复代码遍地、异常被静默吞掉 | >15% 提交引入可检测问题 \[^60^] | AI 默认"永远不报错";局部视角 | 测试先行、质量左移、评审留痕 | 自动测试触发器、CI 门禁、只读评审子 Agent | | 上下文失效 | 后半程忘规矩、行为跑偏、记不准 | 18 个模型全部退化;有效上下文 ≈ 标称 25-30% \[^75^] | 注意力随长度摊薄 | 压缩、遮罩、按需检索、子 Agent 隔离 | Compaction 机制、即时检索、子 Agent 蒸馏 | | 文档与代码不一致 | README 过时、契约只在人脑和聊天记录 | 意图债——设计理由未外化 \[^62^] | 约束散落在聊天记录、老员工脑中 | 文档即代码:规格进 git、同 PR 更新、同评审 | OpenSpec 工件链、AGENTS.md 开放标准 | | 架构渐进腐化 | 分层变乱、复用率下降、依赖如面条 | 重构活动 -60%、函数调用率 -35% \[^63^] | 生成速度 > 理解速度,欠下三重债 | constitution 画红线、PreToolUse 通电、架构守护测试 | 架构守护钩子、章程工作流 | ### 13.7.2 实证数据汇总表 | 数字 | 内容 | 出处性质 | | ---------------- | ------------------------- | ------------------------------------------ | | 30.26 万 / 6,299 | AI 署名提交数 / 覆盖仓库数 | arXiv 学术论文(2026-04,一手研究)\[^60^] | | 10 万+ | 存活的 AI 引入问题累计数 | 同上 | | 4× / -60% / -35% | 代码克隆增长 / 重构活动下降 / 函数调用率下降 | GitClear(2.11 亿行分析,建议回溯原报告)\[^63^]\[^321^] | | 18 个 / 25-30% | 长上下文退化模型数 / 有效上下文占标称比例 | Chroma Context Rot 研究(2025-2026)\[^75^] | | -19% / +20% | METR RCT 实测变慢 / 开发者自认变快 | METR 随机对照试验(2026-02 官方自承)\[^61^] | | +1.3 轮 / +15% | AI 代码评审多出的轮次 / 评论增幅 | Harding GitClear 2025 PR 分析(经二手转引)\[^64^] | ### 13.7.3 仓库健康自检清单(20 条) 每类问题 5 条,建议按月执行一遍;回答为"否"的条目,即转化为下月的技术债工单。 **代码质量** 1. 全仓库搜 catch,空 catch 块和"只打日志不处理"的 catch 块占比是否低于 10%? 2. 用重复代码检测工具扫一遍,克隆率相比上个季度是否持平或下降? 3. 新增工具函数前是否搜过仓库已有实现? 4. AI 生成的修改是否都带"修改点 → 验收标准"映射表? 5. 测试失败时,CI 是否真的挡住了合入? **上下文管理** 6. 单次会话时长是否控制在有效上下文内(按标称窗口 25-30% 折算)? 7. 关键约束是否写进了文件而非只存在于对话里? 8. 长任务是否拆成了可独立验收的小任务? 9. 重度探索是否派给了子 Agent 而非污染主会话? 10. 压缩前,架构决策和未解 bug 是否已落盘? **文档一致性** 11. 规格文件是否与代码同 PR 更新? 12. 仓库根目录是否有 AGENTS.md,且内容与当前构建命令、目录结构一致? 13. CLAUDE.md 是否在 500 行以内、无整段粘贴的 lint 规则? 14. 新人入职能不能只靠仓库文档就把环境跑通? 15. 上月是否有至少一次"删掉过时文档"的提交? **架构健康** 16. constitution.md 是否存在,且最近一个季度评审过? 17. 分层依赖是否有可运行的守护测试,最近一次拦截是什么时候? 18. 受保护路径(迁移脚本、生成物、锁文件)是否有 PreToolUse 钩子通电? 19. 函数复用率/模块依赖图相比半年前是否劣化? 20. 团队成员能否说出任意核心模块"为什么这样设计"——说不出,意图债就在累积。 ### 13.7.4 分阶段实施建议 组合方案虽完整,但一次性全部启用是另一个陷阱。纪律应与场景匹配:探索性的周末项目保持轻量节奏即可;为三天的原型配备全套规格驱动流程,属于典型的过度工程。 实施阶梯: * **个人项目**:先启用成本最低的两项——评审留痕模板与文档即代码习惯 * **小团队(3 至 10 人)**:增加 CI 门禁与自动测试触发器,编写 AGENTS.md * **大团队**:启用完整组合——OpenSpec、constitution、PreToolUse 红线、架构守护测试 落地过程中最大的阻力不是技术,而是"流程感"带来的抵触。治理手段不需要推销,它需要的是一次被验证的机会。 **现场细节**:某次项目,工程师对"治理流程"很抵触,理由是"我们做的是赶时间的原型,流程越多越慢"。项目负责人没有强推,只在第二周做了一件事:把"自动测试触发器"装上,故意让一个无关紧要的测试失败一次。触发器当场把失败信息回传到 AI 会话,AI 主动修了这个测试。工程师当天在群里发了一条消息: > 工程师:今天我让 AI 改一个文件,它改完发现自己写的代码让一个旧的测试挂了,它就自己修好了。我没催它。 这条消息是治理方案在团队内"被验证"的起点——不是文档说服了工程师,是工具在工程师眼前自己工作了一次。**原则**:治理手段的推广路径不是"先说服,再部署",而是"先部署最轻的一环,等团队自己看见收益,再逐步加码"。 ### 13.8.1 本章思考题 1. 13.2 的代码质量下滑:你团队最近一次"被吞掉的异常"是什么时候?这个 bug 的发现延迟了多少天?延迟的代价是什么? 2. 13.3 的上下文失效三类型(溢出/漂移/腐烂):你的项目最常出现的是哪一类?腐烂类(记错细节)有没有被测试覆盖到? 3. 13.4 的文档与代码不一致:你团队的 README "快速开始"最近一次跑通是什么时候?如果超过 30 天没跑过,这份文档处于什么状态? 4. 13.5 的架构渐进腐化:你团队最近半年的 PR 评论里,"这个为什么不放在 X 层"这类问题出现过几次?如果超过 5 次,架构腐化已经累积 3—6 个月。 5. 13.6 的治理三层(测试先行/质量左移/评审留痕):你团队的 CI 流水线是否在每次提交时自动跑测试?如果有,最近一次"测试失败但 AI 报告完成"的事件是什么? ### 13.8.2 本章延伸阅读 1. **\[文章] arXiv Debt Behind the AI Boom(2603.28592v2,2026-04-26)** — 30 万 AI commit 实证:>15% 引入问题、累计存活 10 万+ | 第 13 章 2. **\[文章] METR 官方博客 uplift 更新(2025-07/2026-02-24)** — RCT:慢 19% 自认快 20%;后续选择偏差自我修正 | 第 13 章 3. **\[文章] arXiv 三重债务模型(2603.22106,2026-03-23)** — 技术债/认知债/意图债;文档混乱与架构腐化的理论化 | 第 13 章 4. **\[数据报告] GitClear / LeadDev 代码霉变数据(deepseek.csdn.net 综合,2026-07-13)** — 克隆 4×、重构 -60%、函数调用率 -35%;建议回溯 GitClear 原报告 | 第 13 章 5. **\[文章] particula.tech / unyform.ai 评审与漏洞数据(2026-03)** — AI PR 接受率 32.7% vs 84.4%、多 1.3 轮评审;瓶颈下移到评审端 | 第 13 章 ## 13.8 完整提示词:四类工程问题的诊断与治理 **现场还原**:某次治理项目,工程团队邀请外部顾问做"四类问题诊断",顾问按以下提示词跑了一次完整的仓库扫描,产出了一份 12 页的报告,包含 4 类问题的清单、证据、根因和分阶段治理步骤。报告中的"立即可执行(本周内)"5 条,被工程团队在一周内完成 4 条;剩余 1 条因涉及权限审批,放到本月处理。这份提示词在后续 3 个项目里被复用,每次产出的报告都按统一格式——这是它作为"可复用资产"的核心价值:不需要每次重新设计 prompt 框架,直接填入仓库地址和团队规模即可。**教训**:可复用的提示词比"看起来聪明的提示词"更有价值——前者降低每次启用的成本,后者只能被一次性使用。 以下提示词用于"诊断代码仓库中的四类 AI 编程副作用,并给出可执行的治理方案"。它把"症状—证据—根因—解法"四件套落到 prompt 里,且每类问题都有具体的诊断工具与修复步骤。 ``` 你是资深代码仓库治理顾问,擅长诊断 AI 编程过程中产生的四类工程问题——代码质量下滑、上下文失效、文档与代码不一致、架构渐进腐化。接下来的所有工作,你必须严格按"症状定位 → 证据采集 → 根因分析 → 治理方案"四步推进,且每个治理方案都必须给出"立即可执行的具体步骤",不允许只给"建议"或"原则"。 【你的工作方式】 - 阶段一(症状定位):根据我提供的代码仓库地址(URL 或本地路径),扫描 13.7.3 的 20 条自检清单,标记每条的"通过/不通过/不适用" - 阶段二(证据采集):对"不通过"项,采集具体证据(代码位置、日志、性能数据) - 阶段三(根因分析):基于证据,判断属于四类问题中的哪一类(或哪几类并存) - 阶段四(治理方案):针对每类问题,给出立即可执行的治理步骤,且每步都说明"由谁执行、用什么工具、预计耗时" 【四类问题的判别依据】 - 代码质量下滑:重复代码、被吞掉的异常、`catch` 块静默返回——通过全仓库搜 `catch`、重复检测工具、PR 评审模板检查 - 上下文失效:后半程忘规矩、行为跑偏、记不准——通过会话长度统计、约束文件检查、关键决策留痕检查 - 文档与代码不一致:README 过时、契约只在人脑——通过 PR 时序检查、规格文件检查、文档快照比对 - 架构渐进腐化:分层变乱、复用率下降、依赖如面条——通过依赖图分析、函数调用率统计、constitution 红线检查 【诊断输出格式】 # 仓库治理诊断报告 ## 一、20 条自检清单结果 | # | 类别 | 状态 | 证据 | |---|------|------|------| | 1 | 代码质量 | 通过/不通过/不适用 | [具体证据] | | 2 | ... | ... | ... | ## 二、四类问题归类 - [问题 1]:[具体描述,包含 3—5 个证据点] - [问题 2]:[具体描述,包含 3—5 个证据点] - [问题 3]:[具体描述,包含 3—5 个证据点] - [问题 4]:[具体描述,包含 3—5 个证据点] ## 三、根因分析 [每类问题为什么会出现] ## 四、治理方案(按优先级排序) ### 立即可执行(本周内) 1. [具体步骤 1] - 由 [角色] 执行,使用 [工具],预计 [耗时] 2. [具体步骤 2] - 由 [角色] 执行,使用 [工具],预计 [耗时] ### 短期(本月内) ... ### 长期(下季度) ... 【输入格式】 提供—— - 仓库地址(GitHub URL 或本地路径) - 仓库简介(项目类型、团队规模、用户量) - 我最关心的某一类问题(可选) 【输出格式】 Markdown 报告,按上述结构,每条治理步骤具体到: - 谁来执行(角色,如"工程主管"或"AI Agent") - 用什么工具(具体命令或工具名) - 预计耗时(如"2 小时"或"3 天") - 验收标准(怎么判断"做完了") 【边界约束】 - 不只给"建议"或"原则",必须给具体可执行步骤 - 不夸大问题严重性,按证据判断 - 不在没看代码的情况下,凭"理论"给诊断 - 治理方案按 ROI(投入产出比)排序,不按"理想"排序 - 不引入需要"团队坐下来讨论一周"的大型方案 - 不引入可能"破坏现有开发节奏"的方案 【MCP 工具】 - 代码搜索 MCP:全仓库搜关键字、读文件 - Git MCP:看 commit 历史、PR 历史 - 静态分析 MCP:重复检测、依赖分析 【遇到这些情况,先暂停并通知我】 - 仓库结构异常(无法识别主分支、无法读 package.json 等) - 关键配置文件缺失(无 README、无 CI 配置) - 检测到潜在安全风险(明文密码、过期依赖) - 你对某条自检清单的判断有疑问 - 治理方案涉及重大架构变更 【治理方案必须避免的反模式】 - "全员重写代码"——成本极高 - "引入全新框架"——学习成本高 - "制定详细规范"——执行难 - "立即全部启用"——容易反弹 - "严格 CI 门禁"——可能卡住所有人 【30 天治理纪律】 - 每周一:跑一次 20 条自检清单,记录分数 - 每月 1 日:对比上月数据,看趋势 - 每季度:评估治理方案的有效性,调整 - 不追求"立即完美",追求"持续改善" ``` ## 本章方法论:四类问题都指向"关键信息没落在文件里" 本章的方法论核心是:四类问题的根因里有三类指向同一事实——**关键信息没有落在 AI 能读到的文件里**。把规格、约束、验收标准、章程全部写进仓库,AI 才有"约束记忆"的持久载体。这是后续章节展开"skill、子 Agent、最佳实践"的问题侧基础。 下一章将进入"爬虫与数据获取"——把检索杠杆展开为完整的工程底座,讨论主流爬虫工具的优缺点、行为边界、以及如何用最小成本获取数据。