From c669215fc8a3518ce73b9c227001ee05ed07dc93 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 9 Aug 2026 13:49:21 +0300 Subject: [PATCH] =?UTF-8?q?=D1=8F=D0=B7=D1=8B=D0=BA=20=D1=83=D0=B5=D1=85?= =?UTF-8?q?=D0=B0=D0=BB=20=D0=B2=20shared:=20=D0=B4=D0=BE=D0=BC=20=D0=B2?= =?UTF-8?q?=D0=BD=D0=B5=20=D0=BF=D0=BB=D0=B0=D0=B3=D0=B8=D0=BD=D0=BE=D0=B2?= =?UTF-8?q?,=20=D1=83=D1=81=D1=82=D0=B0=D0=B2=20=D0=B2=D1=8B=D1=87=D0=B8?= =?UTF-8?q?=D1=82=D0=BA=D0=B8=20=E2=80=94=20=D0=BA=D0=BE=D0=BF=D0=B8=D1=8F?= =?UTF-8?q?=20=D1=86=D0=B5=D0=BB=D0=B8=D0=BA=D0=BE=D0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Дом языка лежал в av-dev-pm/skills/canon/references/language.md — внутри одного скилла одного плагина. Пока плагин был один, это читалось как «дом рядом с главным потребителем». Разделение на самодостаточные docs и tasks превращает то же место в утверждение, что язык принадлежит канону: плагин задач, поставленный без канона, потерял бы правила письма вместе с ним. Дом переехал в shared/ и не принадлежит ни одному плагину, плагины везут дословные копии. Самодостаточность держится копией, а не ссылкой: shared/ нужен этому репозиторию, а не установленному плагину. Устав вычитки стал копией целиком. doc-wording копировал из дома англицизмы, словарь, жаргон и порог правки — четыре блока; девять правил он излагал своими словами, и эти слова с домом никто не сверял. Там дрейф и копился молча: в доме правило «одна мысль — одно предложение» требовало выносить придаточное, в уставе — не резать причинную связь, и каждая версия выглядела полной. Из десяти правил машина сверяла четыре, теперь сверяет все. Условие переезда: текст правил написан безлично, а всё, обращённое к проходу («пиши так-то», «про это молчи»), вынесено из блока в раздел «Что из этих правил докладывается особым образом». Правило принадлежит дому, способ доложить о нём — уставу. Блоков три, и делятся они по потребителю, а не по теме: язык-доктрина (зачем стиль, полезное действие, параллельность, заголовок, что отброшено), язык-правила (девять правил с тремя таблицами), порог-правки. Порог оставлен отдельным потому, что его берёт task-form, который правил языка не проверяет вовсе; вложенных блоков copies.py не знает, и внутри язык-правила забрать порог было бы нечем. Потребители собраны из дома скриптом, а не руками. Домов 6 вместо 7 — три таблицы слились в язык-правила; копий 9 вместо 8. Гейт зелёный: копии, фронтматтеры, диаграммы. Решение — 49. Co-Authored-By: Claude Opus 5 (1M context) --- DECISIONS.md | 40 +++ README.md | 8 + av-dev-pm/agents/doc-wording.md | 170 +++++++------ av-dev-pm/agents/task-form.md | 2 +- av-dev-pm/skills/canon/references/language.md | 227 +++++++++--------- shared/language.md | 226 +++++++++++++++++ 6 files changed, 481 insertions(+), 192 deletions(-) create mode 100644 shared/language.md diff --git a/DECISIONS.md b/DECISIONS.md index 27e4292..5a7d5c6 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3127,3 +3127,43 @@ JJJ): у профиля обязан быть один правильный от точно говорит, могла ли измениться дорогая величина. Так дорогая проверка остаётся редкой и при этом не забытой. + +## 49. Дом общего правила вышел из плагина (2026-08-09) + +**АЕАКА. Язык уехал в `shared/`, потому что общее правило не может принадлежать +половине.** Дом языка лежал в `av-dev-pm/skills/canon/references/language.md` — +внутри одного скилла одного плагина. Пока плагин был один, это читалось как «дом +рядом с главным потребителем». Разделение на самодостаточные `docs` и `tasks` +превращает то же место в утверждение, что язык принадлежит канону: плагин задач, +поставленный без канона, потерял бы правила письма вместе с ним. Дом переехал в +`shared/` и не принадлежит ни одному плагину, а плагины везут дословные копии. +Самодостаточность держится **копией, а не ссылкой**: `shared/` нужен этому +репозиторию, а не установленному плагину. + +**АЕАКБ. Устав вычитки стал копией целиком, а не четырьмя таблицами из десяти.** +`doc-wording` копировал из дома англицизмы, словарь, жаргон и порог правки — +четыре блока; девять правил он излагал своими словами, и эти слова с домом никто +не сверял. Там дрейф и копился молча: в доме правило «одна мысль — одно +предложение» требовало выносить придаточное, в уставе — не резать причинную +связь, и каждая версия выглядела полной. Теперь блок один, `язык-правила`, и +берётся он целиком. Условие переезда: текст правил написан безлично, а всё, +обращённое к проходу («пиши так-то», «про это молчи»), вынесено из блока в свой +раздел устава. **Правило принадлежит дому, способ доложить о нём — уставу.** + +**АЕАКВ. `порог-правки` остался отдельным блоком, и это следствие разметки, а не +вкуса.** Его берёт `task-form`, который правил языка не проверяет вовсе. +Вложенных блоков `copies.py` не знает — лежи порог внутри `язык-правила`, забрать +его отдельно было бы нечем, и `task-form` вёз бы весь устав чужого прохода. +Разрез домов идёт **по потребителю, а не по теме**: три блока вместо одного +стоят двух лишних маркеров и снимают ложную зависимость. + +### Что из этого следует + +171. **Общее правило не хранится внутри одного из тех, кто им пользуется.** Пока + пользователь один, дом рядом с ним выглядит удобством; со вторым + пользователем то же место начинает утверждать, что правило принадлежит + первому. +172. **Пересказ своими словами — это копия, которую никто не сверяет.** Блок, + взятый целиком, читается дороже, но расхождение в нём ловит машина; + сокращённое изложение экономит строки и платит молчаливым дрейфом. + diff --git a/README.md b/README.md index 518772f..7672fef 100644 --- a/README.md +++ b/README.md @@ -236,6 +236,7 @@ claude plugin uninstall <плагин>@av-dev-skills --scope project /skills//references/ что читается по ссылке из скилла /skills//scripts/ tasks.py, docs.py /agents/ charter'ы сабагентов +shared/ дома правил, общих для нескольких плагинов scripts/ проверки репозитория: копии, диаграммы, фронтматтеры pyproject.toml линтеры скриптов, только для этого репозитория lefthook.yml гейт коммита: проверки документов @@ -311,6 +312,13 @@ uv run python scripts/copies.py # 0 сошлось, 1 расхождение сверку не входят. Маркер, уехавший в проект вместе со скелетом, там полезен: он говорит, что у текста есть дом и правится он там. +**Дом правила, общего для нескольких плагинов, лежит в `shared/` и ни одному из +них не принадлежит.** Так живёт язык проектных текстов: он одинаково нужен +документам канона и задачам, и хранить его внутри одного плагина значило бы +отдать общее правило во владение половине. Плагин везёт копию и потому остаётся +самодостаточным — `shared/` нужен этому репозиторию, а не установленному +плагину. + Скрипт ловит четыре вещи: копия разошлась с домом (с диффом), копия указывает не на тот файл, дом остался без копий, разметка сломана. Чего он **не** ловит — копию, которую забыли пометить: помечать — по-прежнему решение человека. diff --git a/av-dev-pm/agents/doc-wording.md b/av-dev-pm/agents/doc-wording.md index 94bc008..ffdb167 100644 --- a/av-dev-pm/agents/doc-wording.md +++ b/av-dev-pm/agents/doc-wording.md @@ -25,7 +25,7 @@ color: green Список файлов или каталог: документы канона (`docs/*.md`), решения в `docs/adr/`, записки в `docs/research/`, записи каталога задач -(`docs/tasks/items/.md`) — вперемешку тоже. +(`items/.md`) — вперемешку тоже. Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура, конвенции: по ним проверяется, известен ли термин. **Не назвали — считай @@ -34,9 +34,13 @@ color: green ## Правила -Дом — `av-dev-pm/skills/canon/references/language.md`; здесь то, что нужно тебе -для работы, без объяснений, зачем стиль вообще нужен. У каждого правила названа -причина: она же говорит, где правило **не** применяется. +Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем +стиль вообще нужен. Здесь только то, что нужно тебе для работы. + + + +У каждого правила названа причина: она же говорит, где правило **не** +применяется. 1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик не проверяет владельца», а не «проверка владельца не осуществляется»; @@ -60,106 +64,110 @@ color: green Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут - условие и противопоставление, то есть сведения, — их не трогай. + условие и противопоставление, то есть сведения, — их не трогают. 4. **Одна мысль — одно предложение.** Предложение с двумя независимыми - утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз + утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз так» — смысл, а не длина; рубленые фразы ради краткости тут вредят. **Поля меты не делятся.** «Зачем» в мете задачи по формату — одно предложение: оно повторяется строкой индекса, и второму там не поместиться. - Тесно — сокращай, но не дели. То же с любым полем вида `- **Имя:** …`. + Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`. 5. **Англицизм, у которого есть живое русское слово, заменяется.** - + | Калька | Русский аналог | + | --- | --- | + | флоу | поток, процесс, сценарий | + | фикс, зафиксить | исправление, исправить, починить | + | чекать | проверять | + | апрув, заапрувить | согласование, согласовать | + | best-effort | по возможности | + | кейс | случай, сценарий | + | перформанс | производительность | + | матчинг, смэтчить | сопоставление, сопоставить | + | зарелизить | выпустить, выложить | + | отрефакторить | переписать, разделить, убрать второй путь | -| Калька | Русский аналог | -| --- | --- | -| флоу | поток, процесс, сценарий | -| фикс, зафиксить | исправление, исправить, починить | -| чекать | проверять | -| апрув, заапрувить | согласование, согласовать | -| best-effort | по возможности | -| кейс | случай, сценарий | -| перформанс | производительность | -| матчинг, смэтчить | сопоставление, сопоставить | -| зарелизить | выпустить, выложить | -| отрефакторить | переписать, разделить, убрать второй путь | + Насильно не переводится то, что является **именем вещи**: термины технологий + и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, + полей, таблиц и команд, слаг, а также термин, у которого нет точного русского + эквивалента и который в команде уже прижился. -Насильно не переводится то, что является **именем вещи**: термины технологий и -протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей, -таблиц и команд, слаг, а также термин, у которого нет точного русского -эквивалента и который в команде уже прижился. + Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или + искажает смысл — остаётся термин. -Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или -искажает смысл — остаётся термин. +6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин + прижился» без списка проверяема на глаз и потому не проверяема: прижившимся + выглядит любое слово, встреченное трижды. - + | Термин | Что называет | + | --- | --- | + | интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции | + | триаж | стадия конвейера, сводящая находки в решение | + | провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство | + | дедуп, дедупликация | сверка нового против уже лежащего | + | чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки | + | дифф, `--base` | разница между состояниями в git | + | промпт | текст, которым зовут модель | + | change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента | + | generative, applicative | роды проходов ревью, вводятся определением по месту | -6. **Слово из своего словаря не трогается — список закрыт.** + **Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, + а не «принятый стиль»: у него либо есть живой русский аналог, либо оно + требует ввода одной строкой при первом употреблении. - -| Термин | Что называет | -| --- | --- | -| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции | -| триаж | стадия конвейера, сводящая находки в решение | -| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство | -| дедуп, дедупликация | сверка нового против уже лежащего | -| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки | -| дифф, `--base` | разница между состояниями в git | -| промпт | текст, которым зовут модель | -| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента | -| generative, applicative | роды проходов ревью, вводятся определением по месту | + Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не + надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с + кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный + набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом + русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то + есть выглядело словарём, не будучи им. -**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а -не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует -ввода одной строкой при первом употреблении. +7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен, + читателю — нет. -Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо: -**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то), -**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд** -(руководство). Каждое было латинизмом или калькой при живом русском слове, и -каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело -словарём, не будучи им. + | Метафора-жаргон | Прямо | + | --- | --- | + | рычаг (кэша, отбора) | условие отбора, параметр | + | навешен не на тот счётчик | завязан не на тот счётчик | + | переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | + | костыль | временное решение, обходной путь — и в чём именно | + | просело, отвалилось | стало медленнее на столько-то, перестало отвечать | - - -7. **Жаргон и метафоры заменяются прямым называнием.** - - - -| Метафора-жаргон | Прямо | -| --- | --- | -| рычаг (кэша, отбора) | условие отбора, параметр | -| навешен не на тот счётчик | завязан не на тот счётчик | -| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | -| костыль | временное решение, обходной путь — и в чём именно | -| просело, отвалилось | стало медленнее на столько-то, перестало отвечать | - -Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным -описанием того, что происходит.** - - + Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется + буквальным описанием того, что происходит.** 8. **Термин, которого нет в документах проекта, вводится одной строкой или не - употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную - область. Пиши «термин «X» не встречается ни в документах, ни в других - поданных файлах — введи строкой или назови известным словом». + употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни + в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ + сделать беклог нечитаемым для того, кто вернётся к нему через квартал. + Заменять незнакомый термин догадкой нельзя: догадка о предметной области + дороже непонятного слова, потому что выглядит понятной. - **Слово, занятое в другом смысле, — та же находка.** Термин, который в одном - документе проекта значит одно, а здесь другое, ломает оба; назови оба места. + **Слово, занятое в другом смысле, — то же нарушение.** Термин, который в + одном документе проекта значит одно, а здесь другое, ломает оба. 9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках, - коммитах и путях, которые набирают руками. + коммитах и путях, которые набирают руками. Переименование — **перенос ссылок + одним проходом**, а не правка одного файла. - Кириллицу в имени и не-kebab-case ловят `docs.py` и `tasks.py` — про них - молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и - ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовое - английское имя на замену плюс напоминание, что переименование это **перенос - ссылок одним проходом**, а не правка одного файла. + + +### Что из этих правил докладывается особым образом + +**Правило 8, неизвестный термин.** Своей догадки не подставляй — ты не знаешь +предметную область. Пиши «термин «X» не встречается ни в документах, ни в других +поданных файлах — введи строкой или назови известным словом». Слово, занятое в +другом смысле, — та же находка, и в ней **называются оба места**. + +**Правило 9, имя файла.** Кириллицу в имени и не-kebab-case ловят `docs.py` и +`tasks.py` — про них молчи. Твоё — **транслит**, потому что машина проверяет его +эвристикой и ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — +готовое английское имя на замену плюс напоминание про перенос ссылок одним +проходом. ## Чего ты не проверяешь @@ -181,9 +189,13 @@ color: green **Содержание**: верно ли решение, нужна ли задача, полна ли архитектура. Это разбор, а не вычитка, — и о нём тоже молчи. +**Полезное действие, параллельность и работающий заголовок** — тоже не твои. +Они в доктрине языка, судит их человек: находка по ним требует увидеть текст +целиком, а не фразу. + ## Порог вмешательства - + **Правка без нарушенного правила не делается.** Текст, переписанный «чтобы звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, diff --git a/av-dev-pm/agents/task-form.md b/av-dev-pm/agents/task-form.md index 8be5c80..4b4fbf0 100644 --- a/av-dev-pm/agents/task-form.md +++ b/av-dev-pm/agents/task-form.md @@ -143,7 +143,7 @@ color: green ## Порог вмешательства - + **Правка без нарушенного правила не делается.** Текст, переписанный «чтобы звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, diff --git a/av-dev-pm/skills/canon/references/language.md b/av-dev-pm/skills/canon/references/language.md index d442985..71f0ea3 100644 --- a/av-dev-pm/skills/canon/references/language.md +++ b/av-dev-pm/skills/canon/references/language.md @@ -1,13 +1,18 @@ # Язык проектных текстов -Правила для всего, что пишется словами: задачи и цели, документы канона, +**Копия.** Дом — `shared/language.md` в репозитории плагинов; язык общий для +документов канона и для задач, и потому не принадлежит ни одному плагину. +Правится дом, а не этот файл: расхождение ловит `copies.py` на гейте коммита. + + + +Правила — для всего, что пишется словами: задачи и цели, документы канона, решения ADR, записки разведки, сообщения коммитов. Не для кода и не для сообщений программы пользователю — там свои конвенции проекта. Основа — **информационный стиль** Максима Ильяхова ([учебник бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он -написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что -взято и что отброшено намеренно. +написан для рекламы, статей и писем, поэтому взят не целиком. ## Зачем он здесь @@ -18,7 +23,10 @@ эстетическая: текст, из которого нельзя достать факт, заставляет открывать код, а это и есть цена, которой мы избегаем. -## Что взято +## Что взято сверх правил вычитки + +Эти три требования судит человек, а не проход вычитки: находка по ним требует +увидеть текст целиком, а не фразу. **Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это @@ -27,43 +35,6 @@ Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный исход правки. -**Глагол вместо отглагольного существительного, действие вместо состояния.** -«Обработчик не проверяет владельца», а не «проверка владельца не -осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по -имени». Отглагольное существительное прячет того, кто действует, — а в -техническом тексте именно он и важен. - -**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается -скриптом». Страдательный залог остаётся там, где деятель неизвестен или -неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх -команд. - -**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до -800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а -не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит -факт. Без факта оценка — не сведение, а настроение. - -**Стоп-слова.** Убирается то, что можно убрать без потери смысла: - -| Что | Примеры | -| --- | --- | -| канцелярит | является, осуществляется, в целях, в рамках, данный, вышеуказанный, необходимо отметить | -| вводные-паразиты | в общем, как известно, стоит отметить, не секрет, что | -| усилители | очень, крайне, достаточно, абсолютно, максимально, полностью | -| синонимы одного качества | «понятный и простой», «быстрый и производительный» | -| неопределённое | какой-то, некоторый, соответствующий, определённый | - -Проверка одна: **вычеркни слово. Смысл изменился — оставляй.** - -**Одна мысль — одно предложение.** Предложение, в котором два независимых -утверждения, делится. Придаточное, которое можно вынести в отдельную фразу, -выносится. - -Исключение — **поля, которым формат отвёл одно предложение**. «Зачем» в мете -задачи именно такое: оно повторяется строкой индекса, и второе предложение там -просто не поместится. Такое поле либо укладывается в одну фразу, либо -сокращается, но не делится. - **Параллельность.** Однородное пишется одинаково: пункты списка — одной грамматической формой, разделы одного вида — одним порядком, заголовки одного уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и @@ -95,100 +66,132 @@ значит называть состояние и остаток, а не пересказывать, как было интересно разбираться. -## Англицизмы + -Англицизм-калька заменяется, когда у него есть естественный русский аналог. +## Правила - + -| Калька | Русский аналог | -| --- | --- | -| флоу | поток, процесс, сценарий | -| фикс, зафиксить | исправление, исправить, починить | -| чекать | проверять | -| апрув, заапрувить | согласование, согласовать | -| best-effort | по возможности | -| кейс | случай, сценарий | -| перформанс | производительность | -| матчинг, смэтчить | сопоставление, сопоставить | -| зарелизить | выпустить, выложить | -| отрефакторить | переписать, разделить, убрать второй путь | +У каждого правила названа причина: она же говорит, где правило **не** +применяется. -Насильно не переводится то, что является **именем вещи**: термины технологий и -протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей, -таблиц и команд, слаг, а также термин, у которого нет точного русского -эквивалента и который в команде уже прижился. +1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик + не проверяет владельца», а не «проверка владельца не осуществляется»; + «скрипт переписывает индекс», а не «индекс переписывается скриптом». + Отглагольное существительное прячет того, кто действует, — а в техническом + тексте важен именно он. Страдательный залог **остаётся**, когда деятель + неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх + команд. -Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или -искажает смысл — остаётся термин. +2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает + медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела + тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без + факта это настроение, а не сведение, — и находка тем ценнее, что оценку + потом не проверить. - +3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках, + данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит + отметить), усилители (очень, крайне, достаточно, абсолютно, максимально), + синонимы одного качества («понятный и простой»), неопределённое + (соответствующий, определённый, некоторый). -## Свой словарь — закрытый список + Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с + вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут + условие и противопоставление, то есть сведения, — их не трогают. -Слово, не переводимое потому, что оно **имя вещи этого процесса**, а не украшение. -Оговорка «термин прижился» без списка проверяема на глаз и потому не проверяема: -прижившимся выглядит любое слово, встреченное трижды. +4. **Одна мысль — одно предложение.** Предложение с двумя независимыми + утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз + так» — смысл, а не длина; рубленые фразы ради краткости тут вредят. - -| Термин | Что называет | -| --- | --- | -| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции | -| триаж | стадия конвейера, сводящая находки в решение | -| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство | -| дедуп, дедупликация | сверка нового против уже лежащего | -| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки | -| дифф, `--base` | разница между состояниями в git | -| промпт | текст, которым зовут модель | -| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента | -| generative, applicative | роды проходов ревью, вводятся определением по месту | + **Поля меты не делятся.** «Зачем» в мете задачи по формату — одно + предложение: оно повторяется строкой индекса, и второму там не поместиться. + Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`. -**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а -не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует -ввода одной строкой при первом употреблении. +5. **Англицизм, у которого есть живое русское слово, заменяется.** -Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо: -**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то), -**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд** -(руководство). Каждое было латинизмом или калькой при живом русском слове, и -каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело -словарём, не будучи им. + | Калька | Русский аналог | + | --- | --- | + | флоу | поток, процесс, сценарий | + | фикс, зафиксить | исправление, исправить, починить | + | чекать | проверять | + | апрув, заапрувить | согласование, согласовать | + | best-effort | по возможности | + | кейс | случай, сценарий | + | перформанс | производительность | + | матчинг, смэтчить | сопоставление, сопоставить | + | зарелизить | выпустить, выложить | + | отрефакторить | переписать, разделить, убрать второй путь | - + Насильно не переводится то, что является **именем вещи**: термины технологий + и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, + полей, таблиц и команд, слаг, а также термин, у которого нет точного русского + эквивалента и который в команде уже прижился. -## Жаргон и метафоры + Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или + искажает смысл — остаётся термин. -Система не описывается внутренними метафорами и образными ярлыками: автору они -понятны, читателю — нет. Вещь называется прямо. +6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин + прижился» без списка проверяема на глаз и потому не проверяема: прижившимся + выглядит любое слово, встреченное трижды. - + | Термин | Что называет | + | --- | --- | + | интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции | + | триаж | стадия конвейера, сводящая находки в решение | + | провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство | + | дедуп, дедупликация | сверка нового против уже лежащего | + | чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки | + | дифф, `--base` | разница между состояниями в git | + | промпт | текст, которым зовут модель | + | change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента | + | generative, applicative | роды проходов ревью, вводятся определением по месту | -| Метафора-жаргон | Прямо | -| --- | --- | -| рычаг (кэша, отбора) | условие отбора, параметр | -| навешен не на тот счётчик | завязан не на тот счётчик | -| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | -| костыль | временное решение, обходной путь — и в чём именно | -| просело, отвалилось | стало медленнее на столько-то, перестало отвечать | + **Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, + а не «принятый стиль»: у него либо есть живой русский аналог, либо оно + требует ввода одной строкой при первом употреблении. -Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным -описанием того, что происходит.** + Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не + надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с + кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный + набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом + русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то + есть выглядело словарём, не будучи им. - +7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен, + читателю — нет. -## Термин, которого нет в проекте + | Метафора-жаргон | Прямо | + | --- | --- | + | рычаг (кэша, отбора) | условие отбора, параметр | + | навешен не на тот счётчик | завязан не на тот счётчик | + | переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | + | костыль | временное решение, обходной путь — и в чём именно | + | просело, отвалилось | стало медленнее на столько-то, перестало отвечать | -Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях, -**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи -— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему -через квартал. + Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется + буквальным описанием того, что происходит.** -Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже -непонятного слова, потому что выглядит понятной. +8. **Термин, которого нет в документах проекта, вводится одной строкой или не + употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни + в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ + сделать беклог нечитаемым для того, кто вернётся к нему через квартал. + Заменять незнакомый термин догадкой нельзя: догадка о предметной области + дороже непонятного слова, потому что выглядит понятной. + + **Слово, занятое в другом смысле, — то же нарушение.** Термин, который в + одном документе проекта значит одно, а здесь другое, ломает оба. + +9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а + не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит + нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках, + коммитах и путях, которые набирают руками. Переименование — **перенос ссылок + одним проходом**, а не правка одного файла. + + ## Порог правки - + **Правка без нарушенного правила не делается.** Текст, переписанный «чтобы звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, @@ -202,7 +205,7 @@ записях, перечень: …»), но не как основание промолчать. Принятым считается только то, что назвал зовущий или что записано в конвенциях проекта. - + И обратное: язык правится **по ходу той операции, которая записи касается**. Беклог не переписывают ради языка. diff --git a/shared/language.md b/shared/language.md new file mode 100644 index 0000000..c0dfb62 --- /dev/null +++ b/shared/language.md @@ -0,0 +1,226 @@ +# Язык проектных текстов + +**Это дом.** Файл не входит ни в один плагин: язык общий для документов канона и +для задач, и хранить его внутри одного из них значило бы отдать общее правило во +владение половине. Плагины везут **копии**, помеченные разметкой `copies.py`, и +расхождение ловит гейт коммита, а не внимание. + +Правится **здесь**. Копия, поправленная у себя, — расхождение, а не правка. + +Три блока, и делятся они по потребителю, а не по теме: + +| Блок | Что в нём | Кто копирует | +| --- | --- | --- | +| `язык-доктрина` | зачем стиль нужен, что взято сверх устава, что отброшено | справочник языка в плагине | +| `язык-правила` | девять правил, по которым судят текст | справочник и уставы вычитки | +| `порог-правки` | когда находка не заводится | справочник, уставы вычитки, `task-form` | + +`порог-правки` вынесен из правил намеренно: он нужен и тому, кто правил языка не +проверяет вовсе, — а вложенных блоков разметка не знает, и внутри `язык-правила` +его было бы не забрать отдельно. + + + +Правила — для всего, что пишется словами: задачи и цели, документы канона, +решения ADR, записки разведки, сообщения коммитов. Не для кода и не для +сообщений программы пользователю — там свои конвенции проекта. + +Основа — **информационный стиль** Максима Ильяхова ([учебник +бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он +написан для рекламы, статей и писем, поэтому взят не целиком. + +## Зачем он здесь + +Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли +задачу**, глядя в строку индекса и один экран тела; и **возвращаются через +квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не +несущие сведений. Информационный стиль ровно про это, и его польза здесь не +эстетическая: текст, из которого нельзя достать факт, заставляет открывать код, +а это и есть цена, которой мы избегаем. + +## Что взято сверх правил вычитки + +Эти три требования судит человек, а не проход вычитки: находка по ним требует +увидеть текст целиком, а не фразу. + +**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и +читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это +«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его +собственный вопрос («что это за система», «как сложено», «почему так решили»). +Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный +исход правки. + +**Параллельность.** Однородное пишется одинаково: пункты списка — одной +грамматической формой, разделы одного вида — одним порядком, заголовки одного +уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и +ищет её. + +**Заголовок работает.** Заголовок называет содержание раздела, а не тему +вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится +столько, чтобы длинный текст можно было просматривать, а не только читать +подряд. + +## Что отброшено намеренно + +Инфостиль написан для текстов, где читателя надо удержать. Проектный текст +читают потому, что надо, и держать его нечем. Отсюда три расхождения: + +- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так» + ломает причинную связь, а в решении и в задаче ценность именно в ней: + «поэтому», «иначе», «раз так» несут смысл и остаются. +- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии», + «в отличие от» — это условия и противопоставления, то есть сведения. Режутся + вводные, которые не меняют смысл предложения. +- **Скобки и точка с запятой остаются.** В технической записи скобки несут + уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а + не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит + «дописать позже», и такой текст лучше не публиковать. + +И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь +читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них +значит называть состояние и остаток, а не пересказывать, как было интересно +разбираться. + + + +## Правила + + + +У каждого правила названа причина: она же говорит, где правило **не** +применяется. + +1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик + не проверяет владельца», а не «проверка владельца не осуществляется»; + «скрипт переписывает индекс», а не «индекс переписывается скриптом». + Отглагольное существительное прячет того, кто действует, — а в техническом + тексте важен именно он. Страдательный залог **остаётся**, когда деятель + неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх + команд. + +2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает + медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела + тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без + факта это настроение, а не сведение, — и находка тем ценнее, что оценку + потом не проверить. + +3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках, + данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит + отметить), усилители (очень, крайне, достаточно, абсолютно, максимально), + синонимы одного качества («понятный и простой»), неопределённое + (соответствующий, определённый, некоторый). + + Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с + вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут + условие и противопоставление, то есть сведения, — их не трогают. + +4. **Одна мысль — одно предложение.** Предложение с двумя независимыми + утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз + так» — смысл, а не длина; рубленые фразы ради краткости тут вредят. + + **Поля меты не делятся.** «Зачем» в мете задачи по формату — одно + предложение: оно повторяется строкой индекса, и второму там не поместиться. + Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`. + +5. **Англицизм, у которого есть живое русское слово, заменяется.** + + | Калька | Русский аналог | + | --- | --- | + | флоу | поток, процесс, сценарий | + | фикс, зафиксить | исправление, исправить, починить | + | чекать | проверять | + | апрув, заапрувить | согласование, согласовать | + | best-effort | по возможности | + | кейс | случай, сценарий | + | перформанс | производительность | + | матчинг, смэтчить | сопоставление, сопоставить | + | зарелизить | выпустить, выложить | + | отрефакторить | переписать, разделить, убрать второй путь | + + Насильно не переводится то, что является **именем вещи**: термины технологий + и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, + полей, таблиц и команд, слаг, а также термин, у которого нет точного русского + эквивалента и который в команде уже прижился. + + Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или + искажает смысл — остаётся термин. + +6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин + прижился» без списка проверяема на глаз и потому не проверяема: прижившимся + выглядит любое слово, встреченное трижды. + + | Термин | Что называет | + | --- | --- | + | интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции | + | триаж | стадия конвейера, сводящая находки в решение | + | провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство | + | дедуп, дедупликация | сверка нового против уже лежащего | + | чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки | + | дифф, `--base` | разница между состояниями в git | + | промпт | текст, которым зовут модель | + | change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента | + | generative, applicative | роды проходов ревью, вводятся определением по месту | + + **Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, + а не «принятый стиль»: у него либо есть живой русский аналог, либо оно + требует ввода одной строкой при первом употреблении. + + Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не + надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с + кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный + набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом + русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то + есть выглядело словарём, не будучи им. + +7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен, + читателю — нет. + + | Метафора-жаргон | Прямо | + | --- | --- | + | рычаг (кэша, отбора) | условие отбора, параметр | + | навешен не на тот счётчик | завязан не на тот счётчик | + | переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | + | костыль | временное решение, обходной путь — и в чём именно | + | просело, отвалилось | стало медленнее на столько-то, перестало отвечать | + + Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется + буквальным описанием того, что происходит.** + +8. **Термин, которого нет в документах проекта, вводится одной строкой или не + употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни + в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ + сделать беклог нечитаемым для того, кто вернётся к нему через квартал. + Заменять незнакомый термин догадкой нельзя: догадка о предметной области + дороже непонятного слова, потому что выглядит понятной. + + **Слово, занятое в другом смысле, — то же нарушение.** Термин, который в + одном документе проекта значит одно, а здесь другое, ломает оба. + +9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а + не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит + нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках, + коммитах и путях, которые набирают руками. Переименование — **перенос ссылок + одним проходом**, а не правка одного файла. + + + +## Порог правки + + + +**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы +звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, +перестают читать весь список, и вместе с ним пропадают настоящие находки. +Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка. + +**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в +пяти файлах не становится «принятым стилем»: чаще это значит, что правило не +применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как +основание для **одной находки на весь набор** («правило N нарушено в пяти +записях, перечень: …»), но не как основание промолчать. Принятым считается +только то, что назвал зовущий или что записано в конвенциях проекта. + + + +И обратное: язык правится **по ходу той операции, которая записи касается**. +Беклог не переписывают ради языка.