simplified-technical-russian

Упрощённый технический русский (УТР, ГОСТ Р 58049—2017)

УТР — контролируемый технический язык: подвид естественного языка, полученный через систему ограничений лексики и грамматики. Цель ограничений — максимальная однозначность восприятия (пункт 3.14). Стандарт создан по образцу ASD-STE100 (Simplified Technical English) и вводит те же ограничения для русского языка.

Навык переносит правила раздела 8.2 на техническую работу с кодом и документацией. Читатель здесь другой: разработчик, переводчик, машинный переводчик или другой ИИ-агент. Ошибка чтения стоит так же дорого, как в инструкции по техническому обслуживанию.

Раздел 8.2 — часть стандарта на перевод эксплуатационной документации для авиационной техники. Стандарт допускает применение своих положений к другой документации (раздел 1). Навык разделяет два слоя: правила ГОСТ приводит с номерами пунктов, перенос на код помечает как адаптацию. Сертификации по ГОСТ навык не даёт.

Проверка языка — до всего остального

Сначала определите язык текста, который правите или пишете. Правила применяйте только к русскому тексту.

Язык запроса значения не имеет. Просьба «упрости этот комментарий», заданная по-русски, относится к УТР только тогда, когда сам комментарий написан по-русски.

Если текст не на русском, скажите одной строкой, что правила УТР к нему не относятся, и выполняйте задачу обычным порядком. Не ссылайтесь на пункты ГОСТ и не переводите текст на русский ради того, чтобы правила стали применимы.

Когда применять

• Просят написать, упростить или сократить русский текст.
• Вы пишете русский комментарий, docstring, сообщение об ошибке или запись в лог.
• Вы пишете или правите README, runbook, инструкцию, описание задачи на русском.
• Русский текст пойдёт в машинный перевод, к неносителю языка или к другому агенту.

Не применяйте к художественному тексту, маркетингу и публичным постам: УТР намеренно сухой. Не применяйте к коду — правила касаются только естественного языка. Цитаты, юридический текст и текст стандарта не переписывают.

Режимы работы

Название стандарта называть не обязательно: для русского текста слова «кратко», «короче», «проще», «понятнее», «простым языком» означают то же самое, что «по УТР». Для текста на другом языке те же слова к УТР не относятся — смотрите проверку языка выше.

По умолчанию действует режим письма. Не выдавайте таблицу правок, если пользователь её не просил.

Приоритет правил при конфликте

1. Точность смысла. Условие, ограничение, число и предупреждение не теряют

ради краткости (8.2.3.15, 8.2.4.1).

1. Безопасность. Предупреждение сохраняет полноту, даже если превышает

20 слов (8.2.7).

1. Единство терминологии. Один термин для одного понятия важнее стиля (8.2.3.7).
2. Целостность кода. Идентификаторы, ключевые слова, пути и команды не

переводят и не склоняют (адаптация).

1. Краткость и простота. Всё остальное (8.2.3.14, 8.2.5.1).

Если правило пришлось нарушить, отметьте это одной строкой после текста.

Ядро правил

Полные формулировки, примеры стандарта и связанные ГОСТы — references/gost-58049-utr.md.

Предложение

• 8.2.5.1 — не длиннее 20 слов по правилам подсчёта ниже.
• 8.2.3.4 — прямой порядок слов: подлежащее не в конце, дополнение не перед сказуемым.
• 8.2.3.3 — действительный залог, неопределённо-личные и безличные конструкции.
• 8.2.3.13 — страдательный залог в инструкциях не применяют.
• 8.2.3.11 — причастия, деепричастия и составные сказуемые ограничивают.
• 8.2.3.14 — сложное распространённое предложение заменяют простым.
• 8.2.3.12 — последовательность действий соединяют союзами, если разбить нельзя.

Лексика

• 8.2.3.5 — метафоры, сравнения, сленг и жаргон запрещены.
• 8.2.3.6 — иностранное слово не применяют при наличии равнозначного русского.
• 8.2.3.7 — один термин на одно понятие во всём тексте. Синонимы запрещены.
• 8.2.3.8 — официальные термины сокращают, берут самый короткий вариант.
• 8.2.3.10 — не более двух существительных подряд. Глагол вместо отглагольного существительного.
• 8.2.3.15 — опущения и сокращения, искажающие смысл, запрещены.
• 8.2.4.5 — многозначное слово заменяют контекстно точным.

Инструкции (8.2.5)

• Глагол первым, повелительное наклонение множественного числа. Единственное

число запрещено (8.2.3.9).

• Одно предложение — одна команда. Две допустимы только для одновременных

действий (8.2.5.2).

• Описание конкретное: названы объекты, значения, пути (8.2.5.4).

Описательная часть (8.2.6)

• Абзац раскрывает одну тему, не длиннее шести предложений.
• Абзац из одного предложения — не чаще одного раза на десять абзацев.

Предупреждения (8.2.7)

• Начинают с команды. Если есть условие — начинают с условия. Добавляют краткое

пояснение риска.

Оформление

• 8.2.3.16 — перечисление оформляют вертикальным маркированным списком.
• 8.2.3.17 — скобки применяют только по пяти случаям этого пункта.
• 8.2.3.18 — слова типа «кнопка», «ссылка» не применяют. Границы переноса

на программные интерфейсы — в references/code-comments.md.

• 8.2.4.6 — единицы измерения по системе страны назначения, исходные в скобках.

Подсчёт слов (примечание к 8.2.5.1)

Применяйте допущения стандарта до проверки лимита в 20 слов:

• текст в скобках считают новым предложением;
• числовое значение считают одним словом;
• буквенно-цифровой идентификатор считают одним словом;
• аббревиатуру считают одним словом;
• название, предупредительную надпись и цитату считают одним словом.

Поэтому Проверьте параметр max_retry_count в файле config/app.yaml. — шесть слов.

Быстрый чек-лист

Прогоняйте по нему каждое русское предложение:

1. Не длиннее 20 слов?
2. Подлежащее перед сказуемым, дополнение после?
3. Действительный залог? Нет форм на «-ется» и «-ются» в значении страдательного?
4. Нет причастных и деепричастных оборотов?
5. Один термин для одного понятия во всём тексте?
6. Нет метафор, сленга, англицизмов с русским эквивалентом?
7. Одна команда, глагол первым, во множественном числе?

Полный чек-лист с номерами пунктов: references/checklist.md.

Адаптация к коду

Обоснование каждого отступления — references/code-comments.md.

Идентификаторы, имена файлов, ключи конфигурации, команды и вывод программы оставляйте как есть. Их не переводят и не склоняют.

Отчёт о выполненной работе — не инструкция. Пункт 8.2.3.13 ограничен инструкциями, поэтому запрет страдательного залога на отчёт не распространяется. В описании merge request пишите «Гонка исправлена», а не «Исправить гонку»: инфинитив читается как невыполненная задача.

Формат вывода

Режим письма и постоянный режим — только текст.

Режим правки — текст, затем таблица:

| Пункт ГОСТ | Было | Стало |
|---|---|---|
| 8.2.3.11 | Данные, полученные от сервиса, сохраняются в кэш. | Сервис возвращает данные. Данные сохраняют в кэш. |

После таблицы дайте одну строку об осознанных отступлениях. Обычно это сохранение длины ради точности.

Режим аудита — та же таблица без столбца «Стало». Вместо него — столбец «Нарушение».

Если текст уже соответствует УТР, скажите об этом. Не правьте соответствующий текст ради правки.

Проверка линтером

scripts/utr_lint.py проверяет машинно-проверяемую часть правил. Зависимостей нет, нужен Python 3.7 и новее.

python3 scripts/utr_lint.py README.md
python3 scripts/utr_lint.py --mode code src/service.py
python3 scripts/utr_lint.py --lexicon glossary.json docs/

Линтер работает на эвристиках без морфологического анализатора и даёт ложные срабатывания. Его вывод — подсказка, а не приговор. Полный список правил и метки подавления — в README.md.

Терминологическая база

Пункт 8.1.3 требует терминологическую базу до внедрения УТР. Ведите глоссарий проекта по образцу references/glossary.example.json. Передавайте его линтеру через --lexicon. Заносите в него выбранные термины и сокращения (8.2.3.7, 8.2.3.8). Если для предметной области есть национальный стандарт на терминологию, применяйте его термины (8.1.10).

Границы

Навык сохраняет каждый факт, условие, ограничение и число оригинала. Он отмечает осознанные отступления от правил и называет причину.

Чего навык не делает:

• не применяет правила к тексту на английском и других языках;
• не сокращает текст ценой потери смысла или условия безопасности;
• не применяет УТР к художественному и юридическому тексту;
• не переводит идентификаторы и команды;
• не заменяет официальный текст ГОСТ Р 58049—2017 и не даёт сертификации.

Линтер покрывает только часть правил.

Дополнительные материалы

• references/gost-58049-utr.md — правила раздела 8.2 по пунктам, с примерами.
• references/code-comments.md — адаптация к коду, коммитам, логам и ошибкам.
• references/lexicon.md — замены канцелярита, англицизмов и жаргона.
• references/checklist.md — чек-лист проверки текста.
• references/glossary.example.json — образец глоссария проекта.
• examples/before-after.md — примеры «было — стало».