Simplified Technical English — скилл, который заставляет ИИ писать инструкции по-человечески

Скилл учит LLM писать технические тексты на упрощённом техническом английском — STE. Это контролируемый язык для документации. За основу взят стандарт ASD-STE100. Его используют авиационная и оборонная промышленность, чтобы инструкции читал человек, который плохо знает английский.

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

Что внутри репозитория

Правила в репозитории — это пересказ стандарта своими словами, а не официальный текст ASD. Сам стандарт ASD-STE100 бесплатно лежит на asd-ste100.org.

Пример правки

Было:

Prior to commencing the installation, it should be ensured that all components have been thoroughly inspected for damage.

Стало:

Before you start the installation, examine all the components for damage.

Что произошло: убрали канцелярское «prior to commencing», убрали пассивный залог и вспомогательный глагол «should», поставили императив и сократили предложение.

Как работает скилл

Скилл просит модель сначала определить тип текста.

• Процедурный текст велит читателю что-то сделать: «Remove the four bolts».
• Описательный текст даёт информацию: «The pump supplies fuel to the engine».

У этих двух типов разные ограничения. Смешивать их в одном абзаце нельзя.

Дальше идут правила глаголов, правила предложений, правила слов и отдельный блок про предупреждения о безопасности. Главные ограничения простые:

• Разрешены только шесть форм глагола: инфинитив, императив, простое настоящее, простое прошедшее, будущее с «will» и причастие в роли прилагательного.
• Форма «-ing» запрещена. В списке исключений восемь слов: mating, missing, remaining, lighting, opening, routing, servicing, during.
• Вспомогательные глаголы с причастием запрещены. Пишут «the operator adjusted the linkage», а не «the operator has adjusted the linkage».
• Только активный залог. Пишут «a relay connects the circuits», а не «the circuits are connected by a relay».
• Из вспомогательных глаголов разрешены только «can», «must» и «will». Слова «should», «would», «may», «might», «shall» запрещены.
• В процедурном предложении не больше 20 слов. В описательном — не больше 25.
• В абзаце не больше 6 предложений и только одна тема.
• Одно предложение — одна инструкция. Два действия разрешены, только если они идут одновременно.
• Сокращения запрещены: пишут «do not», а не «don't».
• Точка с запятой запрещена. Вместо неё пишут два предложения.
• Цепочка из существительных — не больше трёх слов. Длинные цепочки разбивают предлогами.

Правило про слова строгое: разрешены только слова из словаря, технические названия и технические глаголы. При этом слово можно использовать только в той части речи, которую даёт словарь. Слово «test» в словаре есть только как существительное. Поэтому «test the system» не подходит, а «do a test of the system» подходит.

Словарь STE бедный — 869 слов. Многие привычные слова в него не входят. Поэтому в репозитории лежит таблица замен: assure → make sure that, begin → start, check → examine или make sure that, may → can, obtain → get, prior to → before, simultaneously → at the same time, technique → method, utilize → use.

Заодно введены 19 категорий технических названий и 4 категории технических глаголов. Техническим глаголом считают, например, install или delete — это компьютерные операции. Их можно использовать, если обычного глагола не хватает.

Предупреждения о безопасности

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

• Слово WARNING ставят, когда есть риск травмы или смерти для человека.
• Слово CAUTION ставят, когда есть риск повредить предметы.
• Предупреждение начинается с короткой команды или условия, а риск идёт следом.

Пример из репозитория:

WARNING: Do not touch the high-voltage terminals. The terminals can cause injury or death to personnel.

Сначала команда, потом риск. Никаких размытых формулировок вроде «соблюдайте крайнюю осторожность».

Проверяющий инструмент

В репозитории лежит скрипт ste_check.py. Он написан только на стандартной библиотеке Python 3, без зависимостей.

Запуск:

python3 scripts/ste_check.py --mode procedural draft.txt
python3 scripts/ste_check.py --mode descriptive chapter.md

Скрипт ищет:

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

Каждая ошибка выводится с номером правила. Код возврата равен 0, если ошибок нет, и 1, если ошибки есть.

Что скрипт пропускает: код, идентификаторы, команды, пути к файлам, цитаты и YAML-фронтматтер. Это сделано намеренно — правила STE не должны применяться к коду.

Скрипт не находит все ошибки. Он не знает, в каком именно смысле вы использовали слово. Если проект обязан соответствовать ASD-STE100, нужен официальный стандарт и утверждённый процесс проверки.

Установка

Для Claude:

git clone https://github.com/0xpili/simplified-technical-english.git ~/.claude/skills/simplified-technical-english

Дальше скажите Claude: «пиши технический текст в STE» или «проверь этот текст в STE». Запустить можно и явно: /simplified-technical-english.

Для другой модели откройте SKILL.md и скопируйте текст в системный промпт. Если модель принимает больше текста, добавьте references/substitutions.md. Для лучшего результата добавьте ещё и словарь references/word-list.md.

Зачем это нужно разработчику

Слоган STE — «write once, read many». Текст на контролируемом языке проще переводить на другие языки и проще отдавать переводчику-человеку. Для ИИ смысл тот же: короткие инструкции выполняются точнее, чем длинные рассуждения.

При этом стандарт родился не в IT. Он создан для авиационных руководств. Поэтому в словаре много слов про болты, провода, клапаны и топливо, и мало слов про софт. Для документации программистов это значит, что почти каждое нужное слово придётся пометить как техническое название.

Второе ограничение — английский язык. Скилл работает только с английским текстом. Русскую техническую документацию по этим правилам писать не получится: словарь английский, запрещённые формы английские.

Ограничения

• Стандарт неофициальный. ASD его не утверждал и не поддерживает.
• Скрипт ловит только то, что можно проверить регулярками. Смысл слова он не проверяет.
• Авиационный уклон делает словарь бедным для софтверных терминов.
• Правила иногда спорные. Например, запрет на «-ing» ломает привычные обороты и требует переписывать фразы целиком.

Словарь ASD — собственность ASD. Текст скилла и скриптов распространяется по лицензии MIT, о чём сказано в NOTICE.md.