AI写代码越来越复杂？用Skill把复杂度治理写进工作协议

1. AI 写代码越写越复杂先弄清楚病根在哪1.1 为什么 AI 会系统性把事情搞复杂先讲一个我不久前遇到的真实场景。我给一个内部管理系统的列表页加导出功能需求本身非常简单把当前筛选条件下的数据导成 Excel。结果 AI 吭哧吭哧改完diff 里出现了 40 多个文件的变动新增了一个抽象的ExportStrategy接口、三个实现类、一个工厂还顺手把列表查询从 MyBatis 换成了 JPA。功能确实能跑但同事 review 的时候整个人是懵的。这不是 AI “笨”而是机制问题。大模型写代码的本质是根据上下文做概率预测它有强烈的“补全倾向”——看到一点复杂需求就倾向于补全成一套完整架构。上下文窗口有限它看不到整个项目的演进历史只能根据当前文件里的局部信息做决策。项目大了之后AI 每次只能读取一小块代码自然会在文件 A 里定义一个通用抽象在文件 B 里再定义一个类似的东西因为这两个文件在它的上下文里毫无关联。你在最后看到的结果就是到处是重复逻辑、层层套娃、依赖满天飞。所以“AI 写代码越写越复杂”不是玄学是缺失了一双始终盯着全局的眼睛。人类程序员靠项目经验、代码规范和 review 机制约束自己AI 如果不能被同样的规则约束它就会按自己的“最可能补全”方式行事。1.2 复杂度的“临界点”什么时候开始失控很多团队都有这种体验项目前两周 AI 写代码又快又干净第三周开始走样一个月后已经没人敢让 AI 大改了。问题在于复杂度不是线性增长的它有个临界点。我自己的判断标准有四个单文件行数。一个文件超过 600 行AI 就很容易“只看这一段、不顾那一段”。函数内部嵌套层级。超过 4 层 if/for/回调AI 在补全新逻辑时大概率会为了省事直接再套一层。抽象层数量。接口套实现、工厂套策略、模板套泛型一旦超过两层AI 自己都容易迷路更别说维护的人。新依赖的引入频率。每次加个小功能都想引一个新库是 AI 开始“堆复杂度”的最明显信号。但你没法靠“感觉”让 AI 遵守这些东西。它不理解“这样写太绕了”它只理解“规则”和“数值”。所以我做了一个专门管这件事的 Skill——一套写进 AI 工作协议里的规则和流程核心目标只有一个让 AI 在动手写代码之前先想清楚“这次改动最小能有多小”在写完之后自己给自己打分。2. 一个 Skill 的核心逻辑把“不能变复杂”写进工作协议2.1 Skill 到底是什么和普通提示词有什么区别现在各类 AI 编程工具都开始支持“Skill”这种机制比如 Claude Code 里的 Skill 目录、Cursor 的 Rules、Codex 的 AGENTS.md本质上都是一种结构化的规则单元。它和普通提示词最大的区别在于普通提示词是一次性的。你每次都得重新说一遍而且说漏一条它就忽略一条。Skill 是常驻的。只要开启AI 会在每次响应前自动加载相当于给它戴上了一副“复杂度眼镜”。用个不太恰当的类比普通提示词像是你在工位上贴的便利贴“记得代码整洁”Skill 则像是给 AI 装了一个强制流程——每次改代码前先读旧代码改完后必须填一张自评表不填完就不许交差。2.2 复杂度治理 Skill 的三条底层机制我设计的这个 Skill不像有些规则文件那样罗列一百条“你应该怎样怎样”而是只用了三个核心机制。第一存量复杂度识别。AI 在改动任何代码之前必须先把涉及的文件和它们的外部调用关系摸一遍。这个动作非常反直觉——很多人让 AI 干活时恨不得它立刻输出代码但恰恰是这一步能拦住一半以上的“顺手重构”。AI 一旦发现核心类被 37 个地方引用它就不太敢乱动了。第二变更影响面评估。让 AI 在动手前列出“我会改动哪些文件、会影响哪些调用方、会不会引入新依赖”。列完它自己就会发现为了加一个导出功能去换 ORM 是最蠢的方案。第三复杂度预算。给每次变更设置硬性上限单文件新增不超过多少行、新引入依赖必须有明确理由、抽象层次不得超过现有代码中最深的那层。超了就让它停下来而不是继续往下写。这三条机制加在一起效果从“AI 自由发挥”变成了“AI 在给定的笼子里发挥”。笼子不是限制功能是防止它把整个项目带着跑偏。3. 可以直接使用的「复杂度治理 Skill」配置示例3.1 Skill 规则文件可复制以下是我目前在用的一个通用版本不绑定具体平台你可以直接放到 Claude Code 的.claude/skills/目录里也可以改写成 Cursor Rules 或 Codex 的 AGENTS.md 格式。name: complexity-guard description: 在每次代码变更前后评估复杂度确保改动最小化、 结构不腐化、依赖不膨胀。适用于多文件业务系统维护和功能迭代。 variables: max_file_new_lines: 200 max_file_total_lines: 600 max_new_dependencies: 1 max_nested_level: 4 rules: - id: r1 message: 动手前必须识别存量复杂度 command: | 先阅读要改动的文件以及所有直接调用它的地方。 在回复中输出“存量复杂度摘要”文件行数、函数数量、 外部引用数、是否已被标记为“技术债”。 摘要不完成禁止输出任何代码。 - id: r2 message: 变更必须最小化 command: | 除非用户明确要求重构否则只动与本次需求直接相关的文件。 禁止顺路重命名、提取公共类、调整目录结构。 如认为某处必须重构写入“重构建议”栏不要直接执行。 - id: r3 message: 依赖新增需要论证 command: | 每新增一个第三方依赖必须在回复中输出 依赖名称、用途、替代方案自己写需要多少行代码、 引入后会拖入多少传递依赖。 新增依赖数超过预算时停止编码并询问用户确认。 - id: r4 message: 抽象层不得高于现有代码 command: | 在新增接口、抽象类、工厂、策略类之前先检查项目里 是否已有同类用法。若没有默认直接用最平铺的方式实现。 所有代码尽量“贴着现有风格写”。 - id: r5 message: 完成后必须输出复杂度自评表 command: | 代码完成后按以下格式输出自评 - 变更文件列表 - 每个文件新增/删除行数 - 是否新增依赖 - 是否新增抽象层 - 预估圈复杂度变化 - 是否有更简单的替代方案 自评表不输出视为任务未完成。 - id: r6 message: 重构机会标记但默认不执行 command: | 如果发现重复代码超过三处、或单文件超过行数上限 在“重构建议”栏中标记具体位置和方案但不要自动执行。这个文件不长但每一条都经过实战打磨。下面说说为什么是这些内容而不是别的内容。3.2 各条规则为什么这么写r1 是最容易被人忽略的一条。AI 有一个看起来无害但杀伤力很大的习惯只看你甩给它的那一段代码就开写根本不管用户是从哪个入口进来的。如果没有 r1你让它改一个订单详情接口它可能只盯着OrderService这一个类完全不知道这个 Service 同时被 App 端、管理后台、定时任务三个入口调用然后就大大方方地改了方法签名。r2 是为了对抗“顺手重构”。AI 特别喜欢在改动时把旁边看着不顺眼的代码一起改了因为在它的概率模型里“顺便优化”是一个高概率的合理行为。但问题是它一顺手就会把 diff 搞得很大review 成本急剧上升。所以我在 Skill 里写了“禁止顺路重命名、提取公共类”让所有超出范围的改动都必须先摆到台面上。r3 是针对依赖膨胀的。AI 引第三方库的手速比人快多了因为它记得各种库的 API不需要自己造轮子。但每引一个库都在给项目埋炸弹。所以我不禁止引依赖但要求它论证“自己写需要多少行代码”。大多数情况下写一个 20 行的工具函数比引一个带 40 个传递依赖的库要划算。r4 是抽象层的刹车。很多 AI 生成的代码之所以难维护不是因为功能有问题而是因为它造的抽象层太“新鲜”——项目里从来没有过这种用法后续维护的人根本不知道该往哪里加代码。让 AI “贴着现有风格写”本质是让它当一个“合群的员工”而不是一个“炫技的天才”。r5 是强制复盘。AI 写完代码特别容易进入“完成了结束”的状态。让它填自评表一是逼它自己看一眼产出二是把复杂度信息留给你方便 review 时快速抓重点。3.3 Skill 的承载方式Claude Code / Cursor / Codex你可能注意到这个 Skill 的格式是 YAML因为它可以直接给 Claude Code 用。如果你用的是其他工具做一次简单的结构转换就行。Claude Code把上面的 YAML 保存为~/.claude/skills/complexity_guard/SKILL.md。Skill 的description会被自动用来匹配触发时机我写的描述里包含“代码变更”“复杂度”“功能迭代”只要对话涉及这些内容它就会自动加载。Cursor把规则部分转写成.cursor/rules/complexity-guard.mdc注意保留rules里的核心命令就行Cursor 对 YAML frontmatter 的支持也比较友好。Codex 或其他遵循 AGENTS.md 的工具把rules里的内容改写成 Markdown 列表放进项目根的AGENTS.md。AGENTS.md 是全仓库级配置规则会被每个会话自动加载。我自己的做法是项目级把 Skill 放在仓库里团队所有成员共享个人级放在全局目录任何项目都能自动加载。前者保证团队一致后者让我的个人偏好也能被 AI 记住。4. 真实项目里的应用流程以“订单模块加优惠券分摊”为例4.1 第一步变更前的“存量复杂度扫描”光有配置文件还不够关键是它在真实项目里怎么跑起来。我拿最近一个实际的电商项目举例子需求是“订单结算时支持多张优惠券按商品金额比例分摊”。按照 Skill 的 r1AI 开工前先输出存量复杂度摘要。它扫描了一圈后汇报OrderCalculator类 480 行、10 个方法、被 6 个模块引用CouponService已有按订单分摊的逻辑但只支持平摊不支持按比例OrderItem实体没有分摊金额字段。这份摘要一出来两个关键信息就摆到桌面上了。第一OrderCalculator是核心类牵一发动全身最好不要大改。第二CouponService里已有同类能力应该在原有逻辑上扩展而不是另起炉灶。没有 Skill 的情况下AI 大概率会直接往核心类里塞一个新方法然后在旁边新建一个PriceProportionalAllocator接口——等项目上线后你才发现它和原有的平摊逻辑各走各的路。4.2 第二步把“改动最小方案”作为硬约束存量扫描完成后AI 按 r2 的要求给出了它还计划执行的变更清单我要求它把清单压到最短。最终方案是在CouponService里加一个calcProportionalShare方法在OrderItem上添加一个discountAmount字段OrderCalculator里只增加三行调用代码。这个过程中 Skill 还拦了一次“顺手重构”——AI 在读代码时发现OrderCalculator里有个废弃的totalPrice字段顺手就想删掉。按 r2 的规定它把这个动作写进了“重构建议”栏但没有执行。后来我们发现这个字段虽说是废弃的但还有一个报表接口在用得先改完报表才能删。要是当时让它顺手删了线上报表第二天就会挂。这一类事情发生多了你会发现Skill 最大的价值不是生成高质量的代码而是挡住高风险的顺手改动。4.3 第三步编码后的“复杂度自评表”代码写完AI 按 r5 输出自评表当时的实际内容如下变更文件CouponService.java、OrderItem.java、OrderCalculator.java、applicationContext.xml新增 Bean 配置行数变化新增 87 行删除 12 行新增依赖0 个新增抽象层0 个预估圈复杂度变化CouponService从 8 升到 11其余基本无变化更简单的替代方案无这张表最大的作用是在 review 之前就给了我一个“复杂度雷达图”。我看一眼就知道重点审哪里CouponService的复杂度升了需要看它的条件分支是不是写得太绕。如果没有自评表我面对的是一个几百行的大 diff只能肉眼硬扫。还有一个优化点是在应用里加“并发模拟测试”——下单高峰期会有大量订单结算请求分摊算法要保证线程安全。自评表里能看到这次改动主要集中在一个方法内锁粒度不用扩大风险可控。4.4 第四步把重构机会留给人类自评表输出后AI 在“重构建议”栏里标了一处OrderCalculator里已经有三个方法都在遍历orderItems做金额计算重复度较高建议抽一个公共方法。按 r6 的规则它没有自己动手抽。这不是因为它不能而是因为这种重构对项目结构影响太大三个方法的调用时机不同抽公共方法后要重新设计参数和返回值很容易引入金额计算顺序的错误。让人类工程师来定夺比让 AI 自主决策要稳得多。后来我在 review 时决定这一期不动它等优惠券分摊上线跑一周、数据验证无误后再做重构。如果当时让 AI 顺手改了一旦线上金额对不上排查范围就会从一个方法扩大到整个计算链路。5. 用了一阵子之后效果变化和几个容易翻车的坑5.1 我观察到的真实变化这个 Skill 我用了大约两个月覆盖三个项目。变化非常明显但我得诚实地说不是所有变化都是“代码变好看了”。最大的变化是 diff 变小了。同样的需求以前 AI 平均动 20 个文件现在控制在 5 个以内。我 review 的时间从每天两小时降到四十分钟这是个实打实的效率提升。第二个变化是“神秘抽象”变少了。以前 AI 特别喜欢发明新接口现在它在动手前会先去项目里翻一遍有没有现成的用法没有就老老实实用平铺的方式写。代码少了很多“设计感”但维护性反而更高了。第三个变化有点意外——重构建议栏成了一个小型技术债清单。AI 会把它在代码里发现的重复、坏味道、过期注释全部记在里面我每周花半小时过一遍挑优先级最高的安排进迭代。相当于多了一个自动巡检员。5.2 坑1Skill 太严AI 连正常的扩展都不敢做了第一个翻车是因为我把参数调得太紧max_file_total_lines: 400而项目里很多老文件本来就超过 400 行。结果 AI 每改一次就停下来提示“文件即将超过上限无法继续”连加一个if判断都要先问一遍根本没法干活。解决办法是给“存量超限”和“新增超限”分开设规则。存量文件超了没事只要新增行数不超过预算就行新文件才严格要求总量。我给 Skill 加了一个进阶规则超过上限的文件允许在其中继续编码但需要在变更记录里注明那种每个文件都超额、还需要继续扩展的才需要停下来讨论重构。调完之后 AI 不再动不动就撂挑子。5.3 坑2规则顺序错了AI 遵守后面的忘了前面的这个坑出在规则排序上。我一开始把 r5输出自评表放在最前面AI 每次都要先输出表格再写代码表格里全是“待定”“计划中”之类的废话既浪费 token 又没用。后来我把规则顺序调整成“扫描 → 列影响 → 编码 → 自评”并明确要求“摘要不完成禁止输出代码”、“自评表不输出视为任务未完成”AI 的执行质量立刻上了一个台阶。这说明规则的顺序其实是一种流程控制AI 会优先满足排在前面的硬性约束后面的规则容易被弱化。重要的约束放前面次要的放后面才能让它在每一步都记得自己该干什么。5.4 坑3和项目里已有的 linter / CI 冲突项目里本来就有 ESLint 和 CheckstyleAI 生成的代码风格常常和 CI 校验不一致。以前我总觉得这是工具之间配合的问题后来才发现是我的 Skill 漏了一条它没有要求 AI 在改完代码后主动跑一遍现有校验命令、并根据结果自纠。加上“改动完成后运行仓库已有的 lint/test输出结果若失败则修复直到通过”这条规则之后AI 交给我的代码基本不会再被 CI 打回来了。这比它自己埋头写规范代码更可靠因为只有项目里的真实校验规矩才是它能真正遵守的边界。5.5 一个容易忽略的规则设计问题规则本身的“歧义”最后一个坑是规则写得模棱两可。比如我一开始写过“代码保持整洁”“不要过度设计”AI 每次都会回复“已确保整洁无过度设计”但实际产出的代码还是一团糟。后来我把这些主观形容词全删了换成可判定的硬指标“不要新增接口除非项目里已有三个以上调用方都在用同一模式”“不要引入新的设计模式除非现有代码里已存在同样用法”。规则一旦可以像单元测试一样被判定AI 的遵守率就会大幅上升。这是所有 Skill 设计里最重要的一条经验写规则的人不能比执行规则的人更模糊。6. 下一步把 Skill 变成 Agent 的习惯而不是一次性的提示词6.1 固化到全局记忆让它成为默认行为我最开始把 Skill 放在项目临时目录里作用范围有限换台机器、换个项目就失效了。后来我把它固化到两个层面个人全局层放在 Claude Code 的~/.claude/skills/全局目录以及 Cursor 的全局 Rules 里任何项目打开都能自动加载。项目团队层放进仓库根目录的.cursor/rules和AGENTS.md团队成员 clone 代码后 Skill 就在那儿不用单独分发包。固化之后我发现自己的工作流悄悄变了——以前是我主动向 AI 提要求现在 AI 在每次动手前都会主动报“存量复杂度摘要”和“变更影响面”这已经成了它的默认行为。所谓 Skill 养成 Agent 的习惯说的就是这件事规则不需要你重复它自己记得。6.2 给 Skill 加触发式规则按需深度介入让 Skill 每次都被加载是个好起点但有时候完全没必要在简单需求上走全套流程。所以我加了一个“触发条件”策略单个文件新增超过 100 行、涉及 3 个以上文件、或要新增依赖时强制输出完整的存量摘要和变更影响面只改一行配置、只加一个字段、纯复制粘贴级别的修改跳过摘要只需提交说明。很多平台支持这种条件式触发的 Skill 描述如果不支持我也提供了一个土办法在规则的开头写“用户如果没有特殊要求默认按流程执行如果你判断本次变动属于低风险类型自行跳过项目级摘要但须在最终回复中给出简短的变更说明”。跑了几个月这个版本比一刀切的效果更省 token也不容易惹人烦。6.3 和别的 Skill 组合成一条“写码流水线”单个 Skill 管复杂度其他 Skill 管测试、管审查、管提效放到一起才能发挥最大价值。我现在常用的组合是复杂度治理 Skill先定边界测试生成 Skill再补防护网代码审查 Skill最后自查顺序不能乱。先让 AI 把改动范围控制住再根据实际改动量生成测试最后做一遍像“老工程师 review”一样的代码审查整体质量比我以前只要求“写完了事”高很多。尤其是测试生成 Skill补测的好处还能反过来约束 AI——当它知道自己写的代码马上要被单测验证时就更容易走稳妥路线。6.4 把 Skill 当“体检报告”用来做存量代码治理我还发现了一个计划外的用途把复杂度治理 Skill 当作存量代码的“体检报告生成器”。不再让它改代码而是让它直接扫描全仓库整理一份技术债清单出来——哪些文件超长、哪些类依赖太重、哪些抽象层根本没有实际调用方。它会按照仓库的真实情况整理出优先治理顺序。然后我再拿着这份清单去安排重构挨个处理那些“历史遗留问题”。这让复杂度治理不再只是在新增功能时才介入而是一个持续运转的“体检-治疗-复查”循环。对我来说Skill 真正的意义不在于它有多智能而在于它能替我把住那些“说了很多次但人总会忘”的底线。它像是一个沉默的警哨每次 AI 准备走捷径、准备顺手重构、准备再引一个新库之前先把这些冲动按回到桌面上让我在动手前看清楚代价。写 AI 编程相关的工具、规则或者工作流我都会默认先给它套上这样一层复杂度治理的壳因为我知道靠自觉是写不出能长期维护的项目来的。