From ca71838037af4ba5cded9ccfee57043feadd7cac Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Tue, 4 Aug 2026 19:38:50 +0300 Subject: [PATCH] =?UTF-8?q?=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=20=D0=B2=D1=8B?= =?UTF-8?q?=D1=87=D0=B8=D1=82=D0=BA=D0=B8=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B8?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D0=BE=D0=B2=D0=B0=D0=BD=20=D0=B2=20doc-wordi?= =?UTF-8?q?ng=20=D0=B8=20=D1=80=D0=B0=D1=81=D1=88=D0=B8=D1=80=D0=B5=D0=BD?= =?UTF-8?q?=20=D0=BD=D0=B0=20=D0=B2=D1=81=D0=B5=20=D0=B4=D0=BE=D0=BA=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Имя пришло из задач, но правила языка относятся ко всем проектным текстам: документам канона, решениям ADR, запискам разведки. Форма записи — вторая половина устава — верна только для файлов docs/tasks/items/, и теперь это сказано заголовком раздела, а не подразумевается. Вход расширен: список файлов или каталог, вперемешку тоже. Обкатка на тестовом наборе из 13 записей показала дыру в пороге вмешательства. Агент нашёл, что раздел «Затрагивает» в нескольких записях называет не только границу, но и её будущее состояние, — и промолчал, объяснив это принятым стилем каталога. Записи писал один агент за один заход: систематичность здесь значит ровно обратное — правило не применялось вовсе. В устав добавлено: одна и та же ошибка в пяти файлах даёт одну находку на весь набор с перечнем, но не даёт права промолчать. Принятым стилем считается только то, что назвал зовущий или что записано в конвенциях проекта. Единственная находка агента попала в слово из собственного скилла. «Цель про станок, а не про игру» — метафора, перенесённая в тестовую запись из tasks/SKILL.md. Проверка показала худшее: «станок» в каноне уже занят, «общий станок» это красная проверка, врывающаяся в замороженный спринт (canon.md, session/SKILL.md). Одно слово в двух смыслах, тот же класс, что и «окружение» в теме 19. Заменено на «работа над инструментом и процессом» — как названа и секция роадмапа. DECISIONS тема 22 (ППП, РРР, следствия 89–90). Co-Authored-By: Claude Opus 5 (1M context) --- DECISIONS.md | 42 +++++++++++++++++- README.md | 2 +- TODO.md | 2 +- .../{task-wording.md => doc-wording.md} | 43 ++++++++++++------- av-dev-pm/skills/canon/SKILL.md | 2 +- .../skills/canon/references/changelog.md | 4 +- av-dev-pm/skills/tasks/SKILL.md | 11 +++-- .../skills/tasks/references/task-format.md | 2 +- 8 files changed, 81 insertions(+), 27 deletions(-) rename av-dev-pm/agents/{task-wording.md => doc-wording.md} (75%) diff --git a/DECISIONS.md b/DECISIONS.md index 35e0914..6dd74c1 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1486,7 +1486,7 @@ SSS: рубрика на узел без нового понятия порож беклог, заведённый до правила, переоформляют не «заодно» — десятки одинаковых строк научили бы пропускать весь блок. -**ЗЗЗ. Годность формулировки судит отдельный агент `task-wording`, а не чек-лист +**ЗЗЗ. Годность формулировки судит отдельный агент `doc-wording`, а не чек-лист в скилле.** Самопроверка текста слабее всего там, где формулировка казалась удачной при написании, — а пишет и проверяет иначе один и тот же агент в одном контексте. Агент читает пачку записей и возвращает **готовые формулировки на @@ -1595,3 +1595,43 @@ ADR, запискам разведки и сообщениям коммитов записан: прочитать и ничего не переписывать задним числом. Сплошная вычитка старых документов стоит дороже, чем даёт, а правила применяются к тому, что правится сейчас. + +## 22. Обкатка агента вычитки: имя, охват и «так везде» (2026-08-04) + +### Что было + +Агента вычитки прогнали по тестовому набору — 13 записей выдуманного проекта. +Устав он читал сам, как обычный подрядчик. + +### Решено + +**ППП. Агент называется `doc-wording`, а не `task-wording`.** Имя пришло из +задач, но правила языка относятся ко всем проектным текстам: документам канона, +решениям ADR, запискам разведки. Форма записи — вторая половина устава — верна +только для файлов `docs/tasks/items/`, и теперь это сказано заголовком раздела, +а не подразумевается. Вход агента расширен: список файлов или каталог, вперемешку +тоже. + +**РРР. «Так сделано везде» — не оправдание, а признак.** Агент нашёл, что раздел +«Затрагивает» в нескольких записях называет не только границу, но и её будущее +состояние («источник хода становится двумя»), — и **промолчал**, объяснив это +принятым стилем каталога. Записи писал один агент за один заход: систематичность +здесь значит ровно обратное — правило не применялось вовсе. + +В устав добавлено: одна и та же ошибка в пяти файлах даёт **одну находку на весь +набор** с перечнем, но не даёт права промолчать. Принятым стилем считается +только то, что назвал зовущий или что записано в конвенциях проекта. + +### Что из этого следует + +89. **Находка агента попала в слово из собственного скилла.** «Цель про станок, + а не про игру» — метафора, которую я перенёс в тестовую запись из + `tasks/SKILL.md`. Проверка показала худшее: `станок` в каноне уже занят — + «общий станок» это красная проверка, врывающаяся в замороженный спринт + (`canon.md`, `session/SKILL.md`). Одно слово в двух смыслах, тот же класс, + что и `окружение` в теме 19. В `tasks/SKILL.md` заменено на «работа над + инструментом и процессом» — как названа и секция роадмапа. +90. **Одна находка на 13 записей — не провал вычитки.** Тексты писались сразу по + правилам, и находить в них было почти нечего. Показательно другое: агент + удержал порог (вкусовых правок не предложил) и явно сказал, по чему проверял + термины, — то есть отработали обе защиты, а не только та, что ищет. diff --git a/README.md b/README.md index b5397cb..a8f0108 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка архитектуры; - `tasks` — задачи и цели каталогом markdown-файлов; вычитку формулировок - ведёт отдельный агент `task-wording`; + ведёт отдельный агент `doc-wording`; - `session` — ритуал между спринтами и ведение спринта. - **av-dev-pipeline** — исполнение. **Требует OpenSpec.** - `task-pipeline` — задача через полный цикл SDD, от постановки до коммита; diff --git a/TODO.md b/TODO.md index d62f621..107af53 100644 --- a/TODO.md +++ b/TODO.md @@ -179,5 +179,5 @@ jellybit 43. Шаги повышения — [changelog.md](av-dev-pm/skills/can отбивку после заголовков и сведёт секцию в мете файлов с заголовками. Секции беклога переименовать руками — имена выбирал проект (тема 20, ККК) - [ ] заголовки задач в форму действия — **не задним числом**: по мере попадания - задачи в работу. `check` печатает их число, `task-wording` предложит + задачи в работу. `check` печатает их число, `doc-wording` предложит формулировки пачкой (тема 20, ЕЕЕ) diff --git a/av-dev-pm/agents/task-wording.md b/av-dev-pm/agents/doc-wording.md similarity index 75% rename from av-dev-pm/agents/task-wording.md rename to av-dev-pm/agents/doc-wording.md index 3e80a35..387ac31 100644 --- a/av-dev-pm/agents/task-wording.md +++ b/av-dev-pm/agents/doc-wording.md @@ -1,34 +1,38 @@ --- -name: task-wording -description: "Вычитка формулировок задач, целей и идей по информационному стилю: форма заголовка по типу записи (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), отглагольные существительные и страдательный залог, оценка без факта, стоп-слова и канцелярит, англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта, «зачем», пересказывающее заголовок вместо состояния и боли, «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах. Отдаёт готовые формулировки на замену и ничего не правит сам. Использовать после заведения или разбора пачки записей и на переоценке. Только чтение." +name: doc-wording +description: "Вычитка формулировок проектных текстов по информационному стилю: документы канона, решения ADR, записки разведки, задачи и цели. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта. У записей каталога задач — дополнительно форму заголовка по типу (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), «зачем», пересказывающее заголовок вместо состояния и боли, «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах. Отдаёт готовые формулировки на замену и ничего не правит сам. Использовать после заведения или разбора пачки записей, после правки документов канона и на переоценке. Только чтение." tools: Read, Grep, Glob model: sonnet color: green --- -Ты — **вычитка формулировок** каталога задач. Оптика — язык записи, а не работа, -которую она описывает: ты не судишь, нужна ли задача, правильно ли выбрана цель и -достаточно ли её декомпозиции. +Ты — **вычитка формулировок** проектных текстов: документов канона, решений ADR, +записок разведки, задач и целей. Оптика — язык, а не то, что текст описывает: ты +не судишь, верно ли решение, нужна ли задача и достаточно ли её декомпозиции. Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену, -которую зовущий подставит командой (`edit <слаг> --title …`, `--why …`) или -впишет в тело. Файлы ты только читаешь. +которую зовущий подставит командой (у задач — `edit <слаг> --title …`, `--why …`) +или впишет сам. Файлы ты только читаешь. ## Что тебе дают -Список файлов записей (`items/.md`) или каталог задач целиком. Плюс, если -зовущий их назвал, документы проекта — паспорт, архитектура, конвенции: по ним -проверяется, известен ли термин. **Не назвали — считай известными только те -слова, что встречаются в других записях того же каталога**, и говори об этом в -границах покрытия. +Список файлов или каталог. Это могут быть записи каталога задач +(`docs/tasks/items/.md`), документы канона (`docs/*.md`), решения в +`docs/adr/`, записки в `docs/research/` — вперемешку тоже. + +Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура, +конвенции: по ним проверяется, известен ли термин. **Не назвали — считай +известными только те слова, что встречаются в других поданных файлах**, и говори +об этом в границах покрытия. ## Правила -Две группы: **форма записи** — то, что верно только для каталога задач; **язык** -— общее для всех проектных текстов, информационный стиль. У каждого правила -названа причина: она же говорит, где правило **не** применяется. +Две группы. **Язык** — общее для любого проектного текста, применяется всегда. +**Форма записи** — только для файлов каталога задач; на документ канона эти +правила не переносятся, у него своя форма. У каждого правила названа причина: +она же говорит, где правило **не** применяется. -### Форма записи +### Форма записи — только для `docs/tasks/items/` 1. **Форма заголовка по типу записи.** @@ -161,6 +165,13 @@ color: green ## Порог вмешательства +**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в +пяти файлах не становится «принятым стилем каталога»: чаще это значит, что +правило не применялось вовсе, — и находка тем важнее. «Так сделано везде» +годится как **основание для одной находки на весь набор** («правило N нарушено в +пяти записях, перечень: …»), но не как основание промолчать. Принятым стилем +считается только то, что назвал зовущий или что записано в конвенциях проекта. + **Правка без нарушенного правила не пишется.** Список, в котором половина — вкусовые переформулировки, перестают читать целиком, и вместе с ним пропадают настоящие находки. Сомневаешься — не пиши. Формулировка, которая просто **не diff --git a/av-dev-pm/skills/canon/SKILL.md b/av-dev-pm/skills/canon/SKILL.md index 212492b..efc9d5a 100644 --- a/av-dev-pm/skills/canon/SKILL.md +++ b/av-dev-pm/skills/canon/SKILL.md @@ -24,7 +24,7 @@ description: Привести проект к канону документов информационный стиль, применённый к проектным текстам, таблицы англицизмов и жаргона. Раскладка отвечает, где текст лежит, — этот файл отвечает, каким он должен быть. Правила общие для документов канона, задач, решений ADR и - записок разведки. + записок разведки; вычитывает их отдельным проходом агент `doc-wording`. - [references/changelog.md](references/changelog.md) — журнал версий канона. ## Три правила, из которых всё следует diff --git a/av-dev-pm/skills/canon/references/changelog.md b/av-dev-pm/skills/canon/references/changelog.md index 90fddad..f71309d 100644 --- a/av-dev-pm/skills/canon/references/changelog.md +++ b/av-dev-pm/skills/canon/references/changelog.md @@ -43,7 +43,7 @@ upgrade` идёт по записям снизу вверх от версии п символы»), цель — на «что приложение будет уметь», идея просто называет, о чём она. `check` считает заголовки не в форме действия и печатает число в блоке здоровья. Годность формулировки — не машине: её смотрит новый агент - `task-wording` (вычитка формулировок, только чтение). + `doc-wording` (вычитка формулировок, только чтение). 5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех индексах. Написание канонических секций и отбивку правит `check --fix`; он же сводит написание секции в мете файла с заголовком индекса. @@ -108,7 +108,7 @@ upgrade` идёт по записям снизу вверх от версии п секцию в мете файлов с заголовками индексов. Секции беклога проект переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе. 11. Переписать заголовки задач в форму действия — по мере того, как задача - попадает в работу, а не «заодно»: `check` печатает их число, а `task-wording` + попадает в работу, а не «заодно»: `check` печатает их число, а `doc-wording` предложит формулировки на замену пачкой. 12. Прочитать [language.md](language.md) — и **ничего не переписывать задним числом**. Правила языка применяются к тому, что пишется и правится сейчас; diff --git a/av-dev-pm/skills/tasks/SKILL.md b/av-dev-pm/skills/tasks/SKILL.md index d9f76fc..0c3abc9 100644 --- a/av-dev-pm/skills/tasks/SKILL.md +++ b/av-dev-pm/skills/tasks/SKILL.md @@ -173,8 +173,9 @@ stateDiagram-v2 только, чтобы формулировка отвечала на «что приложение делает», а не на «какую часть кода мы трогаем». -**Что целью не является — работа над станком.** Инструмент, процесс, сборка, -сам этот скилл: на вопрос «что приложение будет уметь» они не отвечают. Им +**Что целью не является — работа над инструментом и процессом.** Сборка, +проверки, сам этот скилл: на вопрос «что приложение будет уметь» они не +отвечают. Им отведена отдельная секция роадмапа, чтобы они были видны в том же экране и при этом не читались как возможности продукта. @@ -472,9 +473,11 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап ### Вычитка формулировок -Язык записей судит **отдельный проход** — агент `task-wording`, а не тот же +Язык записей судит **отдельный проход** — агент `doc-wording`, а не тот же агент, который их только что написал: самопроверка текста слабее всего ровно -там, где формулировка казалась удачной при написании. +там, где формулировка казалась удачной при написании. Агент общий для всех +проектных текстов (отсюда имя), а форма записи — половина его устава, которая +включается только на файлах `items/`. Зовётся он **пачкой, а не на каждую запись**: после заведения нескольких задач, после разбора находок ревью и на переоценке. Ему передаётся список файлов и — diff --git a/av-dev-pm/skills/tasks/references/task-format.md b/av-dev-pm/skills/tasks/references/task-format.md index b119be5..42dfe3a 100644 --- a/av-dev-pm/skills/tasks/references/task-format.md +++ b/av-dev-pm/skills/tasks/references/task-format.md @@ -45,7 +45,7 @@ «Не отбрасывать молча лишние символы»); цель — на «что приложение будет уметь»; идея просто называет, о чём она. Почему так — SKILL.md, «Как написана задача». `check` считает заголовки не в форме действия и печатает число в - здоровье; годность формулировки смотрит агент `task-wording`. + здоровье; годность формулировки смотрит агент `doc-wording`. - **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна секция, причина после тире желательна (именно она объясняет, почему задача здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги