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

Языковые правила лежали внутри скилла 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/SKILL.md

@@ -20,6 +20,11 @@ description: Привести проект к канону документов
 - [references/skeletons.md](references/skeletons.md) — **что именно класть** в
   каждый незаполненный слот. Своей формой заглушку не выдумывай: `docs.py`
   узнаёт только плейсхолдер `<!-- заполнить: … -->` из шаблонов.
+- [references/language.md](references/language.md) — **как это написано словами**:
+  информационный стиль, применённый к проектным текстам, таблицы англицизмов и
+  жаргона. Раскладка отвечает, где текст лежит, — этот файл отвечает, каким он
+  должен быть. Правила общие для документов канона, задач, решений ADR и
+  записок разведки.
 - [references/changelog.md](references/changelog.md) — журнал версий канона.
 
 ## Три правила, из которых всё следует

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

@@ -17,6 +17,11 @@
 Цена принята сознательно: плагин не переносится на чужой репозиторий как есть —
 чужой репозиторий **приводится** к канону скиллом `canon`.
 
+Раскладка отвечает, **где** текст лежит и на какой вопрос отвечает. Каким он
+должен быть **словами** — общий для всех документов канона файл
+[language.md](language.md): информационный стиль, англицизмы, жаргон. Он
+относится и к задачам, и к решениям ADR, и к запискам разведки.
+
 ## Раскладка
 
 ```

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

@@ -47,7 +47,13 @@ upgrade` идёт по записям снизу вверх от версии п
 5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
    индексах. Написание канонических секций и отбивку правит `check --fix`; он
    же сводит написание секции в мете файла с заголовком индекса.
-6. **Умолчание профиля ревью сменилось** — это не раскладка, но проектный текст
+6. **Язык проектных текстов** — [language.md](language.md), общий дом для
+   документов канона, задач, решений ADR и записок разведки: информационный
+   стиль (глагол вместо отглагольного существительного, активный залог, факт
+   вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и
+   то, что из стиля отброшено намеренно. Проектных файлов не добавляет и
+   раскладку не меняет — это правила письма, а не новый слот.
+7. **Умолчание профиля ревью сменилось** — это не раскладка, но проектный текст
    под него уже написан. `standard` стал рабочим умолчанием: миграция схемы,
    публичный контракт и инвариант ступень больше **не** поднимают, `wide`
    означает новое понятие или структурную единицу. Подраздел «Триггеры профиля»
@@ -104,7 +110,10 @@ upgrade` идёт по записям снизу вверх от версии п
 11. Переписать заголовки задач в форму действия — по мере того, как задача
     попадает в работу, а не «заодно»: `check` печатает их число, а `task-wording`
     предложит формулировки на замену пачкой.
-12. `docs/.pm.json`: `"canon": 3`.
+12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
+    числом**. Правила языка применяются к тому, что пишется и правится сейчас;
+    сплошная вычитка старых документов стоит дороже, чем даёт.
+13. `docs/.pm.json`: `"canon": 3`.
 
 ## Версия 2 — 2026-08-03
 

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`), имена классов, методов, полей,
+таблиц и команд, слаг, а также термин, у которого нет точного русского
+эквивалента и который в команде уже прижился.
+
+Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
+искажает смысл — остаётся термин.
+
+<!-- /дом: язык-англицизмы -->
+
+## Жаргон и метафоры
+
+Система не описывается внутренними метафорами и образными ярлыками: автору они
+понятны, читателю — нет. Вещь называется прямо.
+
+<!-- дом: язык-жаргон -->
+
+| Метафора-жаргон | Прямо |
+| --- | --- |
+| рычаг (кэша, отбора) | условие отбора, параметр |
+| навешен не на тот счётчик | завязан не на тот счётчик |
+| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
+| костыль | временное решение, обходной путь — и в чём именно |
+| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
+
+Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
+описанием того, что происходит.**
+
+<!-- /дом: язык-жаргон -->
+
+## Термин, которого нет в проекте
+
+Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
+**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
+— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
+через квартал.
+
+Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
+непонятного слова, потому что выглядит понятной.
+
+## Порог правки
+
+**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
+звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
+перестают читать весь список, и вместе с ним пропадают настоящие находки.
+Сомневаешься — не правь.
+
+И обратное: язык правится **по ходу той операции, которая записи касается**.
+Беклог не переписывают ради языка.

av-dev-pm/skills/tasks/SKILL.md

@@ -295,16 +295,26 @@ stateDiagram-v2
 **Предметно, но без усложнения.** Текст задачи читает человек, который решает,
 брать её или нет, и делает это по строке индекса и одному экрану тела.
 
-- **англицизм, у которого есть русское слово, — заменяется**: не «зафиксить
-  флоу», а «починить порядок доставки»; не «отрефакторить», а «убрать второй
-  путь приёма». Английские остаются там, где они и есть имя вещи: слаг,
-  `capability`, имя пакета, команда, тип в коде.
-- **термин, которого нет в паспорте, архитектуре или конвенциях проекта, вводится
-  одной строкой** или не употребляется. Свой словарь у задачи — самый дешёвый
-  способ сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
-- **сложность формулировки — не признак сложности работы.** Задачу, которую не
-  удаётся сказать просто, чаще всего не удаётся и оценить: это либо две задачи,
-  либо идея.
+Язык — общий для всех проектных текстов, и живёт он одним файлом:
+[../canon/references/language.md](../canon/references/language.md)
+(информационный стиль, применённый к задачам и документам канона; там же таблицы
+англицизмов и жаргона и то, что из стиля отброшено намеренно). Задаче он даёт
+четыре требования, которые нарушаются чаще прочих:
+
+- **глагол вместо отглагольного существительного**: «обработчик не проверяет
+  владельца», а не «проверка владельца не осуществляется»;
+- **факт вместо оценки**: «время ответа доходит до 800 мс», а не «работает
+  медленно». Оценка без факта рядом — настроение, а не сведение;
+- **англицизм с живым русским аналогом заменяется**: не «зафиксить флоу», а
+  «починить порядок доставки». Имя вещи не переводится: слаг, команда, тип в
+  коде, `API`;
+- **термин не из документов проекта вводится одной строкой** или не
+  употребляется. Свой словарь у задачи — самый дешёвый способ сделать беклог
+  нечитаемым для того, кто вернётся к нему через квартал.
+
+И одно требование, которое есть только у задачи: **сложность формулировки — не
+признак сложности работы.** Задачу, которую не удаётся сказать просто, чаще
+всего не удаётся и оценить: это либо две задачи, либо идея.
 
 Эти правила — про **язык**, а не про объём: короткая задача без границ хуже
 длинной с ними.
@@ -477,9 +487,10 @@ python3 $tk adopt scan --from … | apply --plan …   # разовая адап
 менять их молча нельзя**: покажи предложенное пользователю вместе с тем, что
 было. Правки в теле (границы, критерии, язык) применяются сразу.
 
-Что он смотрит и чего не смотрит — в его уставе; коротко: форму заголовка по
-типу записи, «зачем» вместо пересказа, англицизмы, неизвестные термины, границы
-вместо замысла, годность оракулов, предписания процесса. Всё, что ловит
+Что он смотрит и чего не смотрит — в его уставе; коротко: **форму записи** —
+заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность
+оракулов, предписания процесса; и **язык** — залог и отглагольные, оценка без
+факта, стоп-слова, англицизмы, жаргон, неизвестные термины. Всё, что ловит
 `tasks.py check`, он не трогает намеренно.
 
 ### Гигиена полей