README
¶
hum1izer
CLI на Go: проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы, показывает находки с номерами строк и говорит, что с каждой делать. Русский и английский.
Считается только то, что берётся грепом и арифметикой: 21 хард-бан, 19 категорий маркеров, ритм, номинальность, структура документа, балл чистоты 0-100.
Идея и первоначальные наборы правил - из ilyautov/humanizer-ru (MIT, (c) Ilya Utov), там же корпусное обоснование порогов: AINL-Eval, LLMTrace, M4-ru. Движок здесь свой, правила вынесены в YAML и дополняются.
Установка
Готовый бинарь под macOS, Linux и Windows лежит в
релизах: скачай архив под свою
платформу, распакуй, положи в PATH.
go install github.com/haiodo/hum1izer/cmd/hum1izer@latest # из исходников
make build # локальная сборка
make install # в GOBIN
Одна зависимость - gopkg.in/yaml.v3 для чтения правил, остальное стандартная
библиотека.
Скиллы для агентов
hum1izer install --claude --codex --opencode --hermes --pi
hum1izer install --all # все сразу
hum1izer install --claude --dir . # в проект, а не в домашний каталог
hum1izer install --print # посмотреть SKILL.md, ничего не ставя
make skills # собрать и поставить всем
Формат общий - Agent Skills, различаются только шапка и путь:
| Флаг | Куда |
|---|---|
--claude |
~/.claude/skills/hum1izer/SKILL.md |
--codex |
~/.codex/skills/hum1izer/SKILL.md |
--opencode |
~/.config/opencode/skill/hum1izer/SKILL.md |
--hermes |
~/.hermes/skills/devops/hum1izer/SKILL.md |
--pi |
~/.pi/agent/skills/hum1izer/SKILL.md |
--agents |
~/.agents/skills/hum1izer/SKILL.md |
opencode читает ещё и ~/.claude/skills с ~/.agents/skills, так что ему
хватит и --claude, и --agents - отдельный флаг нужен, только если хочется
держать скилл в его собственном каталоге.
Существующий файл не перезаписывается без --force. Скилл описывает цикл
правки, правила хорошего комментария и список того, что трогать нельзя:
лицензионные шапки, //go:generate, //nolint, eslint-disable, прагмы.
Использование
hum1izer текст.md # отчёт с рекомендациями
hum1izer --lang en post.md # английский набор правил
hum1izer --genre academic статья.md # снять маркеры, законные для регистра
hum1izer --quiet docs/*.md # одна строка на файл
hum1izer --json текст.md # машинный вывод
cat draft.txt | hum1izer - # из stdin
hum1izer --code ./src # комментарии в коде
hum1izer --code . # то же плюс последние 20 коммитов
| Флаг | Что делает |
|---|---|
--genre |
marketing (по умолчанию), academic, legal, fiction, news |
--lang |
набор правил для прозы: ru (по умолчанию) или en |
--format |
text (по умолчанию), jsonl, json, quiet |
--limit N |
сколько блоков отдать, 0 - все. Первыми идут самые грязные |
--json |
то же, что --format json |
--top N |
сколько мягких маркеров показать, 0 - все (по умолчанию 12) |
--quiet |
только итоговая строка на файл |
--rules |
свой файл правил вместо встроенного |
--code |
разбирать аргументы как исходники, а не как прозу |
--commits N |
сколько последних коммитов проверить, 0 - не проверять (20) |
--max-lines N |
комментарий длиннее скольких строк - находка, 0 - не считать (2) |
--skip-tests |
пропускать _test.go, *.test.*, *.spec.* |
--config F |
взять этот файл настроек вместо поиска .hum1izer.yaml |
--no-config |
игнорировать .hum1izer.yaml |
--baseline F |
сверяться со снимком, ругаться только на новое |
--write-baseline |
перезаписать снимок текущими находками |
Код возврата: 0 чисто, 1 найдены хард-баны, 2 ошибка. Годится для
pre-commit и CI.
Что считается
Хард-баны - конструкции из таблицы «Жёсткие запреты»: «в современном мире», «данный», «стоит отметить», «комплексный подход», длинное тире и так далее. Каждая находка идёт с рекомендацией из той же таблицы.
Маркеры - лексические категории каталога: канцелярит, кальки, раздувание значимости, формульные выводы, артефакты чат-бота, мотивационные клише, маркетинговые штампы, эмодзи-декор, подмена символов и ещё десяток. Рекомендация одна на категорию.
Ритм - коэффициент вариации длин предложений. У человека обычно выше 0.45, у генерации ровнее. Плюс тире, многоточия, скобки, вопросы.
Номинальность - плотность отглагольных существительных на 100 слов.
Структура - разброс длин абзацев, доля пунктов списка (listicle-сигнатура), Title Case в заголовках, обрыв текста на полуслове.
У .md, .mdx и .markdown перед разбором гасится разметка: YAML-шапка,
блоки кода, код в строке, импорты MDX, теги HTML и JSX, адреса ссылок, строки
таблиц. Гасится пробелами, поэтому номера строк и позиции находок остаются
верными. Без этого блок кода без единой точки становится одним предложением на
полторы тысячи слов, и ритм не мерится вообще: на посте блога CV падал с 5.04
до 0.82, стоило вырезать код.
Балл - агрегат всего перечисленного, 0-100. Полосы: ≥85 чисто, 60-84
точечная правка, <60 рерайт.
Балл это правила сканера, а не вероятность ИИ и не вердикт об авторстве. Он нужен, чтобы сравнивать «было и стало» на одном и том же тексте.
Плотность маркеров считается на 100 слов, а не штуками: семь маркеров на тысячу слов и семь на сотню - разные вещи, и абсолютный счёт на длинном тексте всегда давал «AI с высокой вероятностью».
Жанры
Без жанра режим строгий, под него откалиброваны пороги оригинала (маркетинг,
блоги). Для научного, юридического, художественного и новостного текста часть
банов - норма регистра, а не признак машины: --genre их снимает.
$ hum1izer --quiet ai-sample.txt
ai-sample.txt 19/100 [рерайт] банов: 14, маркеров: 13
$ hum1izer --genre academic --quiet ai-sample.txt
ai-sample.txt 35/100 [рерайт] банов: 9, маркеров: 5
Комментарии в коде и коммиты
hum1izer --code ./repos/platform
Список файлов в git-репозитории берётся у самого git
(git ls-files --cached --others --exclude-standard), поэтому .gitignore
соблюдается точно, вместе с вложенными и глобальными правилами: собранный код в
lib/ и bundle/ под проверку не попадает. Вне git идёт обычный обход с
пропуском node_modules, vendor, dist и подобного.
Пропускаются также сгенерированные файлы (Code generated ... DO NOT EDIT,
@generated, sourceMappingURL в хвосте) и лицензионные шапки: SPDX в любом
месте, Copyright или Licensed under в первых пяти строках файла.
Разбираются .go, .ts, .tsx, .js, .jsx, .mjs, .cjs, .svelte,
.swift. Go читается через go/parser, остальное - посимвольным сканером,
который знает про строки, шаблоны и литералы регулярок, поэтому // внутри
строки за комментарий не принимается. Границы блока берутся по байтовым
смещениям, а не по строкам: у хвостового комментария x := 1 // счётчик в
raw попадает только сам комментарий, а кодом для проверки пересказа считается
то, что стоит перед ним на той же строке.
Закомментированный код в .go определяется не регуляркой: тело комментария
подставляется в функцию и отдаётся go/parser - разбор прошёл, значит это код.
Так делает go-critic, и разница заметна: на 4159 файлах регулярка давала 168
находок, парсер даёт 13, и почти все настоящие. Для остальных языков штатного
парсера в стандартной библиотеке нет, там осталась доля строк, похожих на код. В .svelte отдельно берутся <script>,
<style> и <!-- -->. Соседние строки склеиваются в один блок: шапка из
десяти // - это один текст, а не десять находок. Сгенерированные файлы
(Code generated ... DO NOT EDIT, @generated), node_modules, vendor,
dist, gen пропускаются.
Язык каждого блока определяется по нему самому: кириллица от 30% - русский
набор, иначе английский. Поверх языкового всегда идёт rules-code.yaml.
Сбор блоков вырос из platform-go/tools/longcomments и
platform/scripts/find-long-comments.{go,mjs}: оттуда взяты разбор Go через
go/parser, посимвольный сканер для TS и склейка соседних комментариев.
Если в аргументе лежит git-репозиторий, туда же попадают последние --commits N
сообщений коммитов: тот же прозаический разбор плюс проверки формы заголовка.
Что проверяется дополнительно к прозаическим правилам:
| Находка | Почему |
|---|---|
| Пересказ кода | // set user name над setUserName() не несёт информации |
| Закомментированный код | история кода живёт в git |
| Пересказ кода | комментарий повторяет имя рядом, в том числе хвостовой |
| Длинный комментарий | длиннее --max-lines строк, по умолчанию 2 |
| Баннер-разделитель | // ========= разделяет файлами, а не линиями |
| TODO без владельца | без имени или ссылки на задачу это вечный TODO |
| Ченджлог в комментарии | «Updated X to Y», «Author:», дата - это git blame |
| Markdown-эссе | заголовки и списки внутри комментария |
| Пошаговая инструкция | «Step 1, Step 2» дублирует сам код |
| Комментарий-пустышка | // constructor, // imports, // инициализация |
| Пустая важность | «ensures that», «отвечает за», «под капотом» |
| Учебный тон | «as you can see», «давайте», «теперь мы» |
| Извинение | «почему-то», «костыль», «hopefully», «not sure why» |
| Комментарий-обещание | «временно», «for now», «will be removed» |
| Эмодзи | в дифф и в grep попадают шумом |
| Метка инструмента | ponytail:, caveman:, claude:, AI: - следы плагина или модели |
| Длинная строка | склеить три строки в одну на 140 символов не значит сократить |
Для коммитов сверх этого: длина заголовка больше 72 символов, точка в конце заголовка, заголовок вида «Update» или «Fix», AI-подпись в трейлере, «This commit adds ...», список из пяти и более пунктов.
Тире в комментариях по умолчанию не считается (жанр code его глушит): их там
столько, что отчёт превращается в список тире. Типографику правь отдельным
проходом без --code.
Настройки проекта
.hum1izer.yaml ищется от проверяемого каталога вверх до корня файловой
системы, поэтому из любого подкаталога монорепы находятся настройки её корня.
Флаги командной строки перекрывают файл; --config F берёт конкретный файл,
--no-config игнорирует любой.
hum1izer init # просканировать и записать .hum1izer.yaml
hum1izer init --print # посмотреть, ничего не записывая
hum1izer init --force # перезаписать существующий
init гоняет обычную проверку, вписывает в файл найденные языки и списком
комментариев показывает, какие правила шумят в этом проекте сильнее всего -
остаётся перенести лишнее в rules.disable.
version: 1
comments:
max_lines: 2 # комментарий длиннее скольких строк - находка, 0 отключает
commits: 20 # сколько последних коммитов проверять, 0 отключает
skip_tests: false
languages:
only: [] # белый список: go, ts, js, svelte, swift. Пусто - все
ignore: [swift]
exclude: # ** проходит через каталоги, * внутри сегмента
- "**/testdata/**"
- "docs/legacy/**"
baseline: .hum1izer-baseline # путь к снимку, считается от файла настроек
rules:
only: [] # белый список. Пусто - все
disable:
- Длинное тире # имя правила
- Структура комментария # или имя категории целиком
genre: code # жанр для правил прозы
rules_file: "" # свой rules.yaml, путь от файла настроек
Имена в rules берутся прямо из отчёта: что напечатано после ! или *, то и
пишется в disable. Работает и имя категории - тогда глушится вся группа.
Категории структурных проверок: Структура комментария и Форма коммита.
Неизвестный ключ, неизвестный язык или битый glob ломают загрузку с ошибкой: молча не работающая настройка хуже её отсутствия.
Снимок для CI
На живом репозитории находок тысячи, и красный CI с первого дня никого ничему не учит. Поэтому есть снимок: прогон сверяется с файлом и ругается только на то, чего в нём нет.
hum1izer --code --baseline .hum1izer-baseline --write-baseline . # записать
hum1izer --code --baseline .hum1izer-baseline . # проверить
Файл кладётся в git. Он отсортирован и хранит относительные пути, чтобы диффы читались:
# hum1izer baseline v1
55dc2ad977ba TODO без владельца internal/code/check.go
Ключ - хэш текста комментария, а не номер строки: код можно двигать и переотступать, находка останется той же. Отредактировал комментарий - он считается новым, и это правильно: раз тронул, приведи в порядок.
В stderr идёт в базе 1200, новых 0, исправлено 7 - прогресс виден, и его
никто не может незаметно отмотать назад.
Код возврата с --baseline ставится за новое, а не за жёсткое. Коммиты в
снимок не попадают: каждый новый коммит был бы новой находкой. Если --commits
не задан явно, при работе со снимком он выключается.
Формат для агента
hum1izer --code --format jsonl --limit 20 ./src
Одна строка JSON на блок, самые грязные первыми, сводка в stderr:
remaining=43 shown=20 findings=61 comments=15035 files=4157.
{"id":"src/a.ts:1-4","file":"src/a.ts","start":1,"end":4,"lang":"ts",
"kind":"comment","score":7,
"raw":"/**\n * This function is responsible for handling the request.\n */",
"findings":[{"rule":"this function is responsible for","line":2,"hard":false,
"fix":"Скажи, почему так сделано, а не что делает строка ниже"}]}
raw - исходный текст байт-в-байт, вместе с // и /* */. Агент правит блок
целиком и заменяет raw точным совпадением: номера строк после первой же правки
уезжают, а raw нет. Дальше перезапуск, пока remaining падает.
Один блок - одна правка, а не отдельная находка на каждое совпадение правила.
--limit режет работу на итерации, score задаёт порядок.
Вес находки в score берётся из поля lift правила: во сколько раз маркер
чаще встречается у машины, чем у человека. Жёсткая находка идёт с тройным
весом, потолок 10, у неизмеренных правил вес равен единице.
Замер свой, на корпусе LLMTrace (Apache-2.0): 2708 человеческих и 1455 машинных текстов на русском, 2056 и 1352 на английском. Генераторы - gpt-4, o3-2025, gigachat, Qwen2.5-72B, Magistral, command-r, DeepSeek-R1, gemini-2.5-flash. Пересчитывается одной командой:
go run ./eval/lift --file valid.jsonl --lang ru # таблица
go run ./eval/lift --file valid.jsonl --lang ru --tsv # машинный вывод для переноса в rules.yaml
Что показал замер:
| Маркер | lift | |
|---|---|---|
| Эмодзи-декор (ru) | у человека нет вовсе | идеальный разделитель |
| seamless(ly) (en) | 21.0 | |
| crucial (en) | 17.7 | |
| Важно понимать/помнить, что (ru) | 15.1 | |
| not only X but also Y (en) | 12.5 | |
| Канцелярит (ru) | 2.8 | |
| Em dash (en) | 1.7 | в английском сигнал есть |
| Длинное тире (ru) | 0.94 | у человека чаще, чем у машины |
| Латиница внутри кириллицы | 0.28 | это опечатки людей, не след машины |
| Tutorial voice (en) | 0.79 | у человека чаще |
Правила с lift ниже 1.2 веса не получают. Русское тире остаётся хард-баном как
типографика, но детектором генерации оно не является, и жанр code его глушит
ровно поэтому.
Числа домен-зависимы: «Является» даёт 2.5 у нас, 4.5 на смешанном регистре и
0.1 на научном по замерам humanizer-ru. Жанр важнее веса. Четыре правила, на
которые в нашем корпусе не хватило попаданий, сохранили чужие значения из
каталога humanizer-ru - они помечены комментарием прямо в rules.yaml.
Свои правила
Правила лежат в трёх файлах, все вшиты в бинарник:
| Файл | Что в нём |
|---|---|
| internal/humanize/rules.yaml | русская проза: баны, маркеры, пороги, жанры |
| internal/humanize/rules-en.yaml | то же для английского |
| internal/humanize/rules-code.yaml | комментарии и коммиты, поверх языкового набора |
Русский набор подменяется флагом:
hum1izer --rules my-rules.yaml текст.md
Формат одного правила:
hard_bans:
- name: Синергия
fix: Скажи, что конкретно с чем соединяется
word_re: 'синерги[\p{L}]+'
categories:
- name: Мой канцелярит
fix: Разверни в глагол
rules:
- lit: осуществлени # подстрока, регистронезависимо
- re: 'посвящен[ао]\s+анализ' # регулярка RE2 как есть
- word_re: 'важн[\p{L}]+ шаг' # то же, но с границами слова
- builtin: en_dash # правило, которое считает код
Три вещи, о которых стоит помнить при правке:
- в Go
\bи\wработают только по ASCII, поэтому для кириллицы пишиword_reвместо\bи[\p{L}]+вместо\w; - lookaround и обратных ссылок в RE2 нет: то, что без них не выражается, живёт
в коде как
builtin(en_dash,fake_range,latin_in_cyrillic); - невидимые символы в наборе пиши кодами (
\x{200b}), а не литералами: в дифф они не видны, и GitHub ругается на bidirectional Unicode.
Загрузчик проверяет набор при старте: если жанр глушит бан, которого нет, hum1izer падает с ошибкой вместо того, чтобы молча ничего не делать.
Отличия от оригинального сканера
Порт сверен с scripts/scan.py на общем тексте: балл, состав штрафов и список
находок совпадают. Три отличия в реализации:
- Номинальность. Оригинал считает сущ./глаг. через
pymorphy3. Здесь словаря нет, вместо отношения считается плотность отглагольных существительных по суффиксам. Сигнал тот же (канцелярит), вес штрафа тот же. Потолок эвристики: не отличает «решение задачи» от «решение принято». - Границы слов и lookaround. В Go
\bи\wработают только по ASCII, а lookaround и обратных ссылок нет вовсе. Границы расставлены явно, три правила (короткое тире, ложный диапазон «от X до Y», латиница внутри кириллицы) считаются кодом. - Номера строк. Точнее, чем в оригинале: там позиция берётся от начала совпадения, поэтому паттерн с ведущим разделителем («. Таким образом,») показывает строку предыдущего предложения.
Заголовки в Title Case оригинал отсеивает по словарю имён собственных, здесь словаря нет: заголовок из нескольких имён даст ложное срабатывание.
Чего тут нет
Семантика: кальки по смыслу, ирония, translationese, пустая образность, «фигуративный ноль». Это принципиально не ловится регулярками, для этого нужен сам скилл humanizer-ru с моделью.
Переписывания текста тоже нет: hum1izer только показывает и советует.
Разработка
cmd/hum1izer/ флаги, вывод, подкоманды install и init
internal/baseline/ снимок находок для CI
eval/lift/ пересчёт весов lift на парном корпусе
internal/config/ .hum1izer.yaml: поиск вверх, языки, исключения, правила
internal/humanize/ правила, разбор прозы, балл + rules*.yaml
internal/code/ комментарии из исходников, коммиты, структурные проверки
internal/skill/ SKILL.md и раскладка по агентам
make check # fmt + vet + golangci-lint + test
make build # бинарь с версией из git describe
CI гоняет go vet, gofmt -l, golangci-lint и go test -race на каждый пуш.
Релиз собирается по тегу v*: darwin/arm64, darwin/amd64, linux/amd64,
linux/arm64, windows/amd64, архивы и SHA256SUMS уезжают в GitHub Release.
git tag v0.1.0 && git push --tags
Лицензия
MIT, (c) 2026 Andrey Sobolev.
Наборы правил, пороги, корпусные веса lift и процедура правки в скилле
изначально взяты из humanizer-ru
(MIT, (c) Ilya Utov).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hum1izer
command
Command hum1izer проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы.
|
Command hum1izer проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы. |
|
eval
|
|
|
lift
command
Command lift считает подъём каждого правила на парном корпусе: во сколько раз маркер чаще встречается у машины, чем у человека.
|
Command lift считает подъём каждого правила на парном корпусе: во сколько раз маркер чаще встречается у машины, чем у человека. |
|
internal
|
|
|
baseline
Package baseline - снимок находок проекта.
|
Package baseline - снимок находок проекта. |
|
config
Package config читает .hum1izer.yaml: настройки проекта рядом с кодом.
|
Package config читает .hum1izer.yaml: настройки проекта рядом с кодом. |
|
skill
Package skill раскладывает SKILL.md по каталогам агентов.
|
Package skill раскладывает SKILL.md по каталогам агентов. |