code-humanizer

humanizer， 但面向代码——一个清除编码 agent 所留结构性 slop 的 agent skill。在 GitHub 上查看

code-humanizer —— humanizer，但面向代码

概览

文本版的 humanizer 编目的是 AI 写作的 tell——破折号、「这不只是 X，而是 Y」、三段式排比。code-humanizer 编目的则是 AI 编码的 tell：编码 agent 为了「测试通过」、 而非「代码库保持健康」所留下的结构性技术债。

它是一个单文件 Markdown 的 agent skill（SKILL.md）——无构建步骤、无依赖。 默认模式是 扫描 → 报告（一张发现表：模式编号、严重度、证据、建议修复、行为风险）； 修复模式仅在你批准后运行，每次提交只处理一类模式，每一步后测试全绿。

模式目录

5 个层级、16 种带编号的 AI 编码 tell——每种都在 skill 里配有检测信号与前后对比示例。每条发现都会给一个 0–4 的严重度。

Tier 1 —— 重复与造轮子

  • 1. 重新实现已有的 helper （招牌 tell）——新写的私有函数其实在 utils / 兄弟模块里早已存在；agent 从 prompt 往外写，而非从仓库往里写
  • 2. _v2 / _new / _impl 克隆——foo 和 foo_v2 并存，出现两个真相来源
  • 3. 重造标准库 / 已装依赖——手写 groupby、用 JSON 做深拷贝、手动解析 URL

Tier 2 —— 投机性架构

  • 4. 单实现的抽象——只有一个实现、一处调用的 ABC / 注册表 / 「可插拔后端」
  • 5. 「留着以后用」的死代码——没有调用点的 helper；docstring 里满是 灵活、可扩展、无缝
  • 6. 什么都没加的 wrapper——函数体只是一次同参调用
  • 7. 为局部场景铺开的 config / API——只在一处被读取的全局开关或公共参数

Tier 3 —— 防御式 slop

  • 8. 粗放地吞异常——except Exception: return "" 把可见的崩溃变成不可见的数据损坏
  • 9. 无根据的 try-import fallback——try: import ujson except ImportError: import json，却没有基准测试、没有 extras、没有 fallback 测试
  • 10. 属性试探链——hasattr/getattr/isinstance 层层堆叠，接受「dict 或 object 或可能 None」
  • 11. 偏执的重复校验——对刚构造出来的值再写 if x is not None

Tier 4 —— 噪声

  • 12. 复述式注释——注释在重复下一行代码（# Join the rows with newlines）
  • 13. 模板式 docstring——把函数名加空格当说明；robust、comprehensive、seamless
  • 14. 死 import、未用变量、横幅注释——删剩的残留；# ===== SECTION =====；散落的调试 print

Tier 5 —— 测试 slop （默认仅报告）

  • 15. 断言 mock 本身的测试——所有协作者都被 mock，测试永远不会因真实原因失败
  • 16. 平凡或重复的断言——断言字面量；同一个 case 换三个名字重测

为什么不只是一份模式清单

现代 agent 在被指到某个文件时，其实认得出大多数 slop。它们缺的是纪律。在基线测试里，一个没带这个 skill 的 agent 把 slop 文件清理得很漂亮——却顺手悄悄改了一个对外的错误类型（把 AttributeError 换成了「更好看的」ValueError）， 而且是在一次无法 review 的巨型改动里、在跑测试之前就改了。所以这个 skill 的内核是目录背后的三条铁律：

  1. 严格保持行为——包括错误类型与时序。潜在 bug 只报告，绝不悄悄「改好」。
  2. 无测试 → 不改。测试套件是「保义」的 oracle；没有 oracle 就进入仅报告模式。
  3. 每次提交只处理一类模式，每步后跑测试，有行为风险的改动隔离在 [BEHAVIOR] 标记的提交里。

外加一道误报防护：严重度 1 =「存在但合理」（有据可依的 fallback、信任边界处的防御代码、 插件注册表、迁移期的 _v2）一律豁免。目标是让仓库更健康，而不是「战果计数」。

实战运行

首次实战：一个私有 ML 研究仓库——1.34 万行 Python（21 个模块的包 + 36 个实验脚本 + 20 个测试文件）， 主要由编码 agent 在人工 review 下写成。扫描模式、零改动，git status 前后都干净。

24 条发现，画像很鲜明。防御式 slop（粗放 except、try-import fallback、试探链、复述式注释）：零。测试 slop：20 个测试文件里全为零。技术债几乎全是 Tier-1 重复（11 条发现、40+ 处粘贴），而且这些副本已经开始咬人：一个 provenance helper 被粘进 22 个运行脚本中的 20 个、 且已经漂移（3 个副本多了个环境变量 fallback，另外 17 个没有）；一个实验类被复制成「learned」变体， 其度量方法悄悄分叉。4 条被判为合理而豁免；36 个脚本中的 8 个、21 个模块中的 6 个完全干净——并被如实报告为干净。

结论正好印证了这个 skill 的前提：在 review 下工作的 agent 不会吞异常——它们会重写已经存在的东西。 真正要紧的那一层，是结合仓库上下文的重复检测。

安装与使用

把这个目录拷贝（或 clone）到你的 agent skills 目录：

git clone https://github.com/LeonardNJU/code-humanizer ~/.claude/skills/code-humanizer

任何读取 SKILL.md agent skill 的 harness 用法都一样——单个 Markdown 文件，无构建、无依赖。然后直接说：

> use code-humanizer to scan this PR
> deslop pkg/report.py — you have my approval to fix
> this repo was vibe-coded, humanize it (report first)

适用范围

  • 示例是 Python；模式与工作流与语言无关（信号部分会提到 Python 惯用法，按需迁移）。
  • 它清除的是结构性技术债，而非格式化偏好——那是 linter 的活。
  • 需要大量判断的债（根因修复 vs 绕过）只报告，不自动改。

介绍帖： linux.do · NJU-AIA 论坛

← 返回项目列表