av/dev-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

язык уехал в shared: дом вне плагинов, устав вычитки — копия целиком

Browse Source 
Дом языка лежал в 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) <noreply@anthropic.com>
This commit is contained in:
av
2026-08-09 13:49:21 +03:00
co-authored by Claude Opus 5
parent 6ff12fedd5
commit c669215fc8
6 changed files with 481 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
av-dev-pm/agents/doc-wording.md
+91 -79
View File
@@ -25,7 +25,7 @@ color: green
Список файлов или каталог: документы канона (`docs/*.md`), решения в
`docs/adr/`, записки в `docs/research/`, записи каталога задач
(`docs/tasks/items/<slug>.md`) — вперемешку тоже.
(`items/<slug>.md`) — вперемешку тоже.
Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура,
конвенции: по ним проверяется, известен ли термин. **Не назвали — считай
@@ -34,9 +34,13 @@ color: green
## Правила
Дом — `av-dev-pm/skills/canon/references/language.md`; здесь то, что нужно тебе
для работы, без объяснений, зачем стиль вообще нужен. У каждого правила названа
причина: она же говорит, где правило **не** применяется.
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
<!-- копия: язык-правила из shared/language.md -->
У каждого правила названа причина: она же говорит, где правило **не**
применяется.
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
не проверяет владельца», а не «проверка владельца не осуществляется»;
@@ -60,106 +64,110 @@ color: green
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
условие и противопоставление, то есть сведения, — их не трогай.
условие и противопоставление, то есть сведения, — их не трогают.
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
предложение: оно повторяется строкой индекса, и второму там не поместиться.
Тесно — сокращай, но не дели. То же с любым полем вида `- **Имя:** …`.
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
5. **Англицизм, у которого есть живое русское слово, заменяется.**
<!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md -->
| Калька | Русский аналог |
| --- | --- |
| флоу | поток, процесс, сценарий |
| фикс, зафиксить | исправление, исправить, починить |
| чекать | проверять |
| апрув, заапрувить | согласование, согласовать |
| 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. **Слово из своего словаря не трогается — список закрыт.**
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
требует ввода одной строкой при первом употреблении.
<!-- копия: язык-словарь из av-dev-pm/skills/canon/references/language.md -->
| Термин | Что называет |
| --- | --- |
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
| триаж | стадия конвейера, сводящая находки в решение |
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
| дедуп, дедупликация | сверка нового против уже лежащего |
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
| дифф, `--base` | разница между состояниями в git |
| промпт | текст, которым зовут модель |
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
| generative, applicative | роды проходов ревью, вводятся определением по месту |
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
есть выглядело словарём, не будучи им.
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка, а
не «принятый стиль»: у него либо есть живой русский аналог, либо оно требует
ввода одной строкой при первом употреблении.
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
читателю — нет.
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не надо:
**конфляция** (смешение), **декорреляция** (разведённость, разведён с кем-то),
**непоймание** (почему не поймали), **эвал-сет** (проверочный набор), **гайд**
(руководство). Каждое было латинизмом или калькой при живом русском слове, и
каждое к моменту снятия жило в трёх-шести файлах разом — то есть выглядело
словарём, не будучи им.
| Метафора-жаргон | Прямо |
| --- | --- |
| рычаг (кэша, отбора) | условие отбора, параметр |
| навешен не на тот счётчик | завязан не на тот счётчик |
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
| костыль | временное решение, обходной путь — и в чём именно |
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
<!-- /копия: язык-словарь -->
7. **Жаргон и метафоры заменяются прямым называнием.**
<!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md -->
| Метафора-жаргон | Прямо |
| --- | --- |
| рычаг (кэша, отбора) | условие отбора, параметр |
| навешен не на тот счётчик | завязан не на тот счётчик |
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
| костыль | временное решение, обходной путь — и в чём именно |
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
описанием того, что происходит.**
<!-- /копия: язык-жаргон -->
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
буквальным описанием того, что происходит.**
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
**Содержание**: верно ли решение, нужна ли задача, полна ли архитектура. Это
разбор, а не вычитка, — и о нём тоже молчи.
**Полезное действие, параллельность и работающий заголовок** — тоже не твои.
Они в доктрине языка, судит их человек: находка по ним требует увидеть текст
целиком, а не фразу.
## Порог вмешательства
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
<!-- копия: порог-правки из shared/language.md -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
av-dev-pm/agents/task-form.md
+1 -1
View File
@@ -143,7 +143,7 @@ color: green
## Порог вмешательства
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
<!-- копия: порог-правки из shared/language.md -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,