AI 生成代码太快了快到让人觉得代码比自来水还便宜。可真要改点什么打开自己项目的src/看看几百个文件改一行崩一片测试覆盖率 12%agent 写的代码没人敢碰。这并非个例。AI 正在加速代码的劣化。一、代码不是变便宜了是劣化变快了每次让 agent 修改一个文件它只看那个文件并不知晓这个改动会牵连另外三个模块。隐蔽的耦合层层堆积依赖关系逐渐失控并行实现之间缺少 seam。几周之后src/就成了没人敢碰的泥球。Matt Pocock 管这叫slop。不是满屏的 bug是逐渐堆积而成的结构性债务。AI 写代码的速度已经远超人工修复的速度。他做了/improve-codebase-architecture。原理来自 John Ousterhout 的《A Philosophy of Software Design》《软件设计的哲学》一本 1994 年的书。他把书里的概念变成了 Agent 能执行的指令。简单来说这个 skill 做三件事扫描代码库。用 Deletion Test 找出哪些模块是 Shallow Module、值得重构生成一份 HTML 报告。把每个候选方案的问题、改进方向和推荐强度列清楚进入/grilling模式。逐题追问帮你把改进方案敲定到可以开 Issue 的程度二、Deep vs Shallow跟 AI 说同一套语言这个 skill 的关键是一套词汇表8 个精确术语。Matt 的原话跟 AI 建立共享词汇比跟人建立更重要。人会跑题、误解、遗忘。AI 用词绝对一致。定义一次「deep module」此后每一次调用含义始终如一。这在人类团队中几乎无法实现。这套语言由四个概念构成Deep Module深模块。意思是接口很小、做的事情很多。拿 TanStack Query 举个例子你只学一个useQueryhook它背后帮你干了缓存、去重、重试、后台刷新一堆事。一个入口换回整个数据层的完整能力。Shallow Module浅模块。刚好反过来接口一大把实际没干多少活。参数暴多、配置项暴多、回调暴多真正有用的逻辑就几行。AI 最爱生成这种代码看着什么都能配其实只是把复杂度从模块里搬到了调用者头上。Seam接缝。代码里「改行为不用改源码」的那个点。比如一个接口换掉实现就能换掉行为原来的代码一行不用动。测试也是靠这个在 seam 处把真实模块换成 mock不碰源码就能测。Locality 和 Leverage。这两个词说的是「好处落在谁头上」。Locality 是对维护者的好处改一个地方就行不用满项目找。Leverage 是对使用者的好处学一点点能用一大片。好的设计两者都要。三、一个 Skill三步把烂代码拉回来执行该 skill分为三个阶段。侦查。Agent 先读CONTEXT.md领域术语表和docs/adr/架构决策记录。然后遍历 commit 历史寻找热点哪些文件频繁变更。判断标准只有一个Deletion Test。假设删除这个模块。若复杂度随之消失说明模块并未真正起作用。若复杂度散落到多个调用者说明它确实在承担职责。出报告。一份自包含的 HTML 文件浏览器打开即可阅读。每个候选方案一张卡片涉及哪些文件、哪里造成了摩擦、如何改进以 locality 和 leverage 解释、Before/After 对照图、推荐强度Strong / Worth exploring / Speculative。末尾附一个 Top Recommendation。讨论。选择一个候选方案后skill 进入/grilling模式逐题追问约束条件是什么依赖关系如何新模块采用哪种结构接口如何定义过程中自动更新CONTEXT.md或提议编写 ADR。这个 skill 并非设计为 AFK 使用。Agent 负责侦查你负责决策。四、在 1500 次提交的项目上实测Matt 在自己的 course video manager 项目上演示。1500 次提交虽非泥球但也称不上完美。关闭 auto mode开启新的 Claude 会话运行 skill。Agent 找到 6 个 deepening opportunity。Matt 挑选了其中一个「前端和后端存在并行实现seam 处缺少测试」。前端修改后后端未能同步典型的低 locality。进入 grilling 阶段之后Module shape 如何设计TypeScript 接口长什么样Agent 逐题追问。对话结束时产出可直接通过/to-issues创建为 GitHub Issue。全程不到 15 分钟。修复可能需要数小时但定位问题这一步skill 已经完成了 80%。五、将军和士官Matt 用一个军官层级的比喻定义人机分工Agent 是战术程序员能够深入代码细节快速执行修改。但它们之上需要一个人战略程序员。Agent 是士官负责跑腿侦查列出候选方案。你是将军决定哪个值得修复、从长期来看哪些对代码库有益。这一分工比「AI 是副驾驶」更加精确。副驾驶没有决策链。六、怎么用到你自己的项目每隔几天运行一次。快速迭代的项目shallow module 的积累速度比你想象的更快。搁置一个月不做往往积压数十个待处理候选。你来决策。Agent 找到的并非都值得修复。先用 Deletion Test 筛一遍删掉它复杂度去了哪里遗留代码先建 harness。改动架构之前用测试将关键 seam 保护起来。Deep module 带来好 seam好 seam 带来好测试好测试让 Agent 的产出更好。小结AI 正在加速代码的劣化。但解法不在于 AI 本身而在于 John Ousterhout 1994 年写下的那本书。/improve-codebase-architecture把 30 年前的设计理论变成了 Agent 能执行的指令。Agent 负责侦查你负责决策。每隔几天运行一次。Matt Pocock 的 skills 仓库已获 41.5K star。并非他发明了新理论而是他把经典理论翻译成了 Agent 能理解的语言。本文基于 Matt Pocock 的 /improve-codebase-architecture skill 源码、演示视频How To De-Slop A Codebase Ruined By AI及 /teach 生成的教程材料编写。 
长河君 · 2026/8/11 15:50:46 · 阅读 1.2k 修复AI代码的混乱，Matt Pocock的/improve-codebase-architecture使用详解
AI 生成代码太快了快到让人觉得代码比自来水还便宜。可真要改点什么打开自己项目的src/看看几百个文件改一行崩一片测试覆盖率 12%agent 写的代码没人敢碰。这并非个例。AI 正在加速代码的劣化。一、代码不是变便宜了是劣化变快了每次让 agent 修改一个文件它只看那个文件并不知晓这个改动会牵连另外三个模块。隐蔽的耦合层层堆积依赖关系逐渐失控并行实现之间缺少 seam。几周之后src/就成了没人敢碰的泥球。Matt Pocock 管这叫slop。不是满屏的 bug是逐渐堆积而成的结构性债务。AI 写代码的速度已经远超人工修复的速度。他做了/improve-codebase-architecture。原理来自 John Ousterhout 的《A Philosophy of Software Design》《软件设计的哲学》一本 1994 年的书。他把书里的概念变成了 Agent 能执行的指令。简单来说这个 skill 做三件事扫描代码库。用 Deletion Test 找出哪些模块是 Shallow Module、值得重构生成一份 HTML 报告。把每个候选方案的问题、改进方向和推荐强度列清楚进入/grilling模式。逐题追问帮你把改进方案敲定到可以开 Issue 的程度二、Deep vs Shallow跟 AI 说同一套语言这个 skill 的关键是一套词汇表8 个精确术语。Matt 的原话跟 AI 建立共享词汇比跟人建立更重要。人会跑题、误解、遗忘。AI 用词绝对一致。定义一次「deep module」此后每一次调用含义始终如一。这在人类团队中几乎无法实现。这套语言由四个概念构成Deep Module深模块。意思是接口很小、做的事情很多。拿 TanStack Query 举个例子你只学一个useQueryhook它背后帮你干了缓存、去重、重试、后台刷新一堆事。一个入口换回整个数据层的完整能力。Shallow Module浅模块。刚好反过来接口一大把实际没干多少活。参数暴多、配置项暴多、回调暴多真正有用的逻辑就几行。AI 最爱生成这种代码看着什么都能配其实只是把复杂度从模块里搬到了调用者头上。Seam接缝。代码里「改行为不用改源码」的那个点。比如一个接口换掉实现就能换掉行为原来的代码一行不用动。测试也是靠这个在 seam 处把真实模块换成 mock不碰源码就能测。Locality 和 Leverage。这两个词说的是「好处落在谁头上」。Locality 是对维护者的好处改一个地方就行不用满项目找。Leverage 是对使用者的好处学一点点能用一大片。好的设计两者都要。三、一个 Skill三步把烂代码拉回来执行该 skill分为三个阶段。侦查。Agent 先读CONTEXT.md领域术语表和docs/adr/架构决策记录。然后遍历 commit 历史寻找热点哪些文件频繁变更。判断标准只有一个Deletion Test。假设删除这个模块。若复杂度随之消失说明模块并未真正起作用。若复杂度散落到多个调用者说明它确实在承担职责。出报告。一份自包含的 HTML 文件浏览器打开即可阅读。每个候选方案一张卡片涉及哪些文件、哪里造成了摩擦、如何改进以 locality 和 leverage 解释、Before/After 对照图、推荐强度Strong / Worth exploring / Speculative。末尾附一个 Top Recommendation。讨论。选择一个候选方案后skill 进入/grilling模式逐题追问约束条件是什么依赖关系如何新模块采用哪种结构接口如何定义过程中自动更新CONTEXT.md或提议编写 ADR。这个 skill 并非设计为 AFK 使用。Agent 负责侦查你负责决策。四、在 1500 次提交的项目上实测Matt 在自己的 course video manager 项目上演示。1500 次提交虽非泥球但也称不上完美。关闭 auto mode开启新的 Claude 会话运行 skill。Agent 找到 6 个 deepening opportunity。Matt 挑选了其中一个「前端和后端存在并行实现seam 处缺少测试」。前端修改后后端未能同步典型的低 locality。进入 grilling 阶段之后Module shape 如何设计TypeScript 接口长什么样Agent 逐题追问。对话结束时产出可直接通过/to-issues创建为 GitHub Issue。全程不到 15 分钟。修复可能需要数小时但定位问题这一步skill 已经完成了 80%。五、将军和士官Matt 用一个军官层级的比喻定义人机分工Agent 是战术程序员能够深入代码细节快速执行修改。但它们之上需要一个人战略程序员。Agent 是士官负责跑腿侦查列出候选方案。你是将军决定哪个值得修复、从长期来看哪些对代码库有益。这一分工比「AI 是副驾驶」更加精确。副驾驶没有决策链。六、怎么用到你自己的项目每隔几天运行一次。快速迭代的项目shallow module 的积累速度比你想象的更快。搁置一个月不做往往积压数十个待处理候选。你来决策。Agent 找到的并非都值得修复。先用 Deletion Test 筛一遍删掉它复杂度去了哪里遗留代码先建 harness。改动架构之前用测试将关键 seam 保护起来。Deep module 带来好 seam好 seam 带来好测试好测试让 Agent 的产出更好。小结AI 正在加速代码的劣化。但解法不在于 AI 本身而在于 John Ousterhout 1994 年写下的那本书。/improve-codebase-architecture把 30 年前的设计理论变成了 Agent 能执行的指令。Agent 负责侦查你负责决策。每隔几天运行一次。Matt Pocock 的 skills 仓库已获 41.5K star。并非他发明了新理论而是他把经典理论翻译成了 Agent 能理解的语言。本文基于 Matt Pocock 的 /improve-codebase-architecture skill 源码、演示视频How To De-Slop A Codebase Ruined By AI及 /teach 生成的教程材料编写。