simplified-technical-russian

---
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` — примеры «было — стало».