Audit Overengineering

Audit Overengineering

对一个或多个仓库做只读的过度工程审计，输出可追溯、按净收益排序的精简候选。少代码不是目标；在不损害业务行为、兼容性、安全性和可维护性的前提下消除无必要复杂度才是目标。

适用边界

• 做：整仓或多仓瘦身审计、依赖替代分析、无必要抽象与死扩展点盘点、精简机会排序。
• 不做：只审查单次 diff、直接修改代码、通用正确性审查、安全审计、性能诊断或仅按行数评判设计。
• 默认扫描当前仓库；用户给出多个路径时逐仓独立审计，再汇总共同模式。
• 没有源码与调用证据时只列为待验证候选，不得宣称可以安全删除。

审计深度

用户未指定时使用 standard：

| 深度 | 覆盖范围 | | --- | --- | | quick | 仓库结构、依赖清单和静态候选；仅在证据范围很小且闭合时给出正式发现，不承诺语义完整性 | | standard | 在声明覆盖范围内盘点完整文件清单，核验主要入口、仓库内消费者、配置、测试与已知契约 | | deep | standard 加仓库外公开契约、动态注册、跨模块影响和主要失败路径核验 |

深度描述的是证据要求，不是无限资源承诺。先评估仓库规模、模块数量和可用时间；无法完整覆盖时按模块分批，明确标记“部分覆盖”及未检查区域，不得静默降低深度或把局部结果外推为整仓结论。

执行流程

1. 确定范围与约束

1. 从用户请求、仓库事实和宿主权限确定仓库根、审计深度及可执行的只读检查；只有关键不确定性会改变范围、风险或验收时才追问。
2. 分别读取适用的 AGENTS.md、构建入口、依赖清单和与审计相关的 Makefile 目标。
3. 检查工作区状态并保留已有改动；未经明确授权不得修改、安装依赖或访问外部服务。
4. 记录排除项。默认排除依赖缓存、构建产物和明确生成物，但保留其来源与消费关系用于判断。

2. 建立仓库地图

先统计仓库规模并盘点文件树、语言、模块、入口、依赖、配置、测试和代码生成关系。大型仓库或多仓任务先划分模块与批次，持续记录已覆盖和未覆盖区域；资源不足时交付部分覆盖报告，不得声称完成整仓审计。若宿主提供语义索引或代码图能力，优先用于符号、调用方与影响分析；不可用时组合文件检索、语言原生命令和源码回读。精确文本命中只能发现候选，不能独立证明无调用或可删除。

3. 发现候选

读取 [审计标准](references/audit-rubric.md)，按以下标签寻找候选：

• delete：没有有效消费者的代码、配置、开关或推测性功能。
• yagni：当前只有一种变化、一个实现或一个产品，却引入额外抽象。
• delegate：只透传参数与返回值、没有边界职责的包装层。
• duplicate：仓库内已有等价能力，当前实现造成重复维护。
• stdlib：语言标准库已提供等价且满足约束的能力。
• native：运行平台、框架或浏览器原生能力可替代自建实现或依赖。
• shrink：保持相同行为与清晰度时可以显著缩短的实现。

4. 证实或驳回

每个正式发现都必须检查定义、声明范围内的全部可见消费者、入口注册、配置引用、测试用途和已知公开契约，并说明结论适用的证据边界。按深度执行以下门槛：

• quick 默认只输出待验证候选；只有检查范围局部且闭合，并已排除该范围内的隐式用途时，才可给出正式发现。
• standard 必须闭合仓库内证据；仓库外消费者或运行时配置无法确认时，只能保留不依赖该未知信息仍然成立的正式发现，并将置信度降为中。未知信息可能推翻建议时，必须降级为候选。
• deep 还要主动核验仓库外公开契约、反射、依赖注入、插件发现、序列化、代码生成、构建标签及跨模块影响；无法排除且可能推翻建议时仍须降级为候选。

因规模或资源限制未检查的区域必须写入报告。任何深度都不得把“未搜索到”当作“没有消费者”的充分证据。

不要建议移除有效的输入校验、鉴权、错误处理、可观测性、数据保护、并发保护、无障碍能力或必要兼容层。抽象有多个实现也不自动合理，只有一个实现也不自动多余；结论取决于已证实的变化需求和边界职责。

5. 排序与汇报

按“预计净收益、证据强度、变更风险、验证成本”综合排序，不按预计删除行数单独排序。使用 [报告模板](references/report-template.md) 输出：

1. 每个仓库的范围、深度、覆盖与未检查区域。
2. 已确认发现，逐项给出标签、位置、证据、替代方案、影响、风险和验证方式。
3. 待验证候选及缺失证据。
4. 多仓共同模式；不得把跨仓协议实现或独立部署需求误判为重复。
5. 有可靠依据时给出可删除代码与依赖的区间估算并说明口径；无法可靠量化时使用定性收益，不得为填充模板虚构数字。

6. 交付与可选落盘

扫描报告与 Skill 分发包是两类产物，不得写入 Skill 的安装目录或源码目录。

• 默认：在最终回复中直接输出报告，不创建文件；报告较长时仍需先给出结论、覆盖状态和最高优先级发现。
• 用户明确要求文件，或宿主提供专用产物机制且当前请求已授权创建产物时，才允许落盘。未指定持久位置时，在系统临时目录下创建本次任务专用目录，不得复用宽泛共享目录或覆盖已有文件。
• 单仓文件使用 /-overengineering-audit.md；多仓时每仓一份并增加 summary.md，名称冲突时加入路径摘要或唯一后缀。
• 用户明确要求持久化到仓库时：先读取仓库文档约定；目标位置不明确且会产生未跟踪文件时先澄清，再写入约定目录。不得自行修改 .gitignore。
• 已落盘时，最终回复仍需给出摘要和绝对路径；临时报告可能被系统清理，必须提示如何复制到持久位置。宿主不能写文件时改为回复内交付并明确标注“未落盘”，不能虚构路径。

完成标准

• 每个正式发现至少提供一个可定位源码位置，并说明消费者与测试核验结果。
• 明确区分事实、推断、候选和未验证假设；不得用搜索无结果证明代码绝对无用。
• 局部或抽样检查不得外推为整仓结论，多仓结果不得相互替代证据。
• 报告默认不实施修复；只有用户另行批准具体方案后才能修改代码。
• 报告已在回复中交付；若声明落盘，则文件已实际写入所述位置。不得把 Skill 安装包路径当作扫描报告路径。
• 没有足够收益或证据时直接说明仓库当前未发现值得实施的精简项。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: betterlmy
• Source: betterlmy/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.