--- name: simplified-technical-russian description: >- Упрощает и проясняет русский технический текст: одно значение на слово, действительный залог, прямой порядок слов, не более 20 слов в предложении (УТР, ГОСТ Р 58049—2017). Применяйте, только если упрощаемый или создаваемый текст написан по-русски; язык запроса значения не имеет. Триггеры: упрости, кратко, короче, проще, понятнее, простым языком, по УТР. К тексту на других языках не применяйте. license: MIT version: 1.1.0 --- # Упрощённый технический русский (УТР, ГОСТ Р 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). 2. **Безопасность.** Предупреждение сохраняет полноту, даже если превышает 20 слов (8.2.7). 3. **Единство терминологии.** Один термин для одного понятия важнее стиля (8.2.3.7). 4. **Целостность кода.** Идентификаторы, ключевые слова, пути и команды не переводят и не склоняют (адаптация). 5. **Краткость и простота.** Всё остальное (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`. | Артефакт | Форма глагола | Пример | |---|---|---| | Комментарий и docstring о поведении кода | 3-е лицо единственного числа, настоящее время | `Возвращает список активных заказов.` | | Комментарий о причине решения | Неопределённо-личная конструкция | `Индекс не применяют: планировщик выбирает seq scan.` | | Инструкция в README и runbook | Повелительное наклонение множественного числа | `Запустите миграции. Проверьте статус.` | | Сообщение об ошибке | Условие, затем команда (8.2.7) | `Файл config.yaml не найден. Создайте файл в каталоге /etc/app.` | | Запись в лог | Неопределённо-личная или безличная конструкция | `Соединение закрывают по таймауту.` | | Заголовок коммита и merge request | Неопределённая форма глагола | `Добавить кэш ответов профиля.` | | Описание merge request, тело коммита | Свершившийся факт | `Гонка исправлена. Добавлен потребитель очереди.` | Идентификаторы, имена файлов, ключи конфигурации, команды и вывод программы оставляйте как есть. Их не переводят и не склоняют. Отчёт о выполненной работе — не инструкция. Пункт 8.2.3.13 ограничен инструкциями, поэтому запрет страдательного залога на отчёт не распространяется. В описании merge request пишите «Гонка исправлена», а не «Исправить гонку»: инфинитив читается как невыполненная задача. ## Формат вывода Режим письма и постоянный режим — только текст. Режим правки — текст, затем таблица: ```markdown | Пункт ГОСТ | Было | Стало | |---|---|---| | 8.2.3.11 | Данные, полученные от сервиса, сохраняются в кэш. | Сервис возвращает данные. Данные сохраняют в кэш. | ``` После таблицы дайте одну строку об осознанных отступлениях. Обычно это сохранение длины ради точности. Режим аудита — та же таблица без столбца «Стало». Вместо него — столбец «Нарушение». Если текст уже соответствует УТР, скажите об этом. Не правьте соответствующий текст ради правки. ## Проверка линтером `scripts/utr_lint.py` проверяет машинно-проверяемую часть правил. Зависимостей нет, нужен Python 3.7 и новее. ```bash 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` — примеры «было — стало».