我最近把 Claude Code 升到 2.1.0 之后突然想明白一件事AI 写代码的速度越快项目里的“代码熵增”就来得越快。如果不做代码治理再强的 AGENT 也救不了一个已经乱成一锅粥的仓库。这篇文章就来聊聊 2.1.0 里和治理相关的新东西以及一个我最近在用的开源项目 code-simplifier最后会附上一份可以直接复制进 Claude Code 的 Prompt。整篇内容没有版本号之外的玄学全是能落地的东西。1. 先把“代码熵增”这件事说清楚它是怎么毁掉项目节奏的1.1 一个我上周刚经历过的现场我接手过一个不算大的服务代码量大概 3 万行。从表面上看目录结构规整文件命名也还算统一。但只要开始改需求问题就暴露出来了我要把一个字段从userId改成accountId结果全局一搜有 6 个地方都在用不同的变量名保存同一个东西有的叫uid有的叫user_id有的叫owner。更夸张的是这 6 个地方各有各的赋值逻辑有些是从 token 里解析的有些是从数据库查出来的还有一个是前端传过来的。我只改字段名当然不行我还得搞清楚每个来源的格式是不是一样。最后这个“简单重构”花了整整一个下午。这个场景就是典型的“代码熵增”现场。它不是说代码里有多少个 TODO、有多少个坏味道而是系统的混乱程度已经到了“每次改动都需要全局重新理解一遍”的地步。1.2 熵增的本质成本非线性上涨热力学里的熵增是一个自发过程代码仓库也差不多。一个项目刚开始的时候逻辑简单依赖清晰写代码就是在白纸上画画。但每加一个需求、每换一个人手、每赶一次项目就会有些“临时方案”留下来。这些临时方案单独看都不致命问题是它们会互相纠缠。纠缠的直接后果是代码行数只涨了 20%但改动成本涨了 200%。我习惯把熵增理解成两个东西的乘积理解成本这个函数到底被谁调用了那两个类为什么都持有同一个状态改动风险牵一发而动全身改完 AB 崩了修完 BC 又不对了。两者是互相放大的。理解越难你越不敢改越不敢改代码就越乱。最后团队只能靠“谁写的谁负责”来维护而不是靠“代码本身好维护”。用一个生活类比就是衣柜刚整理好的时候找一件 T 恤只需要 10 秒。乱了一个月之后找同一件 T 恤可能要 5 分钟而且你还得把堆在上面的毛衣一件件挪开。衣柜没变大但“找衣服的成本”变大了。代码仓库也是同样的道理。1.3 治理和重构不是一回事很多团队一听到代码乱就开始喊“重构”。但重构在我眼里是“外科手术”它针对某一块病灶做一次大动作比如拆分模块、重写核心接口。这种操作风险大、周期长通常需要一个专门的版本和充足的测试保障。而“代码治理”是另一件事。它是日常动作就像每周整理一次桌面、定期清理过期依赖、给最难读的 5 个函数写测试。治理不一定需要大改它需要的是可持续的注意力和规则。Claude Code 这种 AGENT 工具出现之前治理最大的瓶颈是人手和时间。你明明知道哪个文件的圈复杂度爆表但你今天要修 bug明天要加功能哪还有时间去拆函数于是熵增一直积压。而把 AGENT 工具引入治理流程之后至少“拆函数”这种体力活可以交给 AI 先做人只需要负责 review 和方向判断。2. Claude Code 2.1.0 更新里哪些变化真正冲着熵增去的2.1 更新日志里最值得看的三个方向这次 2.1.0 的更新日志很长但我只关注三件事上下文压缩、Plan/Review 模式内建、Hook 系统加强。这三个能力单独拎出来都是体验优化放在一起就是一套“代码治理基础设施”。先说上下文压缩。以前用 Claude Code 跑长会话聊到后面它经常忘掉前面的约定。比如你一开始说“这个模块的对外接口不要动”过了 20 轮它开始在接口上加参数。这种失忆会让 AI 在不知不觉中制造新的不一致等同于加速熵增。2.1.0 引入了更激进的上下文摘要机制它在会把早期内容压缩成结构化摘要保留关键决策丢掉无关日志。实测下来长会话的“行为漂移”问题比之前轻很多。然后是 Plan/Review 模式。这个对治理最重要。Claude Code 不再是一拿到指令就冲进代码库里乱改而是能先输出一份改动计划让用户确认后再动手。我现在的标准操作是先让它跑一个plan模式把“要改哪些文件、每处怎么改、影响范围是什么”列出来我看完确认再让它执行。这一步直接把 AI 的“自由发挥”关进了笼子里。最后是 Hook 系统。2.1.0 里可以在特定时机触发外部脚本或命令比如提交前自动跑 linter、生成 diff 之后自动调用 code-simplifier 扫描。它的意义在于把“治理规则”变成流程的一部分而不是依赖某个人每次都记住要跑一遍检查。2.2 对新版 Skills 机制的理解2.1.0 之前很多人把 Claude Code 当成“对话式编程工具”问一句写一句。但 Skills 机制出来之后它可以被看成一套“AI 可复用的团队操作手册”。举个例子我们团队有自己的一套 Git 提交规范不要一次性提交 500 行、提交信息必须标注模块前缀、重构类提交不允许夹杂功能改动。以前每次让 Claude Code 干活之前我都要在 Prompt 里重新交代一遍。现在把这些规范写成一个 Skill会话开始后自动加载它每次执行完就会按这个规范整理最终结果。我理解里Skills 解决的就是“让 AI 长期稳定按既有约定行事”。约定越稳定AI 产出的代码就越统一熵增速度自然就被压住了。2.3 一个容易误解的点功能变多不等于熵减Claude Code 2.1.0 的功能确实更丰富了但有人会陷入“功能越多越好全部打开”的陷阱。我自己是不赞成的。AGENT 工具的能力越强它每个会话能做的事情就越多。如果没有足够的约束它完全可能在一个小时内把十几个文件全部重写一遍表面上代码变“简洁”实际上整个模块的依赖关系都被挪了个位置review 的人根本看不完。所以我在 2.1.0 里只保留了两样东西一个是“先出计划再动手”一个是“对计划说 No 的权利”。这才是治理心态。3. code-simplifier用数据把“感觉复杂”变成可治理的指标3.1 这个工具解决什么问题复杂度高不高很多人靠“感觉”。但感觉是不靠谱的尤其是你在一个项目里泡了半年之后你会习惯很多原来很怪的结构。这时候就需要一个客观工具来告诉你哪几个文件就是当前仓库的熵增热点。code-simplifier 就是我在 GitHub 上翻到的一个开源小工具。它做的事情非常简单扫描整个仓库算出几个核心复杂度指标然后输出一份按严重程度排序的报告。它不直接改代码只负责“指出哪里乱”。我用下来最大的感受是它把代码治理从一个“凭良心”的行为变成了一个“看数据”的行为。以前你很难跟产品经理解释为什么这周要花两天时间拆一个函数现在你可以直接说这个文件的圈复杂度已经到 47是所有 Bug 的高发地不拆它下周迭代的修改成本只会更高。3.2 核心指标怎么看code-simplifier 产出的指标不算多但每一个都很有针对性。我整理了一个表格方便对照理解指标含义我习惯的警戒阈值圈复杂度一个函数里独立路径的数量超过 10 就需要关注超过 20 必须拆扇入有多少地方调用这个函数超过 15 就要小心改它影响面很大扇出一个函数依赖了多少外部东西超过 8 说明职责可能过重重复代码块相同/相似代码出现的次数出现 3 次以上就该提取公共逻辑超长函数单函数超过设定行数超过 80 行建议拆分熵分数上面几个指标的综合值每次发布前对比持续上升就要处理单独看一个指标意义不大比如圈复杂度高但函数很稳定也不是必须马上动。关键是看多个指标叠加一个函数既长又有很多分支同时还有一堆调用方那它就是仓库里最危险的地方优先治理。3.3 典型使用流程这个工具用起来不复杂。我的流程是克隆仓库到本地按照 README 里的说明完成安装。它是一个命令行工具不依赖 GUI所以也方便塞进 CI。对整个项目做一次全量扫描code-simplifier scan --path src --format table输出一份 JSON 格式的报告给 Claude Code 当输入code-simplifier scan --path src --format json entropy.json把entropy.json和治理 Prompt 一起发给 Claude Code让它基于真实数据做治理计划而不是凭感觉瞎猜。这套流程我大概每周跑一次。跑完之后不用马上处理所有问题只需要挑出“熵分数最高”的前 3 个文件交给治理流程处理就够了。3.4 和 Linter 的边界很多团队已经有 ESLint 或 SonarQube 这类工具了那 code-simplifier 是不是重复造轮子我觉得不是。Linter 解决的是“局部规范”问题缩进、命名、有没有未使用变量、有没有明显反模式。它管的是“一行代码好不好看”。而 code-simplifier 解决的是“全局结构”问题哪些文件之间耦合太深、哪个函数被 20 个地方依赖、哪些重复逻辑散落在不同模块。它管的是“整个系统的修改成本”。打个比方Linter 是检查你有没有把餐具洗干净的洗碗机code-simplifier 则是帮你分析“这个厨房动线是不是有问题冰箱放这合不合理”。两个层面都需要。4. 治理 Prompt 全文与用法说明4.1 为什么需要一个专用的治理 Prompt如果你直接跟 Claude Code 说“帮我清理一下代码”它大概率会给你一个大动作重构。AI 对“清理”的理解往往是“大幅简化”于是会移动文件、合并函数、抽公共方法最后给你一个看起来很漂亮但 diff 巨大的结果。所以我专门写了一份治理 Prompt核心不是“让它干活”而是给它的工作方式设边界。目标是在不改变外部行为的前提下把局部的结构复杂度降下来。这份 Prompt 我用了好几个星期也踩过一些坑调整了几轮下面是当前稳定可用的一版。4.2 完整 Prompt你是这个代码仓库的架构治理顾问。你的目标不是“重构”而是把代码熵增控制在一个可维护的范围内。 在开始任何代码修改之前你必须 1. 先阅读仓库结构和关键文件结合我提供的分析报告如果有。 2. 输出一份“熵源清单”按影响面排序格式如下 - 文件路径 - 熵增类型重复逻辑 / 职责混乱 / 超长流程 / 依赖纠缠 / 命名漂移 - 影响面哪些模块在改动时会受影响 - 推荐动作提取公共函数 / 拆分模块 / 清理死代码 / 调整依赖方向 3. 给出“最小干预计划”只能对清单中影响面最大的前 3 个熵源动手并明确说明每个文件打算怎么改预计删除或新增多少行。 4. 在执行阶段每改完一个文件先停下来运行测试和代码检查再继续下一个。 硬性约束 - 不要在没有明确理由的情况下移动文件或重命名函数。 - 不要引入新的依赖库除非熵源清单里明确说明只能通过引入依赖解决。 - 如果某个修改会引发超过 3 个文件的连锁改动先停下来向我确认。 - 重构后的代码必须保持对外行为不变如果行为需要变请单独说明不要混入这次治理。 - 每个完成的改动都要求返回一个简短摘要改动原因、改动行数、验证方式。 - 如果现有的测试无法覆盖某个文件修改前先指出风险并建议补充哪些测试用例。4.3 怎么用这个 Prompt我推荐两种用法。一次性使用把上面的 Prompt 复制到 Claude Code 会话开头然后把entropy.json的内容一起贴进去。它就会先输出熵源清单再等你的确认。固化使用把这份 Prompt 放进 CLAUDE.md 文件或者转成一个自定义 Skill。这样每次打开 Claude Code 的时候它都会自动加载这段约束不用每次手动粘贴。关键点是分阶段。第一次让它只输出熵源清单和最小干预计划不要直接让它动手。你看到计划后挑选最值得改的部分再让它执行。这样才能保证每一步都由你控制。4.4 为什么这样设计 Prompt这份 Prompt 的设计逻辑其实就三条。第一先诊断后动手。它强制 AI 先输出熵源清单再给计划最后才执行。这避免了 AI 自作主张地“边看边改”。第二明确影响面约束。限定了前 3 个熵源并限制连锁改动不能超过 3 个文件。AI 一旦自由发挥改动范围很容易滚雪球所以这个约束就是把雪球先按住。第三把“治理”和“需求变更”隔离。硬性约束里有“保持对外行为不变”。这一点特别重要。治理应该是一次纯结构性调整如果你允许它顺便修一个逻辑 bug那整个 diff 就分不清哪些是重构、哪些是行为变化review 难度急剧上升。5. 我在实际项目中跑出来的经验与坑5.1 第一个坑AI 太想“做漂亮事”我最早用治理 Prompt 时让 Claude Code 拆一个 357 行的函数。结果它不光拆了那个函数还把两个公共方法挪进了工具类顺手删了一个看起来“没用”的接口。功能没坏但整个 PR 有 800 多行 diff。我 review 了一个多小时最后只合并了其中一半改动另一半回滚了。为什么因为“删接口”虽然现在没有调用方但不能确定是不是有外部系统还在偷偷用。这种不可控的“顺手优化”很危险。教训就是治理 Prompt 里的“前 3 个熵源”和“不要移动文件或重命名函数”这两个约束绝对不能去掉。AI 太容易追求漂亮人必须负责把目标框住。5.2 第二个坑没有测试时AI 的自信是幻觉有一次我要治理一个老模块那个模块几乎没有单测只有几条最粗粒度的接口测试。Claude Code 改完之后自己跑了一遍测试然后告诉我“应该没问题”。我不放心手动画了几组输入去验证结果发现有一个边界行为跟原来不一样原来函数对空字符串会返回null重写之后返回了空对象。这种问题测试没覆盖但线上会影响很多调用方。从那以后我就给自己定了条规矩没有测试覆盖的文件先让 AI 补关键测试再执行治理重构。这份治理 Prompt 里的最后一条“如果现有测试无法覆盖先指出风险并提出测试建议”就是从这次教训里加进去的。5.3 第三个坑把治理和需求开发混在一起有段时间为了赶效率我一边让 Claude Code 加新功能一边让它顺手治理触达过的代码。听起来很省事实际上非常糟糕。功能开发的 diff 里混入了几十行重构review 的人很难判断“这个改动会不会引入 bug”。而且一旦新功能上线后出问题回滚也会很麻烦你想回滚功能但重构代码已经铺开回滚会把正常代码也带回去。所以我现在都是把治理单独开分支单独跑测试单独合并。绝不混在需求分支里。这个原则比用什么工具都重要。5.4 一些值得推荐的小流程几个流程坚持下来效果比我想象的好每周固定跑一次 code-simplifier把熵分数趋势发给团队。不用人肉 review 好坏只看数字涨跌。每次治理只挑前 3 个文件控制在别人 10 分钟内能 review 完的量。在 CI 里卡熵分数阈值。比如某个文件的圈复杂度超过 20 就阻止合并修复后再放行。硬性卡点比口头约定有效得多。让 Claude Code 在提交信息里标出“治理”还是“需求”这样 filter 提交历史的时候一眼就能看出哪些是和治理相关。5.5 对 2.1.0 和 code-simplifier 组合的最终评价用了一段时间我的体感是Claude Code 2.1.0 像是给 AI 装上了一套“先想后做”的刹车code-simplifier 像是给团队发了一张“哪里最乱”的地图而那份治理 Prompt 则是把这张地图和刹车绑到一起的螺丝。这套组合不可能让代码熵增彻底消失但它能把“熵增失控”的临界点往后推很远。以前代码乱到一定程度就只能重写现在至少能在每个版本里花很少的时间把最危险的几个结构问题按下去。最后分享一个我自己的小习惯每次治理完我会让 Claude Code 把这段会话里的关键决策摘要追加到docs/architecture-decisions.md。下次再遇到类似问题时直接在 Prompt 里引用这条记录就行。这样做之后代码熵增不会彻底归零但它会从一个失控的雪球变成一条每周都在缓慢下降的曲线。