diff --git a/DECISIONS.md b/DECISIONS.md index a541266..35e0914 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1530,3 +1530,68 @@ SSS: рубрика на узел без нового понятия порож соперника), но не мерджится порознь: без сильного соперника выбирать не из чего. Тест декомпозиции её отбил — частичный ответ на вопрос «не выродились ли цели в ярлыки тем». + +## 21. Язык проектных текстов — информационный стиль (2026-08-04) + +### Что было + +Языковые правила лежали внутри скилла `tasks`, в разделе «Как написана задача»: +англицизмы, неизвестные термины, «сложность формулировки — не признак сложности +работы». Три пункта, выведенные из практики, без общей опоры и без ответа на +вопрос «а что ещё сюда относится». + +Дал ссылку на чужой скилл `prepare-jira-text` — там раздел «Язык» с +информационным стилем, таблицей англицизмов-калек и таблицей жаргона. Заодно +попросил найти справку об информационном стиле Максима Ильяхова и адаптировать +его. + +### Решено + +**ЛЛЛ. У языка появился один дом — `canon/references/language.md`.** Не в +`tasks`, хотя пришёл он оттуда: правила относятся к документам канона, решениям +ADR, запискам разведки и сообщениям коммитов в той же мере, что к задачам, а +каталог задач и сам часть `docs/`. Раскладка отвечает, **где** текст лежит; +этот файл — **каким он должен быть**. `tasks/SKILL.md` оставил у себя четыре +правила, которые нарушаются чаще прочих, и ссылку. + +**МММ. Инфостиль взят не целиком, и отброшенное названо вслух.** Он написан для +рекламы, статей и писем — текстов, где читателя надо удержать; проектный текст +читают потому, что надо. Взято: полезное действие, глагол вместо отглагольного +существительного, активный залог, факт вместо оценки, стоп-слова, +«одна мысль — одно предложение», параллельность, работающий заголовок. +Отброшено: **парцелляция** (рубленые фразы ломают причинную связь, а в решении +ценность именно в ней), **запрет вводных целиком** («если», «иначе», «в отличие +от» — это условия, то есть сведения), **запрет скобок и точки с запятой** (в +технической записи скобки несут уточнение — имя команды, единицы, слаг). +Многоточие запрещено: в проектном тексте оно значит «дописать позже». + +Раздел «Что отброшено намеренно» написан не для полноты. Без него правило +читается как «пиши короче», и первый же агент начинает резать «поэтому» и +«иначе» — то есть ровно то, ради чего текст и писался. + +**ННН. «Снять корону» переведено на здешнего читателя.** У Ильяхова это «надеть +корону на клиента». Здесь клиент — **ты сам через квартал** и тот, кто возьмёт +задачу. Отсюда конкретное требование: называть состояние и остаток, а не +пересказывать, как было интересно разбираться. + +**ООО. Таблицы англицизмов и жаргона уехали в агента помеченной копией.** Устав +агента обязан быть самодостаточным — он не разрешает пути плагина и не ходит по +ссылкам, — а два дома у одного правила уже трижды расходились. Механизм для +этого в репозитории есть (`scripts/copies.py`), и это ровно его случай: копия +дословная и помеченная, проверка ловит расхождение. + +### Что из этого следует + +86. **У агента вычитки правил стало двенадцать, и они разделены на две группы.** + «Форма записи» верна только для каталога задач, «язык» — для любого + проектного текста. Разделение не косметическое: находки докладываются + группами и в этом порядке, потому что форма меняет решение «брать или не + брать», а язык — только цену чтения. +87. **Порог правки записан дважды и одинаково** — в `language.md` и в уставе + агента: правка без нарушенного правила не делается. Это единственная защита + от списка, в котором половина замечаний вкусовые: такой список перестают + читать целиком, и настоящие находки пропадают вместе с ним. +88. **Переезд на канон 3 языком ничего не требует.** Шаг в changelog так и + записан: прочитать и ничего не переписывать задним числом. Сплошная вычитка + старых документов стоит дороже, чем даёт, а правила применяются к тому, что + правится сейчас. diff --git a/README.md b/README.md index 3921605..b5397cb 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ - `init` — новый проект: интервью по свободному описанию замысла → первичная документация; - `canon` — привести проект к канону документов: `check` / `adopt` / - `upgrade`, плюс скрипт `docs.py`; + `upgrade`, плюс скрипт `docs.py`. Там же живёт язык проектных текстов — + информационный стиль, англицизмы, жаргон; - `docs` — содержимое канона по ходу разработки: ADR из архивного `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка архитектуры; diff --git a/av-dev-pm/agents/task-wording.md b/av-dev-pm/agents/task-wording.md index cf72629..3e80a35 100644 --- a/av-dev-pm/agents/task-wording.md +++ b/av-dev-pm/agents/task-wording.md @@ -1,6 +1,6 @@ --- name: task-wording -description: "Вычитка формулировок задач, целей и идей: форма заголовка по типу записи (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), англицизм при живом русском слове, термин, которого нет в документах проекта, «зачем», пересказывающее заголовок вместо состояния и боли, «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах. Отдаёт готовые формулировки на замену и ничего не правит сам. Использовать после заведения или разбора пачки записей и на переоценке. Только чтение." +description: "Вычитка формулировок задач, целей и идей по информационному стилю: форма заголовка по типу записи (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), отглагольные существительные и страдательный залог, оценка без факта, стоп-слова и канцелярит, англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта, «зачем», пересказывающее заголовок вместо состояния и боли, «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах. Отдаёт готовые формулировки на замену и ничего не правит сам. Использовать после заведения или разбора пачки записей и на переоценке. Только чтение." tools: Read, Grep, Glob model: sonnet color: green @@ -24,8 +24,11 @@ color: green ## Правила -Проверяешь семь, и у каждого своя причина — она объясняет, где правило **не** -применяется. +Две группы: **форма записи** — то, что верно только для каталога задач; **язык** +— общее для всех проектных текстов, информационный стиль. У каждого правила +названа причина: она же говорит, где правило **не** применяется. + +### Форма записи 1. **Форма заголовка по типу записи.** @@ -49,31 +52,103 @@ color: green отбрасывать молча лишние символы» — пересказ: читающий узнаёт то же самое дважды и по-прежнему не знает, почему это лежит в беклоге. -3. **Англицизм, у которого есть живое русское слово, заменяется.** Не - «зафиксить флоу», а «починить порядок доставки»; не «отрефакторить», а - «убрать второй путь приёма». **Не трогай** то, что является именем вещи: слаг, - имя пакета, команда, тип в коде, устоявшийся термин предметной области. - -4. **Термин, которого нет в документах проекта, вводится одной строкой или не - употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную - область. Пиши «термин «X» не встречается ни в документах, ни в других - записях — введи строкой или назови известным словом». - -5. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть +3. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть внешняя сторона: команда и её аргументы, эндпоинт, таблица и миграция, формат на диске, публичный тип пакета, внешний сервис. «Переписать хранилище на новый драйвер» — замысел; проверяется вопросом «это можно назвать до того, как решено *как* делать?». Свойства репозитория (номер миграции, версия зависимости, хеш) — тоже находка: они протухают молча. -6. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на +4. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на утверждение, которого глазами не проверить («компьютер не проигрывает ни в одной партии»), — находка: слово стоит, проверки нет. Число критериев считает `check`, тебе оно неинтересно. -7. **Предписания процесса в теле нет.** «Делать профилем standard», «взять такой-то +5. **Предписания процесса в теле нет.** «Делать профилем standard», «взять такой-то агент» — это выбор, который делают, увидев изменение, а не при постановке. +### Язык + +Дом этих правил — `av-dev-pm/skills/canon/references/language.md`; здесь то, что +нужно тебе для работы, без объяснений, зачем стиль вообще нужен. + +6. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик + не проверяет владельца», а не «проверка владельца не осуществляется»; + «скрипт переписывает индекс», а не «индекс переписывается скриптом». + Отглагольное существительное прячет того, кто действует, — а в техническом + тексте важен именно он. Страдательный залог **остаётся**, когда деятель + неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх + команд. + +7. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает + медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела + тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без + факта это настроение, а не сведение, — и находка тем ценнее, что оценку + потом не проверить. + +8. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках, + данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит + отметить), усилители (очень, крайне, достаточно, абсолютно, максимально), + синонимы одного качества («понятный и простой»), неопределённое + (соответствующий, определённый, некоторый). + + Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с + вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут + условие и противопоставление, то есть сведения, — их не трогай. + +9. **Одна мысль — одно предложение.** Предложение с двумя независимыми + утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз + так» — смысл, а не длина; рубленые фразы ради краткости тут вредят. + +10. **Англицизм, у которого есть живое русское слово, заменяется.** + + + +| Калька | Русский аналог | +| --- | --- | +| флоу | поток, процесс, сценарий | +| фикс, зафиксить | исправление, исправить, починить | +| чекать | проверять | +| апрув, заапрувить | согласование, согласовать | +| best-effort | по возможности | +| кейс | случай, сценарий | +| перформанс | производительность | +| матчинг, смэтчить | сопоставление, сопоставить | +| зарелизить | выпустить, выложить | +| отрефакторить | переписать, разделить, убрать второй путь | + +Насильно не переводится то, что является **именем вещи**: термины технологий и +протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей, +таблиц и команд, слаг, а также термин, у которого нет точного русского +эквивалента и который в команде уже прижился. + +Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или +искажает смысл — остаётся термин. + + + +11. **Жаргон и метафоры заменяются прямым называнием.** + + + +| Метафора-жаргон | Прямо | +| --- | --- | +| рычаг (кэша, отбора) | условие отбора, параметр | +| навешен не на тот счётчик | завязан не на тот счётчик | +| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | +| костыль | временное решение, обходной путь — и в чём именно | +| просело, отвалилось | стало медленнее на столько-то, перестало отвечать | + +Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным +описанием того, что происходит.** + + + +12. **Термин, которого нет в документах проекта, вводится одной строкой или не + употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную + область. Пиши «термин «X» не встречается ни в документах, ни в других + записях — введи строкой или назови известным словом». + ## Чего ты не проверяешь Всё, что ловит `tasks.py check`: состав и написание секций, наличие разделов, @@ -96,8 +171,10 @@ color: green ## Доклад -Находки по одной, в порядке важности (заголовок → «зачем» → границы → критерии → -язык): +Находки по одной, в порядке важности: сперва **форма записи** (заголовок → +«зачем» → границы → критерии), потом **язык** (залог и оценки → жаргон и +англицизмы → стоп-слова). Порядок такой, потому что форма меняет решение «брать +или не брать», а язык — только цену чтения. ``` <файл> diff --git a/av-dev-pm/skills/canon/SKILL.md b/av-dev-pm/skills/canon/SKILL.md index 5b5d1d3..212492b 100644 --- a/av-dev-pm/skills/canon/SKILL.md +++ b/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) — журнал версий канона. ## Три правила, из которых всё следует diff --git a/av-dev-pm/skills/canon/references/canon.md b/av-dev-pm/skills/canon/references/canon.md index 64bca13..d3a5f64 100644 --- a/av-dev-pm/skills/canon/references/canon.md +++ b/av-dev-pm/skills/canon/references/canon.md @@ -17,6 +17,11 @@ Цена принята сознательно: плагин не переносится на чужой репозиторий как есть — чужой репозиторий **приводится** к канону скиллом `canon`. +Раскладка отвечает, **где** текст лежит и на какой вопрос отвечает. Каким он +должен быть **словами** — общий для всех документов канона файл +[language.md](language.md): информационный стиль, англицизмы, жаргон. Он +относится и к задачам, и к решениям ADR, и к запискам разведки. + ## Раскладка ``` diff --git a/av-dev-pm/skills/canon/references/changelog.md b/av-dev-pm/skills/canon/references/changelog.md index 085d2a3..90fddad 100644 --- a/av-dev-pm/skills/canon/references/changelog.md +++ b/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 diff --git a/av-dev-pm/skills/canon/references/language.md b/av-dev-pm/skills/canon/references/language.md new file mode 100644 index 0000000..f0db65b --- /dev/null +++ b/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`), имена классов, методов, полей, +таблиц и команд, слаг, а также термин, у которого нет точного русского +эквивалента и который в команде уже прижился. + +Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или +искажает смысл — остаётся термин. + + + +## Жаргон и метафоры + +Система не описывается внутренними метафорами и образными ярлыками: автору они +понятны, читателю — нет. Вещь называется прямо. + + + +| Метафора-жаргон | Прямо | +| --- | --- | +| рычаг (кэша, отбора) | условие отбора, параметр | +| навешен не на тот счётчик | завязан не на тот счётчик | +| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений | +| костыль | временное решение, обходной путь — и в чём именно | +| просело, отвалилось | стало медленнее на столько-то, перестало отвечать | + +Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным +описанием того, что происходит.** + + + +## Термин, которого нет в проекте + +Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях, +**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи +— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему +через квартал. + +Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже +непонятного слова, потому что выглядит понятной. + +## Порог правки + +**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы +звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, +перестают читать весь список, и вместе с ним пропадают настоящие находки. +Сомневаешься — не правь. + +И обратное: язык правится **по ходу той операции, которая записи касается**. +Беклог не переписывают ради языка. diff --git a/av-dev-pm/skills/tasks/SKILL.md b/av-dev-pm/skills/tasks/SKILL.md index 03000e3..d9f76fc 100644 --- a/av-dev-pm/skills/tasks/SKILL.md +++ b/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`, он не трогает намеренно. ### Гигиена полей