avandClaude Opus 5
6609012696
В уставе стоял заголовок «Форма записи — только для docs/tasks/items/»: условная половина, которая на документе канона молчит, а на задаче включается. Условное правило агент применяет по своему усмотрению, а усмотрение и есть то, чего от него не ждут. Два коротких устава без условий надёжнее одного длинного с ними. Разделены не по охвату — по глубине. Язык проверяется по словам и фразам, поштучно: залог, оценки, стоп-слова, англицизмы, жаргон. Форма записи требует понять, что задача делает, и открыть файл цели, на которую она ссылается, чтобы сверить, какую строку «Завершения» задача двигает. Слитый проход одну половину делает дорогой, а вторую — поверхностной. Отсюда и разные модели: doc-wording на sonnet, task-form на opus. Первый подметает, второй судит смысл, и ровно на суждении обкатка показала провал. Каждый устав отказывается от чужой половины прямо: увиденное не по своей части идёт строкой в границах покрытия, а не находкой. Две проверки одного места расходятся и начинают спорить. Исключение ровно одно и названо: неудачное слово в заголовке судит task-form, потому что заголовок целиком его. У task-form появилось шестое правило, которого не было ни у кого: связь задачи со строкой «Завершения» её цели. Оно единственное читает больше одного файла и единственное смотрит набор, а не запись — строка «Завершения», к которой не относится ни одна поданная задача, докладывается отдельным блоком. Это граница между вычиткой и разбором, проведённая внутри правила. Порог правки переехал в language.md помеченным домом «порог-правки» и копируется в оба устава: правка без нарушенного правила не делается, систематичность нарушения — не довод в его пользу. Дублировать его руками значило бы получить два разных порога через месяц. Копий стало шесть при пяти домах. Порядок вызова — сперва task-form: его находки меняют решение «брать или не брать», а язык меняет только цену чтения. DECISIONS тема 23 (ССС–ФФФ, следствия 91–93). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
172 lines
13 KiB
Markdown
172 lines
13 KiB
Markdown
# Язык проектных текстов
|
|
|
|
Правила для всего, что пишется словами: задачи и цели, документы канона,
|
|
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
|
сообщений программы пользователю — там свои конвенции проекта.
|
|
|
|
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
|
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
|
написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что
|
|
взято и что отброшено намеренно.
|
|
|
|
## Зачем он здесь
|
|
|
|
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
|
|
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
|
|
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
|
|
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
|
|
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
|
а это и есть цена, которой мы избегаем.
|
|
|
|
## Что взято
|
|
|
|
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
|
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
|
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
|
|
собственный вопрос («что это за система», «как сложено», «почему так решили»).
|
|
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
|
исход правки.
|
|
|
|
**Глагол вместо отглагольного существительного, действие вместо состояния.**
|
|
«Обработчик не проверяет владельца», а не «проверка владельца не
|
|
осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по
|
|
имени». Отглагольное существительное прячет того, кто действует, — а в
|
|
техническом тексте именно он и важен.
|
|
|
|
**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается
|
|
скриптом». Страдательный залог остаётся там, где деятель неизвестен или
|
|
неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх
|
|
команд.
|
|
|
|
**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до
|
|
800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а
|
|
не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит
|
|
факт. Без факта оценка — не сведение, а настроение.
|
|
|
|
**Стоп-слова.** Убирается то, что можно убрать без потери смысла:
|
|
|
|
| Что | Примеры |
|
|
| --- | --- |
|
|
| канцелярит | является, осуществляется, в целях, в рамках, данный, вышеуказанный, необходимо отметить |
|
|
| вводные-паразиты | в общем, как известно, стоит отметить, не секрет, что |
|
|
| усилители | очень, крайне, достаточно, абсолютно, максимально, полностью |
|
|
| синонимы одного качества | «понятный и простой», «быстрый и производительный» |
|
|
| неопределённое | какой-то, некоторый, соответствующий, определённый |
|
|
|
|
Проверка одна: **вычеркни слово. Смысл изменился — оставляй.**
|
|
|
|
**Одна мысль — одно предложение.** Предложение, в котором два независимых
|
|
утверждения, делится. Придаточное, которое можно вынести в отдельную фразу,
|
|
выносится.
|
|
|
|
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
|
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
|
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
|
ищет её.
|
|
|
|
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
|
|
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
|
|
столько, чтобы длинный текст можно было просматривать, а не только читать
|
|
подряд.
|
|
|
|
## Что отброшено намеренно
|
|
|
|
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
|
|
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
|
|
|
|
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
|
|
ломает причинную связь, а в решении и в задаче ценность именно в ней:
|
|
«поэтому», «иначе», «раз так» несут смысл и остаются.
|
|
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
|
|
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
|
|
вводные, которые не меняют смысл предложения.
|
|
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
|
|
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
|
|
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
|
|
«дописать позже», и такой текст лучше не публиковать.
|
|
|
|
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
|
|
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
|
|
значит называть состояние и остаток, а не пересказывать, как было интересно
|
|
разбираться.
|
|
|
|
## Англицизмы
|
|
|
|
Англицизм-калька заменяется, когда у него есть естественный русский аналог.
|
|
|
|
<!-- дом: язык-англицизмы -->
|
|
|
|
| Калька | Русский аналог |
|
|
| --- | --- |
|
|
| флоу | поток, процесс, сценарий |
|
|
| фикс, зафиксить | исправление, исправить, починить |
|
|
| чекать | проверять |
|
|
| апрув, заапрувить | согласование, согласовать |
|
|
| best-effort | по возможности |
|
|
| кейс | случай, сценарий |
|
|
| перформанс | производительность |
|
|
| матчинг, смэтчить | сопоставление, сопоставить |
|
|
| зарелизить | выпустить, выложить |
|
|
| отрефакторить | переписать, разделить, убрать второй путь |
|
|
|
|
Насильно не переводится то, что является **именем вещи**: термины технологий и
|
|
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
|
|
таблиц и команд, слаг, а также термин, у которого нет точного русского
|
|
эквивалента и который в команде уже прижился.
|
|
|
|
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
|
искажает смысл — остаётся термин.
|
|
|
|
<!-- /дом: язык-англицизмы -->
|
|
|
|
## Жаргон и метафоры
|
|
|
|
Система не описывается внутренними метафорами и образными ярлыками: автору они
|
|
понятны, читателю — нет. Вещь называется прямо.
|
|
|
|
<!-- дом: язык-жаргон -->
|
|
|
|
| Метафора-жаргон | Прямо |
|
|
| --- | --- |
|
|
| рычаг (кэша, отбора) | условие отбора, параметр |
|
|
| навешен не на тот счётчик | завязан не на тот счётчик |
|
|
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
|
| костыль | временное решение, обходной путь — и в чём именно |
|
|
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
|
|
|
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
|
|
описанием того, что происходит.**
|
|
|
|
<!-- /дом: язык-жаргон -->
|
|
|
|
## Термин, которого нет в проекте
|
|
|
|
Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
|
|
**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
|
|
— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
|
|
через квартал.
|
|
|
|
Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
|
|
непонятного слова, потому что выглядит понятной.
|
|
|
|
## Порог правки
|
|
|
|
<!-- дом: порог-правки -->
|
|
|
|
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
|
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
|
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
|
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
|
|
|
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
|
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
|
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
|
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
|
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
|
только то, что назвал зовущий или что записано в конвенциях проекта.
|
|
|
|
<!-- /дом: порог-правки -->
|
|
|
|
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
|
Беклог не переписывают ради языка.
|