Community编程与开发github.com

查找过度工程化

识别并消除项目内部信任边界内不必要的防御性代码,如死分支、吞错误、无用的兼容层等;每个守卫都是一条需要测试的分支和一个需要维护的路径,沉默的容错会把响亮的失败变成安静的错误答案。

查找过度工程化 是什么?

该技能帮助开发者系统性地审计代码库中的防御性代码,识别那些保护成本高于其防御价值的“过度工程化”模式。它专注于信任边界内部的保护(如内部调用者、项目自身配置或数据库的校验),而非对外部不可信输入的验证(如用户文件、网络响应、第三方负载)。技能提供了一个六步流程:清点保护手段、命名其处理的场景及输入控制者、测试场景的可达性、量化成本(代码行、分支、测试等)、决定回滚/收窄/保留,并在结构性回滚前确认。每个发现都需要报告保护的场景、输入控制方、是否曾发生、成本以及处置方式:回滚(小且不可达的立即删除)、收窄(优先边界检查替代内部检查)或保留(必须仅限于真实、可达且位于信任边界外部的场景)。该技能广泛应用于各类开发平台和编辑器工具(如Claude Code、Cursor、Codex),帮助团队减少维护负担、避免由错误掩码导致的静默失效。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomasdolash/code-audit-skills/tree/HEAD/find-overengineering

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

查找过度工程化 是做什么的?

一个没有调用方会生产的输入的回退、一个没有人会设置两个选项的三个选项、一个为不再存在的消费者准备的兼容层、以及一个为只有一位用户的模式准备的迁移框架,其成本都超过了它们防御的场景。防御不是免费的,也不是中立的。每个守卫都是一条需要测试的分支和一个需要维护的路径,一个沉默的容错会把响亮的失败变成安静的错误答案。

真正重要的失败

处理极端情况的极端情况的保护代码通常会隐藏真正的失败,而不是处理它。回退掩盖了null,重试掩盖了bug,shim则让一个死掉的接口永远存活。它也会腐烂。没有人去执行它,因为它所守卫的场景从未发生过,所以当它停止工作时,也没有人能察觉。

一个发现不是“这看起来很防御性”。针对每段保护,报告它处理的场景、谁控制该输入、该场景是否曾经发生过,以及保护的成本。 然后建议回滚、收窄或保留的理由。

硬性边界:对项目无法控制的输入的检查,保留。 用户的文件、网络响应、第三方的负载和设备是真实边界,它们的验证是本职工作。这次审计关注的是信任边界内部的防御。

过程

  1. 清点保护手段。 没有可达触发器的守卫和提前返回、吞掉异常的catch块、没有人传的默认参数、无人设置的功能标志和选项、对不可能以那种方式失败的操作的重试和超时、兼容性 shim、迁移,以及只有一个实现的抽象。

  2. 命名每个保护手段处理的场景,以及谁控制该输入。 内部调用方、项目自身的配置或数据库属于边界内部,是候选对象。任何来自外部的都不是。

  3. 在声称场景不可能之前测试其可达性。 构造它,grep 调用方,查找产生它的输入,检查缺陷历史中是否有该事件。“防御性”并非场景发生的证据,你无法想象它也不是证据。说明你检查了什么。

  4. 给成本定价。 计算它增加的代码行数和分支数、状态和选项数、它强制编写的测试数,以及读者必须掌握的复杂度。然后说明它隐藏了什么:被吞掉的错误、错误的默认值、在表面上之前传播得更远的失败。

  5. 决定:回滚、收窄或保留。 对于没有东西能到达的场景,回滚。收窄优先考虑边界的一个检查而不是内部的 N 个检查,一个选项而不是三个,响亮的失败而不是安静的容错。保留了场景真实、可达且位于边界之外的情况,并说明它是哪一种。

  6. 在结构性回滚前确认。 删除兼容层、迁移或公共选项可能会破坏已写入的数据或已部署的消费者;小的、明显不可达的才是你可以直接删除的。

修复

  • 小的不可达回滚:现在就去执行。 删除没有调用方触发的守卫、针对不可能发生的场景的回退、无人读取的选项(参见 find-accepted-but-ignored 寻找那些被读取却什么也不做的选项)、只隐藏错误的重试、只有一个实现且近期无第二个的抽象。
  • 结构性回滚:先确认。 对于固定版本、协议 shim、数据迁移、为已部署消费者准备的兼容路径,带着消费者描述提建议,让负责人决定。
  • 绝不能回滚边界检查。 对不可信输入的验证、转义和授权保留,无论成本如何。
  • 优先删除,优先于收窄而非删除。 一个边界检查胜过五个内部检查;最小且正确的防御是那个不会漂移的防御。

报告

以保护手段及其成本开始:

保护手段处理的场景控制输入方是否曾观察到定价成本处置方式
defaultConfig 回退调用方未传配置内部所有调用方都传了配置2 分支,1 测试删除
本地写入的重试同一磁盘上的瞬时 IO内部从未隐藏错误,增加 3 秒删除
--legacy 标志2.0 之前的消费者外部没有部署的消费者1 条路径,1 个选项先确认
输入长度检查恶意负载外部不适用1 个守卫保留

然后,针对每个发现:它保护什么、为什么该场景不发生(或确实发生)、成本,以及回滚或保留的理由。

以如下内容结尾:已删除、已收窄、已与负责人确认、作为真实边界保留,以便读者可以看到幸存下来且为什么存活的防御。

归属

改编自 dzhng/jevgrep (https://github.com/dzhng/jevgrep),MIT 许可,版权 (c) 2026 David Zhang。它审计的类别以及小的场景立即回滚的规则来自该项目;此文件以自身语言陈述并扩展为流程。仓库 README 包含完整的许可声明;当重新分发时,必须将副本保留在此文件旁边。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能