最近刷到一个挺有意思的热搜词串：“Hygiene-sweep”“skill”“代码卫生”。点进去看了半天，发现“Hygiene-sweep”其实是一个给AI编程助手用的skill——全名叫“代码卫生六步清扫”，翻译成人话就是：让AI在写完代码之后，自动做一轮体检和清扫，把那些临时调试代码、没用到的变量、不统一的命名、可能泄漏的密钥全都揪出来。

先别急着觉得“这有啥稀罕的”，这个skill踩中的痛点恰恰是这两年AI编程普及后大家最头疼的问题：AI写代码的确快，但也确实会留下各种“现场痕迹”。你让它一口气写出一个功能，它顺手就会给你埋几个console.log、保留几段注释掉的旧代码、塞进去一个只有测试环境才有的写死配置。这些在代码review里往往是最耗时间、也最容易漏掉的环节。有了Hygiene-sweep这种skill，相当于在你和AI之间加了一道“强制保洁流程”，让产出物不再是一坨能跑就行的代码，而是一份可以直接进review的干净交付物。

这篇文章我就从“这个skill到底解决了什么问题”讲起，把六步清扫的每一步设计逻辑拆开，再教你怎么自己搭一个同款skill、怎么配自动化脚本、实测效果如何，最后把我在使用中踩过的坑和排查办法整理成一份速查表。如果你也在用各种AI编程助手，或者正在琢磨“skill到底怎么判断好不好用”，这篇应该能给你一个比较完整的参考。

1. 这个skill到底在解决什么问题

1.1 “skill”概念速通：它本质上是一份给AI的“岗位说明书”

在展开Hygiene-sweep之前，先把“skill”这个热度飙升的概念讲清楚。最近你肯定刷到过“skill编码193”“豆包怎么使用skill”“codex skill”这类热搜词，有些还带编号、带版本号，搞得跟手机系统更新一样。其实往简单了说，skill就是一套能被AI Agent加载的“能力包”：它通常由一个指令文件（最常见的叫SKILL.md）外加若干辅助脚本组成，用来告诉AI“你面对什么场景、要按什么流程、调什么工具、输出什么格式”。

我之前在博客里打过比方：skill之于AI，就像菜谱之于厨师。没有菜谱的厨师全靠临场发挥，有菜谱的厨师知道油温几成、下锅顺序、什么火候起锅。AI也一样，你不给它skill，它只能靠内置的通用能力“自由发挥”；你给它一份写好的skill，它就能按你的规矩干活。Hygiene-sweep就是这样一个“规矩包”，它专门管“代码写完之后的清理流程”。

另一个容易被忽略的点是，skill和普通prompt最大的区别在于“可复用、可分发”。你可以把一份调教好的skill文件直接分享给同事，或者发布到社区，别人一加载就获得了你的经验和流程。所以在GitHub上搜一下，已经能看到大量这种命名格式的项目——“某某.skill”“某某-sweep.skill”，本质就是一群有经验的开发者在把自己的工作SOP封装成AI能执行的规范。

1.2 代码卫生的痛点：AI写代码是真会“留垃圾”

我自己用了快两年的AI编程工具，从最早的补全插件用到现在的Agent模式，最深的一个感受是：AI写代码就像一个手脚麻利但不太讲究的实习生。它写功能的时候脑子很清楚，但不太会管“事后卫生”，具体病征有几个：一是调试残留，比如console.log、print语句、打断点用的sleep，代码合并时经常漏删；二是死代码，AI为了保证改动不破坏原有逻辑，经常把旧实现注释掉、留一整块“备用”，结果一留就是几个版本；三是不一致性，同一种含义的变量，前面叫userInfo，后面叫user_detail，AI在不同上下文中会写出两套风格；四是重复造轮子，AI有时候会无视项目已有的工具函数，重新实现一遍。

这些问题单次出现看着不大，堆在一起就是一场灾难。代码review的时候，资深工程师花在“删垃圾、改命名、调结构”上的时间，往往比看业务逻辑本身还多。更闹心的是那些硬编码的敏感信息，比如API Key直接写在配置里、测试环境的数据库地址混进生产代码，这种AI“顺手写出来”的东西一旦漏进仓库，出事的级别就不只是代码质量了。

Hygiene-sweep就是冲着这些问题设计的。它不帮你写新功能，只负责“打扫战场”：把AI或你自己留下的脏东西找出来、分类、给出处理建议。我挺喜欢这个定位——它没有想着让AI变得更聪明，而是先让AI变得更“整洁”，这恰恰是当前阶段最实用的一件事。

1.3 Hygiene-sweep的设计定位：让清洁流程可执行化

第一次看到“六步清扫”这个名字的时候，我第一反应是：是不是有点“为了凑数强行分六步”？等我仔细分析完它的步骤划分，发现每一步对应一类确实需要独立处理的卫生问题，六步合起来恰好覆盖了从“表面垃圾”到“深层隐患”的全过程。这个设计思路其实很值得借鉴——做任何检查类流程，第一步不是列检查项，而是先把检查维度分层。

Hygiene-sweep的六步大致可以分成三个层次：第一层是“看得见的脏东西”，比如残留代码、调试语句；第二层是“不脏但让人难受”的问题，比如命名不一致、结构混乱、依赖膨胀；第三层是“平时看不见但会咬人”的问题，比如硬编码密钥、异常被吞掉、日志缺失。这种分层逻辑很重要，因为如果只停留在第一层，扫完表面之后代码看起来干净了，实际上的深层隐患一个没解决；如果一上来就查第三层，又容易因为打击面太广导致AI误报一堆。

实际用下来，我觉得它最好的地方是“把标准定清楚了”。以往你说“帮我把代码整理干净”，AI的理解大概率只是格式化一下代码、删删注释，但Hygiene-sweep会把“干净”拆成六十多个具体的检查点，比如“是否存在无被引用的import”“是否存在重复的异常捕获块”“是否存在文件路径中带有个人用户名”等等。当检查项足够具体，AI的执行稳定性就会大幅提升，这也是为什么这个skill比一句随口指令好用得多的原因。

2. 六步清扫是哪六步：每个环节的设计逻辑

2.1 清扫前先定范围：让AI别“扫过头”

真正开始拆六步之前，我得先提一个很多skill没做好、但Hygiene-sweep做得不错的地方：它会在清扫前先明确“清扫边界”。什么意思呢？就是它会让AI先回答几个问题：当前检查的项目是什么语言、有没有既定的代码规范文件（比如.editorconfig、.eslintrc、pylintrc）、是整体清扫还是只清扫当前改动过的文件。搞清楚这些之后，AI才会开始动手。

这个“先定边界”太重要了，因为代码卫生清扫最大的风险就是“越扫越乱”。举个例子，你本来只想让AI检查一下某个模块，结果它把整个项目的命名风格都改了，diff动辄上千行，review根本没法做。Hygiene-sweep在开头就约束了AI：没有明确指令时，默认只在“当前会话涉及的文件范围”内清扫，绝不允许跨文件大范围重构。这相当于给清扫车装上了护栏，让它只在指定车道作业。

还有个细节是它会要求AI先读项目的“现有规范文件”。很多AI助手不看项目里的lint配置就直接按自己的偏好改代码，结果代码风格变得更加混乱。Hygiene-sweep把这个动作前置，让“按项目既有规范清扫”成为默认规则，而不是可选项。这一点看着不起眼，但恰恰决定了清扫结果是“贴合项目的整洁”还是“AI自说自话的整洁”。

2.2 清扫第一、二步：残骸清除与结构与命名修整

第一步是“残骸清除”，这是最直观、也最解压的一步。目标是找出四类垃圾：临时调试语句（console.log、print、debugger、断点）、被注释掉的旧代码块、无用的TODO/FIXME标签、以及没有任何引用的变量或函数。AI在这步会逐个文件扫，把所有可疑点列成一个清单，标注文件路径、行号、垃圾类型、建议动作（删除/保留/转成issue）。

这里有个很关键的执行细节：AI不能“一声不吭就删”，而是要把结果呈现出来，由你确认后再动。注意，这不是AI能力不够，而是清洁类操作必须如此。调试语句好判断，但注释掉的旧代码偶尔会有人还想看；TODO早就失效还是今天刚加的，只有写代码的人知道。所以Hygiene-sweep在这一步的输出会是表格化的“垃圾清单”，而不是直接改代码。

第二步是“结构与命名修整”。这一步重点查三件事：命名是否一致、职责是否内聚、层级是否合理。AI会检查同一个术语是不是用了两种写法（比如getUserById和get_user_by_id混用）、一个函数是不是塞进了太多无关逻辑、文件夹命名是不是大小写混乱、同一层的代构模块是不是有的叫service有的叫utils。

命名问题看着小，但在长期维护的项目里影响极大。我见过一个老项目里光是与用户相关的类就有五种叫法，新人每次上手都要先猜一下“这个和那个是不是一回事”。Hygiene-sweep会让AI做一张“名称对照表”，把同一语义不同写法的标识符全部列出来，然后根据项目主流风格统一。执行时同样只做建议，AI会把改动方案列给你，你确认一次，它再批量替换。小心驶得万年船。

2.3 清扫第三、四步：依赖与资源瘦身，边界与容错加固

第三步是“依赖与资源瘦身”。AI会查三样东西：有没有import了但没被引用的包、有没有重复实现（项目里已经有工具函数了但当前文件又写了一份）、有没有明显体积过大或不必要的资源文件引用。这一步对Python和JavaScript项目特别有效，因为动态语言里没有用到的import往往不会在编译期报错，只能靠静态扫描逐一排查。

不过我把话放在前头：这一步AI的自动删改风险最高。原因很简单，“未被引用”有时候是相对的，可能是动态导入、反射调用，或者被模板字符串间接使用。所以Hygiene-sweep在处理这一步时会把“判定为未引用的项目”按置信度分两级：高置信度直接提示可删，低置信度只提示“请人工确认”。这块设计我觉得值得所有skill学习——AI的判断只作为线索，最终决策权始终留在人手里。

第四步是“边界与容错加固”，到这一步就脱离“表面清扫”了，开始碰代码的健壮性。AI会重点查空指针/空值处理、异常捕获是否“吞异常”、魔法数字是否该抽成常量、有没有明显缺失的默认分支（比如switch里没有default、if..else缺少兜底）、外部接口调用有没有做超时处理。

你可能觉得这块已经超出“卫生”的范围了，但仔细想，代码卫生本来就不只是“看着舒服”，还包括“不出暗病”。一个方法取用户信息时不判断None就直接.get("name")，这种写法在当前逻辑下跑得好好的，换一个数据源就当场崩。Hygiene-sweep把这类问题纳入清扫范围，等于让AI在提交前先帮你叠了一层防御，这个思路我很赞同。

2.4 清扫第五、六步：敏感信息排查与可观测性体检

第五步我称之为“灵魂一步”：敏感信息排查。AI会扫代码、配置文件、日志输出语句中是否存在硬编码的密钥、Token、密码、内网地址、个人路径（比如“C:\Users\lisi”这种带用户名的路径）、以及测试数据残留。这步我强烈建议每个团队都纳入日常代码审查流程，社会工程攻击里很大一部分突破口就是开发者不小心把内部地址或密钥推到仓库里。

Hygiene-sweep做这一步的方式不是简单的关键字扫描，而是分级检查：高敏信息（AK/SK、密码、私钥）直接报“必须清理”，中敏信息（内网域名、IP）报“建议脱敏”，低敏信息（个人路径、机器名）报“提示处理”。这种分级带来的直接好处是误报可控，不会因为扫出一个不痛不痒的机器名就整体高亮成红色警报。

第六步是“可观测性体检”，很多人一开始会觉得这步有点凑数，但实际操作后我发现它其实是六步里最具“预防价值”的一步。AI会检查：新写的核心逻辑有没有打关键日志、异常分支里有没有记录上下文、一些耗时操作有没有性能埋点、对外暴露的接口/函数有没有文档注释。如果这些都没有，这段新代码上线之后会变成“黑盒”，出了问题只能靠猜。

这步最妙的地方在于它把“可观测性”变成了一项可检查的卫生指标，而不是一种模糊的工程素养。AI会逐一给关键路径打分，比如一个处理订单的函数如果只有入口日志没有出口日志、异常分支也没有打印参数，就会被标成“可观测性不足”，建议补全。用过一段时间之后，你会发现被Hygiene-sweep扫过的代码在生产环境里“好查问题”很多，排查故障的时间明显缩短。

3. 自己动手搭建一个Hygiene-sweep同款skill

3.1 skill文件的基本骨架：SKILL.md的结构

如果你想在某个AI编码助手里使用Hygiene-sweep，最简单的办法是直接拉一份现成的文件放到技能目录；但如果找不到合心意的版本，或者你想做一个适合自己团队风格的，自己搭一个也很简单。搭一个skill，首先得明白SKILL.md这套文件的骨架长什么样。

skill的核心是一份Markdown文件，文件名无所谓，系统识别主要靠文件开头的YAML frontmatter和正文规范。基本结构如下：

--- name: hygiene-sweep description: 对代码项目执行六步卫生清扫，包括残骸清除、命名修整、依赖瘦身、边界加固、敏感信息排查和可观测性体检。仅用于检查与建议，不做未确认的大范围修改。 --- # Hygiene-sweep ## 适用场景 ... ## 清扫边界 ... ## 工作流程 ...

frontmatter里name是技能名称，description是“什么场景该调用这个技能”的描述，这个字段非常重要，因为Agent会通过它来判断“当前该不该加载这个skill”。description写得越具体，命中的准确率越高。你如果写“整理代码”，Agent反而容易在不需要的时候加载；如果写“仅用于提交代码前的卫生清扫”，匹配场景就清晰很多。

正文部分就是核心指令区。我从自己的使用经验里总结了一条：指令文件里最重要的不是“告诉AI怎么做”，而是“定义什么不能做”。所以我的SKILL.md里最醒目的是“红线规则”，比如“未确认不得删除代码”“不得改动与清扫无关的文件”“不得移动文件路径”，这些约束比操作步骤更重要。没有红线的skill，执行起来你是要担惊受怕的。

3.2 六步清扫的指令要怎么描述：从“目的”到“验收标准”

写指令的时候，每一类清扫动作要给AI四个要素：检查目标、检查方法、输出格式、验收标准。我用第一步“残骸清除”举例。检查目标要写清楚扫什么——“查找console.log、print、debugger、断点语句、被注释的旧代码块、未被引用的变量和函数”，检查方法要给出具体的判别规则——“注释代码块是指连续超过5行的注释内容且被大段包裹”，输出格式则是“按文件路径列出清单表格”。

关键点是验收标准。比如残骸清除的验收标准是“清除后项目中不存在任何调试输出语句，所有被注释的代码块要么删除要么新增说明性注释”。当验收标准写清楚了，AI才知道干完活之后要怎么自查，而不是扫描一轮就算交差了。我在实际测试中发现，加了验收标准之后，skill的完成度肉眼可见地提升，因为AI会把“确认结果”也当成流程的一部分。

其余五步的描述方式类似，我就不一一贴代码了。但有个通用技巧值得分享：六步的顺序是固定的，AI必须按顺序执行并输出每一步的清扫报告，最后汇总一份总报告。这种“强制分步输出”能有效避免AI把不同层面的问题混在一起糊弄你。看到某一步的输出为空，你也能快速判断出“这一步没有发现问题”，而不是AI偷懒跳过了。

3.3 让清扫自动化：脚本辅助的关键设计

文本指令之外，一个专业的skill通常还会带一个scripts目录，放一些确定性脚本来做文本指令做不到的精确扫描。我这么说可能有点抽象，换个说法你就懂了：AI看代码是“读”出来的，会有理解误差；脚本扫代码是“逐字匹配”出来的，不会漏，也不会错，但缺少语义理解。所以好的skill应该“脚本先做粗筛，AI再做判断”。

比如你可以给Hygiene-sweep配一个shell脚本，用正则快速扫两种确定性垃圾：调试语句和硬编码密钥格式。调试语句的匹配规则很好写，以Python项目为例：

grep -nE "(print\(|console\.log|debugger|pdb\.set_trace)" --include="*.py" -r src/

关键格式也有现成模式可循，比如AK开头特征、私钥的头部标记等。脚本把匹配结果输出成JSON，AI读完JSON再结合上下文判断哪些是误报、哪些真的要清理。这个组合的好处很实在：确定性扫描交给脚本，100%尽责；语义判断交给AI，智能又灵活。我试过完全靠AI扫，会有漏网之鱼；完全靠脚本，误报多到没法看。两者结合起来才是正解。

脚本部分用Python写会比Shell更舒服，因为可以输出结构化数据。大致思路是先定义一个“检查规则列表”，每条规则包含名称、匹配模式、严重级别、建议动作，然后脚本递归扫描代码目录，把命中的结果按文件、行号、内容片段写入JSON文件。AI在执行清扫时先运行脚本拿到JSON，再针对每条记录给出“确认删除/确认保留/需人工判断”的最终决定。

3.4 安装与调用的完整流程

搭建好SKILL.md和脚本之后，把整个目录放到AI编码助手的技能目录下即可。不同的工具路径不一样，以常见的方式来看，大部分AI编程工具都是识别一个固定目录下的技能文件夹，比如“~/.your-tool/skills/my-hygiene-sweep/”，目录里放SKILL.md和scripts文件夹就算完成安装。装好之后重启工具，Agent就能识别到它。

调用方式有两种：一种是显式指定，直接在对话里说“执行hygiene-sweep，清扫当前变更的代码”；另一种是自动匹配，当你输入“帮我把代码清理一下”“检查一下提交前代码”这类话术时，Agent根据description字段自动加载这个skill。从实际体验来看，显式调用更适合我们这种有分步要求的人，自动匹配则更适合给团队里的其他人用，不用他们记什么特殊指令。

第一次运行的时候不建议直接全流程跑，我的做法是先只执行前两步（残骸清除和命名修整），观察AI的输出风格和准确率，确认没问题之后再放开到六步全跑。reason很简单：AI技能执行有一个“信任建立期”，前几步跑得是否符合预期，决定了后面高风险的删除操作能不能放心交出去。

4. 实测记录：把一个“脏乱差”项目扫干净是什么体验

4.1 测试样板：我挑了一个有“年代感”的小项目

为了验证这个skill的实际效果，我特意翻出一个几个月前用AI辅助写的小工具，不算大，大概十几个Python文件，当时写得急，属于典型的“能跑就行”。我自己都不敢细看那种。中间还经历过两三轮需求变更，旧逻辑被注释了好几大段，调试输出估计连成了一条河。拿这个项目测试Hygiene-sweep，正好能检验“清扫能力”，而不是只在干净的代码上装样子。

测试之前我先蹲了个大概数：仓库里console级别的调试输出有二十多处，大段被注释的旧代码至少有五六块，有个模块还出现了两种命名风格混用。当时这些脏东西我都是知道的，只是一直没动力去清。让AI清扫的最大好处就是——终于不用自己面对这摊旧账了。

4.2 实际清扫结果：每一步都有收获也有意外

跑完六步之后，结果分几张表出来。先说意料之中的收获：残骸清除那步非常利落，二十多处调试输出全列出来了，其中大部分是正确的删除对象；被注释的旧代码里，AI准确识别出哪些是被新逻辑替代了的，可以放心删除，哪些是备用的降级方案，建议保留并加一行说明注释。命名修整那步有点意思，它给了我一张“同义词对照表”，把user_name、username、name三兄弟全列出来让我选一个标准写法。

依赖瘦身这步则给了我一个惊喜，它发现了我一个工具脚本里import了一个整个都没用到的库，累计能砍掉好几千行的依赖树，这个我自己都没注意到。边界加固那步才是真正的“意外现场”，AI指出了我某个函数对用户输入完全没有做类型校验，如果有人传了个None进来会在运行中间才炸，排查起来费劲得很。我把这段改了之后，整个模块的健壮性确实上了一个台阶。

切回敏感信息排查的结果，我倒吸一口凉气：配置样例文件里真有一个测试环境的密码，虽然不是生产环境，但按照安全规范这种凭据就不该出现在仓库里。更吓人的是日志代码里有一行会把完整的请求对象打出来，一下没注意就会把不该打印的字段也带出来。这份清扫报告发出来之后，我感觉这份代码才终于“敢见人”了。

4.3 执行效率评估与调优建议

整轮跑下来的耗时大概是三四分钟，比我自己手动review快多了。不过在使用中也发现了一些可以调优的细节。第一个问题是，AI有时候会把“建议”和“发现”混在一起，比如某个函数命名不符它列在了“问题”里，但读代码的人未必觉得这是问题。我调优的方式是在输出模板里增加一个“严重程度”字段，让“必须改”“建议改”“可选改”三个级别分开，这样review起来轻重缓急一目了然。

第二个问题是，扫描范围如果设置成“整个项目”，AI会花费大量时间去扫那些永远不会被改动的第三方依赖目录。解决方式很简单，在SKILL.md里显式声明“跳过标准外部依赖目录（如node_modules、vendor、venv、dist、build）”，AI的执行效率几乎翻倍。第三个问题是关于“清扫是否要把格式化也纳入”，实测发现格式化和卫生扫分开做效果更好，混在一起会增大diff量，review体验反而更差。

5. 常见问题与排查技巧实录

5.1 我实际踩过的坑和应对方案

第一个坑是“AI把误删当成了输出风格”。我在早期测试时遇到过几次AI直接把我注释掉的代码整段删除的情况，虽然它把删除动作写进了报告，但我没来得及确认它就已经执行了，而且没有备份。后来我在红线上专门加了一条：“任何删除操作必须先输出待删内容，并等待用户明确确认”，同时让脚本在扫描前给整个目录生成一份git diff快照，出意外可随时回滚。改了之后再也没出过岔子。

第二个坑是“关键词匹配的误报”。脚本扫密钥格式时，经常把公众号appid、地图SDK的key都误报成“硬编码密钥”，跟真实风险混在一起，看多了就麻了。应对办法是给脚本增加“白名单规则”和“上下文判断”，比如扫描到某个值后，AI要看一下它是不是示例值、是不是测试环境专用值，再决定是否上报。这个过滤逻辑加上去之后，误报率下降得非常明显。

第三个坑是“skill加载时机不当”。有个阶段我装了好几个整理类skill，结果问题描述稍微沾点边Agent就会加载它们，有时候我只是问一个数据结构优化建议，它也跑一遍六步清扫，输出一大堆完全无关的检查报告。解决方法是把description改成带排除条件的语句，比如“仅在用户提到提交前检查、代码清理、代码卫生时使用，其余代码讨论场景一律不加载”。description写得精确一些，碰撞率能降一大半。

5.2 排查速查表：常见异常一表看明白

5.3 判断一个skill好不好用的三条经验

最后说一个连我自己都摸索了好一阵才总结出来的判断标准：怎么快速判断一个代码卫生类skill是否值得长期用。第一，先看它有没有“边界定义”。如果一个skill上来就让你扫全库、没有任何文件范围约束，别用，它会给你制造海量diff。真正成熟的skill一定会先问“你是想扫全局还是扫当前改动”，或者预设一个合理边界。

第二，看它对“删除”的态度。一个稳妥的skill不会让AI直接执行删除，而是要求先列清单再确认；凡是上来就“清扫并自动修复”的，用之前一定要掂量掂量。代码清扫这件事，勇气可以有，但回滚机制必须有。

第三，看它的输出是否结构化。好的skill最后输出的是一份带文件路径、行号、严重程度、处理建议的表格，而不是一段“我检查了代码，发现了一些可以优化的地方”这种套话。输出越结构化，说明流程被定义得越清晰，这样的skill在Agent手里才能稳定复现，上限才足够高。

我在实际使用中最大的体会是：Hygiene-sweep这类工具的定位很聪明，它没有试图替代程序员做判断，而是把“必须判断”的点集中呈现出来，让人的注意力落在最该落的地方。写代码这件事，AI替我们省了很多时间，清扫却始终是绕不开的收尾工作。有一个能把这一步也托管出去的skill，等于给日常工作加了一条流水线，边际收益越用越明显。如果你也在密集使用AI编程助手，我建议别光眼馋别人的skill好，自己动手搭一个适合自己项目习惯的卫生清扫工具，这套流程熟练之后，省下的review时间远比想象中多。