язык проектных текстов — один дом и информационный стиль

Языковые правила лежали внутри скилла tasks: англицизмы, неизвестные
термины, «сложность формулировки — не признак сложности работы». Три
пункта из практики, без общей опоры и без ответа на «а что ещё сюда
относится».

Дом у языка теперь один — canon/references/language.md. Не в tasks, хотя
пришли правила оттуда: они относятся к документам канона, решениям ADR,
запискам разведки и сообщениям коммитов в той же мере, что к задачам, а
каталог задач и сам часть docs/. Раскладка отвечает, где текст лежит, —
этот файл отвечает, каким он должен быть словами.

Основа — информационный стиль Ильяхова, взятый не целиком. Взято:
полезное действие, глагол вместо отглагольного существительного,
активный залог, факт вместо оценки, стоп-слова, одна мысль — одно
предложение, параллельность, работающий заголовок.

Отброшенное названо вслух, и это отдельный раздел. Инфостиль написан для
текстов, где читателя надо удержать, а проектный текст читают потому,
что надо. Парцелляция ломает причинную связь, а в решении ценность
именно в ней. Запрет вводных целиком режет «если» и «в отличие от» —
условия, то есть сведения. Скобки в технической записи несут уточнение:
имя команды, единицы, слаг. Без этого раздела правило читается как «пиши
короче», и первый же агент начинает резать «поэтому» и «иначе».

«Снять корону с себя и надеть на клиента» переведено на здешнего
читателя: клиент — ты сам через квартал и тот, кто возьмёт задачу.

Таблицы англицизмов и жаргона взяты из скилла prepare-jira-text и
дополнены; в устав агента они уехали помеченной копией. Устав обязан
быть самодостаточным — он не разрешает пути плагина и не ходит по
ссылкам, — а два дома у одного правила здесь уже трижды расходились.
scripts/copies.py считает теперь 4 копии при 4 домах.

У агента вычитки правил стало двенадцать, разделены на форму записи
(только для задач) и язык (для любого проектного текста). Находки
докладываются в этом порядке: форма меняет решение «брать или не брать»,
язык — только цену чтения.

DECISIONS тема 21 (ЛЛЛ–ООО, следствия 86–88), changelog канона v3 —
пункт 6 и шаг переезда «прочитать и ничего не переписывать задним
числом».

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

av-dev-pm/skills/canon/references/language.md

@@ -0,0 +1,160 @@
+# Язык проектных текстов
+
+Правила для всего, что пишется словами: задачи и цели, документы канона,
+решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
+сообщений программы пользователю — там свои конвенции проекта.
+
+Основа — **информационный стиль** Максима Ильяхова ([учебник
+бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
+написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что
+взято и что отброшено намеренно.
+
+## Зачем он здесь
+
+Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
+задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
+квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
+несущие сведений. Информационный стиль ровно про это, и его польза здесь не
+эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
+а это и есть цена, которой мы избегаем.
+
+## Что взято
+
+**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
+читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
+«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
+собственный вопрос («что это за система», «как сложено», «почему так решили»).
+Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
+исход правки.
+
+**Глагол вместо отглагольного существительного, действие вместо состояния.**
+«Обработчик не проверяет владельца», а не «проверка владельца не
+осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по
+имени». Отглагольное существительное прячет того, кто действует, — а в
+техническом тексте именно он и важен.
+
+**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается
+скриптом». Страдательный залог остаётся там, где деятель неизвестен или
+неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх
+команд.
+
+**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до
+800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а
+не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит
+факт. Без факта оценка — не сведение, а настроение.
+
+**Стоп-слова.** Убирается то, что можно убрать без потери смысла:
+
+| Что | Примеры |
+| --- | --- |
+| канцелярит | является, осуществляется, в целях, в рамках, данный, вышеуказанный, необходимо отметить |
+| вводные-паразиты | в общем, как известно, стоит отметить, не секрет, что |
+| усилители | очень, крайне, достаточно, абсолютно, максимально, полностью |
+| синонимы одного качества | «понятный и простой», «быстрый и производительный» |
+| неопределённое | какой-то, некоторый, соответствующий, определённый |
+
+Проверка одна: **вычеркни слово. Смысл изменился — оставляй.**
+
+**Одна мысль — одно предложение.** Предложение, в котором два независимых
+утверждения, делится. Придаточное, которое можно вынести в отдельную фразу,
+выносится.
+
+**Параллельность.** Однородное пишется одинаково: пункты списка — одной
+грамматической формой, разделы одного вида — одним порядком, заголовки одного
+уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
+ищет её.
+
+**Заголовок работает.** Заголовок называет содержание раздела, а не тему
+вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
+столько, чтобы длинный текст можно было просматривать, а не только читать
+подряд.
+
+## Что отброшено намеренно
+
+Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
+читают потому, что надо, и держать его нечем. Отсюда три расхождения:
+
+- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
+  ломает причинную связь, а в решении и в задаче ценность именно в ней:
+  «поэтому», «иначе», «раз так» несут смысл и остаются.
+- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
+  «в отличие от» — это условия и противопоставления, то есть сведения. Режутся
+  вводные, которые не меняют смысл предложения.
+- **Скобки и точка с запятой остаются.** В технической записи скобки несут
+  уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
+  не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
+  «дописать позже», и такой текст лучше не публиковать.
+
+И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
+читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
+значит называть состояние и остаток, а не пересказывать, как было интересно
+разбираться.
+
+## Англицизмы
+
+Англицизм-калька заменяется, когда у него есть естественный русский аналог.
+
+<!-- дом: язык-англицизмы -->
+
+| Калька | Русский аналог |
+| --- | --- |
+| флоу | поток, процесс, сценарий |
+| фикс, зафиксить | исправление, исправить, починить |
+| чекать | проверять |
+| апрув, заапрувить | согласование, согласовать |
+| best-effort | по возможности |
+| кейс | случай, сценарий |
+| перформанс | производительность |
+| матчинг, смэтчить | сопоставление, сопоставить |
+| зарелизить | выпустить, выложить |
+| отрефакторить | переписать, разделить, убрать второй путь |
+
+Насильно не переводится то, что является **именем вещи**: термины технологий и
+протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
+таблиц и команд, слаг, а также термин, у которого нет точного русского
+эквивалента и который в команде уже прижился.
+
+Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
+искажает смысл — остаётся термин.
+
+<!-- /дом: язык-англицизмы -->
+
+## Жаргон и метафоры
+
+Система не описывается внутренними метафорами и образными ярлыками: автору они
+понятны, читателю — нет. Вещь называется прямо.
+
+<!-- дом: язык-жаргон -->
+
+| Метафора-жаргон | Прямо |
+| --- | --- |
+| рычаг (кэша, отбора) | условие отбора, параметр |
+| навешен не на тот счётчик | завязан не на тот счётчик |
+| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
+| костыль | временное решение, обходной путь — и в чём именно |
+| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
+
+Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
+описанием того, что происходит.**
+
+<!-- /дом: язык-жаргон -->
+
+## Термин, которого нет в проекте
+
+Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
+**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
+— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
+через квартал.
+
+Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
+непонятного слова, потому что выглядит понятной.
+
+## Порог правки
+
+**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
+звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
+перестают читать весь список, и вместе с ним пропадают настоящие находки.
+Сомневаешься — не правь.
+
+И обратное: язык правится **по ходу той операции, которая записи касается**.
+Беклог не переписывают ради языка.