接手过一个遗留了四五年的老仓库之后你会对“代码卫生”这四个字产生一种生理性的敬畏。功能还能跑但一次依赖升级能炸出十几个问题改一个方法要顺着三层继承去找引用目录里散落着不知道哪个版本的缓存和临时文件——这时候你真正需要的不是重写业务的勇气而是一套可靠的清扫流程。我最近把这个流程固化成了一个叫 Hygiene-sweep 的 skill给常用的 AI 编程助手装上一句话就能触发完整的代码卫生六步清扫。这篇文章就来说说这个 skill 到底是怎么设计的、里面的指令怎么写、实际跑起来效果和坑在哪里给同样在和技术债搏斗的朋友一个可复用的参考。先说清楚这里说的 skill 不是指某种编程技能而是最近在各类 AI 编程助手里非常流行的一种结构化指令文件——你把它丢进助手的 skills 目录或者在会话里显式调用AI 就会按照你定义好的步骤、规则、输出格式去执行。它可以是一套代码审查流程也可以是一个 Git 提交规范本质上就是把“人脑里的经验”翻译成“AI 能稳定执行的 SOP”。Hygiene-sweep 做的就是后者把代码卫生检查拆成六步每一步都有明确的检查对象、执行命令、判断标准和输出要求让 AI 不会自由发挥也不会漏掉关键环节。1. 内容整体设计与思路拆解1.1 代码卫生到底在解决什么问题代码卫生这件事听起来不如性能优化或者架构重构那么“高大上”但它的实际影响往往被严重低估。脏乱差的仓库会以非常隐蔽的方式拖慢开发效率构建脚本扫到一堆不该存在的文件导致缓存失效IDE 因为巨大的目录树而变卡新成员花两天时间搞不清哪些文件是真正在用的CI 日志里混着无意义的警告遮蔽了真实错误。最麻烦的是技术债的“复利效应”——一个 TODO 注释三个月后变成五个一个废弃依赖半年后牵扯出三条隐藏的兼容性问题。我见过很多团队想解决这个问题但结果常常是一阵风式的“大扫除”。有人直接在代码里狂删文件删完发现某个动态加载的模块被误杀了有人跑一遍 lint 修复结果把整个项目的格式化风格全改了Pull Request 里多了几百行无关 diff。问题的根源在于代码卫生检查不像构建或者测试那样有一个明确的“完成定义”它需要的是有节奏、有边界的系统性操作——这正是我决定把它写成 skill 的动机。1.2 为什么选“六步清扫”而不是一个通用的清理脚本如果只想清理垃圾文件其实一个git clean加几行 shell 脚本就够了。但真实世界的代码卫生问题远比这个复杂它至少横跨文件系统、源码引用、依赖关系、代码风格、遗留标记、文档一致性六个维度。把这六个维度拆成独立步骤而不是写成一个“一键清理”的脚本是因为每步的风险等级和人工介入程度完全不一样。比如垃圾文件清扫可以用git clean -n无风险预览但死代码删除就必须先确认引用关系依赖体检需要区分“直接依赖”和“传递依赖”盲目删除可能直接打破运行环境而文档同步虽然看起来无关紧要恰恰是团队协作中最容易积累误差的地方。分步设计的另一个好处是可控——每一步都能单独执行、单独输出结果、单独回滚用户不需要为了修一个小问题而跑完全部六步。2. 六步流程的定义与每一步的设计逻辑2.1 从文件系统到代码逻辑的清扫顺序我给 Hygiene-sweep 定义的第一版流程顺序是垃圾文件清扫、死代码识别、依赖关系体检、风格与规范对齐、遗留标记整理、文档与事实同步。这个顺序不是随便排的它遵循一个基本原则——先处理“不会影响逻辑”的层面再处理“可能影响逻辑”的层面最后做格式化和文档收尾。实际操作里垃圾文件清扫通常没有任何副作用适合作为第一步来建立初步的“干净状态”死代码识别和依赖体检都要读取源码结构必须等目录层面清爽之后再做否则扫描结果会被无关文件干扰风格对齐和文档同步虽然经常改动大量文件但属于机械操作放在最后可以避免在功能修改过程中反复处理冲突。这个顺序跑过几次之后你会感觉到每步的输出正好是下一步的输入整个流程是一层层递进的关系。2.2 每一步的边界与判断标准六个步骤最大的设计难点不是“做什么”而是“做到什么程度算完”。我在 skill 里为每一步都设定了明确的完成标准避免 AI 无休止地“清扫”或者把活儿干过头。下面这张表是我在 SKILL.md 里定义的核心判断逻辑步骤检查对象安全阈值处理方式1. 垃圾文件缓存、编译产物、临时文件仅限 Git 未跟踪文件先预览后确认逐项删除2. 死代码未使用的函数、变量、组件排除动态导入和字符串拼接引用生成候选清单人工确认后删3. 依赖体检package 配置文件、依赖树区分直接/传递依赖不自动升级输出废弃与漏洞报告4. 风格对齐代码格式、lint 规则只处理明确规则覆盖的部分修复后输出变更文件数5. 遗留标记TODO/FIXME/HACK/XXX 注释保留有提交记录的注释生成清单并给出处理建议6. 文档同步README、API 注释、版本号不擅自改功能和接口描述标记差异按需更新这里最关键的是“安全阈值”一栏。AI 很容易在执行清扫任务时表现出两种极端要么过于保守扫了半天什么都没改要么过于激进直接rm -rf一把梭。定义好每一步的边界本质上是在告诉 AI“你有权限做什么、没有权限做什么、做到哪一步必须停下来向用户确认。”没有这层约束skill 的执行结果就会变得不可预测。3. SKILL.md 核心细节解析与实操要点3.1 skill 文件的基础结构与 frontmatter 写法如果你打算自己写一个 skill最省事的做法是参照社区通用规范组织文件结构。一个完整的 skill 目录通常长这样hygiene-sweep/ ├── SKILL.md └── assets/ ├── checksheet.md └── report_template.mdSKILL.md 是入口文件frontmatter 里定义了 skill 的名称和触发条件正文是 AI 实际会执行的指令序列。我这里附一个精简版的 frontmatter 示例--- name: hygiene-sweep description: 对当前项目仓库执行一次六步代码卫生清扫包括垃圾文件、死代码、依赖、风格、遗留标记与文档同步检查。 trigger: 代码卫生, 卫生清扫, 清理仓库, hygiene, sweep, 技术债清理 version: 1.2.0 ---trigger字段非常实用它会帮助 AI 在对话中识别用户意图。比如你随手说了一句“这个仓库该打扫一下了”助手如果加载了这份 skill就可能自动激活六步流程不需要你把所有步骤都手工描述一遍。但要注意不同平台的 skill 触发机制不完全一样有的靠语义匹配有的必须在 prompt 里显式调用这个差异我后面在第五部分展开。3.2 六步指令的写法与常见设计陷阱正文部分我建议按步骤编号书写每步都遵循“检查 → 分析 → 处理 → 输出”的结构。以第二步死代码识别为例单纯的“找出没有用到的函数”是不够的——AI 会在有动态引用、条件编译或者模板字符串拼接的情况下产生误判。我在指令里特意加了这样一段约束在识别死代码时必须检查是否存在 import() 动态导入、window 或 globalThis 上的动态属性访问、通过字符串拼接生成的模块路径。只要存在以上任何一种情况直接标记为“需人工确认”不得删除。这种“反向列举例外情况”的写法比正向描述“只删除确认未使用的代码”要有效得多。AI 模型对明确的行为清单比抽象原则执行得更好这也是我写 skill 之后最大的体会。依赖体检这一步也有个容易踩的坑很多开发者会下意识让 AI 直接跑npm audit fix这个命令在某些项目里会一次性升级几十个间接依赖轻则 CI 挂掉重则运行时行为改变。所以在我的 skill 里依赖处理被明确划分为“报告阶段”和“处理阶段”AI 默认只跑npm audit和npm outdated收集信息所有升级操作必须带上--force之外的明确确认流程。我在指令里还会要求它区分 dependencies 和 devDependencies避免把构建期工具链和运行时依赖混为一谈。3.3 提升 AI 执行稳定性的几个指令细节skill 指令写得好不好直接体现在 AI 执行是否稳定。除了最基本的步骤描述我还加入了三个细节来避免自由发挥。第一个是“先预览后执行”的固定句式。无论哪一步涉及文件删除或修改AI 必须先输出将要执行的命令和影响范围用户回复确认之后才能继续。这个过程在交互上多了一轮对话但能挡住绝大部分不可逆操作。第二个是输出格式约束。我在 checksheet.md 里定义了每一步的结果输出模板AI 在完成每个步骤后必须按模板汇报——扫描范围、发现数量、已处理数量、跳过数量、需要人工确认的清单。模板的好处是不需要依赖模型“临时编排”报告结构永远一致。第三个是“停止条件”。很多 AI 在收到清扫任务后会倾向于把所有能改的地方都改了导致最终 diff 巨大。我在指令末尾明确要求整个 skill 执行完毕后AI 不得主动进行额外的代码重构、逻辑调整或性能优化。如果你需要这些操作请另行描述这样能保住清扫动作的纯粹性。4. 实操过程从触发到出报告的完整流程4.1 触发的两种方式与上下文准备在我常用的助手环境里触发 Hygiene-sweep 有两种路径。第一种是直接通过 trigger 关键词触发比如在对话框输入“帮我对当前仓库做一次代码卫生清扫”助手会识别意图并加载 skill第二种是显式指定比如输入“使用 hygiene-sweep skill 检查依赖和死代码”适合只跑部分步骤的场景。不管哪种触发方式我都会在第一步先做一件事让 AI 确认当前工作目录的 Git 状态和仓库规模。Git 状态很重要因为代码卫生清扫最忌讳在半成品代码或者有未提交改动时执行——很容易把别人正在写的东西当垃圾清掉。我会建议 AI 先跑git status --short和git rev-parse --show-toplevel确认仓库路径和当前分支如果有大量未提交改动直接中止流程并提示用户先提交或 stash。4.2 六步的实际执行细节与命令选择以 Node.js 项目为例第一步垃圾文件清扫我通常让 AI 先跑git clean -nxd做预览。这里-x表示也包含被.gitignore忽略的文件-d包含未跟踪的目录-n是 dry-run 模式只展示不删除。预览结果里经常会出现node_modules/.cache、dist、coverage、.eslintcache、各种日志文件。确认之后可以分两种情况执行只清未被忽略的用git clean -nd连忽略文件一起清的用git clean -nxdf但必须在命令里保留一个-f之后的确认步骤。第二步死代码识别推荐组合下面三条命令# 列出所有定义了但未被引用的导出仅作参考动态引用需人工复核 npx depcheck --json depcheck-report.json # 搜索直接 import 语句中疑似未使用的模块 npx eslint . --ext .js,.ts --rule {no-unused-vars: warn, no-unused-modules: warn} --format json # 查找可能的死文件被其他文件引用少于一定次数的可疑文件 find src -name *.ts -o -name *.js | xargs grep -l from \./constants | head -20这里必须提醒的是depcheck的--json输出非常长直接丢给 AI 解析很容易被无关项干扰。更稳健的做法是先让 AI 读一遍depcheck-report.json只把unused和missing字段提取出来再和grep -rn的结果做交叉验证。第三步依赖体检基础命令是npm outdated和npm audit --json如果项目用的是 pnpm 就换成pnpm outdated和pnpm auditYarn 则用yarn outdated和yarn audit。这里要注意npm audit在某些网络环境下可能超时或卡住最好给 AI 一个明确指示如果命令 60 秒内没有返回记录异常并跳过该步骤不要反复重试。第四步风格对齐命令相对简单# 只修复可自动修复的风格问题不改变任何逻辑 npx eslint . --fix但这里有一个很多人忽略的问题eslint --fix可能会修改大量文件包括那些根本没在本次卫生检查范围里的文件。所以我在 skill 里会强制 AI 在跑完--fix后输出git diff --stat和总的变更文件数如果超过 50 个文件会主动提出“是否需要保留这些改动”。第五步遗留标记整理用grep -rnE TODO|FIXME|HACK|XXX扫出所有注释后我会让 AI 按“严重程度”分类而不是一股脑列出来。FIXME通常是已知问题需要优先处理或创建 issueTODO是计划中的任务可以标记负责人HACK一般是最危险的往往隐藏着对代码库正常逻辑的临时绕过。分类之后AI 会生成一张带上下文引用的清单不直接修改任何注释。第六步文档同步这一步的核心是找“文档与事实不一致”的地方。我的做法是让 AI 对比以下信息README 中描述的项目启动方式和 package.json 里实际的scripts字段标注的 Node 版本和.nvmrc或engines字段接口文档中写的返回值结构和实际源码的return。如果发现不一致AI 直接修改 README 是低风险操作但涉及接口文档的行为变更必须单独列出请求确认。4.3 输出报告与整个流程的“完成定义”六步执行完后我会要求 AI 生成一份 Markdown 报告结构固定如下# 代码卫生清扫报告 - 仓库路径与分支 - 执行时间与 Git 变更状态 - 各步骤汇总发现/处理/跳过/待人工确认 ## 需要人工确认的清单 - 文件清单与原因 ## 建议的后续动作 - 按优先级排列报告的重要功能是给整个清扫一个“完成感”。如果 AI 只是闷头改完所有文件而没有任何汇总用户很难判断这次操作到底改变了什么、还有什么风险。我实际用下来的体会是报告本身就是一种质量门禁——只要报告里还存在“待人工确认”项清扫就不算真正完成这一步能拦住很多因过度自信而产生的误操作。5. 常见问题与排查技巧实录5.1 最容易出事的两种情况误删与误判我在真实项目里跑这个 skill 的时候踩过两次大坑每次都和“边界条件”有关。第一次是垃圾文件清扫时git clean -nxdf的-x参数把.env.local这种本地环境配置文件也显示成待删除项。虽然 dotenv 文件通常也会被.gitignore忽略但它包含真实的本地配置删掉之后需要重新拉取或重新生成。从那以后我在 skill 里加了固定规则任何包含.env、config/local、credentials字样的文件一律禁止自动删除无论是否被 Git 跟踪。第二次是死代码识别因为动态导入的存在AI 把两个实际在用的页面组件判定成了死代码。排查之后发现这两个组件的引用方式是通过一个自定义路由配置动态加载的字符串是配置驱动的静态分析工具查不到。后来我把判断规则改成了“强制查看是否存在路由配置文件、是否存在 glob 导入、是否存在require.context之类的动态机制”只要命中其中一条即使用grep搜不到直接 import也不能算死代码。5.2 skill 没有触发或者触发了但指令被执行一半skill 触发失败是我收到反馈中最高频的问题。一部分原因是平台差异某些助手只有在上下文里出现明确的 skill 关键词时才会加载对应文件单纯说“把代码清理一下”它可能只是按通用知识回答而不会走六步流程。解决方法很简单在对话中显式提到“hygiene-sweep”或“代码卫生清扫”必要时手动增加一步“请先读取 SKILL.md”来强制加载。还有一种情况是流程跑了一半就停了——通常在依赖体检环节因为npm audit在网络波动时会长时间静默AI 误以为命令执行完成直接跳到下一步。我的处理方法是让 AI 在每一步启动时确认“上一条命令是否正常退出exit code 0”如果不是 0 就暂停当前步骤并报告错误。这个显式检查看似多余但能避免一堆后续步骤建立在一个失败的基础上。5.3 与团队协作和 CI 集成的边界最后说说这个 skill 不适合做什么。它最适合的是个人在本地仓库执行的卫生整理如果想要引入团队流程我建议只在“生成报告”这个阶段做集成——比如让 AI 把清扫报告输出成 CI 的 artifact 文件或者作为 PR 评论中的检查清单。不要直接让 CI 在流水线里自动执行文件删除、依赖升级、代码格式化这些不可逆操作。代码卫生本质上依赖项目上下文机器可以帮你找到问题但“哪些可以动、哪些必须保留”永远需要人来拍板。我在和几个朋友交流后也发现团队场景下最适合的落地方式是把 Hygiene-sweep 的六步流程拆成一个“扫描命令集”接入 CI所有的-f、--fix、--force都换成“生成报告 移交人工处理”。这样既保留了 skill 的分析能力和标准化报告结构又把风险控制在了可回滚的范围内。另外提醒一句编写 SKILL.md 的时候不要塞太多一次性指令。我把 skill 的版本号从 1.0 改到 1.2最大的变化就是去掉了所有依赖具体项目路径的内容全部改成“读取当前项目内的配置文件动态判断”。写 skill 这件事本身也符合代码卫生的原则——保持通用、减少硬编码、让每一步都清晰可审计。这套 Hygiene-sweep 目前已经陪我处理了三个历史仓库从一个 5 年 old 的 Vue 2 项目到一个 node_modules 比 src 体积大三倍的 Electron 应用每次跑完都能清出几十个无用文件和几页值得跟踪的技术债清单。最让我意外的是它并没有替代我做决策而是逼我把做决策的标准写了下来——哪些文件不许动、哪些警告必须人工复核、哪些操作必须经过确认。所以我也建议你在使用或者仿写这个 skill 的时候多从自己的实际工程习惯出发把那些属于你的“默认不碰”的规则写进指令里。越早把这个标准写清楚后面的清扫就越省心。