Hygiene-sweep这套技能最早是因为我自己受不了一个项目里的脏乱差才动手做的。接手过一个别人留下的仓库函数命名随意到像是在玩猜谜几百行代码里混着五六种风格注释基本靠猜依赖列表里躺着一堆根本不知道干嘛用的包。那天晚上改bug改到凌晨越改越气最后干脆花了两天做了这个专门做“代码卫生清扫”的Agent技能。做完之后自己用了半年又陆续补了几个版本现在把它整理出来分享给同样被代码烂摊子折磨的人。所谓代码卫生就是那些不直接影响功能、但决定项目能不能长期维护的东西文件监听有没有冗余、代码里有没有残留的调试标记、多语言文件标记是否一致、依赖关系是否锁定、注释和文档有没有跟上改动节奏。这些问题单个看都不致命但攒在一起项目就会变得越来越难改直到某一天谁都动不了。如果你用的是支持Agent Skills机制的AI编程工具比如Codex、豆包、DeepSeek Harness这类那这套技能可以直接以文件夹形式导入就算你只是想在人工review时有个检查清单里面的步骤和规则也完全能独立使用。1. 为什么代码会“变脏”一套清扫逻辑背后的观察在具体讲六步清扫之前我想先花点篇幅说说我观察到的“脏代码”是怎么积累出来的。明白这个你才能理解为什么清扫步骤要这样设计而不是简单粗暴地跑一遍格式化工具。1.1 三个人三种风格代码卫生问题的真实来源代码卫生问题不是某个人写代码“不认真”造成的它更像是一个必然结果。我见过太多项目前三个月写得干干净净半年之后就开始乱套。原因基本可以归结为这么几类第一类是多人协作下的风格漂移。每个人对于“怎么命名变量”“怎么组织函数”“怎么写注释”都有自己的习惯。今天A提交一段代码用下划线命名后天B在同一文件里用驼峰命名再过一个星期C来了他两种都接受随手就混着写。代码风格就变成了一个逐渐失控的东西。第二类是时间压力下的妥协。赶进度的时候谁还有心思把临时变量命名成userPreferredLanguage直接一个temp、data、x就完事了。这种代码当时能跑但一个月后连写它的人自己都认不出来。第三类是重构不彻底留下的残骸。比如之前有个功能是用A方案实现的后来改成了B方案但是A方案留下的一些函数、变量、文件没人清理就这么一直躺在那里。它们不会报错但会让后来读代码的人非常困惑这段代码到底还有没有在用1.2 从“看得见”到“看不见”为什么简单格式化不够很多团队应对代码卫生问题的第一反应是上格式化工具比如Prettier、Black、ESLint这类。这些工具当然有用但它们的覆盖范围其实非常有限。格式化工具能解决的是看得见的风格问题缩进对不对、引号统不统一、行长超没超。但代码卫生里更麻烦的是看不见的结构问题调试代码残留、无用的依赖声明、不匹配的多语言标记、缺失或过时的状态说明。这些问题格式化工具根本检测不到因为它们不影响程序运行只影响人类理解。我当时做Hygiene-sweep的核心想法就是能不能让AI Agent像人一样带着“卫生意识”去读代码把那些格式化工具管不到的问题也一并揪出来后来我发现这个思路完全可行因为大模型在理解代码语义、识别代码意图方面有天然优势它们能看懂一段代码到底是“正式逻辑”还是“临时调试”能判断一个依赖到底有没有被真正使用。1.3 Skill的定义与价值给Agent装上领域能力在正式介绍六步清扫之前我得先解释一下什么是“Skill”。如果你用过Claude的Skills、Codex的AGENTS.md机制或者豆包、DeepSeek Harness的自定义技能应该已经有个大概概念。简单来说Skill就是一段结构化的“专业能力包”它让AI Agent在特定场景下不是泛泛地回答而是按照一套成熟的工作流来执行任务。Hygiene-sweep就是一个典型的领域技能包。它把“代码卫生检查”这件事拆解成六个可以独立执行、又可以串成流程的步骤每个步骤都有明确的输入、输出、检查规则和操作标准。Agent加载这个技能之后就不再是机械地回答“这段代码哪里不干净”而是会按照技能规定的方法论一步步完成从扫描、识别、锁定到清理的完整闭环。打个比方普通AI对话模式就像一个什么都会一点但什么都不精的杂工装了Skill的AI就像一个持证上岗的专业清洁员——他知道先干什么后干什么知道每个环节有什么标准也知道遇到特殊情况该怎么处理。这就是Skill机制最大的价值。2. 六步清扫的完整流程从“看一眼”到“彻底干净”现在进入正题Hygiene-sweep的核心是六个步骤我把它设计成一个线性流程监听-识别-标记-锁定-规范-快照。每一步解决一类特定问题六步合起来覆盖代码卫生的主要方面。2.1 第一步监听变更确定清扫范围清扫代码不是把整个仓库翻个底朝天那样成本太高而且容易误伤。正确做法是先监听变更确定清扫范围。这个步骤的原理是代码卫生问题往往集中在最近改动的文件里。一个文件如果半年没动过它内部的卫生状况大概率是稳定的反倒是那些被频繁修改的文件风格漂移和垃圾代码的风险最高。所以第一步的核心工作是列出本次需要检查的文件清单。具体操作上我会让Agent先获取Git的最近提交记录找出最近N次提交中涉及的文件列表。这里的N可以根据项目规模调整建议小型项目取20-30次提交大型项目取最近一周的提交即可。然后去除掉一些不需要检查的目录比如node_modules、vendor、dist、build这些生成目录还有各种锁文件的变更记录。这个步骤还有一个隐藏价值它能让你快速知道项目里哪些文件是“高频修改区”——这些区域就是你代码卫生问题的重灾区也是后续清扫需要重点关注的地方。2.2 第二步识别代码中的异味模式确定了文件清单之后第二步是在这些文件里做气味检测。所谓“代码异味”就是那些暗示设计或实现可能存在问题的代码模式。常见的有这么几类语义模糊的命名变量叫data、temp、thing函数叫doStuff、handleIt完全看不出意图。超长函数一个函数动辄一两百行做的事情太多职责不清晰。重复代码同一段逻辑在不同位置复制粘贴了多份。魔法数字代码里直接出现没有解释的数字比如if (status 3)没人知道3是什么意思。过深嵌套一堆if套if缩进层层叠叠逻辑难以追踪。调试残留console.log、print、断点调试代码没删干净。这一步的关键在于Agent不能只是“发现”这些问题还要给每个问题标注严重等级和位置生成一个结构化的异味清单。我建议分成三个等级等级说明处理优先级严重可能导致误解或后续bug的命名、结构问题必须修复中等影响可读性但不至于引起错误的模式建议修复轻微纯风格偏好不影响理解可选修复这样分级的好处是清理的时候不会眉毛胡子一把抓而是能优先处理那些真正有价值的问题。2.3 第三步清扫标记乱象统一多语言项目中的标记规范这一步是我当时做这个技能时收获最大的一块也是很多开发者容易忽略的领域。现在的项目几乎都是多语言混合的前端用TypeScript后端用Python有些地方还要写Shell脚本、SQL查询、配置文件。不同语言有不同的注释语法、命名风格、文件组织习惯放在一个仓库里就很容易出现标记乱象。最典型的问题有几种一是注释语法混用。比如在Python文件里用了//开头的注释在JavaScript文件里用了#开头虽然大多数情况下代码还是能跑有些解析器宽容但读起来非常别扭而且某些严格的lint工具会直接报错。二是特殊标记不一致。比如TODO和FIXME的用法有些人习惯写TODO: 这里要处理XX有些人写// fixme 之后改大小写不一致、格式不统一后期想全局搜索TODO列表时就会漏掉很多。三是多语言文件之间的引用标记对不上。典型场景是HTML模板里引用的CSS类名、JS模块名和实际定义的文件对不上号——这种问题在重构尤其容易产生。Hygiene-sweep的第三步就是让Agent在第二步识别出的异味清单基础上专门扫描这些标记规范问题统一注释语法格式、统一TODO/FIXME标记风格、检查跨语言引用的一致性和有效性。我给Agent设定的规则很简单项目中80%以上文件使用的风格就是默认风格。比如仓库里大多数Python文件用# TODO: xxx那所有Python文件里的TODO都按这个格式统一大多数JS文件用// FIXME: xxx那JS侧也跟着对齐。2.4 第四步锁定依赖与版本排除“隐性污染源”依赖管理是代码卫生里最容易被忽视、但后果最严重的一块。很多人以为依赖问题就是版本冲突其实远不止如此。常见的依赖卫生问题包括幽灵依赖代码里import了某个包但该包并不在package.json或requirements.txt里。这种情况往往是因为那个包是另一个包传递引入的当时能跑但一旦上游包升级代码立刻崩。孤儿依赖requirements.txt里躺着好几个包但全项目搜索根本找不到引入语句。每个多出来的依赖都是攻击面也是构建时间的浪费。无版本锁定的宽泛声明package.json里写lodash: ^4.0.0这种声明允许安装4.x.x的最新版本。今天是4.17.21明天可能就变成4.18.0到时候构建结果就不确定了。多余的环境隔离文件比如既有requirements.txt又有Pipfile、poetry.lock互相之间不同步谁也不知道该信哪个。第四步的任务是让Agent逐项核对依赖声明文件与实际代码找出幽灵依赖、孤儿依赖、版本宽泛声明和重复的依赖管理文件然后生成一份“依赖洁净度报告”。这一步我建议配合具体的包管理工具命令来操作。比如在Node项目里跑npm ls --depth0看顶层依赖在Python项目里用pip freeze检查实际安装的包再和声明文件比对。2.5 第五步规范化提交信息与文档注释代码卫生不光是代码本身还包括代码的“书面记录”是否清晰。很多人提交代码时git commit -m 更新、git commit -m fix bug这种话写了一大堆回头想通过git blame找到某次改动的原因看到这些commit message完全是一头雾水。同时还有文档注释的问题函数上面的docstring或者JSDoc注释严重过时、和实际参数对不上。这种“说谎的注释”比没有注释更坑人因为它会让你相信一个错误的用法。第五步做两件事检查最近的commit message。我设定了一个简单的规范每条提交信息需要能回答“做了什么”和“为什么做”。理想格式是类型(范围): 简短描述比如fix(auth): 修复token刷新竞态条件。如果发现类似“update”“fix”这种无法传达信息的提交Agent会把它们标记出来并给出建议的改写版本。核对函数/模块文档与实际代码的一致性。重点是看文档里声明的参数数量、类型、返回值和实际函数签名是不是一致。不需要检查每个函数只检查那些公开的、被多处调用的核心接口就行。2.6 第六步生成清扫快照形成可执行的改进报告最后一步不是修复而是报告。这一步的价值在于让整个清扫过程的结果变得可跟踪、可执行、可复盘。Hygiene-sweep的第六步会生成一份结构化的“清扫快照”文件我建议叫hygiene-report.md内容包括本次清扫的范围检查了哪些文件、哪几次提交发现的问题清单按严重程度分组每条带文件位置和具体说明建议的处理方案针对每个问题给出具体改法下次清扫时需要注意的重点区域我把报告分成两个版本一个完整版存到仓库的.hygiene/目录里方便长期追踪一个精简版直接输出到对话窗口让你一眼看到重点。为什么要专门做报告这一步因为我发现如果清扫完直接就改代码很多问题的处理过程会不可追溯——三个月后再看你根本不知道当初为什么要动这几行。有了快照文件整个项目的“卫生史”就是清晰透明的了。3. 实现细节Skill的目录结构与核心脚本前面讲的是设计思路和流程这一节说说具体怎么实现。如果你想把Hygiene-sweep做成一个真正可用的Agent技能需要做三件事设计好目录结构、写好SKILL.md指令文件、准备几个核心工具脚本。3.1 技能包目录结构设计Hygiene-sweep的技能包目录结构我是这样设计的hygiene-sweep/ ├── SKILL.md ├── scripts/ │ ├── scan_git_changes.py │ ├── detect_smells.py │ ├── check_markers.py │ ├── analyze_dependencies.py │ └── generate_report.py ├── rules/ │ ├── naming_conventions.yaml │ ├── marker_formats.yaml │ └── priority_rules.yaml └── templates/ └── hygiene_report_template.md说明一下每个部分的作用SKILL.md技能的核心指令文件Agent加载这个技能时首先读取的就是它。里面规定了整个技能的执行流程、每一步的具体操作、调用的脚本和判定标准。这个文件的质量直接决定技能好不好用。scripts/存放实际执行扫描、检测、分析的Python脚本。采用Python是为了跨平台兼容性主流的Agent运行环境都能跑。rules/存放可配置的规则文件。把规则从代码里抽离出来这样以后想调整命名规范的标准或者新增一类特殊标记的检查规则直接改yaml文件就行不用动Python脚本。templates/存放报告模板保证每次生成的清扫报告格式统一。3.2 SKILL.md的核心内容怎么写SKILL.md的核心是让Agent清楚知道“每一步该怎么做、依据什么标准做”。如果这一步写得含糊Agent执行的自由度就会太大不同环境下表现差异巨大技能就不稳定。我建议SKILL.md至少包含以下块# 技能名称Hygiene-sweep代码卫生六步清扫 ## 技能目标 对指定代码仓库执行一套标准化的代码卫生检查与改良流程 覆盖文件变更监听、代码异味检测、标记统一、依赖锁定、 提交与文档规范化、清扫报告生成六个步骤。 ## 适用范围 - 适用仓库任何基于Git管理的代码仓库 - 适用场景代码Review前检查、重构前摸底、项目交接前清理 - 不适用单文件格式美化请直接用格式化工具 ## 执行流程 ### 步骤1监听变更 - 执行命令python scripts/scan_git_changes.py --commits 20 - 输出结果变更文件清单写入临时文件 ... ## 判定标准 - 命名异味... - 标记统一... - 依赖问题... ## 注意事项 - 所有修改建议输出到报告不直接改动代码除非用户明确要求 - 报告文件统一使用 templates/ 下的模板生成 ...这里有一个很重要的设计决策默认情况下Hygiene-sweep只生成报告不直接改代码。原因有两方面一是自动改代码风险太大万一改坏了反而增加负担二是很多卫生问题比如重构函数结构需要结合业务背景来做决策AI不适合单方面拍板。所以技能默认输出“建议方案”让开发者在review之后手动决策。如果用户明确要求“自动修复”Agent才会按照规则逐项执行修改但我会在报告里保留修改前后的diff记录。3.3 核心脚本从扫描到报告下面挑几个核心脚本的关键实现思路说说。scan_git_changes.py的逻辑不复杂核心就是调用git log和git diffdef get_recent_changed_files(commit_count20, exclude_dirsNone): cmd fgit log -{commit_count} --name-only --prettyformat: result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) files [] for line in result.stdout.splitlines(): line line.strip() if line and not any(line.startswith(d) for d in exclude_dirs): files.append(line) return list(set(files))这里的exclude_dirs非常重要默认排除node_modules、vendor、dist、build、.git等目录。如果不排除扫描器会把几万个无关文件全列进来后续步骤全部白跑。detect_smells.py是核心的逻辑判断模块。它的实现方式是先按扩展名把文件分类然后调用相应的分析逻辑。比如对Python文件用ast模块把代码解析成抽象语法树再遍历语法树找出异味模式对JavaScript/TypeScript文件用正则加启发式规则做初步筛查。def detect_smells_in_python(source): tree ast.parse(source) smells [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): func_len node.end_lineno - node.lineno if func_len 80: smells.append({ type: long_function, name: node.name, line: node.lineno, level: medium, desc: f函数 {node.name} 超过80行建议拆分 }) args [a.arg for a in node.args.args] for arg in args: if arg in (temp, data, x, y, val): smells.append({...}) return smells用ast的好处是能准确识别代码结构不会因为缩进、换行之类的格式差异产生误报。check_markers.py负责标记规范检查。这块我实现了一个简单的“风格投票”机制先扫描所有文件里的TODO/FIXME等标记统计不同格式的出现次数然后把出现次数最多的格式设为标准最后找出所有不符合标准的实例给出统一修改建议。analyze_dependencies.py的实现取决于项目类型。对Node项目我建议让它解析package.json和package-lock.json或yarn.lock然后结合import require语句做交叉比对对Python项目则是解析requirements.txt或pyproject.toml再用pip show或importlib.util.find_spec验证依赖是否真实存在。generate_report.py最简单就是把前面几个脚本的输出汇总按模板生成hygiene-report.md。3.4 规则文件灵活配置是保持通用性的关键我把判定标准抽离到rules目录的yaml文件里这样不同团队可以根据自己的规范灵活调整。举个例子naming_conventions.yaml大概长这样naming: variables: - pattern: ^[a-z][a-zA-Z0-9]*$ message: 变量命名应使用驼峰风格 level: minor - blacklist: [temp, data, tmp, res, result_val] message: 存在语义模糊的命名建议重命名表达具体含义 level: major functions: - pattern: ^[a-z][a-zA-Z0-9]*$ message: 函数命名应使用驼峰风格 level: minor - forbidden: [doStuff, handleIt, processData] message: 存在过于泛化的函数命名建议拆分为具体动作 level: majormarker_formats.yaml则定义各种标记的标准格式markers: todo: - regex: TODO[:]?\\s style: TODO: 描述事项 level: minor fixme: - regex: FIXME[:]?\\s style: FIXME: 描述问题及原因 level: medium hack: - regex: HACK[:]?\\s style: HACK: 描述妥协方案及触发条件 level: medium这些配置文件的好处是团队内部如果用的是BUG:而不是FIXME:直接改yaml就行完全不用碰脚本代码。这也是Skill机制相比硬编码工具的优势所在——专业能力可以像插件一样灵活调参。4. 部署与调用在不同平台上的落地方式编写好技能之后最关键的一步就是部署。不同平台的Skill部署方式差异还挺大的我在实际使用中也踩过不少坑这一节单独拿出来说。4.1 Codex与AGENTS.md类平台的接入方式Codex是OpenAI推出的一款AI编程Agent它支持通过AGENTS.md文件来定义Agent的行为规范。Hygiene-sweep作为一个外部技能在Codex平台上的部署方式比较轻量把技能目录放到一个约定位置比如项目的~/.codex/skills/目录或者.codex/目录下然后在AGENTS.md里添加一行引用指定技能路径即可。关于“skill编码193”这种说法其实是社区里对某些技能编号的指代。不同平台对技能的管理方式不一样有些平台会给每个技能分配一个内部编码ID方便在指令中引用。但核心思路是一致的先注册技能包然后在主指令文件中声明“当前环境已加载Hygiene-sweep技能处理代码检查任务时须调用该技能的执行流程”。在AGENTS.md里的写法类似这样## Skills - hygiene-sweep: 当用户要求进行代码卫生检查、代码质量分析、 清理调试残留、统一代码风格时自动加载并使用 hygiene-sweep 技能 路径~/.codex/skills/hygiene-sweep/这样配置之后每次向Codex发出“帮我清一下这个项目的代码卫生”它就会自动走Hygiene-sweep的六步流程而不是泛泛地回答几句建议。4.2 豆包、DeepSeek Harness等平台的skill部署差异豆包和DeepSeek Harness这类平台的Skill机制也类似但部署路径和配置方式略有差别。豆包的技能市场里有现成的技能可以直接用也支持自定义导入。DeepSeek Harness则更偏本地化部署如果要在内网服务器上使用技能需要注意权限配置问题。有一个常见问题值得单独说一下在某些Harness类工具中技能读取文件时会报setnamedsecurityinfow failed (win32,...)之类的权限错误。这通常是因为在Windows环境下技能进程没有获得目标目录的完整访问权限。解决办法有三个把技能包和项目目录放在同一个层级避免跨用户目录访问。以管理员身份运行Agent进程或者在Windows的安全设置里给目标目录添加当前用户的完全控制权限。检查是否为只读目录必要时在技能执行前先设置chmod或attrib -r命令。如果你是在内网服务器上部署DeepSeek Harness附带的自定义技能我建议额外注意路径问题。服务器上的用户权限管理往往比本地开发机严格得多技能的临时文件写入目录、缓存目录最好都在Agent进程的权限范围内否则会频繁遇到“读取文件报权限”的问题。4.3 调用方式与触发词设计部署好之后调用就很简单了。你可以用自然语言直接触发比如“用Hygiene-sweep帮我检查一下src目录的代码卫生”“跑一遍代码卫生六步清扫”也可以配置简短的触发词比如“清扫代码”“执行卫生检查”把它绑定成快捷指令。实际操作中我更推荐把触发词绑定在具体的代码动作上每次准备commit之前先让Agent跑一遍Hygiene-sweep的快速版只做前四步生成一份简短报告确认没问题后再提交。这样就相当于给代码提交加了一道“卫生门禁”长期坚持下来项目质量会有非常明显的提升。4.4 不同触发方式下的输出形态对比为了让你直观理解不同触发方式的效果我整理了一张对比表触发方式执行内容输出形态适用场景快速模式仅监听异味检测精简报告10条以内重点问题每次commit前标准模式六步全流程完整报告改进建议清单周期性全面检查深度模式六步实际执行修复需确认完整报告修改diff记录重构前清理实际经验是快速模式不要每次commit都用那样会拖慢提交节奏建议每天集中跑一次标准模式周末做一次深度清理节奏刚刚好。5. 实测效果与踩坑记录这套技能的真实表现技能写出来效果到底怎么样最终还是要靠实战说话。我在自己的项目上跑了将近半年积累了不少真实数据和踩坑经验专门分享一下。5.1 一次真实清扫案例从“能跑”到“能维护”拿我自己维护的一个Python后端项目举例。项目大概有2万行代码涉及API接口、数据库操作、业务逻辑和几个异步任务模块。跑了一次完整版Hygiene-sweep结果如下变更监听最近20次提交涉及47个文件排除掉配置文件后实际需要检查的是39个。异味检测发现超长函数11处其中最长的一个函数有187行语义模糊命名23处最典型的是到处都是data和result魔法数字7处重复代码段3组。严重等级占比约三成。标记规范发现TODO有三种格式混用其中有7处用的是TODO - fix this这种非标格式FIXME有2处是全大写、2处是全小写还找到一个Python文件里误用了//注释。依赖分析找出2个孤儿依赖声明了但代码里完全没用到1个幽灵依赖代码里import了但没声明还有3处依赖版本用了宽泛声明而不是锁定精确版本。规范检查最近20次提交中有6条commit message不合格其中3条就是单纯的update或fix。整个检查过程花了大约3分钟主要是Git操作和依赖分析消耗时间生成的报告有40多行。我按着报告一项项清理大约花了两个小时整理项目从此变得清爽很多。最明显的变化是之后再改代码时不再需要反复猜测某个变量的含义了。5.2 踩过的坑识别准确率、误报和边界问题用下来也发现了一些问题这些问题在初期挺让人头疼的分享一下解决思路。第一个坑是异味识别容易出现误报。比如“超长函数”这个判断我一开始设定的是超过50行就该报警结果发现很多业务函数天生就要写那么长硬拆反而破坏逻辑连贯性。后来我调整了规则超过80行报中等严重度超过150行才报严重。还加入了一个豁免机制——如果函数的复杂度和行数都高但整体逻辑是线性的、每一步都清晰那可以标记为“建议关注但非必须处理”。第二个坑是历史遗留代码的“我先记着以后再说”问题。虽然技能能发现所有问题但真正修复时往往要面对一个现实这段脏代码马上要重写了那我还要不要花时间清理它我的答案是报告里照实记录但修复优先级要结合重构计划来调整。Hygiene-sweep的报告里专门有一栏“关联重构计划”把即将被替换的代码单独做标记避免浪费时间。第三个坑是换行符和编码问题。如果你教儿是Windows上开发、在Linux上部署扫描器读文件时可能会遇到\r\n和\n的差异某些编码格式比如GBK也会导致乱码。我后来在脚本里统一做了处理读文件时以二进制方式读取尝试用utf-8解码失败则用latin-1兜底从根源上避免了这类问题。第四个坑是多语言项目里注释识别的边界。比如你想统一所有语言的TODO格式但在Markdown文件里的待办事项列表- [ ]也可能含有TODO字样如果不加区分就会被误判。我在check_markers.py里加了文件类型过滤只有代码类文件.py、.js、.ts、.java等才执行标记规范检查文档类和Markdown类文件直接跳过。5.3 与其他代码分析工具的配合方式Hygiene-sweep和已有的代码分析工具不是替代关系而是互补关系。我推荐的工作流是先用自带工具做静态扫描在Python项目里跑一遍pylint或ruff在JS项目里跑一遍ESLint把所有格式级、表达式级别的问题处理掉。再用Hygiene-sweep查深层次卫生问题重点盯命名语义、依赖健康度、注释一致性、提交规范这些格式化工具管不到的事。最后用SonarQube或CodeClimate做定量指标监控拿到复杂度、重复率、技术债等硬性指标长期追踪项目健康趋势。这样三步合起来的覆盖度是最完整的既有快速的机器硬校验又有语义级别的AI深度检查还有长期的量化跟踪。6. 进阶玩法把Hygiene-sweep改造成团队共用技能目前这套技能更多是个人使用的状态但我一直在想怎么把它变成团队级的基础设施。一个人整洁不算整洁整个团队的代码卫生习惯才是项目长期健康的关键。分享几个我验证过的进阶方向你可以根据自己的团队情况选择。6.1 团队规范沉淀技能库与公共配置每个团队都有自己的编码规范硬编码在技能里当然不行。我的建议是创建一个团队级的技能配置中心把rules/目录下的yaml统一托管到内部的Git仓库里所有成员的Agent启动时自动拉取最新配置。这样做的收益很明显规范不是写在文档里“请自觉遵守”而是嵌在工具链里“不遵守就会被标出来”。新成员入职之后不需要背规范文档只要习惯让Agent跑一遍清扫自然就知道团队的标准是什么。6.2 与GitHub Actions/CI流水线的集成另一个实用的方向是把Hygiene-sweep接到CI流水线里。可以写一个GitHub Action在每次Pull Request创建或更新时自动执行一遍精简版清扫快速模式把生成的清扫报告附到PR评论里。这样做的最直接好处是把“代码卫生审查”变成自动化流程的一部分而不是靠某个人的自觉。审查者看PR的时候能同时看到功能改动和卫生报告一旦发现新增了调试残留、依赖声明和实际import不符等问题直接就在评论里指出来整个积累过程会干净很多。需要提醒的是CI里跑清扫要注意控制时间。完整版清扫在大型仓库里可能要跑10分钟以上这对CI来说太久了。建议CI里只启用前四步并且只针对PR中变更的文件做增量扫描而不是全仓库扫描。6.3 技能间的协作编排Agent工作流的高级用法最后说一个更进阶的玩法如果你所在平台支持多技能串联比如目前社区里比较火的“Agent技能编排”思路完全可以把Hygiene-sweep和其他技能组合起来形成自动化的工作流。举两个例子“提交前卫生检查”工作流Hygiene-sweep快速模式→ 自动生成commit message建议 → 输出到对话窗口由开发者确认后提交。这个组合既保证了代码卫生又顺便规范了提交信息一举两得。“重构前摸底”工作流Hygiene-sweep深度模式→ 架构分析技能识别模块依赖和耦合度→ 生成重构风险报告。先用卫生技能把表面问题清掉再用架构分析技能做深层评估能得到一份非常完整的重构可行性报告。这些玩法在理论上能用但实际落地时要注意平台对多技能调用顺序和上下文管理的支持程度。有的平台一个会话只能串行执行技能有的支持并行执行要根据平台能力来设计工作流。6.4 技能的可迁移性Hygiene-sweep这套方法论不只适用于代码卫生很多思想可以迁移到其他场景。比如你负责的仓库里有一堆文档、设计稿、配置文件同样可以用“监听变更→识别问题→统一规范→生成快照”的四步逻辑去管理。核心思路是一致的用自动化的方式维持人工容易忽略的秩序让混乱在积累之前就被发现和纠正。以上就是Hygiene-sweep的全部设计思路和实现细节。写这个技能的初衷很朴素我受够了在一个越来越混乱的代码仓库里工作的感觉而我希望你也不用来受这份罪。如果你的项目里也有那种“能跑但谁都不愿意碰它”的代码不妨把这套技能拿过去跑一遍。项目也许不会因为一次清扫就焕然一新但至少你会拿到一份清晰的现状报告——知道问题在哪里就已经解决了一半。