dev-skills/av-dev/shared/language.md

Язык проектных текстов

Это дом. Файл не принадлежит ни одному скиллу: язык общий для документов канона, для задач и для решений ADR, и хранить его внутри одного из них значило бы отдать общее правило во владение части. Скиллы читают этот файл по ссылке; дословные копии, помеченные разметкой copies.py, уезжают только в уставы вычитки — там текст обязан лежать внутри самого промпта, потому что именно он и есть критерий суждения. Расхождение ловит гейт коммита, а не внимание.

Правится здесь. Копия, поправленная у себя, — расхождение, а не правка.

Два блока копируются, и делятся они по потребителю, а не по теме:

Блок	Что в нём	Кто копирует
язык-правила	правила, по которым судят текст	уставы вычитки
порог-правки	когда находка не заводится	уставы вычитки, task-form

порог-правки вынесен из правил намеренно: он нужен и тому, кто правил языка не проверяет вовсе, — а вложенных блоков разметка не знает, и внутри язык-правила его было бы не забрать отдельно.

Правила — для всего, что пишется словами в этом плагине: задачи, документы канона, решения ADR, записки разведки. Не для кода и не для сообщений программы пользователю — там свои конвенции проекта.

Сообщения коммитов сюда не входят, и это названо намеренно. Их форму держит отдельный плагин av-dev-git, скилл commit, и она с этими правилами расходится по существу: там предписан результат страдательным залогом («добавлены», «обновлено»), здесь — действие активным. Расхождение осознанное: строка коммита отвечает на «что стало», а не на «что я сделал», и читают её в git log подряд сотнями. Объявлять юрисдикцию над чужим плагином, до которого отсюда нет и ссылки, значило бы завести правило, нарушение которого никто не увидит.

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

Зачем он здесь

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

Образец: научно-популярная книга

Так, как пишут хорошую научно-популярную книгу. Не спецификация, не статья в блоге, не конспект для себя: текст, который объясняет устройство точными простыми словами и понятен с первого прохода тому, кто эту систему не писал.

Из образца следуют три умолчания, и все три — про плотность, а не про красоту:

• воды нет. Каждая фраза несёт сведение: что устроено так, почему так и что из этого следует. Абзац, из которого ничего нельзя достать, вычёркивается целиком, а не переписывается;
• сложных конструкций нет. Причастный оборот внутри придаточного, три отрицания подряд, предложение на пять строк — читатель разбирает такую фразу дважды, и второй раз он её уже не разбирает. Причинную связь при этом не режут: «поэтому», «иначе», «раз так» — сведения;
• англицизм — исключение, требующее причины. Умолчание обратное принятому в разработке: пишем по-русски, а иностранное слово остаётся, только когда оно имя вещи или когда русский аналог искажает смысл. Какая причина годится, разбирает правило 5; закрытый список принятых слов — правило 6.

Термин здесь не запрещён — запрещена перегрузка: термин, который вводится одной строкой, дешевле описания в три предложения, а термин, который предполагается известным, дороже обоих (правило 8).

Образец находок не порождает. Он для того, кто пишет; вычитка судит по правилам, и правка без нарушенного правила не делается (раздел «Порог правки»). Иначе «мне кажется, звучит сложно» стало бы находкой, и список замечаний перестали бы читать целиком.

Что взято сверх правил вычитки

Эти три требования судит человек, а не проход вычитки: находка по ним требует увидеть текст целиком, а не фразу.

Полезное действие. У каждого текста есть вопрос, на который он отвечает, и читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это «зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его собственный вопрос («что это за система», «как сложено», «почему так решили»). Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный исход правки.

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

Заголовок работает. Заголовок называет содержание раздела, а не тему вообще: «Что проверяет 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. Транслит нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках, коммитах и путях, которые набирают руками. Переименование — перенос ссылок одним проходом, а не правка одного файла.

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

    Сослаться можно двумя способами, и ни один не стареет:

    Как	Пример
    на конкретную запись — именем, слагом, датой	«ревью от 3 августа», adr/0007-queue-as-table.md, capability recognition
    на корпус целиком	«ревью проекта», «capability, объявленные в openspec/specs/»

    Величина нужна читателю редко, а когда нужна — её называет сам корпус в момент чтения: каталог, индекс, команда. Абзац её только запоминает.

    Замер с названным происхождением — не счёт корпуса. «Прозаический триггер дал 6 записей ADR на 43 изменения» описывает прошлое, а прошлое не пополняется: это факт по правилу 2, и трогать его нельзя. Разница проверяется вопросом «изменится ли число само, без правки текста».

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

Порог правки

Правка без нарушенного правила не делается. Текст, переписанный «чтобы звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, перестают читать весь список, и вместе с ним пропадают настоящие находки. Сомневаешься — не правь. Формулировка, которая просто не твоя, — не находка.

Систематичность нарушения — не довод в его пользу. Одна и та же ошибка в пяти файлах не становится «принятым стилем»: чаще это значит, что правило не применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как основание для одной находки на весь набор («правило N нарушено в пяти записях, перечень: …»), но не как основание промолчать. Принятым считается только то, что назвал зовущий или что записано в конвенциях проекта.

И обратное: язык правится по ходу той операции, которая записи касается. Беклог не переписывают ради языка.

Доклад вычитки

Не правило языка, а контракт прохода: форма, в которой находка приходит к человеку. Живёт здесь потому, что проходов вычитки два — doc-wording по документам и task-wording по записям задач, — и разойтись формой они не должны.

Находки по одной, в порядке важности: залог и оценки → жаргон и англицизмы → стоп-слова. Первые меняют, что читатель понимает; последние — только сколько он на это тратит.

<файл>
  правило: <номер и короткое имя>
  сейчас: <как написано>
  предложение: <готовая формулировка, подставляемая как есть>
  почему: <одна фраза>

В конце — границы покрытия: сколько файлов просмотрено из скольких, какие не смотрел и почему, и по чему проверялись термины (документы проекта названы или нет). Отчёт без этой строки читается как «всё вычитано», не сообщая, какая часть осталась нетронутой. Туда же — строка «замечено не по моей части»; машинно проверяемое в неё не идёт.

Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия полезнее выдуманной находки.