язык проектных текстов — один дом и информационный стиль
Языковые правила лежали внутри скилла tasks: англицизмы, неизвестные термины, «сложность формулировки — не признак сложности работы». Три пункта из практики, без общей опоры и без ответа на «а что ещё сюда относится». Дом у языка теперь один — canon/references/language.md. Не в tasks, хотя пришли правила оттуда: они относятся к документам канона, решениям ADR, запискам разведки и сообщениям коммитов в той же мере, что к задачам, а каталог задач и сам часть docs/. Раскладка отвечает, где текст лежит, — этот файл отвечает, каким он должен быть словами. Основа — информационный стиль Ильяхова, взятый не целиком. Взято: полезное действие, глагол вместо отглагольного существительного, активный залог, факт вместо оценки, стоп-слова, одна мысль — одно предложение, параллельность, работающий заголовок. Отброшенное названо вслух, и это отдельный раздел. Инфостиль написан для текстов, где читателя надо удержать, а проектный текст читают потому, что надо. Парцелляция ломает причинную связь, а в решении ценность именно в ней. Запрет вводных целиком режет «если» и «в отличие от» — условия, то есть сведения. Скобки в технической записи несут уточнение: имя команды, единицы, слаг. Без этого раздела правило читается как «пиши короче», и первый же агент начинает резать «поэтому» и «иначе». «Снять корону с себя и надеть на клиента» переведено на здешнего читателя: клиент — ты сам через квартал и тот, кто возьмёт задачу. Таблицы англицизмов и жаргона взяты из скилла prepare-jira-text и дополнены; в устав агента они уехали помеченной копией. Устав обязан быть самодостаточным — он не разрешает пути плагина и не ходит по ссылкам, — а два дома у одного правила здесь уже трижды расходились. scripts/copies.py считает теперь 4 копии при 4 домах. У агента вычитки правил стало двенадцать, разделены на форму записи (только для задач) и язык (для любого проектного текста). Находки докладываются в этом порядке: форма меняет решение «брать или не брать», язык — только цену чтения. DECISIONS тема 21 (ЛЛЛ–ООО, следствия 86–88), changelog канона v3 — пункт 6 и шаг переезда «прочитать и ничего не переписывать задним числом». Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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`, он не трогает намеренно.
|
||||
|
||||
### Гигиена полей
|
||||
|
||||
Reference in New Issue
Block a user