Навык заставляет Claude Code, Codex, Cursor и другие ИИ-агенты писать русский текст по правилам упрощённого технического русского языка (УТР) из ГОСТ Р 58049—2017, раздел 8.2.
УТР — российский контролируемый технический язык. Стандарт создан по образцу ASD-STE100 (Simplified Technical English), который авиационная отрасль применяет с 1983 года. Цель одна: инструкцию нельзя прочитать двумя способами.
Навык применяют к комментариям в коде, docstring, сообщениям об ошибках, записям в лог, README, инструкциям, описаниям коммитов и ответам агента.
Было: Данная функция является методом, который осуществляет получение
списка активных заказов пользователя, отфильтрованных по статусу.
Стало: Возвращает активные заказы пользователя.
Заказы сортирует по дате создания, от новых к старым.
ИИ-агент по умолчанию пишет по-русски канцеляритом: страдательный залог, причастные обороты, отглагольные существительные, англицизмы. Такой текст:
- читается медленнее и допускает два толкования;
- плохо переводится машинным переводчиком;
- расходится в терминах от абзаца к абзацу;
- ломает работу другого агента, который разбирает этот текст.
ГОСТ Р 58049—2017 решает ровно эту задачу для человека. Навык переносит его решение на код и на общение с агентом.
| Файл | Назначение |
|---|---|
SKILL.md |
Сам навык: правила, режимы работы, приоритеты, формат вывода |
references/gost-58049-utr.md |
Правила раздела 8.2 по пунктам, с примерами стандарта |
references/code-comments.md |
Адаптация к коду, коммитам, логам и сообщениям об ошибках |
references/lexicon.md |
Замены канцелярита, англицизмов, жаргона и метафор |
references/checklist.md |
Чек-лист проверки текста |
references/glossary.example.json |
Образец глоссария проекта (пункты 8.1.3—8.1.9) |
examples/before-after.md |
Примеры «было — стало» из стандарта и из практики |
scripts/utr_lint.py |
Линтер на 18 правил. Без зависимостей, Python 3.7 и новее |
CHANGELOG.md |
Что меняется в поведении после git pull |
git clone https://github.com/loadkpi/simplified-technical-russian-skill \
~/.claude/skills/simplified-technical-russianКаталог назван без суффикса -skill: его имя должно совпадать с полем name
во фронтматтере SKILL.md.
Для одного проекта:
git clone https://github.com/loadkpi/simplified-technical-russian-skill \
.claude/skills/simplified-technical-russianПроверка: спросите агента «какие навыки доступны» или напишите «перепиши этот комментарий по УТР».
git clone https://github.com/loadkpi/simplified-technical-russian-skill \
.agents/simplified-technical-russianДобавьте в AGENTS.md проекта строку:
Русский текст пишите по правилам УТР: см. .agents/simplified-technical-russian/SKILL.mdСкопируйте SKILL.md в правила проекта:
- Cursor —
.cursor/rules/utr.mdc; - Windsurf —
.windsurfrules; - Cline —
.clinerules.
Вставьте содержимое SKILL.md в системную подсказку или в первое сообщение.
Установка навыка не включает УТР автоматически. Навык — инструмент: агент берёт его, когда задача подходит под описание. Чтобы правила действовали постоянно, нужен один из двух шагов ниже.
CLAUDE.md попадает в контекст каждой сессии, в отличие от навыка. Добавьте
в CLAUDE.md проекта — или в ~/.claude/CLAUDE.md для всех проектов:
## Русский язык
Весь русский текст — комментарии, docstring, сообщения об ошибках, логи,
README, описания коммитов, ответы в чате — пишите по правилам УТР
(ГОСТ Р 58049—2017, раздел 8.2).
Правила: ~/.claude/skills/simplified-technical-russian/SKILL.mdДля Codex, Cursor и Cline то же самое делает AGENTS.md из этого репозитория.
CLAUDE.md даёт инструкцию, которой агент следует, но не обязан. Хук проверяет
механически: после каждой записи файла линтер прогоняет текст, и найденные
нарушения возвращаются модели. Добавьте в .claude/settings.json проекта или в
~/.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/skills/simplified-technical-russian/scripts/utr_lint.py --hook",
"statusMessage": "Проверка УТР"
}
]
}
]
}
}Хук читает событие со стандартного ввода, проверяет записанный файл и молчит,
если нарушений нет. По умолчанию сообщает только об ошибках; добавьте
--min-severity warning для предупреждений и --lexicon glossary.json для
глоссария проекта.
Ход выполнения хук не прерывает: модель получает список нарушений и исправляет текст сама.
Навык работает в четырёх режимах.
| Режим | Как включить | Что получите |
|---|---|---|
| Письмо | «Напиши комментарии на русском» | Готовый текст по правилам УТР |
| Правка | «Упрости этот текст», «сделай короче» | Текст и таблицу правок с номерами пунктов |
| Аудит | «Проверь текст», «насколько это понятно» | Таблицу нарушений без правки текста |
| Постоянный | «Дальше пиши кратко», «дальше — по УТР» | Все ответы и комментарии по правилам |
Навык срабатывает на просьбу упростить или прояснить текст — знать слово «УТР» для этого не нужно. Для русского текста «кратко», «короче», «проще», «понятнее» означают то же самое, что «по УТР».
Упрости этот комментарий
Напиши сообщение об ошибке кратко
Перепиши docstring проще
Проверь README.md по УТР
Правила действуют только для русского текста. Язык запроса значения не имеет: просьба «упрости этот комментарий», заданная по-русски, включает УТР только тогда, когда сам комментарий написан по-русски. Для текста на другом языке навык сообщает, что правила к нему не относятся, и в работу не вмешивается — упрощением иноязычного текста занимаются другие инструменты.
python3 scripts/utr_lint.py README.md # проверить документ
python3 scripts/utr_lint.py --mode code src/service.py # проверить комментарии
python3 scripts/utr_lint.py --mode report MR.md # описание MR, журнал изменений
python3 scripts/utr_lint.py docs/ # проверить каталог
python3 scripts/utr_lint.py --format json --fail-on error docs/
python3 scripts/utr_lint.py --lexicon glossary.json docs/
echo "Текст для проверки" | python3 scripts/utr_lint.py -
python3 scripts/utr_lint.py --list-rulesПример вывода:
docs/setup.md:12: STR001 [ошибка] Предложение содержит 32 слов при пределе 20.
→ Для того чтобы запустить проект, необходимо сначала произвести установку…
docs/setup.md:12: STR012 [предупреждение] Возможен страдательный залог: «запускаются».
docs/setup.md:18: STR030 [ошибка] Повелительное наклонение единственного числа: «Нажми».
| Код | Уровень | Пункт | Что ловит |
|---|---|---|---|
| STR001 | ошибка | 8.2.5.1 | Предложение длиннее 20 слов |
| STR002 | предупреждение | 8.2.6.2 | Абзац длиннее шести предложений |
| STR003 | подсказка | 8.2.6.2 | Частые абзацы из одного предложения |
| STR010 | предупреждение | 8.2.3.11 | Причастие |
| STR011 | предупреждение | 8.2.3.11 | Деепричастие |
| STR012 | предупреждение | 8.2.3.13 | Страдательный залог |
| STR013 | предупреждение | 8.2.3.11 | Составное сказуемое, связка «является» |
| STR020 | подсказка | 8.2.3.10 | Цепочка из трёх и более существительных |
| STR030 | ошибка | 8.2.3.9 | Повелительное наклонение единственного числа |
| STR031 | предупреждение | 8.2.5.2 | Более одной команды в предложении |
| STR040 | предупреждение | 8.2.3.5 | Метафора, сравнение, сленг, жаргон |
| STR041 | предупреждение | 8.2.3.6 | Англицизм при наличии русского слова |
| STR042 | предупреждение | 8.2.3.10 | Канцелярит и номинативные конструкции |
| STR043 | подсказка | 8.2.3.2 | Оценочные и неопределённые слова |
| STR050 | подсказка | 8.2.3.16 | Перечисление внутри предложения |
| STR051 | подсказка | 8.2.3.18 | Слова «кнопка», «ссылка» |
| STR060 | предупреждение | 8.2.3.7 | Синоним вместо термина глоссария |
| STR061 | подсказка | 8.2.3.8 | Сокращение без расшифровки |
<!-- utr-lint: disable-file --> весь файл
<!-- utr-lint: disable-next-line --> следующая строка
текст <!-- utr-lint: disable --> эта строкаВ коде те же метки пишут в комментарии: # utr-lint: disable-next-line.
Пункт 8.1.3 требует терминологическую базу до внедрения УТР. Скопируйте
references/glossary.example.json в корень проекта и заполните его. Линтер
сообщит о синонимах и о сокращениях без расшифровки.
| Код | Значение |
|---|---|
| 0 | Нарушений выше порога --fail-on нет |
| 1 | Найдены нарушения уровня --fail-on и выше |
| 2 | Файл или каталог не прочитан. Возвращается независимо от --fail-on |
Код 2 отделяет отказ инструмента от находок линтера: --fail-on never подавляет
код 1, но не скрывает недоступный файл. Иначе каталог без прав на чтение молча
выпадал бы из проверки.
- name: Проверка русского текста по УТР
run: python3 scripts/utr_lint.py --fail-on error --min-severity warning docs/python3 -m unittest discover -s tests -vСтандарт регламентирует перевод эксплуатационной документации на изделия авиационной техники. Раздел 1 стандарта допускает применение его положений к другим видам документации.
Навык честно разделяет два слоя:
- правила ГОСТ — с номерами пунктов, смысл формулировок не изменён;
- адаптация — перенос на код. Каждое отступление отмечено и обосновано в
references/code-comments.md.
Навык не даёт сертификации по ГОСТ. Для авиационной документации применяйте официальный текст стандарта и утверждённую терминологическую базу.
Не применяйте УТР к художественному тексту, маркетингу и публичным постам. УТР намеренно сухой.
Линтер работает на эвристиках без морфологического анализатора. Он даёт ложные срабатывания: краткие прилагательные путает с причастиями, часть цепочек существительных находит там, где их нет. Уровень «подсказка» — это гипотеза, а не нарушение.
Собственные файлы навыка проходят проверку с нулём ошибок. Предупреждения уровня «страдательный залог» в справочных файлах оставлены осознанно: пункт 8.2.3.13 требует избегать страдательного залога в инструкциях, а не запрещает его.
| Проект | Отличие |
|---|---|
| asd-ste100-skill | ASD-STE100 для английского. Образец, по которому построен УТР |
| ru-text | Инфостиль, типографика, редакторские стандарты. Не контролируемый язык |
| humanizer-ru | Убирает следы машинной генерации. Другая задача |
| russian-text-quality | Ошибки склонения и плюрализации в коде. Дополняет этот навык |
Этот навык — единственный, который опирается на национальный стандарт контролируемого технического языка и приводит номера пунктов.
ГОСТ Р 58049—2017 «Перевод эксплуатационной документации на изделия авиационной техники с/на иностранные языки. Общие положения». Утверждён приказом Росстандарта от 29.12.2017 № 2129-ст. Введён в действие 01.07.2018.
Репозиторий не воспроизводит текст стандарта. Он пересказывает требования раздела 8.2 и цитирует короткие примеры с указанием пунктов.
MIT. Смотрите LICENSE. Лицензия не распространяется на текст ГОСТ Р 58049—2017.
Skill that makes Claude Code, Codex, Cursor and other AI coding agents write Russian technical text in Simplified Technical Russian, the controlled language defined by the Russian national standard GOST R 58049-2017, clause 8.2.
GOST R 58049-2017 is the Russian counterpart of ASD-STE100 Simplified Technical English: short sentences (max 20 words), direct word order, active voice, imperative plural for instructions, one term per concept, no participles, no metaphors, no slang.
The skill covers code comments, docstrings, error messages, log records, README files, runbooks, commit messages and agent replies. It ships with a dependency-free Python linter (18 rules mapped to standard clauses) that reads Markdown and extracts comments from source files in 30+ languages.
Install for Claude Code:
git clone https://github.com/loadkpi/simplified-technical-russian-skill \
~/.claude/skills/simplified-technical-russian