Compare commits

..
12 Commits
Author SHA1 Message Date
avandClaude Opus 5 8ce2a29160 уставы вычитки: оговорка про поля меты и два рода «не своего»
Обкатка обоих проходов на тестовом наборе нашла два расхождения в
правилах, которые я же и написал.

«Одна мысль — одно предложение» не распространяется на поля меты.
doc-wording предложил разбить «зачем» надвое, а task-format.md требует
от него одного предложения: оно повторяется строкой индекса, и второму
там не поместиться. Агент честно выполнил тот документ, который читал;
виновато правило без оговорки. Оговорка записана и в доме language.md, и
в уставе: тесно — сокращай, но не дели.

«Не своё» бывает двух родов. Чужому подрядчику — строкой в границах
покрытия, чтобы находка не пропала. Машинной проверке — вообще ничего,
даже строкой: это не потерянная находка, а уже проверенное. doc-wording
отправил в «замечено не по моей части» открытый вопрос в задаче, который
ловит tasks.py check, и строка получилась шумом, выглядящим как работа.
Разделение прописано в обоих уставах.

DECISIONS тема 24 (ХХХ, ЦЦЦ, следствия 94–95).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 19:58:28 +03:00
avandClaude Opus 5 6609012696 вычитка разделена на два прохода: task-form и doc-wording
В уставе стоял заголовок «Форма записи — только для 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>
2026-08-04 19:45:43 +03:00
avandClaude Opus 5 ca71838037 агент вычитки переименован в doc-wording и расширен на все документы
Имя пришло из задач, но правила языка относятся ко всем проектным
текстам: документам канона, решениям 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) <noreply@anthropic.com>
2026-08-04 19:38:50 +03:00
avandClaude Opus 5 2d69ab691e язык проектных текстов — один дом и информационный стиль
Языковые правила лежали внутри скилла 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>
2026-08-04 19:20:20 +03:00
avandClaude Opus 5 0c8390d774 форма записи: заголовок отвечает на вопрос своего типа
Обкатка скилла tasks на выдуманном проекте — консольные крестики-нолики
на JavaScript, каталог заведён с нуля тем же скриптом. Форма вылезла
раньше содержания, и правки все про неё.

Заголовок отвечает на вопрос типа записи, и форм три: цель —
утверждение о возможности, задача — глагол в неопределённой форме
(допускается «не» перед ним), идея — назывное, без обещания. Причина не
стилистическая: описательный заголовок называет состояние, а из
состояния не видно, чего от работы ждут — «Ничья объявляется, пока
клетки есть» одинаково читается как жалоба и как задание. Отсюда же
разница индексов: роадмап — список возможностей, беклог — список работ,
и перепутанные формы делают каждый похожим на другой.

Механизировано ровно то, что механизируется: check считает заголовки,
где первое слово не на -ть/-ти/-чь, и печатает число в блоке здоровья.
Замечанием на файл нельзя — эвристика грубая, а на 97 записях двух живых
проектов это поток одинаковых строк, после которого пропускают весь блок.

Годность формулировки судит отдельный агент task-wording, а не чек-лист
в скилле: сейчас формулировку пишет и проверяет один агент в одном
контексте, а самопроверка текста слабее всего там, где формулировка
казалась удачной при написании. Он ничего не правит — возвращает готовые
формулировки, и заголовок с «зачем» показываются человеку, потому что
по ним задачу выбирают. Ничего из того, что ловит tasks.py check, он не
трогает намеренно: это был бы второй дом для правила.

Заголовки секций — с прописной, после заголовка пустая строка, во всех
индексах. Канонические имена стали Готово | Запланировано | Направления
| Разработка (англ. Done | Planned | Directions | Tooling), сверка везде
по нижнему регистру, так что старые индексы читаются по-прежнему.
Отбивка живёт на записи, а не на вставке: через Plan.index проходит
каждая правка индекса, а мест вставки три.

Имя секции принадлежит заголовку индекса, файл на неё только ссылается.
Это разрешает единственную неоднозначность починки — расхождение в одном
регистре правится в пользу заголовка. Без него переезд на канон оставил
бы «Готово» в роадмапе и «готово» в каждом файле цели, и свести это было
бы некому. Регистр правится только у канонических секций: имена секций
беклога выбирает проект.

Обкатка нашла два дефекта, которых не находили ни линтеры, ни свои
проверки. Вставка в пустую секцию съедала отбивку перед следующим
заголовком — пропуск пустых строк теперь идёт только до первой непустой.
Мета, разорванная пустой строкой, теряла поля молча: check видел лишь
следствие («без рода работы») и советовал edit --kind, который дописывал
второе такое же поле. Поле меты в теле стало ошибкой с названной
причиной, и --fix её намеренно не чинит — какое из двух значений верное,
знает человек.

DECISIONS тема 20 (ЕЕЕ–ККК, следствия 82–85), changelog канона v3
пополнен двумя пунктами и двумя шагами переезда, TODO — два шага для
healthlog и jellybit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 19:06:54 +03:00
avandClaude Opus 5 ef0183b06b секции роадмапа названы и закреплены линтером
готово | запланировано | направления | разработка, англ. done | planned |
directions | tooling. Из четырёх предложенных имён отвергнуто одно, и по
проверяемой причине: «окружение» уже занято — в architecture.md это боевое
окружение приложения, «где работает, что рядом, кто перезапускает», и одно
слово в двух смыслах развело бы документы канона.

Секции роадмапа стали каноническими, в отличие от секций беклога, и разница
выведена, а не назначена: у каждой секции роадмапа своя семантика, в первую
пишет сам close, и роадмап, названный по-своему, читался бы только своим
автором. Секции беклога — полки, смысла не несут, остаются делом проекта.

check проверяет три вещи: состав закреплён (чужая секция — ошибка), все четыре
обязаны быть, язык один на весь индекс. Проверено на том случае, ради которого
правило и заводилось: «Что уже пройдено», которую healthlog вёл руками, теперь
называется ошибкой поимённо. Оба языка прогнаны вживую, включая close в
английский роадмап.

Ключа tasks.achieved_section не появилось — секция достигнутого опознаётся по
каноническому имени в любом из языков; --roadmap-sections у init упразднён,
выбирать больше нечего.

Названные вслух компромиссы: «готово» слегка тянет в трекерную рамку
«состояние работы», тогда как секция про возможность — перевесила читаемость;
цель в «запланировано» может быть уже наполовину построена, это очередь, а не
«не начато», «в работе» живёт в SPRINT.md.

DECISIONS 19: ГГГ переписан, добавлен ДДД, следствие 78 заменено. TODO 7 закрыт.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 17:58:31 +03:00
avandClaude Opus 5 e847bfa0ea роадмап — состояние проекта, а не очередь работ
Основной инструмент владельца отвечал на половину своего вопроса. Оценка идёт
по поведению: что приложение уже может и чего ещё не может, — а close
--implemented удалял у достигнутой цели и файл, и строку, так что роадмап по
построению показывал только «что осталось». Свидетельство лежало в самом
роадмапе healthlog: секция «Что уже пройдено» на двадцать строк прозы, руками,
с припиской «Эти звенья целями не заведены: закрытая цель записи не оставляет».

Теперь строка с датой переезжает в секцию достигнутого, файл удаляется
по-прежнему. Вторым домом поведения это не делает: нормативное поведение живёт
в openspec/specs, роадмап отвечает, когда и в каком порядке оно появилось.
Ссылки на файл в строке нет — файла больше нет, форма как в REJECTED.md.

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

Цель обязательна не у всякой задачи. Прежнее «иначе она не попадёт ни в один
спринт» было угрозой, а не аргументом, и заставляло операционную работу
выдумывать себе направление. Граница по роду: feature без цели не бывает, fix,
chore и research живут без неё и входят в набор помимо цели спринта.

Тип [epic] упразднён: зонтиком стала цель, а слишком крупный шаг дробится под
ней. Ноль употреблений на 97 записей двух живых проектов.

Секции роадмапа — умеет / строим / направления / станок, четыре вместо двух;
имена приняты как временные и запаркованы (TODO 7). Имя секции достигнутого
знает скрипт — docs/.pm.json, ключ tasks.achieved_section. reopen цели снимает
строку достигнутого, круг проверен вживую.

Всё дописано в версию 3 канона: она ещё нигде не выкачена. DECISIONS 19,
YYY–ГГГ и следствия 78–81.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 17:43:55 +03:00
avandClaude Opus 5 5bf599a767 верхняя ступень ревью задана тестом, а не списком
«Идентичность, слияние, разбор» пришли из одного проекта, и в общем виде
формулировка не читалась: вопрос «как применить это к моему проекту» не имел
ответа в тексте. Теперь класс задан тремя условиями, не зависящими ни от
домена, ни от языка: вариантов несколько и оба защитимы; спека между ними не
выбирает; неверный выбор не падает, а даёт правдоподобный результат и молча
меняет смысл данных.

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

Три слова остались как три места, где такие правила водятся — граница, где
данные входят или встречаются: состав ключа и нормализация перед сравнением;
победитель конфликта и тай-брейк при равенстве; границы токенов и неоднозначный
вход. Проект перечисляет свои места в docs/review.md, и перечень производен от
теста, а не заменяет его.

Две оговорки, без которых правило вырождается:
- триггер — новое или изменённое по существу правило, а не код рядом с ним;
  иначе проект, чей домен и состоит из таких правил, всегда в deep;
- проект, где такого класса нет вовсе, deep не запускает никогда, и это
  законное состояние, а не недонастройка.

review-reimpl получил тот же тест и право сказать первой строкой, что позвали
не на его класс, — строкой в границы покрытия, а не отказом работать.
DECISIONS 18, XXX и следствия 76–77.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 17:12:40 +03:00
avandClaude Opus 5 cc173b6b94 ступень ревью поднимает проход, а не риск
Полный набор гонялся чаще, чем оправдано, и размер задач тут вторая причина,
не первая. Первая — триггеры: миграция схемы, публичный контракт и инвариант
поднимали ступень, не добавляя ни одного прохода. Миграцию гоняет gate шагом
миграций и разбирает ops, контракт сверяет specs направлением code→spec,
инвариант даёт основание для critical любому проходу — все трое уже в
standard. На проекте с базой и эндпоинтами верхняя ступень оказывалась не
исключением, а умолчанием: правило объявляло исключением то, что происходит
всегда.

Теперь ступень поднимает то, что даёт работу новому проходу. wide означает
ровно одно — изменение вводит новое понятие или структурную единицу; добавить
поле в существующий ответ это не концепт. standard стал рабочим умолчанием.
Проект, где изменение контракта и правда архитектурное, поднимает его сам в
docs/review.md — уточнением, а не возвратом прежнего умолчания.

Чекпоинт design получил то же условие: specs идёт всегда, rubric и
architecture — только при новом понятии. Он стоит на каждой задаче, поэтому
при мелкой нарезке три прохода умножаются на число задач.

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

Правило выведено из состава проходов, а не из статистики прогонов — замер
остаётся за обкаткой. DECISIONS 18, RRR–WWW и следствия 72–75; JJJ темы 17
помечен как пересмотренный. Шаг про «Триггеры профиля» дописан в ещё не
выкаченную версию 3 канона, а не отдельной версией.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 17:06:12 +03:00
avandClaude Opus 5 69f67c20aa DECISIONS 17 и TODO: итоги разбора заметок
Тема 17, решения HHH–QQQ и следствия 68–71. Отдельной строкой — что версию
канона 3 занял роадмап с родом работы, поэтому отложенное решение темы 16
(каталог вместо файла в docs/) вводится версией 4; поправлено в обоих
местах.

TODO раздел 6: повышение healthlog и jellybit до канона 3. Оба стоят на
версии 2 с живым PLAN.md — 55 и 43 задачи, — так что переименование это не
свободная правка, а миграция по журналу версий. Род работы и «Затрагивает»
там проставляются не задним числом: сперва то, что идёт в ближайший набор,
остальное по ходу переоценки.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:49:58 +03:00
avandClaude Opus 5 b99c0c2366 канон версии 3: роадмап, род работы, границы задачи
Три изменения одной версией, потому что все три про одно — можно ли
оценить задачу, не открывая код.

PLAN.md → ROADMAP.md. Слово «план» значило в репозитории три разных вещи:
оглавление целей, план реализации внутри задачи и PLAN.json разовой
адаптации. Переименовано целиком — ключ конфига tasks.plan → tasks.roadmap,
--index roadmap, --roadmap-sections, --roadmap. Старый ключ в docs/.pm.json
не игнорируется молча: скрипт останавливается кодом 3 и называет
переименование, иначе проект искал бы опечатку там, где на самом деле
версия канона.

Род работы — тег kind:feature|fix|chore|research, вторая ось поверх типа
записи. В один префикс их не свести: идея бывает про функцию, эпик функцией
и является. Дом — тег, потому что теги здесь единственный механизм
разметки, а list --kind работает даром; цена принята — в строку индекса род
не попадает. Словарь закрыт, иначе он разъедется на bug/bugfix/fix/defect.
Отдельно легализован chore: у него «что станет наблюдаемо иначе» отвечается
разработчику, а раньше такие задачи либо не заводились, либо придумывали
себе пользовательскую пользу — и это второе хуже, оно проходит проверку.

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

Род и границы требуются к взятию в спринт, а не к заведению — тот же приём,
что уже работает для критериев приёмки, и по той же причине. check о
пропаже только напоминает: иначе два живых проекта покраснели бы на 98
задачах, заведённых до этого решения.

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:49:58 +03:00
avandClaude Opus 5 84134cac1e ревью: ступень wide, цвета по модели, проверка фронтматтеров
Прыжок standard → deep стоил самого дорогого прохода конвейера, а платить
приходилось за одну архитектурную находку: изменений, которые трогают
публичный контракт, но не вводят нового правила слияния, — большинство.
Ступень wide это standard плюс architecture (вход шире диффа, отсюда имя),
семь проходов против восьми.

Заодно вычистилась давняя неровность: триггер reimpl стоял внутри deep, и
профиль означал то семь проходов, то восемь — реестр состава, который
«сверяется взглядом до коммита», проверять было нечем. Теперь условие
«новое правило идентичности, слияния или разбора» выбирает профиль, reimpl
в deep безусловен и есть единственное отличие от wide. Барьер стоимости
остался только в deep: в wide за ним стоял бы один дешёвый проход с
потолком в 3 находки, а барьер сериализует то, что могло идти разом.

Цвет charter'а теперь кодирует модель, а не роль: sonnet → green,
opus → yellow, fable → red. Роль видна из имени, стоимость прогона —
ниоткуда, а список агентов читается взглядом.

scripts/frontmatter.py ловит три класса ошибок, невидимых при чтении:
- двоеточие с пробелом в незакавыченном описании — для YAML это вложенное
  отображение, а не текст. Так было написано три описания из четырнадцати,
  и читались они правильно;
- name, разошедшееся с именем каталога скилла или файла charter'а;
- цвет, не отвечающий модели: он ставится один раз при заведении charter'а,
  а модель потом двигает калибровка.

Обе ветки проверены, коды выхода — общий словарь. Триггеры профиля в
canon.md и skeletons.md подтянуты под wide.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:49:02 +03:00
36 changed files with 2829 additions and 353 deletions
+576
View File
@@ -1152,3 +1152,579 @@ HTML-комментарии, невидимые в отрендеренном ma
67. **Материал для решения даёт `healthlog`, а не `jellybit`.** У второго 169 67. **Материал для решения даёт `healthlog`, а не `jellybit`.** У второго 169
строк архитектуры — там вопрос не стоит вовсе, и принимать по нему решение строк архитектуры — там вопрос не стоит вовсе, и принимать по нему решение
значит принимать его без предмета. значит принимать его без предмета.
## 17. Разбор заметок: ступень ревью, род работы, роадмап (2026-08-04)
### Что было
Семь заметок из `NOTES.md`, накопленных по ходу работы: переименование
`PLAN.md`, тип у каждой задачи, цвета сабагентов по модели, кавычки во
фронтматтерах, уровни ревью для проекта, задачи в терминах функций и границ,
язык задач без англицизмов. Разного размера и из разных мест, но три из них
оказались об одном — **о том, можно ли оценить задачу, не открывая код**.
### Решено
**HHH. Цвет charter'а кодирует модель, а не роль прохода.** Раскладка
`sonnet` → green, `opus` → yellow, `fable` → red. Роль прохода видна из имени, а
стоимость прогона — ниоткуда; цвет, розданный по ролям, не отвечает ни на один
вопрос, который задают во время прогона. Дом раскладки — таблица «Модель по
проходу» в `review-pipeline/SKILL.md`.
**III. Фронтматтеры проверяются машиной, а не вниманием.** Три описания из
четырнадцати содержали `: ` в незакавыченном значении — для YAML это вложенное
отображение, то есть синтаксическая ошибка, которую **нельзя увидеть чтением**:
текст читается правильно. Тот же класс, что у mermaid-диаграмм, и лечится тем же
способом — `scripts/frontmatter.py`. Он же держит раскладку цветов (HHH) и
сверку `name` с именем каталога.
**JJJ. Между `standard` и `deep` заведена ступень `wide`.** *(содержание
триггеров пересмотрено темой 18, TTT: миграция схемы и публичный контракт ступень
не поднимают.)* Прыжок стоил самого
дорогого прохода конвейера, а платить приходилось за одну архитектурную находку:
изменений, которые трогают публичный контракт, но не вводят нового правила
слияния, — большинство. `wide` — это `standard` плюс `architecture` (вход шире
диффа, отсюда имя), семь проходов против восьми у `deep`.
**KKK. Триггер независимой реализации стал триггером профиля.** Раньше условие
«изменение вводит новое правило идентичности, слияния или разбора» стояло
**внутри** `deep`, и профиль означал то семь проходов, то восемь. Реестр состава,
который «сверяется взглядом до коммита», проверять было нечем: у профиля не было
одного правильного ответа. Теперь условие выбирает профиль, а `reimpl` в `deep`
безусловен — и он единственное, чем `deep` отличается от `wide`.
**LLL. Барьер стоимости остался только в `deep`.** В `wide` за ним стоял бы один
дешёвый проход с потолком в 3 находки, а барьер не бесплатен — он сериализует то,
что могло идти разом. Вторая причина помельче: барьер спрашивает «выживает ли
форма изменения», а `architecture` — как раз тот, кто на этот вопрос отвечает.
**MMM. Род работы — вторая ось типа, и живёт тегом.** Тип записи
(`goal`/`idea`/`epic`/`task`) отвечает «что это за запись», род
(`feature`/`fix`/`chore`/`research`) — «какого рода работа». В один префикс их не
свести: идея бывает *про* функцию, эпик функцией *и является*. Дом — тег
`kind:<род>`, потому что теги здесь и есть единственный механизм разметки, а
`list --kind` работает даром. Принятая цена: в строку индекса род не попадает
(индексы производны), и состав набора по роду виден командой, а не глазами.
Словарь **закрыт** — открытый разъехался бы на синонимах `bug`/`bugfix`/`fix`.
**NNN. У `chore` тест готовности ослаблен честно.** Вопрос «что станет наблюдаемо
иначе» для обслуживания отвечается разработчику, а не пользователю. Пока рода не
было, такие задачи либо не заводились, либо придумывали себе пользовательскую
пользу — и это второе хуже: оно проходит проверку.
**OOO. Задача называет границы, а не намерения.** Раздел «Затрагивает» —
эндпоинт, таблица и миграция, формат на диске, публичный тип пакета. Без него
задача оценивается по объёму текста, а не по объёму поверхности, и оценка
систематически занижена ровно там, где текст короткий, а границ много. Механизм
проверяет **наличие** непустого раздела: полноту перечня машина не видит, и
делать вид, что видит, хуже, чем не проверять.
**PPP. Род и границы требуются к взятию в спринт, а не к заведению.** Тот же
приём, что уже работает для критериев приёмки, и по той же причине: беклог
пополняется чаще, чем разбирается, а требование на входе выгоняет в заметки то,
что должно лежать задачей. `check` о пропаже напоминает замечанием — иначе два
живых проекта покраснели бы на 98 задачах, заведённых до этого решения.
**QQQ. `PLAN.md` → `ROADMAP.md`, вместе с ключом конфига и токенами команд.**
Слово «план» в репозитории значит три разных вещи — оглавление целей, план
реализации внутри задачи и `PLAN.json` разовой адаптации. Переименовано всё:
`tasks.plan` → `tasks.roadmap`, `--index plan` → `--index roadmap`,
`--plan-sections` → `--roadmap-sections`. Старый ключ в `docs/.pm.json` не
игнорируется молча — скрипт останавливается и называет переименование.
### Что из этого следует
68. **Версия канона 3 занята этим изменением.** Отложенное решение темы 16
(каталог вместо файла в `docs/`) вводится теперь версией **4**, а не 3.
69. **Род работы ничего не предписывает конвейеру.** Профиль ревью выбирается по
факту изменения: `chore` бывает миграцией схемы, `fix` — правкой публичного
контракта. Правило «предписание процесса в теле задачи снимается» родом не
отменяется, а подтверждается.
70. **Проверка фронтматтеров — третья проверка репозитория того же класса.**
Копии, диаграммы, фронтматтеры: всё это ошибки, невидимые при чтении. Класс
опознаётся по признаку «диff выглядит разумно, а результат ломается», и
каждый его представитель получает скрипт, а не пункт чек-листа.
71. **Ступеней профиля четыре, и правило выбора читается сверху вниз.** Первое
сработавшее условие и есть ответ: правило слияния → `deep`, контракт или
схема → `wide`, видимое снаружи поведение → `standard`, иначе `quick`.
## 18. Ступень поднимает проход, а не риск (2026-08-04)
### Что было
Наблюдение с живых проектов: полный набор проходов гоняется чаще, чем оправдано —
архитектура и независимая реализация нужны заметно реже, чем запускаются. Развилка
названа сразу: крупные задачи с частым полным ревью либо мелкие и средние задачи
со средним ревью. Выбран второй путь.
Разбор показал, что размер задач — только половина причины, и не главная.
### Решено
**RRR. Профиль — максимум по поверхности, а не средневзвешенное.** Условия
читаются сверху вниз, первое подошедшее отвечает за весь дифф. Значит цена ревью
растёт быстрее размера задачи: на крупной задаче верхний профиль оплачивается в
том числе за ту её часть, которая сама по себе была бы `quick`. Это и есть
механизм, ради которого выбран путь мелких задач.
**SSS. Ступень поднимает то, что даёт работу новому проходу, а не то, что кажется
рискованным.** Правило вывода, по которому спорные случаи решаются без нового
списка. Проверка нынешних триггеров этим правилом:
| Триггер | Кто закрывает | Где этот проход |
| --- | --- | --- |
| миграция схемы | `gate` (шаг миграций), `ops` (миграция под потоком, откат при двух версиях) | уже в `standard` |
| публичный контракт | `specs`, направление `code → spec` | во всех профилях |
| инвариант проекта | основание для `critical` у любого прохода | во всех |
| новый пакет, новое понятие | `architecture` | только `wide` |
| новое правило слияния | `reimpl` | только `deep` |
Три верхних триггера не добавляли ни одного прохода — они поднимали ступень «на
всякий случай». На проекте с базой и эндпоинтами это делало верхнюю ступень
умолчанием, то есть правило объявляло исключением то, что происходит всегда.
**TTT. Миграция схемы, публичный контракт и инвариант уехали в `standard`.**
`wide` теперь означает ровно одно: изменение вводит **новое понятие или
структурную единицу** — новый пакет или слой, новая точка входа, второй способ
делать то, что уже делается, перенос ответственности между узлами. Добавленное
поле в существующем ответе концептом не является. Это **отменяет часть JJJ темы
17**: ступень `wide` остаётся, её содержание меняется. Проект, где изменение
контракта и правда архитектурное (публичный SDK, чужие потребители), поднимает
его сам в `docs/review.md` — уточнением, а не возвратом прежнего умолчания.
**UUU. Чекпоинт `design` получил то же условие.** `review-specs` в режиме «дизайн
ДО кода» идёт всегда — это самый дешёвый чекпоинт конвейера. `review-rubric` и
`review-architecture` — только при новом понятии. Причина арифметическая: чекпоинт
стоит на **каждой** задаче, поэтому при мелкой нарезке три прохода умножаются на
число задач и становятся самой большой статьёй. Причина по существу та же, что в
SSS: рубрика на узел без нового понятия порождает свойства уже существующего
рода, записанные конвенциями и спеками.
**VVV. Шов нарезки — граница, за которой падает ступень.** Тест декомпозиции
отвечает, **допустим** ли разрез; шов отвечает, **где** его провести. Раздел
«Затрагивает» перечисляет границы; строка, поднимающая ступень выше остальных, и
есть кандидат на отдельную задачу.
**WWW. Костяк из четырёх проходов платится за каждую задачу.** Гейт, спеки, код,
триаж несокращаемы, поэтому разрез, после которого обе половины остаются в одной
ступени, делает ревью **дороже**: тот же объём тем же составом, но костяк оплачен
дважды. Резать — когда разрез снимает дорогой проход с большей части диффа.
**XXX. Верхняя ступень задана тестом, а не списком.** «Идентичность, слияние,
разбор» — формулировка, пришедшая из одного проекта, и в общем виде она не
читалась: вопрос «как это применить к моему проекту» не имел ответа в тексте.
Теперь класс задан тремя условиями, независимыми от домена и языка: вариантов
несколько и оба защитимы; спека между ними не выбирает; неверный выбор не падает,
а молча меняет смысл данных. Отрицательный тест сильнее положительных — то, что
красит гейт или роняет запрос, в класс не входит. Три слова остались как **три
места**, где такие правила водятся (граница входа данных и место их встречи), а
проект перечисляет свои места в `docs/review.md` — перечень производен от теста и
не расширяет класс.
Оговорка, без которой правило вырождается: триггер — **новое или изменённое по
существу правило**, а не код рядом с ним. Проект, чей домен и состоит из таких
правил, иначе оказывался бы в `deep` всегда — та же болезнь, от которой лечилась
ступень `wide`.
### Что из этого следует
72. **Порога в числе границ не заводится.** Тот же принцип, что в теме 16 (CCC):
размер не триггер. Шов проходит по скачку ступени, а не по длине перечня.
73. **Ступень — признак для планирования, но не запись в задаче.** Строка «делать
профилем standard» в теле — тот самый второй дом правила выбора, который
снимает гигиена полей. Профиль выбирает тот, кто видит изменение.
74. **Дешёвое место заметить разнородную задачу — показ набора спринта.** Там
«Затрагивает» уже написан, а предложение об изменении ещё не заведено: разрез
стоит одного `edit` вместо выброшенного предложения.
75. **Замер остаётся за обкаткой.** Правило выведено из состава проходов, а не из
статистики прогонов: считать, какая доля задач попадает в каждую ступень,
можно только на спринтах нового процесса (TODO шаг 4).
76. **Отсутствие верхней ступени — законное состояние проекта.** Бывают проекты,
где данные приходят нормализованными, ничего ни с чем не сливается, а внешних
форматов нет: `deep` там не срабатывает никогда, и придумывать ему повод не
надо. Раньше это читалось как недонастройка.
77. **Ступень определяет класс правила, а не вид работы.** Миграция схемы —
`standard`, но миграция, переносящая данные по правилу («сложить дубли»,
«привести к одному виду перед сравнением»), несёт правило идентичности и
потому `deep`. Одно слово в описании задачи попадает в разные ступени — это не
противоречие, смотрят не на слово.
## 19. Роадмап — состояние проекта, а не очередь работ (2026-08-04)
### Что было
Основной инструмент владельца — роадмап и набор целей: «на каком этапе проект,
что сделали и что осталось». Оценка идёт по **поведению**, а не по внутреннему
устройству: что приложение уже может делать и чего ещё не может. Отсюда
требование к формулировкам: цель отвечает на «что приложение будет делать»,
задача — на «что для этого нужно сделать».
Разбор показал, что инструмент отвечал ровно на половину этого вопроса.
### Решено
**YYY. Достигнутая цель из роадмапа не исчезает.** `close --implemented` удалял
у цели и файл, и строку — роадмап по построению показывал только «что осталось».
Свидетельство нашлось в самом роадмапе healthlog: там руками заведена секция «Что
уже пройдено» на двадцать строк прозы, и заканчивается она фразой «Эти звенья
целями не заведены: закрытая цель записи не оставляет, ей хватает коммита и
спеки». Обходной путь и его причина записаны рукой владельца. Теперь строка с
датой переезжает в секцию достигнутого; файл удаляется по-прежнему.
Вторым домом поведения это не делает: нормативное поведение живёт в
`openspec/specs/`, роадмап отвечает **когда и в каком порядке** оно появилось —
другой вопрос. Ссылки на файл в строке нет намеренно: файла больше нет, а битая
ссылка это законная ошибка `check`. Форма строки — как в `REJECTED.md`, и по той
же причине.
**ZZZ. Цель — возможность приложения, задача — шаг к ней.** Заголовок цели
отвечает на «что приложение будет уметь»: не «Работа со слиянием», а «Исход
слияния не зависит от порядка доставки». **Свойство поведения — тоже
возможность**: «сообщает о своём состоянии», «исход не зависит от порядка» —
законные цели, переформулировки в функцию не требуют. Единственный настоящий
чужак — работа над инструментом и процессом: на вопрос «что приложение будет
уметь» она не отвечает и живёт в отдельной секции роадмапа.
**ААА. Тест готовности задачи сменил защиту.** Требование «что станет наблюдаемо
иначе снаружи» переехало к цели. У задачи вместо него — **какую строку
«Завершения» своей цели она двигает**. «Отрефакторить X» проваливает тест не
потому, что невидим снаружи, а потому, что не находит строки, к которой
относится. Побочная выгода: видно и обратное — строка «Завершения», к которой не
относится ни одна задача, это незакрытая часть возможности. Отсюда требование к
«Завершению» быть **списком**, а не абзацем: на абзац не сошлёшься.
**БББ. Цель обязательна не у всякой задачи.** Прежнее правило — «у каждой задачи
должен быть `goal:`, иначе она не попадёт ни в один спринт» — было угрозой, а не
аргументом, и заставляло операционную работу выдумывать себе направление.
Граница проходит по роду работы: `feature` без цели не бывает (новая возможность
и есть содержание цели), `fix`, `chore` и `research` живут без цели законно и
входят в набор спринта помимо его цели. Это второй раз, когда род работы
окупается, — и первый, когда он что-то определяет за пределами отбора.
**ВВВ. Тип `[epic]` упразднён.** Зонтик между целью и задачами не нужен: зонтиком
стала цель, а слишком крупный шаг дробится на шаги помельче под ней. Замер: ноль
употреблений на 97 записей двух живых проектов, при том что тип занимал место в
словаре, тесте готовности, автомате переходов, `split.md` и трёх местах
`tasks.py`.
**ГГГ. Имена секций роадмапа — `Готово` / `Запланировано` / `Направления` /
`Разработка`.** Первый набор (`умеет` / `строим` / `станок`) прожил один заход и
был признан неудачным. Из четырёх предложенных имён отвергнуто одно, и по
проверяемой причине: **`окружение` уже занято** — в `architecture.md` это боевое
окружение приложения, «где работает, что рядом, кто перезапускает», и одно слово
в двух смыслах развело бы документы канона. Взято `Разработка`.
Принятый компромисс назван вслух: `Готово` слегка тянет обратно в трекерную рамку
«состояние работы», тогда как секция про **возможность**. Перевесила читаемость с
первого взгляда, а смысл несут заголовки целей внутри секции. Так же принято, что
цель в `Запланировано` может быть уже наполовину построена: это очередь, а не
«не начато», а «в работе» живёт в `SPRINT.md`.
**ДДД. Секции роадмапа канонические, секции беклога — нет.** Разница выведена, а
не назначена: у секций роадмапа есть **семантика** (достигнутое, очередь, долгое,
не про продукт), в первую пишет сам `close`, и роадмап, названный по-своему,
читался бы только своим автором. Секции беклога (`Ядро`, `Инфра`) семантики не
несут — это полки. Поэтому `check` проверяет у роадмапа три вещи: состав закреплён
(чужая секция — ошибка), все четыре обязаны быть, язык один на весь индекс;
`--roadmap-sections` у `init` упразднён. Английский набор — `Done` | `Planned` |
`Directions` | `Tooling`.
Проверено на том самом случае, ради которого правило и заводилось: секция «Что
уже пройдено», которую healthlog вёл руками, теперь называется ошибкой поимённо.
### Что из этого следует
78. **Ключа `tasks.achieved_section` не появилось.** Секция достигнутого
опознаётся по каноническому имени в любом из двух языков, и лишний knob не
заводится: канонический состав отвечает на тот же вопрос надёжнее конфига.
79. **`reopen` цели снимает строку достигнутого.** Иначе роадмап продолжает
утверждать, что приложение умеет то, что вернулось в работу.
80. **Прозаический раздел в индексе — дрейф.** Любой `##` проверка считает
секцией, поэтому «Что уже пройдено» и «Почему в таком порядке» в healthlog
формально были двумя лишними секциями, куда могла уехать задача. При
повышении они разбираются: звенья — строками в `Готово`, обоснование очереди —
прозой внутри `Запланировано`.
81. **Правил стало пять, и нулевое — про смысл, а не про механику.** «Цель —
возможность, задача — шаг к ней» стоит перед правилами о гниении беклога и
производности индексов, потому что из него следует, зачем эти механики нужны.
## 20. Форма записи: заголовок, секции, вычитка (2026-08-04)
### Что было
Обкатка обновлённого скилла на выдуманном проекте — консольные крестики-нолики
на JavaScript. Каталог задач заведён с нуля тем же скриптом: шесть целей, девять
задач, отказ, достижение цели, спринт. Смотрели три вещи: тексты, разделы, состав
задач.
Форма вылезла раньше содержания. Индексы вышли с секциями со строчной буквы и без
отбивки после заголовка — читается как список списков, а не как документ. А все
заголовки задач оказались **описательными**: «Лишние символы в ходе молча
отбрасываются», «Поле печатается одним куском кода», «Линтер и тесты гоняются
одной командой». Правило «задача отвечает на «что для этого нужно сделать»» в
скилле стояло с самого начала — но относилось к содержанию задачи, а не к её
заголовку, и потому не применялось там, где заголовок и есть всё, что видно в
списке.
### Решено
**ЕЕЕ. Заголовок отвечает на вопрос своего типа, и форм три.** Цель — утверждение
о возможности («Соперником может быть компьютер»); задача — глагол в
неопределённой форме, допускается «не» перед ним («Не отбрасывать молча лишние
символы в ходе»); идея — назывное, без обещания. Причина не стилистическая:
описательный заголовок называет **состояние**, а из состояния не видно, чего от
работы ждут — «Ничья объявляется, пока клетки есть» одинаково читается как жалоба
и как задание. В списке, где решают «брать или не брать», это разные вещи.
Отсюда же разница индексов: роадмап — список возможностей, беклог — список работ.
Перепутанные формы заголовков делают каждый из них похожим на другой.
**ЖЖЖ. Механизировано ровно то, что механизируется, — счётчиком, а не
замечанием.** `check` считает заголовки, у которых первое слово не оканчивается
на `-ть`/`-ти`/`-чь` (перед ним допускается «не»), и печатает **число** в блоке
здоровья. Замечанием на файл этого делать нельзя: проверка эвристическая, а
беклог, заведённый до правила, переоформляют не «заодно» — десятки одинаковых
строк научили бы пропускать весь блок.
**ЗЗЗ. Годность формулировки судит отдельный агент `doc-wording`, а не чек-лист
в скилле.** Самопроверка текста слабее всего там, где формулировка казалась
удачной при написании, — а пишет и проверяет иначе один и тот же агент в одном
контексте. Агент читает пачку записей и возвращает **готовые формулировки на
замену**, ничего не правя сам; заголовок и «зачем» подставляются командой и
показываются человеку, потому что именно по ним задачу выбирают. Он намеренно не
проверяет ничего из того, что ловит `tasks.py check`: повторить машинную проверку
словами значит завести правилу второй дом.
**ИИИ. Заголовок секции — с прописной, после него пустая строка.** Во всех
индексах, включая секции беклога, имена которых выбирает проект: правило про
**оформление**, а не про имя. Канонические имена стали писаться с прописной
(`Готово` | `Запланировано` | `Направления` | `Разработка`, англ. `Done` |
`Planned` | `Directions` | `Tooling`), сверка везде идёт по нижнему регистру, так
что старые индексы читаются по-прежнему и поднимаются `check --fix`.
**ККК. Имя секции принадлежит заголовку индекса, файл на неё только ссылается.**
Это разрешает единственную неоднозначность починки: расхождение файла и заголовка
**в одном регистре** правится в пользу заголовка. Без этого шага переезд на канон
оставил бы `Готово` в роадмапе и `готово` в каждом файле цели — расхождение
безвредное, но вечное, потому что свести его было бы некому.
### Что из этого следует
82. **Отбивка живёт на записи, а не на вставке.** `spaced_sections` вызывается в
`Plan.index`, через который проходит **каждая** запись индекса. Чинить
отбивку в каждом месте вставки значило бы полагаться на то, что ни одного не
забыли, — а мест вставки три (`--first`, `--after`, в конец).
83. **Обкатка нашла два дефекта, которых не нашли ни линтеры, ни свои проверки.**
Вставка в пустую секцию съедала отбивку перед следующим заголовком; мета,
разорванная пустой строкой, теряла поля молча, а `check` видел только
следствие («без рода работы») и советовал `edit --kind`, который дописывал
**второе** такое же поле. Оба класса теперь названы: пропуск пустых строк
идёт только до первой непустой, а поле меты в теле — ошибка с названной
причиной, которую `--fix` намеренно не чинит.
84. **Пустой проект показывает форму хуже живого.** Чтобы увидеть достигнутую
цель, отказ, спринт и все четыре рода работы, проект пришлось поставить на
середину пути. Это довод в пользу того, чтобы обкатку вести на *состоянии*, а
не на *старте*: у старта половина формы не наблюдаема.
85. **Мелкая цель даёт две задачи, и это не повод её укрупнять.** У цели
«Соперником может быть компьютер» третья задача напрашивалась (выбор уровня
соперника), но не мерджится порознь: без сильного соперника выбирать не из
чего. Тест декомпозиции её отбил — частичный ответ на вопрос «не выродились
ли цели в ярлыки тем».
## 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 так и
записан: прочитать и ничего не переписывать задним числом. Сплошная вычитка
старых документов стоит дороже, чем даёт, а правила применяются к тому, что
правится сейчас.
## 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 записей — не провал вычитки.** Тексты писались сразу по
правилам, и находить в них было почти нечего. Показательно другое: агент
удержал порог (вкусовых правок не предложил) и явно сказал, по чему проверял
термины, — то есть отработали обе защиты, а не только та, что ищет.
## 23. Вычитка разделена на два прохода (2026-08-04)
### Что было
В уставе агента вычитки стоял заголовок «Форма записи — только для
`docs/tasks/items/`». Условная половина устава: на документе канона она молчит,
на задаче включается.
### Решено
**ССС. Проходов два: `task-form` и `doc-wording`.** Разделены не по охвату — по
**глубине**. Язык проверяется по словам и фразам, поштучно, и это подметание:
залог, оценки, стоп-слова, англицизмы, жаргон. Форма записи требует понять, что
задача делает, и **открыть файл цели**, на которую она ссылается, чтобы сверить,
какую строку «Завершения» задача двигает. Слитый проход одну половину делает
дорогой, а вторую — поверхностной.
Отсюда и разные модели: `doc-wording` — sonnet, `task-form` — opus. Первый
подметает, второй судит смысл, и ровно на суждении обкатка показала провал —
агент сам себе объяснил находку «принятым стилем каталога» (тема 22).
**ТТТ. Условная половина устава — плохая конструкция сама по себе.** Правило,
которое «применяется только если», агент применяет по своему усмотрению, а
усмотрение и есть то, чего от него не ждут. Два коротких устава без условий
надёжнее одного длинного с ними — и это довод, годный за пределами этого случая.
**УУУ. Каждый устав отказывается от чужой половины прямо.** «Увидел не по своей
части — скажи строкой в границах покрытия, не находкой». Без такого отказа две
проверки одного места расходятся и начинают спорить, а разнимать их потом
дороже, чем не сводить. Исключение ровно одно и названо: неудачное слово **в
заголовке** судит `task-form`, потому что заголовок целиком его.
**ФФФ. Порог правки переехал в дом и копируется в оба устава.** Он теперь в
`language.md` помеченным домом `порог-правки`: правка без нарушенного правила не
делается, систематичность нарушения — не довод в его пользу. Дублировать его
руками в двух уставах значило бы получить два разных порога через месяц.
### Что из этого следует
91. **Шестое правило `task-form` — единственное, что читает больше одного
файла.** Оно же единственное, что смотрит **набор**, а не запись: строка
«Завершения», к которой не относится ни одна поданная задача, докладывается
отдельным блоком. Это граница между вычиткой и разбором, и она проведена
внутри правила, а не между агентами.
92. **Порядок вызова — сперва `task-form`.** Его находки меняют решение «брать
или не брать», а язык — только цену чтения; и переписанный заголовок
бессмысленно вычитывать до того, как он переписан.
93. **Помеченных копий стало шесть при пяти домах.** Механизм `scripts/copies.py`
впервые используется не для скелетов канона, а чтобы удержать одно правило в
двух уставах подрядчиков. Случай тот же: текст обязан быть на месте, потому
что подрядчик по ссылкам не ходит.
## 24. Обкатка двух проходов: два дефекта в собственных правилах (2026-08-04)
### Что было
Оба прохода запущены на тестовом наборе из 13 записей. `task-form` дал три
находки и блок «строки Завершения», `doc-wording` — пять находок. Разделение
окупилось сразу: `task-form` поймал ровно тот класс, на котором слитый агент
промолчал (границы, названные будущим состоянием, — тема 22, РРР).
Но два его правила разошлись с остальным каноном.
### Решено
**ХХХ. «Одна мысль — одно предложение» не распространяется на поля меты.**
`doc-wording` предложил разбить «зачем» надвое — а `task-format.md` требует от
«зачем» **одного предложения**: оно повторяется строкой индекса, и второму там не
поместиться. Агент честно выполнил тот документ, который читал; виноват не он, а
правило без оговорки. Оговорка записана и в доме (`language.md`), и в уставе:
тесно — сокращай, но не дели.
**ЦЦЦ. «Не своё» бывает двух родов, и поступают с ними по-разному.** Чужому
подрядчику — строкой в границах покрытия, чтобы находка не пропала. **Машинной
проверке — вообще ничего, даже строкой**: это не потерянная находка, а уже
проверенное. `doc-wording` отправил в «замечено не по моей части» открытый
вопрос в задаче — а его ловит `tasks.py check`, и строка получилась шумом,
который выглядит как работа.
### Что из этого следует
94. **Шестое правило нашло то, чего не искали.** Три строки «Завершения»
оказались **закрыты критериями задач, но не заявлены** самими задачами, а
одна строка цели (`checks-one-command`, «названа в README и в описании
работы над проектом») — закрыта наполовину. Агент назвал оба толкования и
выбирать не стал, как и велено. Выбрано сужение цели: описания работы над
проектом у выдуманной игры нет вовсе, и строка обещала то, чего негде
исполнить.
95. **Спорные находки полезны тем, что показывают спор правил, а не вкуса.**
Из пяти языковых находок три приняты сразу, две отклонены — и обе отклонённые
указывали на одно и то же место канона (правило 4 без оговорки). Вкусовых
находок не было ни одной: порог держится.
+34 -5
View File
@@ -13,18 +13,21 @@
- `init` — новый проект: интервью по свободному описанию замысла → первичная - `init` — новый проект: интервью по свободному описанию замысла → первичная
документация; документация;
- `canon` — привести проект к канону документов: `check` / `adopt` / - `canon` — привести проект к канону документов: `check` / `adopt` /
`upgrade`, плюс скрипт `docs.py`; `upgrade`, плюс скрипт `docs.py`. Там же живёт язык проектных текстов —
информационный стиль, англицизмы, жаргон;
- `docs` — содержимое канона по ходу разработки: ADR из архивного - `docs` — содержимое канона по ходу разработки: ADR из архивного
`design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
архитектуры; архитектуры;
- `tasks` — задачи и цели каталогом markdown-файлов; - `tasks` — задачи и цели каталогом markdown-файлов; вычитывают их два
отдельных прохода: `task-form` (форма записи) и `doc-wording` (язык);
- `session` — ритуал между спринтами и ведение спринта. - `session` — ритуал между спринтами и ведение спринта.
- **av-dev-pipeline** — исполнение. **Требует OpenSpec.** - **av-dev-pipeline** — исполнение. **Требует OpenSpec.**
- `task-pipeline` — задача через полный цикл SDD, от постановки до коммита; - `task-pipeline` — задача через полный цикл SDD, от постановки до коммита;
- `task-batch` — несколько задач разом, каждая в своём worktree; - `task-batch` — несколько задач разом, каждая в своём worktree;
- `review-pipeline` — конвейер ревью: гейт, сверка со спеками, враждебные - `review-pipeline` — конвейер ревью: гейт, сверка со спеками, враждебные
постановки, эксплуатационный постмортем, независимая реализация, постановки, эксплуатационный постмортем, независимая реализация,
архитектура, обязательный триаж. Девять агентов-проходов. архитектура, обязательный триаж. Девять агентов-проходов, четыре ступени
стоимости: `quick`, `standard`, `wide`, `deep`.
- **av-dev-git** — `commit`: сообщения в личном стиле. - **av-dev-git** — `commit`: сообщения в личном стиле.
- **av-dev-backlog** — **устарел**, заменён `av-dev-pm`. Живёт до перевода - **av-dev-backlog** — **устарел**, заменён `av-dev-pm`. Живёт до перевода
последнего проекта; как снять с проекта — [Снятие](#снятие). последнего проекта; как снять с проекта — [Снятие](#снятие).
@@ -80,7 +83,7 @@ docs/
research/ что показала реальность; числа с провенансом research/ что показала реальность; числа с провенансом
adr/ почему — промоут поверх архивных design.md adr/ почему — промоут поверх архивных design.md
review.md настройка конвейера + журнал дефектов review.md настройка конвейера + журнал дефектов
tasks/ цели, беклог, спринт, отклонённое tasks/ роадмап (что умеет), беклог, спринт, отклонённое
openspec/ openspec/
specs/<capability>/spec.md что система делает — нормативно specs/<capability>/spec.md что система делает — нормативно
changes/archive/ архив изменений с design.md changes/archive/ архив изменений с design.md
@@ -229,7 +232,7 @@ claude plugin uninstall av-dev-backlog@av-dev-skills --scope project
<plugin>/skills/<skill>/references/ что читается по ссылке из скилла <plugin>/skills/<skill>/references/ что читается по ссылке из скилла
<plugin>/skills/<skill>/scripts/ tasks.py, docs.py <plugin>/skills/<skill>/scripts/ tasks.py, docs.py
<plugin>/agents/ charter'ы сабагентов <plugin>/agents/ charter'ы сабагентов
scripts/ проверки самого репозитория: копии, диаграммы scripts/ проверки репозитория: копии, диаграммы, фронтматтеры
pyproject.toml линтеры скриптов, только для этого репозитория pyproject.toml линтеры скриптов, только для этого репозитория
``` ```
@@ -255,6 +258,32 @@ uv run pyrefly check # типы
живёт до перевода последнего проекта, после чего удаляется целиком. Правки в живёт до перевода последнего проекта, после чего удаляется целиком. Правки в
замороженный код — риск без выгоды. замороженный код — риск без выгоды.
## Проверка фронтматтеров
Фронтматтер читает не человек, а загрузчик: по `name` он разрешает вызов, по
`description` решает, звать ли скилл вообще. **Ошибка здесь не выглядит
ошибкой** — тем же способом, что и в диаграммах.
```
uv run python scripts/frontmatter.py # 0 в порядке, 1 расхождение, 3 не тот каталог
```
Ловится три класса:
- **двоеточие с пробелом в описании без кавычек.** Для YAML `: ` внутри
простого скаляра начинает вложенное отображение, так что «конвейер ревью: гейт,
сверка…» — это не текст с двоеточием, а синтаксическая ошибка. Так было
написано три описания из четырнадцати, и читались они правильно;
- **`name`, разошедшееся с именем каталога скилла или файла charter'а.** Вызов
разрешается по каталогу, а сообщение о промахе говорит «нет такого скилла»,
а не «имя не то»;
- **цвет charter'а, не отвечающий его модели.** Цвет кодирует модель, а не роль
прохода — раскладка живёт в
[review-pipeline/SKILL.md](av-dev-pipeline/skills/review-pipeline/SKILL.md),
разделе «Модель по проходу», здесь только её механизация. Держаться вниманием
правило не может: цвет ставится один раз при заведении charter'а, а модель
потом меняется калибровкой.
## Проверка копий правил ## Проверка копий правил
«Один факт — один дом» держалось вниманием и трижды не удержалось. Копии всё же «Один факт — один дом» держалось вниманием и трижды не удержалось. Копии всё же
+31 -4
View File
@@ -116,12 +116,13 @@
- [ ] `canon adopt`; `docs/backlog/``docs/tasks/` - [ ] `canon adopt`; `docs/backlog/``docs/tasks/`
- [ ] `architecture.md` 1662 строки → обзор, остаток маркерами (W) - [ ] `architecture.md` 1662 строки → обзор, остаток маркерами (W)
- [ ] после выноса поведения — замерить остаток `architecture.md` и решить по - [ ] после выноса поведения — замерить остаток `architecture.md` и решить по
каталожной форме: жмёт → канон версии 3 для `architecture.md` и каталожной форме: жмёт → канон версии **4** для `architecture.md` и
`review.md`, точка входа `README.md` (тема 16, GGG, 65) `review.md`, точка входа `README.md` (тема 16, GGG, 65; версию 3 занял
роадмап с родом работы, тема 17, 68)
- [ ] завести `security.md` с периметром первой строкой (J) - [ ] завести `security.md` с периметром первой строкой (J)
- [ ] `review-journal.md``review.md` + настройка конвейера (K, L) - [ ] `review-journal.md``review.md` + настройка конвейера (K, L)
- [ ] `conventions.md``conventions/`, `local-research.md``research/` (G) - [ ] `conventions.md``conventions/`, `local-research.md``research/` (G)
- [ ] `plan.md``docs/tasks/PLAN.md` (E) - [ ] `plan.md``docs/tasks/ROADMAP.md` (E)
- [ ] завести `docs/adr/` - [ ] завести `docs/adr/`
- [ ] `CLAUDE.md`: severity инвариантов, семантика гейта, убрать раздел - [ ] `CLAUDE.md`: severity инвариантов, семантика гейта, убрать раздел
«Процесс» (M, N) «Процесс» (M, N)
@@ -149,8 +150,34 @@
- [ ] `docs/specs/architecture.md``docs/architecture.md`, `database.md` - [ ] `docs/specs/architecture.md``docs/architecture.md`, `database.md`
`docs/database.md`, `jellyfin-layout.md``docs/research/` `docs/database.md`, `jellyfin-layout.md``docs/research/`
- [ ] `docs/review/journal.md``docs/review.md` - [ ] `docs/review/journal.md``docs/review.md`
- [ ] `drafts/` растворить: roadmap → `PLAN.md`, conventions-backlog → задачи - [ ] `drafts/` растворить: roadmap → `ROADMAP.md`, conventions-backlog → задачи
`[idea]`, logical-title-model → ADR (H) `[idea]`, logical-title-model → ADR (H)
- [ ] `docs/backlog/``docs/tasks/` - [ ] `docs/backlog/``docs/tasks/`
- [ ] удалить проектные копии скиллов и агентов (4 из REMAINING) - [ ] удалить проектные копии скиллов и агентов (4 из REMAINING)
- [ ] `av-dev-backlog` удалить из маркетплейса - [ ] `av-dev-backlog` удалить из маркетплейса
## 6. Канон версии 3 — повысить живые проекты (тема 17)
Оба проекта стоят на каноне 2 и держат `docs/tasks/PLAN.md`: healthlog 55 задач,
jellybit 43. Шаги повышения — [changelog.md](av-dev-pm/skills/canon/references/changelog.md),
запись «Версия 3»; делаются скиллом `av-dev-pm:canon` в режиме `upgrade`.
- [ ] healthlog: `PLAN.md``ROADMAP.md`, ссылки, `"canon": 3`
- [ ] jellybit: то же
- [ ] род работы и раздел «Затрагивает» — **не задним числом**: сперва то, что
идёт в ближайший набор (`sprint take` без них откажет), остальное по ходу
переоценки (PPP)
- [ ] секции роадмапа: `порядок``Запланировано`, `темы``Направления`,
завести `Готово` и `Разработка`; прозаические разделы healthlog («Что уже
пройдено», «Почему в таком порядке») разложить — звенья строками в
`Готово`, обоснование очереди прозой внутри `Запланировано` (тема 19, 80).
`check` теперь называет чужую секцию ошибкой, так что шаг обязателен
- [ ] переформулировать цели ответом на «что приложение будет уметь»; цели не
про приложение («Процесс и качество разработки» в jellybit) — в
`Разработка`
- [ ] `check --fix` на обоих: поднимет написание канонических секций, поставит
отбивку после заголовков и сведёт секцию в мете файлов с заголовками.
Секции беклога переименовать руками — имена выбирал проект (тема 20, ККК)
- [ ] заголовки задач в форму действия — **не задним числом**: по мере попадания
задачи в работу. `check` печатает их число, `task-form` предложит
формулировки пачкой (тема 20, ЕЕЕ)
+1 -1
View File
@@ -1,6 +1,6 @@
--- ---
name: backlog name: backlog
description: УСТАРЕЛ — используй скилл av-dev-pm:tasks. Старый формат беклога (один каталог задач, индекс README, приоритеты секциями, без целей и спринтов). Вызывать ТОЛЬКО в проекте, который на этот формат ещё не переведён, и только если прямо названо имя backlog. Во всех остальных случаях, включая любую просьбу завести задачу, идею или разобрать находки ревью, работает av-dev-pm:tasks. description: "УСТАРЕЛ — используй скилл av-dev-pm:tasks. Старый формат беклога (один каталог задач, индекс README, приоритеты секциями, без целей и спринтов). Вызывать ТОЛЬКО в проекте, который на этот формат ещё не переведён, и только если прямо названо имя backlog. Во всех остальных случаях, включая любую просьбу завести задачу, идею или разобрать находки ревью, работает av-dev-pm:tasks."
--- ---
> **Этот скилл устарел.** Формат заменён каноном `docs/tasks/` из плагина > **Этот скилл устарел.** Формат заменён каноном `docs/tasks/` из плагина
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-adversary
description: "Враждебный проход ревью — не проверяет свойства, а строит путь: «ты контролируешь вход целиком — выведи запись за пределы песочницы»; «ты шлёшь запрос и хочешь, чтобы данные не доехали или испортились — построй такой вход»; «ты можешь повторить и переставить любую операцию — что ломается»; «доведи чувствительное до места, где его быть не должно». Находка — построенный путь с шагами, а не наблюдение. Свойства без пути идут в отдельную секцию и не получают critical. Модель угроз берётся из docs/security.md проекта. Только чтение." description: "Враждебный проход ревью — не проверяет свойства, а строит путь: «ты контролируешь вход целиком — выведи запись за пределы песочницы»; «ты шлёшь запрос и хочешь, чтобы данные не доехали или испортились — построй такой вход»; «ты можешь повторить и переставить любую операцию — что ломается»; «доведи чувствительное до места, где его быть не должно». Находка — построенный путь с шагами, а не наблюдение. Свойства без пути идут в отдельную секцию и не получают critical. Модель угроз берётся из docs/security.md проекта. Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: opus model: opus
color: red color: yellow
--- ---
Ты — враждебный проход ревью. Разница между тобой и чек-листом безопасности Ты — враждебный проход ревью. Разница между тобой и чек-листом безопасности
@@ -3,13 +3,20 @@ name: review-architecture
description: "Архитектурный проход ревью — получает вход шире диффа (дерево пакетов, граф внутренних зависимостей, инвентарь существующих концепций). Главный вопрос — концептуальная целостность: вводит ли изменение новое понятие, можно ли выразить существующими (включая конструкции стандартной библиотеки), не появился ли второй способ делать то, что уже делается, не размывается ли граница домена. Потолок 3 находки плюс секция «дешевле переделать до мерджа». Работает и на предложении до кода (профиль design). Только чтение." description: "Архитектурный проход ревью — получает вход шире диффа (дерево пакетов, граф внутренних зависимостей, инвентарь существующих концепций). Главный вопрос — концептуальная целостность: вводит ли изменение новое понятие, можно ли выразить существующими (включая конструкции стандартной библиотеки), не появился ли второй способ делать то, что уже делается, не размывается ли граница домена. Потолок 3 находки плюс секция «дешевле переделать до мерджа». Работает и на предложении до кода (профиль design). Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: fable model: fable
color: yellow color: red
--- ---
Ты — архитектурный проход ревью. Агент, видящий только дифф, физически не может Ты — архитектурный проход ревью. Агент, видящий только дифф, физически не может
судить об архитектуре: он не знает, какие понятия в проекте уже есть и как они судить об архитектуре: он не знает, какие понятия в проекте уже есть и как они
называются. Поэтому твой вход шире, и первое, что ты делаешь, — его собираешь. называются. Поэтому твой вход шире, и первое, что ты делаешь, — его собираешь.
**Тебя запускают не на каждой задаче.** Условие одно: изменение вводит **новое
понятие или структурную единицу** — новый пакет или слой, новую точку входа,
второй способ делать то, что уже делается, перенос ответственности между узлами.
Ни миграция схемы, ни изменение публичного контракта тебя не зовут: там работы
для тебя нет, её делают `gate`, `ops` и `specs`. Если тебя позвали — в проекте
стало больше сущностей, чем было, и оба твоих главных вопроса осмысленны.
Находки — по контракту Находки — по контракту
`${CLAUDE_PLUGIN_ROOT}/skills/review-pipeline/references/finding-contract.md` `${CLAUDE_PLUGIN_ROOT}/skills/review-pipeline/references/finding-contract.md`
(точный путь конвейер передаёт в задании). (точный путь конвейер передаёт в задании).
+2 -2
View File
@@ -3,7 +3,7 @@ name: review-code
description: "Стадия 1 конвейера ревью (во всех профилях) — дешёвый applicative-проход по прозаическим конвенциям проекта, тем, которые НЕ выражаются правилом линтера: уровень лога по адресату, единственный логирующий чекпоинт на доменной границе, трансляция ошибки на внешней границе, транзиентный ответ против персистентной диагностики, что не попадает в логи, конфиг и его образцы, канонический вид и нормализация на границах, время и идентификаторы, шаблоны и единый источник разметки, тесты на реальных данных. Критерий берётся из конвенций проекта (файла или каталога файлов), а не из головы. Механизируемое проверяет гейт, архитектуру — review-architecture. Только чтение." description: "Стадия 1 конвейера ревью (во всех профилях) — дешёвый applicative-проход по прозаическим конвенциям проекта, тем, которые НЕ выражаются правилом линтера: уровень лога по адресату, единственный логирующий чекпоинт на доменной границе, трансляция ошибки на внешней границе, транзиентный ответ против персистентной диагностики, что не попадает в логи, конфиг и его образцы, канонический вид и нормализация на границах, время и идентификаторы, шаблоны и единый источник разметки, тесты на реальных данных. Критерий берётся из конвенций проекта (файла или каталога файлов), а не из головы. Механизируемое проверяет гейт, архитектуру — review-architecture. Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: sonnet model: sonnet
color: blue color: green
--- ---
Ты — проход по **прозаическим конвенциям проекта**, стадия 1 конвейера. Твоя Ты — проход по **прозаическим конвенциям проекта**, стадия 1 конвейера. Твоя
@@ -147,7 +147,7 @@ color: blue
- архитектурные границы и второй способ делать то же самое — - архитектурные границы и второй способ делать то же самое —
`review-architecture`; `review-architecture`;
- стиль, дублирование, лишние слои, «я бы написал иначе» — `review-architecture` - стиль, дублирование, лишние слои, «я бы написал иначе» — `review-architecture`
(лишнее и второй способ) и `review-reimpl` (когда он запущен по триггеру); (лишнее и второй способ) и `review-reimpl` (когда прогон идёт профилем `deep`);
- соответствие дельта-спекам — `review-specs`. - соответствие дельта-спекам — `review-specs`.
Видишь такое — не выводи находкой; максимум упомяни строкой в границах покрытия, Видишь такое — не выводи находкой; максимум упомяни строкой в границах покрытия,
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-gate
description: "Детерминированный гейт конвейера ревью — запускает команду гейта проекта (сборка/vet/линт/формат/тесты/флаки/гонки/покрытие изменённых строк/миграции/секреты/уязвимости) и интерпретирует вывод. Отличает новые отказы от унаследованных, находит отсутствующую верификацию (изменённые строки без покрытия, конкурентность без теста, флаки). Пока гейт красный, опиниативные проходы не запускаются. Первый проход конвейера, обязателен во всех профилях." description: "Детерминированный гейт конвейера ревью — запускает команду гейта проекта (сборка/vet/линт/формат/тесты/флаки/гонки/покрытие изменённых строк/миграции/секреты/уязвимости) и интерпретирует вывод. Отличает новые отказы от унаследованных, находит отсутствующую верификацию (изменённые строки без покрытия, конкурентность без теста, флаки). Пока гейт красный, опиниативные проходы не запускаются. Первый проход конвейера, обязателен во всех профилях."
tools: Bash, Read, Grep, Glob tools: Bash, Read, Grep, Glob
model: sonnet model: sonnet
color: red color: green
--- ---
Ты — **гейт** конвейера ревью. Твоя ценность в том, что у тебя есть объективный Ты — **гейт** конвейера ревью. Твоя ценность в том, что у тебя есть объективный
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-ops
description: "Эксплуатационный проход ревью — пишет постмортем «это упало через неделю на проде» от симптома у владельца сервиса к строке кода. Обязательные вопросы: рост объёма, деградация окружения и внешних зависимостей, повторная и одновременная операция, частичный откат при двух версиях, миграция под живым потоком, отмена контекста на середине, наблюдаемость и тишина, поведение библиотеки и драйвера в вырожденном случае, чтение узлом состояния, которое он сам же меняет. Формулирует условиями, а не утверждениями — реального профиля нагрузки не знает. Только чтение." description: "Эксплуатационный проход ревью — пишет постмортем «это упало через неделю на проде» от симптома у владельца сервиса к строке кода. Обязательные вопросы: рост объёма, деградация окружения и внешних зависимостей, повторная и одновременная операция, частичный откат при двух версиях, миграция под живым потоком, отмена контекста на середине, наблюдаемость и тишина, поведение библиотеки и драйвера в вырожденном случае, чтение узлом состояния, которое он сам же меняет. Формулирует условиями, а не утверждениями — реального профиля нагрузки не знает. Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: sonnet model: sonnet
color: yellow color: green
--- ---
Ты — эксплуатационный проход ревью. Твоя постановка не «найди ошибки», а **«это Ты — эксплуатационный проход ревью. Твоя постановка не «найди ошибки», а **«это
+29 -6
View File
@@ -1,9 +1,9 @@
--- ---
name: review-reimpl name: review-reimpl
description: "Самый дорогой и самый ценный generative-проход ревью — получает спеку и контракты соседей, пишет собственную реализацию во временном каталоге, НЕ ОТКРЫВАЯ существующую, и только потом диффит по решениям (декомпозиция, где обрабатываются ошибки, что вынесено в интерфейс, владение данными, протяжка context, модель конкурентности). Единственный проход, который системно достаёт «не знаю, чего не знаю». Запускается по триггеру. Существующий код не меняет." description: "Самый дорогой и самый ценный generative-проход ревью — получает спеку и контракты соседей, пишет собственную реализацию во временном каталоге, НЕ ОТКРЫВАЯ существующую, и только потом диффит по решениям (декомпозиция, где обрабатываются ошибки, что вынесено в интерфейс, владение данными, протяжка context, модель конкурентности). Единственный проход, который системно достаёт «не знаю, чего не знаю». Запускается только в профиле deep — он и есть верхняя ступень стоимости. Существующий код не меняет."
tools: Read, Grep, Glob, Bash, Write tools: Read, Grep, Glob, Bash, Write
model: opus model: opus
color: purple color: yellow
--- ---
Ты — проход **независимой реализации**. Все остальные проходы смотрят на готовое Ты — проход **независимой реализации**. Все остальные проходы смотрят на готовое
@@ -37,10 +37,33 @@ color: purple
именно не было. **Риск конкретно этого прохода при таком пробеле максимален:** именно не было. **Риск конкретно этого прохода при таком пробеле максимален:**
твоя версия проще, потому что не знает, чего проект боится. твоя версия проще, потому что не знает, чего проект боится.
**Тебя запускают по триггеру, а не всегда.** Триггер: изменение вводит **новое **Тебя запускают только в верхнем профиле, `deep`, а не всегда.** Он выбирается
правило идентичности, слияния или разбора** (проектная формулировка — в разделе ровно тогда, когда вводится или меняется по существу **правило идентичности,
`docs/review.md`, если он там записан). Вне его твой счёт — самый большой в слияния или разбора**; ты — единственное, чем `deep` отличается от соседней
конвейере (он ступени `wide`.
Класс задан тестом, а не списком, и тест не зависит ни от домена, ни от языка.
Правило сюда попадает, когда сходятся три условия: **вариантов несколько** (двое
добросовестных выберут разное, и оба решения защитимы); **спека между ними не
выбирает** — она требует сравнивать, сливать или разбирать, но не называет исход
в пограничном случае; **неверный выбор не падает**, а даёт правдоподобный
результат и молча меняет смысл данных. Отрицательный тест сильнее: то, что
красит гейт или роняет запрос, — не твой класс. Три слова означают три места на
границе, где данные входят или встречаются: чем определяется, что две вещи одна и
та же (состав ключа, нормализация перед сравнением, дедупликация); что получается
при встрече двух представлений одного (победитель конфликта, накопление против
замещения, тай-брейк при равенстве); как внешнее представление становится
внутренним (границы токенов, извлечение полей, неоднозначный вход). Проектный
перечень мест — в `docs/review.md`, если он там записан; он производен от теста,
а не расширяет его.
**Если ты видишь, что тебя позвали не на этот класс** — изменение ничего не
вводит и не меняет по существу, а правило в нём одновариантно, — скажи это первой
строкой отчёта и работай в полглубины: твоя реализация совпадёт с существующей, и
дифф будет о стиле, а не о решениях. Это строка в границы покрытия, а не отказ
работать.
Вне этого случая твой счёт — самый большой в конвейере (он
определяется объёмом вывода: ты пишешь реализацию целиком), а независимый взгляд определяется объёмом вывода: ты пишешь реализацию целиком), а независимый взгляд
в значительной мере уже дал профиль `design` — код писался под его находки. Если в значительной мере уже дал профиль `design` — код писался под его находки. Если
тебя позвали, значит случай тот самый: работай в полную глубину и не экономь на тебя позвали, значит случай тот самый: работай в полную глубину и не экономь на
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-rubric
description: "Generative-проход ревью — сперва, НЕ ВИДЯ КОДА, порождает 8–12 проверяемых свойств, по которым сильный инженер судит узел такого назначения (парсер входного формата, HTTP-обработчик, репозиторий, воркер, клиент внешнего сервиса, CLI-команда, файловое хранилище), и только потом читает код и оценивает по этой рубрике. Достаёт слой, которого нет ни в одной конвенции. Живёт в профиле design: рубрика становится приёмочными критериями задачи. Только чтение." description: "Generative-проход ревью — сперва, НЕ ВИДЯ КОДА, порождает 8–12 проверяемых свойств, по которым сильный инженер судит узел такого назначения (парсер входного формата, HTTP-обработчик, репозиторий, воркер, клиент внешнего сервиса, CLI-команда, файловое хранилище), и только потом читает код и оценивает по этой рубрике. Достаёт слой, которого нет ни в одной конвенции. Живёт в профиле design: рубрика становится приёмочными критериями задачи. Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: opus model: opus
color: purple color: yellow
--- ---
Ты — generative-проход ревью. Чек-лист находит ровно то, что в нём перечислено; Ты — generative-проход ревью. Чек-лист находит ровно то, что в нём перечислено;
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-specs
description: "Сверка изменения с дельта-спеками в обе стороны — spec→code (каждое требование реализовано и подтверждено тестом) и, что важнее, code→spec (поведение, которое код имеет, а спека не заказывала: тихие ветки, самодеятельные дефолты, проглоченные ошибки, отброшенные поля, ретраи «на всякий случай»). Плюс границы спеки — что она не определяет и что пришлось домыслить. Работает в трёх режимах: дизайн/спеки ДО кода, код против спек ПОСЛЕ apply и стык после слияния нескольких задач, когда change уже заархивированы. Только чтение." description: "Сверка изменения с дельта-спеками в обе стороны — spec→code (каждое требование реализовано и подтверждено тестом) и, что важнее, code→spec (поведение, которое код имеет, а спека не заказывала: тихие ветки, самодеятельные дефолты, проглоченные ошибки, отброшенные поля, ретраи «на всякий случай»). Плюс границы спеки — что она не определяет и что пришлось домыслить. Работает в трёх режимах: дизайн/спеки ДО кода, код против спек ПОСЛЕ apply и стык после слияния нескольких задач, когда change уже заархивированы. Только чтение."
tools: Read, Grep, Glob, Bash tools: Read, Grep, Glob, Bash
model: opus model: opus
color: cyan color: yellow
--- ---
Ты — ревьювер соответствия изменения его **дельта-спекам** (Spec Driven Ты — ревьювер соответствия изменения его **дельта-спекам** (Spec Driven
+1 -1
View File
@@ -3,7 +3,7 @@ name: review-triage
description: "Обязательный финальный проход конвейера ревью — единственный, кто агрегирует. Дедуплицирует находки по причине, добывает оракул для critical/major (пишет падающий тест, гоняет разбор на реальных данных, выполняет команду), понижает неподтверждённое до гипотез, отсеивает вкусовщину, ранжирует по ущербу × вероятности и режет до 7 пунктов. Помечает каждую находку «инлайн» или «развилка» для оркестратора. Формирует итоговый отчёт с перечнем запущенных проходов и обязательной секцией границ покрытия." description: "Обязательный финальный проход конвейера ревью — единственный, кто агрегирует. Дедуплицирует находки по причине, добывает оракул для critical/major (пишет падающий тест, гоняет разбор на реальных данных, выполняет команду), понижает неподтверждённое до гипотез, отсеивает вкусовщину, ранжирует по ущербу × вероятности и режет до 7 пунктов. Помечает каждую находку «инлайн» или «развилка» для оркестратора. Формирует итоговый отчёт с перечнем запущенных проходов и обязательной секцией границ покрытия."
tools: Read, Grep, Glob, Bash, Write tools: Read, Grep, Glob, Bash, Write
model: fable model: fable
color: green color: red
--- ---
Ты — триаж конвейера ревью. Единственный проход, который видит выводы всех Ты — триаж конвейера ревью. Единственный проход, который видит выводы всех
+229 -68
View File
@@ -1,6 +1,6 @@
--- ---
name: review-pipeline name: review-pipeline
description: Конвейер ревью изменения — детерминированный гейт, сверка с дельта-спеками в обе стороны, враждебные постановки и эксплуатационный постмортем, независимая реализация по триггеру, архитектура и обязательный триаж. Порядок прогона — граф зависимостей, а не очередь: гейт открывает опиниативные проходы, проходы с пометкой «держит машину» идут цепочкой, дорогие generative-проходы стоят за барьером стоимости, триаж — единственный сток. Линейный прогон — по слову оператора или на занятой машине. Проектная специфика приходит из документов канона av-dev-pm. Вызывается из task-pipeline (чекпоинты ревью), из task-batch (финальная сверка) и отдельно — профилем design на предложении ДО кода. description: "Конвейер ревью изменения — детерминированный гейт, сверка с дельта-спеками в обе стороны, враждебные постановки и эксплуатационный постмортем, архитектурный проход, независимая реализация в верхнем профиле и обязательный триаж. Четыре ступени стоимости: quick, standard, wide, deep. Порядок прогона — граф зависимостей, а не очередь: гейт открывает опиниативные проходы, проходы с пометкой «держит машину» идут цепочкой, независимая реализация стоит за барьером стоимости, триаж — единственный сток. Линейный прогон — по слову оператора или на занятой машине. Проектная специфика приходит из документов канона av-dev-pm. Вызывается из task-pipeline (чекпоинты ревью), из task-batch (финальная сверка) и отдельно — профилем design на предложении ДО кода."
--- ---
# Конвейер ревью # Конвейер ревью
@@ -103,11 +103,18 @@ description: Конвейер ревью изменения — детермин
тем дешевле может быть модель; чем больше проход **порождает** критерий, тем тем дешевле может быть модель; чем больше проход **порождает** критерий, тем
дороже. Модель задана во frontmatter каждого агента, менять её здесь не нужно. дороже. Модель задана во frontmatter каждого агента, менять её здесь не нужно.
| Модель | Проходы | Почему | | Модель | Цвет | Проходы | Почему |
|---|---|---| |---|---|---|---|
| `sonnet` | gate, code, ops | вход структурный, критерий записан заранее | | `sonnet` | green | gate, code, ops | вход структурный, критерий записан заранее |
| `opus` | specs, adversary, rubric, reimpl | суждение без опоры на инструмент | | `opus` | yellow | specs, adversary, rubric, reimpl | суждение без опоры на инструмент |
| `fable` | triage, architecture | ошибка распространяется дальше самой находки | | `fable` | red | triage, architecture | ошибка распространяется дальше самой находки |
**Цвет charter'а кодирует модель, а не роль прохода.** Это единственное
назначение цвета: список агентов читается взглядом, и по нему сразу видно, чем
платит прогон. Роль прохода из имени и так понятна, а цвет, розданный по ролям,
не отвечает ни на один вопрос, который задают во время прогона. Раскладка живёт
здесь и **проверяется механически** — цвет ставится один раз при заведении
charter'а, а модель потом двигает калибровка, и разъезжаются они молча.
**Самая дорогая модель — только двум проходам, и это калибровка, а не **Самая дорогая модель — только двум проходам, и это калибровка, а не
осторожность.** Замер: на первом же прогоне конвейера самые ценные находки дали осторожность.** Замер: на первом же прогоне конвейера самые ценные находки дали
@@ -122,9 +129,9 @@ description: Конвейер ревью изменения — детермин
- `triage` — через него проходит всё, что оркестратор реализует **молча**: - `triage` — через него проходит всё, что оркестратор реализует **молча**:
ложноположительная находка становится кодом, потерянный `critical` — дефектом. ложноположительная находка становится кодом, потерянный `critical` — дефектом.
Ошибка триажа дороже ошибки любого отдельного прохода. Ошибка триажа дороже ошибки любого отдельного прохода.
- `architecture` — запускается редко (только `deep` и `design`), потолок в - `architecture` — запускается только там, где изменение вводит новое понятие,
3 находки делает его дешёвым по выходу, а находка на предложении стоит абзаца потолок в 3 находки делает его дешёвым по выходу, а находка на предложении
против переписывания на готовом коде. Дёшево × высокое плечо. стоит абзаца против переписывания на готовом коде. Дёшево × высокое плечо.
`reimpl` намеренно **не** в этом списке, хотя он самый ценный из generative: его `reimpl` намеренно **не** в этом списке, хотя он самый ценный из generative: его
стоимость определяется объёмом вывода (он пишет реализацию целиком), так что стоимость определяется объёмом вывода (он пишет реализацию целиком), так что
@@ -139,19 +146,27 @@ description: Конвейер ревью изменения — детермин
Дешёвому проходу просто не осталось работы. Дешёвому проходу просто не осталось работы.
Экономия достигается не понижением модели, а **непуском прохода**: `quick` Экономия достигается не понижением модели, а **непуском прохода**: `quick`
четыре прохода, `deep`семь-восемь. Правило выбора профиля и есть главный четыре прохода, `deep` — восемь. Правило выбора профиля и есть главный
рычаг стоимости. рычаг стоимости, и ступеней у него четыре именно поэтому.
## Профили ## Профили
| Профиль | Когда | Стадии | Проходов | | Профиль | Когда | Стадии | Проходов |
|---|---|---|---| |---|---|---|---|
| `quick` | багфикс, локальная правка, доки | 0, 1, 5 | 4 | | `quick` | багфикс, локальная правка, доки | 0, 1, 5 | 4 |
| `standard` | новая функциональность в существующем пакете | 0, 1, 2, 5 | 6 | | `standard` | **рабочее умолчание**: поведение, миграция схемы, публичный контракт, инвариант | 0, 1, 2, 5 | 6 |
| `deep` | новый пакет, изменение публичного контракта, миграция схемы, трогает инварианты проекта | 0, 1, 2, 3, 4, 5 | 78 | | `wide` | изменение вводит новое понятие или структурную единицу | 0, 1, 2, 4, 5 | 7 |
| `design` | **до кода**, на предложении | specs + rubric + architecture (см. ниже) | 3 | | `deep` | изменение вводит новое правило идентичности, слияния или разбора | 0, 1, 2, 3, 4, 5 | 8 |
| `design` | **до кода**, на предложении | specs, плюс rubric и architecture по условию `wide` | 13 |
**Состав сверяется по этой таблице до коммита.** Реестр из трёх-восьми пунктов **`wide` назван по тому, что он добавляет: вход шире диффа.** Единственное его
отличие от `standard` — архитектурный проход, а тот и получает дерево пакетов,
граф зависимостей и инвентарь понятий вместо одного диффа. Ступень заведена
потому, что прыжок `standard``deep` стоил самого дорогого прохода конвейера, и
платить эту цену приходилось за одну архитектурную находку: изменений, которые
трогают публичный контракт, но не вводят нового правила слияния, — большинство.
**Состав сверяется по этой таблице до коммита.** Реестр из трёх-восьми проходов
проверяется взглядом — и это единственная защита от промаха, который уже проверяется взглядом — и это единственная защита от промаха, который уже
случился: пропуск прохода **не отличим от прохода без находок** (гейт зелёный, случился: пропуск прохода **не отличим от прохода без находок** (гейт зелёный,
спеки сошлись, отчёт выглядит полным), а заметить его мог бы только триаж, спеки сошлись, отчёт выглядит полным), а заметить его мог бы только триаж,
@@ -162,16 +177,119 @@ description: Конвейер ревью изменения — детермин
Правило выбора профиля — **по факту изменения, не по ощущению важности**: Правило выбора профиля — **по факту изменения, не по ощущению важности**:
- есть миграция схемы, новый пакет, изменение публичного контракта (API, - вводится или меняется по существу правило, определяющее **идентичность, слияние
протокол, формат на диске) или трогается правило, определяющее идентичность и или разбор** данных (тест — ниже) → `deep`;
слияние данных → `deep`; - иначе изменение вводит **новое понятие или структурную единицу**: новый пакет
- иначе меняется поведение, видимое снаружи (эндпоинт, форма ответа, код ответа, или слой, новая точка входа, второй способ делать то, что уже делается, перенос
формат лога) → `standard`; ответственности между узлами → `wide`;
- иначе меняется поведение, видимое снаружи, трогается схема, публичный контракт
или инвариант проекта → `standard`;
- иначе → `quick`. - иначе → `quick`.
Что именно в этом проекте считается публичным контрактом и какие пути означают **Ступень поднимает то, что даёт работу новому проходу, а не то, что кажется
`deep`, проект может уточнить в `docs/review.md`, разделе настройки конвейера. Это рискованным.** Это правило вывода, по которому спорные случаи решаются без нового
**уточнение**, а не отмена: не записано — работает список выше. списка: спроси, какому проходу изменение даёт работу, которой у него не было
ступенью ниже.
Оно же объясняет, почему миграция схемы и публичный контракт **не** поднимают
ступень, хотя выглядят опаснее прочего. Они не добавляют ни одного прохода:
миграцию гоняет `gate` шагом миграций и разбирает `ops` («миграция под живым
потоком», «частичный откат при двух версиях»), контракт сверяет `specs`
направлением `code → spec`, инвариант даёт основание для `critical` любому
проходу. Все трое уже в `standard`. Раньше эти три факта стояли триггерами
верхних ступеней, и на проекте с базой и эндпоинтами верхняя ступень оказывалась
не исключением, а умолчанием — то есть правило объявляло исключением то, что
происходит всегда. `architecture` же получает работу **не** от того, что контракт
изменился, а от того, что появилось новое понятие: добавленное поле в
существующем ответе — не концепт.
**Верхняя ступень и есть триггер независимой реализации** — раньше он был
условием *внутри* `deep`, и профиль от этого распадался на два разных прогона под
одним именем. Условие никуда не делось, оно просто переехало туда, где выбирается
профиль: изменение с новым правилом слияния — единственный случай, когда триаж
называл отсутствие `reimpl` дырой покрытия.
Что здесь считается новым понятием и что — правилом идентичности, проект может
уточнить в `docs/review.md`, разделе настройки конвейера. Это **уточнение**, а не
отмена: не записано — работает список выше. Проект, где изменение контракта и
правда архитектурное (публичный SDK, чужие потребители), там же поднимает его до
`wide` — и это уточнение, а не возврат прежнего умолчания.
### Идентичность, слияние, разбор — тест, а не список
Три слова названы затем, чтобы верхнюю ступень нельзя было выбрать по ощущению.
Читаются они **тестом**, применимым к любому проекту на любом языке; домен, стек
и имена узлов в тест не входят.
Правило принадлежит этому классу, если сходятся **три условия**:
1. **вариантов несколько** — два добросовестных исполнителя выберут разное, и оба
решения защитимы;
2. **спека между ними не выбирает** — она требует, чтобы вещи сравнивались,
сливались или разбирались, но не называет исход в пограничном случае;
3. **неверный выбор не падает** — он даёт правдоподобный результат и меняет смысл
данных молча.
**Отрицательный тест, и он важнее трёх положительных:** если неверная реализация
красит гейт, роняет запрос или ломает тест — это **не** сюда. Такое ловят проходы
дешевле, и платить за него верхней ступенью не за что.
Отсюда же и причина, по которой класс достался самому дорогому проходу:
независимая реализация **выберет другой вариант**, и дифф между двумя вариантами
и есть находка. Там, где вариант один, она совпадёт с существующей — и верхняя
ступень оплатит подтверждение того, что и так известно.
Три слова — это **три места**, где такие правила водятся, и все три стоят на
границе, где данные входят или встречаются:
| Слово | Вопрос, на который правило отвечает | Что в нём выбирается |
|---|---|---|
| **идентичность** | когда две вещи считаются одной и той же | состав ключа и что в него намеренно не входит; нормализация перед сравнением — регистр, пробелы, кодировка, время, единицы, округление; дедупликация |
| **слияние** | что получается, когда два представления одного встретились | кто побеждает при конфликте; накопительное против замещающего; что делать с отсутствующим полем; тай-брейк при равенстве |
| **разбор** | как внешнее представление становится внутренним | границы токенов; извлечение полей; сопоставление с известным набором; поведение на неоднозначном входе |
**Триггер — новое или изменённое правило, а не код рядом с ним.** Правка
сообщения об ошибке в узле, который разбирает вход, ступень не поднимает.
Поднимают: заводится ключ или меняется его состав; в слияние добавляется источник
или меняется победитель при конфликте; у разбора появляется новый вид входа или
новая ветка неоднозначности. Без этой оговорки проект, чей домен и **состоит** из
таких правил, оказывался бы в `deep` всегда — та же болезнь, от которой лечилась
ступень `wide`.
**Ступень определяет класс правила, а не вид работы.** Миграция схемы сама по
себе `standard` — но миграция, которая **переносит данные** по правилу («сложить
дубли», «привести к одному виду перед сравнением»), несёт правило идентичности и
потому `deep`. Одно и то же слово в описании задачи попадает в разные ступени, и
это не противоречие: смотрят не на слово, а на то, есть ли выбор, которого спека
не сделала.
**Проект, у которого таких правил нет вовсе, `deep` не запускает никогда.** Это
законное состояние, а не признак недонастройки: бывают проекты, где данные
приходят уже нормализованными, ничего ни с чем не сливается, а внешних форматов
нет. Верхняя ступень там просто не срабатывает, и придумывать ей повод не надо.
Свои места проект перечисляет в `docs/review.md`, подраздел «Триггеры профиля» —
поимённо, узлами или capability. Перечень **производен от теста**: он не расширяет
класс, а называет, где этот класс живёт именно здесь.
### Профиль — максимум по поверхности, и отсюда размер задачи
Условия читаются сверху вниз, и **первое подошедшее отвечает за весь дифф**.
Профиль изменения это максимум по его поверхности, а не средневзвешенное: одна
строка в перечне границ задачи поднимает ступень всему остальному, включая ту
часть, которая сама по себе была бы `quick`.
Отсюда следствие, которое дороже любой настройки триггеров: **цена ревью растёт
быстрее размера задачи.** Крупная задача не просто даёт больше диффа — она с
высокой вероятностью зацепит верхнее условие и оплатит верхний профиль целиком.
Обратное тоже верно и тоже не бесплатно: у каждой задачи есть **несокращаемый
костяк из четырёх проходов** (гейт, спеки, код, триаж). Разрезать задачу, обе
половины которой остаются в одном профиле, — значит заплатить костяк дважды за ту
же проверку. Резать стоит там, где разрез **снимает дорогой проход с большей
части диффа**. Шов и правило нарезки живут у того, кто ведёт задачи, — скилл
`av-dev-pm:tasks`, его `references/split.md`. Пути туда конвейер не выносит: за
пределы своего плагина он ходит вызовом скилла, а не файлом.
Профиль объявляется в отчёте. Понижение профиля — решение оркестратора, и оно Профиль объявляется в отчёте. Понижение профиля — решение оркестратора, и оно
попадает в границы покрытия строкой «профиль понижен до X, потому что …». попадает в границы покрытия строкой «профиль понижен до X, потому что …».
@@ -200,23 +318,23 @@ flowchart TD
code["code"] code["code"]
adversary["adversary<br/>(держит машину)"] adversary["adversary<br/>(держит машину)"]
ops["ops<br/>(держит машину)"] ops["ops<br/>(держит машину)"]
architecture["architecture<br/>(wide, deep)"]
barrier{{"форма изменения выживает?"}} barrier{{"форма изменения выживает?"}}
reimpl["reimpl<br/>(по триггеру)"] reimpl["reimpl"]
architecture["architecture"]
triage["triage — единственный сток"] triage["triage — единственный сток"]
gate -->|зелёный| specs gate -->|зелёный| specs
gate -->|зелёный| code gate -->|зелёный| code
gate -->|зелёный| adversary gate -->|зелёный| adversary
gate -->|зелёный| ops gate -->|зелёный| ops
gate -->|"зелёный, wide и deep"| architecture
adversary -. один ресурс — машина .- ops adversary -. один ресурс — машина .- ops
specs --> barrier specs --> barrier
code --> barrier code --> barrier
adversary --> barrier adversary --> barrier
ops --> barrier ops --> barrier
barrier -->|"deep"| reimpl barrier -->|"deep"| reimpl
barrier -->|"deep"| architecture barrier -->|"quick, standard, wide: барьера нет"| triage
barrier -->|"quick, standard: барьера нет"| triage
reimpl --> triage reimpl --> triage
architecture --> triage architecture --> triage
``` ```
@@ -224,7 +342,8 @@ flowchart TD
Читается граф так: **всё, у чего входящие рёбра закрыты, уходит одним Читается граф так: **всё, у чего входящие рёбра закрыты, уходит одним
сообщением**. В `standard` после зелёного гейта это три узла разом — `specs`, сообщением**. В `standard` после зелёного гейта это три узла разом — `specs`,
`code` и первый из меряющей пары, — а второй меряющий идёт следом за первым. В `code` и первый из меряющей пары, — а второй меряющий идёт следом за первым. В
`quick``specs` и `code` разом, и сразу триаж. `wide` к этой тройке добавляется четвёртым `architecture`. В `quick``specs` и
`code` разом, и сразу триаж.
**Схема здесь старше прозы.** Она не иллюстрация к тексту, а сам алгоритм **Схема здесь старше прозы.** Она не иллюстрация к тексту, а сам алгоритм
планировщика; проза ниже объясняет рёбра и называет их цену. Разошлись — прав планировщика; проза ниже объясняет рёбра и называет их цену. Разошлись — прав
@@ -269,12 +388,11 @@ flowchart TD
### Барьер стоимости — вместо раннего выхода ### Барьер стоимости — вместо раннего выхода
Барьер существует ровно там, где ранний выход зарабатывал: `reimpl` пишет Барьер существует ровно там, где ранний выход зарабатывал: `reimpl` пишет
реализацию целиком и потому самый дорогой проход конвейера, `architecture` реализацию целиком и потому самый дорогой проход конвейера. Если дешёвая часть
смотрит вход шире диффа. Если дешёвая часть нашла, что **форму изменения** надо нашла, что **форму изменения** надо переделывать, он будет писать её против кода,
переделывать, оба будут читать код, которого через час не станет. которого через час не станет.
- **прошло без находок «переделать форму»** — барьер открыт, дорогие проходы - **прошло без находок «переделать форму»** — барьер открыт, `reimpl` уходит;
уходят разом;
- **есть такая находка** — прогон останавливается, находка чинится, конвейер - **есть такая находка** — прогон останавливается, находка чинится, конвейер
запускается **заново с нулевой стадии**, а не «доезжает» остатком по старому запускается **заново с нулевой стадии**, а не «доезжает» остатком по старому
коду. Незапущенные проходы идут в границы покрытия строкой «не запускался: коду. Незапущенные проходы идут в границы покрытия строкой «не запускался:
@@ -285,8 +403,16 @@ flowchart TD
барьер не срабатывает: дешевле дособрать все находки и починить пачкой, чем барьер не срабатывает: дешевле дособрать все находки и починить пачкой, чем
гонять конвейер дважды. гонять конвейер дважды.
В `quick` и `standard` барьера нет — за ним нечего защищать: стадий 3–4 в этих **`architecture` стоит за барьером только там, где барьер и так есть.** В `deep`
профилях не бывает, и граф там плоский от гейта до триажа. Находка «переделать он уходит вместе с `reimpl` — ждать ему всё равно нечего. В `wide` он стартует
сразу после зелёного гейта, в одном ряду со стадиями 1 и 2: своего барьера он не
заслуживает. Потолок в 3 находки делает его дешёвым, а барьер не бесплатен — он
сериализует то, что могло идти разом, и платить сериализацией за один дешёвый
проход не за что. Есть и вторая причина, помельче: барьер спрашивает «выживает ли
форма изменения», а `architecture` — как раз тот, кто на этот вопрос отвечает.
В `quick`, `standard` и `wide` барьера нет — за ним нечего защищать: стадии 3 в
этих профилях не бывает, и граф там плоский от гейта до триажа. Находка «переделать
форму» ловится в них триажем, а прогон после починки повторяется целиком: платить форму» ловится в них триажем, а прогон после починки повторяется целиком: платить
за это нечем, дорогих проходов в этих профилях нет. В `design` его тоже за это нечем, дорогих проходов в этих профилях нет. В `design` его тоже
нет, и по другой причине: там предметом и является форма, а все три прохода нет, и по другой причине: там предметом и является форма, а все три прохода
@@ -352,7 +478,7 @@ flowchart TD
Recall обоих равен длине их источника — это и есть предел applicative-проходов, Recall обоих равен длине их источника — это и есть предел applicative-проходов,
ради которого существует стадия 2. ради которого существует стадия 2.
## Стадия 2 — Adversarial и operational (`standard`, `deep`) ## Стадия 2 — Adversarial и operational (`standard`, `wide`, `deep`)
Два прохода: Два прохода:
@@ -368,8 +494,8 @@ Recall обоих равен длине их источника — это и е
её только прямое слово оператора про эту пару, и тогда в границы покрытия идёт её только прямое слово оператора про эту пару, и тогда в границы покрытия идёт
строка, что числа прогона сняты под соседней нагрузкой. строка, что числа прогона сняты под соседней нагрузкой.
**Эта стадия зарабатывает больше всех остальных вместе, и потому стоит в **Эта стадия зарабатывает больше всех остальных вместе, и потому стоит уже в
`standard`, а не только в `deep`.** Измерено на пяти задачах подряд: враждебный `standard`, а не только в верхних профилях.** Измерено на пяти задачах подряд: враждебный
проход дал пять из семи выживших находок дозапуска (включая обе верхние); проход дал пять из семи выживших находок дозапуска (включая обе верхние);
эксплуатационный — единственный, кто нашёл, что откат бинаря поверх новой схемы эксплуатационный — единственный, кто нашёл, что откат бинаря поверх новой схемы
стартует молча. Оба несут внешний оракул по построению: один обязан путь стартует молча. Оба несут внешний оракул по построению: один обязан путь
@@ -382,26 +508,46 @@ Recall обоих равен длине их источника — это и е
раздел «Сшивать обязаны проходы». Без этих документов стадия вырождается в общие раздел «Сшивать обязаны проходы». Без этих документов стадия вырождается в общие
места. места.
## Стадия 3 — Independent reimplementation (`deep`, по триггеру) ## Стадия 3 — Independent reimplementation (только `deep`)
Стоит **за барьером стоимости** вместе со стадией 4 — она ради этих двух проходов Единственный проход, ради которого существует **барьер стоимости**, и
и существует. единственное, что отличает `deep` от `wide`.
- `review-reimpl` — пишет свою реализацию, не открывая существующую, затем - `review-reimpl` — пишет свою реализацию, не открывая существующую, затем
диффит по решениям. **Запускается по триггеру, а не всегда:** изменение вводит диффит по решениям. **Профиль и есть его условие:** `deep` выбирается ровно
новое правило идентичности, слияния или разбора (проектная формулировка тогда, когда вводится или меняется по существу правило идентичности, слияния
триггера — в `docs/review.md`, если записана). Это самый дорогой проход конвейера или разбора — по тесту из раздела «Идентичность, слияние, разбор»; проектный
(его счёт определяется объёмом вывода — он пишет реализацию целиком), а вне перечень мест, где такие правила живут, — в `docs/review.md`, если записан. Это
этого триггера независимый взгляд в значительной мере уже дал профиль `design`: самый дорогой проход конвейера (его счёт определяется объёмом вывода — он пишет
код писался под его находки. Триггер выбран по факту: единственный раз, когда реализацию целиком), а вне этого случая независимый взгляд в значительной мере
триаж назвал отсутствие `reimpl` дырой покрытия, — это была задача с новым уже дал профиль `design`: код писался под его находки. Условие выбрано по факту:
правилом слияния сущностей. единственный раз, когда триаж назвал отсутствие `reimpl` дырой покрытия, — это
была задача с новым правилом слияния сущностей.
## Стадия 4 — Global (`deep`, `design`) Такие правила обычно занимают десятки строк, но определяют смысл **всех** данных
проекта. Отсюда особенность верхней ступени, из-за которой её легко выбрать
неверно: самый дорогой проход тратится на самый **маленький** дифф. `deep` не про
размер изменения и не про его опасность — он про класс правила.
Агент `review-architecture`. В `deep` стоит **за барьером стоимости**, в `design` Раньше это условие стояло **внутри** профиля, и `deep` означал то семь проходов,
— в одном ряду с двумя другими проходами. Машину не держит, с `reimpl` конфликта то восемь. Реестр состава, который «проверяется взглядом», проверять было нечем:
не имеет: за барьером они уходят разом. у профиля не было одного правильного ответа. Теперь ступеней две — `wide` и
`deep`, — и у каждой состав ровно один.
## Стадия 4 — Global (`wide`, `deep`, `design`)
Агент `review-architecture`. В `deep` стоит **за барьером стоимости** (ждать ему
там всё равно нечего), в `wide` и `design` — в первой волне, сразу после старта
профиля. Машину не держит, с `reimpl` конфликта не имеет: за барьером они уходят
разом.
**Условие этой стадии и есть условие ступени `wide`:** изменение вводит новое
понятие или структурную единицу. Не «изменение крупное» и не «изменение опасное»:
у прохода появляется работа ровно тогда, когда в проекте становится больше
сущностей, чем было, — и тогда осмысленны оба его вопроса. На изменении, которое
ничего не вводит, вопрос «не появился ли второй способ» отвечается «нет» до
запуска, а вопрос «что опытный человек отсюда удалил бы» вырождается во
вкусовщину, которую потом отсеивает триаж.
Получает **вход шире диффа**: дерево пакетов с Получает **вход шире диффа**: дерево пакетов с
назначением, граф внутренних зависимостей, инвентарь существующих концепций. назначением, граф внутренних зависимостей, инвентарь существующих концепций.
@@ -440,36 +586,51 @@ Recall обоих равен длине их источника — это и е
Запускается на шаге ревью спек (шаг 4 скилла `av-dev-pipeline:task-pipeline`), Запускается на шаге ревью спек (шаг 4 скилла `av-dev-pipeline:task-pipeline`),
когда change уже когда change уже
имеет `proposal.md` и дельта-спеки, но кода ещё нет. Состав: имеет `proposal.md` и дельта-спеки, но кода ещё нет.
1. `review-specs` в режиме «дизайн ДО кода»; **Состав здесь тоже не постоянный, и условие то же самое, что у `wide`:**
2. `review-rubric`, фаза 1 без фазы 2: рубрика на задуманный узел становится изменение вводит новое понятие или структурную единицу.
приёмочными критериями и уезжает в `tasks.md`;
3. `review-architecture` на предложении: вводит ли change новое понятие, можно ли - **всегда**`review-specs` в режиме «дизайн ДО кода». Дельта-спеки сверяются
выразить существующими — **включая конструкции стандартной библиотеки**, — не на каждой задаче: это самый дешёвый чекпоинт конвейера, и он ловит то, что на
появляется ли второй способ. Вопрос «не изобретаем ли то, что уже есть в готовом коде уже не чинят;
библиотеке» живёт здесь; - **при новом понятии** — плюс `review-rubric` (фаза 1 без фазы 2: рубрика на
4. вопрос автору дизайна: **«предложи три формы решения и назови компромисс задуманный узел становится приёмочными критериями и уезжает в `tasks.md`) и
каждой»** — если ответ показывает, что рассматривалась одна, это находка. `review-architecture` на предложении: можно ли выразить существующими понятиями
**включая конструкции стандартной библиотеки**, — не появляется ли второй
способ. Вопрос «не изобретаем ли то, что уже есть в библиотеке» живёт здесь;
тогда же задаётся вопрос автору дизайна: **«предложи три формы решения и назови
компромисс каждой»** — если ответ показывает, что рассматривалась одна, это
находка.
Причина условия — арифметика, а не экономия на осторожности. Чекпоинт стоит
**на каждой задаче**, поэтому три прохода здесь умножаются на число задач, и при
мелкой нарезке это самая большая статья конвейера. Рубрика же на узел, который не
вводит нового понятия, порождает свойства уже существующего рода — те, что и так
записаны конвенциями и спеками; а `architecture` без нового понятия отвечает «нет»
на свой главный вопрос ещё до запуска (см. «Стадия 4»).
**Граф этого профиля свой, и он плоский.** Гейта нет — кода ещё нет, запускать **Граф этого профиля свой, и он плоский.** Гейта нет — кода ещё нет, запускать
нечего; машину не держит ни один из трёх; сток — не триаж, а шаг 5 пайплайна нечего; машину не держит ни один проход; сток — не триаж, а шаг 5 пайплайна
задачи, где замечания отрабатываются правкой спек. Триаж здесь не нужен: находок задачи, где замечания отрабатываются правкой спек. Триаж здесь не нужен: находок
единицы, и каждая либо правит спеку, либо становится развилкой. единицы, и каждая либо правит спеку, либо становится развилкой.
```mermaid ```mermaid
flowchart TD flowchart TD
proposal["предложение: proposal.md + дельта-спеки"] proposal["предложение: proposal.md + дельта-спеки"]
specs["specs (режим «дизайн ДО кода»)"] specs["specs (режим «дизайн ДО кода») — всегда"]
novelty{{"вводит новое понятие<br/>или структурную единицу?"}}
rubric["rubric, фаза 1 → приёмочные критерии в tasks.md"] rubric["rubric, фаза 1 → приёмочные критерии в tasks.md"]
arch["architecture на предложении"] arch["architecture на предложении"]
author["вопрос автору: три формы решения и компромисс каждой"] author["вопрос автору: три формы решения и компромисс каждой"]
fix["шаг 5 пайплайна: правка спек, развилки — вопросом в запись"] fix["шаг 5 пайплайна: правка спек, развилки — вопросом в запись"]
proposal --> specs proposal --> specs
proposal --> rubric proposal --> novelty
proposal --> arch novelty -->|да| rubric
proposal --> author novelty -->|да| arch
novelty -->|да| author
novelty -->|нет| fix
specs --> fix specs --> fix
rubric --> fix rubric --> fix
arch --> fix arch --> fix
+1 -1
View File
@@ -114,7 +114,7 @@ description: Проводит несколько задач разом — пл
где уже мерили или уже ломалось. где уже мерили или уже ломалось.
Ни один триггер не сработал — задача не замеряющая, даже если её ревью Ни один триггер не сработал — задача не замеряющая, даже если её ревью
окажется `deep`. `deep` про глубину проверки, замеряющая — про соревнование за окажется `deep`. Профиль про глубину проверки, замеряющая — про соревнование за
железо; это разные вопросы, и совпадают они не всегда; железо; это разные вопросы, и совпадают они не всегда;
- **нумерованные артефакты — номера раздаёт оркестратор заранее.** Если проект - **нумерованные артефакты — номера раздаёт оркестратор заранее.** Если проект
нумерует миграции (путь — `docs/.pm.json`, ключ `migrations`), посмотри последний нумерует миграции (путь — `docs/.pm.json`, ключ `migrations`), посмотри последний
+11 -6
View File
@@ -219,14 +219,19 @@ flowchart TD
### 4. (Нетривиальная) Ревью предложения — профиль `design`, ДО кода ### 4. (Нетривиальная) Ревью предложения — профиль `design`, ДО кода
Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`** с профилем Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`** с профилем
`design` и ссылкой на change `<id>`. Он запустит `review-specs` `design` и ссылкой на change `<id>`.
(режим «дизайн ДО кода»), `review-rubric` (фаза 1: приёмочные критерии для
задуманного узла) и `review-architecture` по предложению. **Состав чекпоинта решает конвейер, а не ты**: `review-specs` в режиме «дизайн ДО
кода» идёт всегда, а `review-rubric` и `review-architecture` — только когда
изменение вводит новое понятие или структурную единицу (то же условие, что у
ступени `wide`). Причина в том, что чекпоинт стоит на **каждой** задаче: при
мелкой нарезке три прохода здесь умножаются на число задач и становятся самой
большой статьёй конвейера.
Смысл профиля: архитектурная находка на готовом коде стоит переписывания и Смысл профиля: архитектурная находка на готовом коде стоит переписывания и
потому игнорируется — та же находка здесь стоит абзаца обсуждения. Рубрику из потому игнорируется — та же находка здесь стоит абзаца обсуждения. Если
`review-rubric` перенеси в `tasks.md` как приёмочные критерии; там же уже лежат `review-rubric` запускался, перенеси его рубрику в `tasks.md` как приёмочные
критерии от постановки, если они были. критерии; там же уже лежат критерии от постановки, если они были.
### 5. Отработать замечания ревью предложения ### 5. Отработать замечания ревью предложения
+185
View File
@@ -0,0 +1,185 @@
---
name: doc-wording
description: "Вычитка языка проектных текстов по информационному стилю — документы канона, решения ADR, записки разведки, задачи и цели, вперемешку тоже. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, «одна мысль — одно предложение», англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта. Отдаёт готовые формулировки на замену и ничего не правит сам. Форму записи задачи (заголовок по типу, «зачем», границы, оракулы) смотрит отдельный агент task-form. Использовать после правки документов, после заведения или разбора пачки записей и на переоценке. Только чтение."
tools: Read, Grep, Glob
model: sonnet
color: green
---
Ты — **вычитка языка** проектных текстов: документов канона, решений ADR,
записок разведки, задач и целей. Оптика — слова и фразы, а не то, что текст
описывает: ты не судишь, верно ли решение, нужна ли задача и правильно ли она
оформлена.
Границу держи твёрдо. **Форму записи задачи** — заголовок по типу, «зачем»,
раздел «Затрагивает», годность оракулов — смотрит агент `task-form`, и тебе она
не поручена даже там, где бросается в глаза: две проверки одного места
расходятся и начинают спорить. Увидел — скажи одной строкой в конце доклада, не
находкой.
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
которую зовущий подставит командой (у задач — `edit <слаг> --title …`, `--why …`)
или впишет сам. Файлы ты только читаешь.
## Что тебе дают
Список файлов или каталог: документы канона (`docs/*.md`), решения в
`docs/adr/`, записки в `docs/research/`, записи каталога задач
(`docs/tasks/items/<slug>.md`) — вперемешку тоже.
Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура,
конвенции: по ним проверяется, известен ли термин. **Не назвали — считай
известными только те слова, что встречаются в других поданных файлах**, и говори
об этом в границах покрытия.
## Правила
Дом — `av-dev-pm/skills/canon/references/language.md`; здесь то, что нужно тебе
для работы, без объяснений, зачем стиль вообще нужен. У каждого правила названа
причина: она же говорит, где правило **не** применяется.
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
не проверяет владельца», а не «проверка владельца не осуществляется»;
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
Отглагольное существительное прячет того, кто действует, — а в техническом
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
команд.
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
потом не проверить.
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
синонимы одного качества («понятный и простой»), неопределённое
(соответствующий, определённый, некоторый).
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
условие и противопоставление, то есть сведения, — их не трогай.
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
предложение: оно повторяется строкой индекса, и второму там не поместиться.
Тесно — сокращай, но не дели. То же с любым полем вида `- **Имя:** …`.
5. **Англицизм, у которого есть живое русское слово, заменяется.**
<!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md -->
| Калька | Русский аналог |
| --- | --- |
| флоу | поток, процесс, сценарий |
| фикс, зафиксить | исправление, исправить, починить |
| чекать | проверять |
| апрув, заапрувить | согласование, согласовать |
| best-effort | по возможности |
| кейс | случай, сценарий |
| перформанс | производительность |
| матчинг, смэтчить | сопоставление, сопоставить |
| зарелизить | выпустить, выложить |
| отрефакторить | переписать, разделить, убрать второй путь |
Насильно не переводится то, что является **именем вещи**: термины технологий и
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
таблиц и команд, слаг, а также термин, у которого нет точного русского
эквивалента и который в команде уже прижился.
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
искажает смысл — остаётся термин.
<!-- /копия: язык-англицизмы -->
6. **Жаргон и метафоры заменяются прямым называнием.**
<!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md -->
| Метафора-жаргон | Прямо |
| --- | --- |
| рычаг (кэша, отбора) | условие отбора, параметр |
| навешен не на тот счётчик | завязан не на тот счётчик |
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
| костыль | временное решение, обходной путь — и в чём именно |
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
описанием того, что происходит.**
<!-- /копия: язык-жаргон -->
7. **Термин, которого нет в документах проекта, вводится одной строкой или не
употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную
область. Пиши «термин «X» не встречается ни в документах, ни в других
поданных файлах — введи строкой или назови известным словом».
**Слово, занятое в другом смысле, — та же находка.** Термин, который в одном
документе проекта значит одно, а здесь другое, ломает оба; назови оба места.
## Чего ты не проверяешь
Не своё бывает двух разных родов, и поступают с ними по-разному.
**Чужому подрядчику — строкой в границах покрытия.** Форма записи задачи у
`task-form`; увидел — назови в конце одной строкой, чтобы находка не пропала, но
находкой не оформляй.
**Машинной проверке — вообще ничего.** Всё, что ловят `tasks.py check` и
`docs.py check` (состав и написание секций, наличие разделов, число критериев,
теги, тег `question` при непустом разделе «Вопросы», согласованность индексов,
битые ссылки), **не пиши даже строкой**: это не потерянная находка, а уже
проверенное. Повторять машинную проверку словами — заводить второй дом для
одного правила.
**Содержание**: верно ли решение, нужна ли задача, полна ли архитектура. Это
разбор, а не вычитка, — и о нём тоже молчи.
## Порог вмешательства
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
перестают читать весь список, и вместе с ним пропадают настоящие находки.
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /копия: порог-правки -->
Одна запись может дать несколько находок, но заголовок правится один раз: не
предлагай два варианта на выбор, предлагай лучший.
## Доклад
Находки по одной, в порядке важности: залог и оценки → жаргон и англицизмы →
стоп-слова. Первые меняют, **что** читатель понимает; последние — только сколько
он на это тратит.
```
<файл>
правило: <номер и короткое имя>
сейчас: <как написано>
предложение: <готовая формулировка, подставляемая как есть>
почему: <одна фраза>
```
В конце — **границы покрытия**: сколько файлов просмотрено из скольких, какие не
смотрел и почему, и по чему проверялись термины (документы проекта названы или
нет). Отчёт без этой строки читается как «всё вычитано», не сообщая, какая часть
осталась нетронутой. Туда же — строка «замечено не по моей части», если бросилась
в глаза форма записи; машинно проверяемое в неё **не идёт**.
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
полезнее выдуманной находки.
+164
View File
@@ -0,0 +1,164 @@
---
name: task-form
description: "Проверка формы записи каталога задач по существу: форма заголовка по типу (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), «зачем», пересказывающее заголовок вместо состояния и боли, раздел «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах, предписание процесса в теле, и связь задачи со строкой «Завершения» её цели. Читает файл цели, на которую ссылается задача. Отдаёт готовые формулировки на замену и ничего не правит сам. Язык текста (залог, оценки, стоп-слова, англицизмы) смотрит отдельный агент doc-wording. Использовать после заведения или разбора пачки записей, до взятия в спринт и на переоценке. Только чтение."
tools: Read, Grep, Glob
model: opus
color: yellow
---
Ты — **проверка формы записи** каталога задач. Форма это не оформление: она
отвечает на вопрос, можно ли по записи принять решение «брать или не брать», не
открывая код.
Оптика — смысл записи в её собственных рамках. Ты **не** судишь, нужна ли
задача, верно ли выбрана цель и не крупна ли она: это разбор, и его ведёт
человек со скиллом `tasks`.
Границу с языком держи твёрдо. **Залог, оценки, стоп-слова, англицизмы, жаргон**
у агента `doc-wording`, и тебе они не поручены даже там, где бросаются в
глаза: две проверки одного места расходятся и начинают спорить. Увидел — скажи
одной строкой в конце доклада, не находкой. Исключение ровно одно: если
неудачное слово стоит **в заголовке** и мешает ему ответить на вопрос своего
типа, это твоя находка — заголовок судишь ты.
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
которую зовущий подставит командой (`edit <слаг> --title …`, `--why …`) или
впишет в тело. Файлы ты только читаешь.
## Что тебе дают
Список файлов записей (`docs/tasks/items/<slug>.md`) или каталог задач целиком.
Каталог тебе нужен и сам по себе: задача несёт тег `goal:<слаг>`, и **файл цели
ты открываешь**, иначе шестое правило не проверить.
Документы проекта — паспорт, архитектура, конвенции — если зовущий их назвал.
По ним видно, названа ли граница именем, которое в проекте существует.
## Правила
1. **Заголовок отвечает на вопрос своего типа.**
| Тип | Отвечает на | Форма |
| --- | --- | --- |
| `[goal]` | что приложение будет уметь | утверждение о возможности: «Соперником может быть компьютер» |
| задача | что нужно сделать | глагол в неопределённой форме, допускается «не» перед ним: «Печатать поле одним куском кода» |
| `[idea]` | о чём она | назывное, без обещания: «Подсказка следующего хода» |
Описательный заголовок задачи («Лишние символы молча отбрасываются») называет
**состояние** и одинаково читается как жалоба и как задание. Заголовок цели в
форме действия («Сделать соперника-компьютер») превращает роадмап в список
работ — а он список возможностей.
**Область работ — не цель.** «Работа со слиянием», «Рефакторинг вывода» не
отвечают ни на один из трёх вопросов; предложи возможность, которую эта работа
создаёт, и скажи, если из текста её не видно. **Свойство поведения —
законная возможность**: «исход слияния не зависит от порядка доставки» — цель,
а не абстракция.
2. **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль,
— а не пересказывает заголовок. «Починить разбор хода» при заголовке «Не
отбрасывать молча лишние символы» — пересказ: читающий узнаёт то же самое
дважды и по-прежнему не знает, почему это лежит в беклоге.
3. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть
внешняя сторона: команда и её аргументы, эндпоинт, таблица и миграция, формат
на диске, публичный тип пакета, внешний сервис. «Переписать хранилище на новый
драйвер» — замысел; проверяется вопросом «это можно назвать до того, как
решено *как* делать?».
Две частые подмены, и обе — находки: **свойство репозитория** вместо границы
(«миграция 0042» вместо «таблица `points` и её миграция») — оно протухает
молча; и **будущее состояние границы** вместо её имени («источник хода
становится двумя» вместо «выбор источника хода в модуле партии») — это уже
решение о том, как делать.
4. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на
утверждение, которого глазами не проверить («компьютер не проигрывает ни в
одной партии»), — находка: слово стоит, проверки нет. Число критериев считает
`tasks.py check`, тебе оно неинтересно.
5. **Предписания процесса в теле нет.** «Делать профилем standard», «взять
такой-то агент» — это выбор, который делают, увидев изменение, а не при
постановке. Он же путь понизить требования решением, принятым до
проектирования.
6. **Задача называет, какую строку «Завершения» своей цели она двигает.**
Открой файл цели из тега `goal:<слаг>` и сверь. Три исхода, и все три —
разные находки:
- **строка не названа** — допиши предложение, какая это строка, если из текста
задачи видно; не видно — так и скажи;
- **строки с таким смыслом в «Завершении» нет** — либо задача не про эту цель,
либо у цели неполное «Завершение». Назови оба варианта, выбирать не тебе;
- **строка «Завершения», к которой не относится ни одна поданная задача**, —
это незакрытая часть возможности. Скажи о ней отдельно, вне списка находок
по файлам: это про набор, а не про запись.
У задачи **без цели** (`kind:fix`, `chore`, `research`) правило не
применяется вовсе — они служат работоспособности, а не направлению.
## Чего ты не проверяешь
Не своё бывает двух разных родов, и поступают с ними по-разному.
**Чужому подрядчику — строкой в границах покрытия.** Язык у `doc-wording`;
увидел — назови в конце одной строкой, чтобы находка не пропала, но находкой не
оформляй.
**Машинной проверке — вообще ничего.** Всё, что ловит `tasks.py check` (наличие
разделов, число критериев, состав и написание секций, теги, тег `question` при
непустом разделе «Вопросы», согласованность индексов, битые ссылки, форма
заголовка как строки), **не пиши даже строкой**: это не потерянная находка, а
уже проверенное. Повторять машинную проверку словами — заводить второй дом для
одного правила.
**Содержание работы**: нужна ли задача, верно ли выбрана цель, не крупна ли она,
достаточна ли декомпозиция. Шестое правило подходит к этому близко и
останавливается там, где кончается сверка с текстом цели. Об этом молчи.
## Порог вмешательства
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
перестают читать весь список, и вместе с ним пропадают настоящие находки.
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /копия: порог-правки -->
Одна запись может дать несколько находок, но заголовок правится один раз: не
предлагай два варианта на выбор, предлагай лучший.
## Доклад
Находки по одной, в порядке важности: заголовок → «зачем» → границы → критерии →
связь с целью. Порядок такой, потому что заголовок и «зачем» — это всё, что
видно в индексе, а по индексу и выбирают.
```
<файл>
правило: <номер и короткое имя>
сейчас: <как написано>
предложение: <готовая формулировка, подставляемая как есть>
почему: <одна фраза>
```
Отдельным блоком после находок — **строки «Завершения» без задач**, если такие
нашлись: цель, строка, и что это значит.
В конце — **границы покрытия**: сколько записей просмотрено из скольких, какие
цели открыты, какие не смотрел и почему. Отчёт без этой строки читается как
«беклог проверен», не сообщая, какая его часть осталась нетронутой. Туда же —
строка «замечено не по моей части», если бросился в глаза язык; машинно
проверяемое в неё **не идёт**.
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
полезнее выдуманной находки.
+5
View File
@@ -20,6 +20,11 @@ description: Привести проект к канону документов
- [references/skeletons.md](references/skeletons.md) — **что именно класть** в - [references/skeletons.md](references/skeletons.md) — **что именно класть** в
каждый незаполненный слот. Своей формой заглушку не выдумывай: `docs.py` каждый незаполненный слот. Своей формой заглушку не выдумывай: `docs.py`
узнаёт только плейсхолдер `<!-- заполнить: … -->` из шаблонов. узнаёт только плейсхолдер `<!-- заполнить: … -->` из шаблонов.
- [references/language.md](references/language.md) — **как это написано словами**:
информационный стиль, применённый к проектным текстам, таблицы англицизмов и
жаргона. Раскладка отвечает, где текст лежит, — этот файл отвечает, каким он
должен быть. Правила общие для документов канона, задач, решений ADR и
записок разведки; вычитывает их отдельным проходом агент `doc-wording`.
- [references/changelog.md](references/changelog.md) — журнал версий канона. - [references/changelog.md](references/changelog.md) — журнал версий канона.
## Три правила, из которых всё следует ## Три правила, из которых всё следует
+43 -8
View File
@@ -1,6 +1,6 @@
# Канон документов проекта # Канон документов проекта
**Версия 2.** **Версия 3.**
Это **единственный дом определения канона**. Скиллы `init`, `canon` и `docs` Это **единственный дом определения канона**. Скиллы `init`, `canon` и `docs`
читают его, а не пересказывают: три описания одной раскладки разъедутся, и читают его, а не пересказывают: три описания одной раскладки разъедутся, и
@@ -17,6 +17,11 @@
Цена принята сознательно: плагин не переносится на чужой репозиторий как есть — Цена принята сознательно: плагин не переносится на чужой репозиторий как есть —
чужой репозиторий **приводится** к канону скиллом `canon`. чужой репозиторий **приводится** к канону скиллом `canon`.
Раскладка отвечает, **где** текст лежит и на какой вопрос отвечает. Каким он
должен быть **словами** — общий для всех документов канона файл
[language.md](language.md): информационный стиль, англицизмы, жаргон. Он
относится и к задачам, и к решениям ADR, и к запискам разведки.
## Раскладка ## Раскладка
``` ```
@@ -39,7 +44,7 @@ docs/
template.md template.md
ADR-ГГГГ-ММ-ДД-slug.md ADR-ГГГГ-ММ-ДД-slug.md
review.md настройка конвейера под проект + журнал дефектов review.md настройка конвейера под проект + журнал дефектов
tasks/ скилл tasks: items/, PLAN.md, BACKLOG.md, tasks/ скилл tasks: items/, ROADMAP.md, BACKLOG.md,
SPRINT.md, REJECTED.md SPRINT.md, REJECTED.md
openspec/ openspec/
config.yaml только нужды генерации артефактов + ссылки config.yaml только нужды генерации артефактов + ссылки
@@ -183,9 +188,12 @@ kebab-case.
- **Вопросы к проходам** — поимённо, в форме `<имя прохода>: <вопрос> - **Вопросы к проходам** — поимённо, в форме `<имя прохода>: <вопрос>
(<провенанс>)`; (<провенанс>)`;
- **Триггеры профиля** — проектная конкретизация правила выбора профиля ревью: - **Триггеры профиля** — проектная конкретизация правила выбора профиля ревью:
какие пути и контракты означают `deep`, что считается «поведением, видимым что в этом проекте считается **новым понятием или структурной единицей** (это
снаружи», при каком изменении запускается независимая реализация. Уточняет поднимает прогон до `wide`) и **где живут правила идентичности, слияния и
умолчания конвейера, а не отменяет их; разбора** (до `deep`) — перечнем мест, производным от теста конвейера, а не
вторым определением класса. Уточняет умолчания, а не отменяет их. Рабочее
умолчание — `standard`: миграция схемы и публичный контракт ступень **не**
поднимают, их проверяют проходы, которые в `standard` и так есть;
- **Недоступно проверке** — два подраздела: «не проверит ни один проход» - **Недоступно проверке** — два подраздела: «не проверит ни один проход»
(принципиальная граница, по факту промаха не пересматривается) и «перестали (принципиальная граница, по факту промаха не пересматривается) и «перестали
проверять сознательно» (пересматривается первым). проверять сознательно» (пересматривается первым).
@@ -195,6 +203,33 @@ kebab-case.
выборка по пометке. Пойманные с оракулом — лучшая опора для прохода: проектные, выборка по пометке. Пойманные с оракулом — лучшая опора для прохода: проектные,
воспроизводимые, однажды оказавшиеся правдой. воспроизводимые, однажды оказавшиеся правдой.
### `tasks/`
Раскладку, форму записи и команды держит скилл `tasks` — канон фиксирует имена
файлов (`items/`, `ROADMAP.md`, `BACKLOG.md`, `SPRINT.md`, `REJECTED.md`) и то,
от чего зависит, читается ли проект как продукт.
**`ROADMAP.md` отвечает на «что приложение уже умеет и чего ещё не умеет».** Это
не очередь работ: цель — **возможность приложения**, задача — шаг к ней.
Достигнутая цель из роадмапа **не исчезает** — строка с датой переезжает в
секцию достигнутого, потому что «что умеет» и есть половина вопроса, ради
которого документ открывают. Вторым домом поведения роадмап при этом не
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
**когда и в каком порядке** оно появилось.
Плюс два требования к записи задачи, потому что от них зависит, можно ли её
оценить:
- **род работы** тегом `kind:<род>` из закрытого словаря `feature` | `fix` |
`chore` | `research` — у задачи обязателен, у цели запрещён. Он же решает,
нужна ли цель: у `feature` обязательна, у остальных нет;
- **раздел «Затрагивает»** в теле задачи — границы, которых изменение касается
(эндпоинт, таблица и миграция, формат на диске, публичный тип пакета).
Оба требуются **к взятию в спринт**, а не к заведению: беклог пополняется чаще,
чем разбирается, и требование на входе выгоняло бы в заметки то, что должно
лежать задачей.
### `CLAUDE.md` ### `CLAUDE.md`
Что это и стек; **инварианты с severity рядом с формулировкой** — по ним проходы Что это и стек; **инварианты с severity рядом с формулировкой** — по ним проходы
@@ -233,7 +268,7 @@ kebab-case.
| почему решено так | `adr/`, источник — архивный `design.md` | | почему решено так | `adr/`, источник — архивный `design.md` |
| граница домена, «чем не является» | `passport.md` | | граница домена, «чем не является» | `passport.md` |
| инвариант и его severity | `CLAUDE.md` | | инвариант и его severity | `CLAUDE.md` |
| порядок работ и его обоснование | `docs/tasks/PLAN.md` | | что приложение умеет и чего не умеет; порядок работ | `docs/tasks/ROADMAP.md` |
| измеренное число | `research/` | | измеренное число | `research/` |
| настройка с числовым значением | `database.md` | | настройка с числовым значением | `database.md` |
| периметр и модель угроз | `security.md` | | периметр и модель угроз | `security.md` |
@@ -266,8 +301,8 @@ kebab-case.
| --- | --- | | --- | --- |
| `docs/review-brief.md` | документы канона и есть бриф; остаток — в `review.md` | | `docs/review-brief.md` | документы канона и есть бриф; остаток — в `review.md` |
| `docs/specs/` | `openspec/specs/` (поведение) и `architecture.md` (обзор) | | `docs/specs/` | `openspec/specs/` (поведение) и `architecture.md` (обзор) |
| `docs/drafts/` | идея → задача `[idea]`; отказ → ADR; порядок → `PLAN.md`; размышление → `opsx:explore` | | `docs/drafts/` | идея → задача `[idea]`; отказ → ADR; порядок → `ROADMAP.md`; размышление → `opsx:explore` |
| `docs/plan.md` | `docs/tasks/PLAN.md` | | `docs/plan.md` | `docs/tasks/ROADMAP.md` |
| `BRIEF.md` | `passport.md` | | `BRIEF.md` | `passport.md` |
| `docs/backlog/` | `docs/tasks/` | | `docs/backlog/` | `docs/tasks/` |
| `docs/review-journal.md`, `docs/review/journal.md` | `docs/review.md` | | `docs/review-journal.md`, `docs/review/journal.md` | `docs/review.md` |
@@ -13,6 +13,108 @@ upgrade` идёт по записям снизу вверх от версии п
--- ---
## Версия 3 — 2026-08-04
Роадмап стал **состоянием проекта**, а не очередью работ: цель — возможность
приложения, задача — шаг к ней, достигнутое из роадмапа не исчезает. Плюс род
работы, раздел «Затрагивает» и новое умолчание профиля ревью. Раскладка меняется
в одном файле, но переименование и смена секций тянут за собой ссылки, поэтому
шаги делаются одним заходом.
**Что добавилось:**
1. **Род работы** — тег `kind:<род>` в мете задачи, словарь закрыт:
`feature` | `fix` | `chore` | `research`. Обязателен у задачи, у цели
запрещён. `sprint take` без него отказывает, `check` о пропаже напоминает
замечанием. Определение — [canon.md](canon.md), раздел `tasks/`; смысл и
причина, почему тегом, — в SKILL.md скилла `tasks`, раздел «Род работы».
2. **Раздел «Затрагивает»** в теле задачи — перечень границ, которых изменение
касается (эндпоинт, таблица и миграция, формат на диске, публичный тип). Как
и критерии приёмки, требуется к взятию в спринт, а не к заведению.
3. **Секции роадмапа** — четыре вместо двух и **канонические**, в отличие от
секций беклога: `Готово` (достигнутые цели строкой с датой, без ссылки на
файл), `Запланировано` (очередь значима), `Направления` (очереди нет),
`Разработка` (инструмент и процесс, не возможности приложения). Английский
вариант — `Done` | `Planned` | `Directions` | `Tooling`, один язык на весь
индекс. Переименованию проектом не подлежат: у каждой свой смысл, и в первую
пишет сам `close`; `tasks.py check` проверяет состав.
4. **Форма заголовка записи** — по типу: задача отвечает на «что нужно сделать»
и пишется глаголом в неопределённой форме («Не отбрасывать молча лишние
символы»), цель — на «что приложение будет уметь», идея просто называет, о
чём она. `check` считает заголовки не в форме действия и печатает число в
блоке здоровья. Годность формулировки — не машине: её смотрит новый агент
`task-form` (форма записи, только чтение), а язык текста — `doc-wording`.
5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
индексах. Написание канонических секций и отбивку правит `check --fix`; он
же сводит написание секции в мете файла с заголовком индекса.
6. **Язык проектных текстов** — [language.md](language.md), общий дом для
документов канона, задач, решений ADR и записок разведки: информационный
стиль (глагол вместо отглагольного существительного, активный залог, факт
вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и
то, что из стиля отброшено намеренно. Проектных файлов не добавляет и
раскладку не меняет — это правила письма, а не новый слот.
7. **Умолчание профиля ревью сменилось** — это не раскладка, но проектный текст
под него уже написан. `standard` стал рабочим умолчанием: миграция схемы,
публичный контракт и инвариант ступень больше **не** поднимают, `wide`
означает новое понятие или структурную единицу. Подраздел «Триггеры профиля»
в `docs/review.md` остаётся на месте, но его содержимое надо перечитать.
**Что переехало:** `docs/tasks/PLAN.md``docs/tasks/ROADMAP.md`; достигнутая
цель — из небытия в секцию `Готово`: `close <цель> --implemented` удаляет файл, но
**оставляет строку с датой**. Прежде роадмап отвечал только «что осталось», и
половину его вопроса вели прозой руками. Вместе с
файлом переименован ключ конфига `tasks.plan``tasks.roadmap` и токены
команд: `--index plan``--index roadmap`, `init --plan-sections`
`--roadmap-sections`, `init --plan``--roadmap`. Старый ключ в
`docs/.pm.json` не игнорируется молча — `tasks.py` останавливается и называет
переименование.
**Что удалено:** тип `[epic]`. Он был зонтиком между целью и задачами; зонтиком
стала цель, а слишком крупный шаг дробится на шаги помельче под ней. Ноль
употреблений на 97 записей двух живых проектов.
**Что сделать проекту:**
1. `git mv docs/tasks/PLAN.md docs/tasks/ROADMAP.md`.
2. Починить ссылки на прежнее имя: `grep -rn 'PLAN\.md' docs/ CLAUDE.md`
заголовок самого файла («# План» → «# Роадмап»), строка в `docs/tasks/BACKLOG.md`,
упоминания в `docs/passport.md` и в телах задач.
3. `docs/.pm.json`: ключ `tasks.plan`, если он там был, — в `tasks.roadmap`.
4. Проставить род работы живым задачам: `python3 tasks.py check --dir docs/tasks`
перечислит те, у кого его нет. Задним числом весь беклог не переоформляется —
род нужен к взятию, так что порядок такой: сперва то, что берётся в ближайший
спринт, остальное по ходу переоценки.
5. Дописать раздел «Затрагивает» — тем же порядком и по той же причине: сперва
набор спринта, остальное по мере того, как задача попадает в работу.
6. Перечитать «Триггеры профиля» в `docs/review.md`: строки вида «миграция →
`deep`» теперь дублируют умолчание с обратным знаком. Оставить там только то,
что для этого проекта считается **новым понятием** и **правилом
идентичности**, — и убрать остальное, иначе проект возвращает себе прежнюю
частоту полного набора уточнением.
7. Переименовать секции роадмапа: `порядок``Запланировано`, `темы`
`Направления`; завести `Готово` **первой** и `Разработка` последней.
Прозаические разделы вроде «Что уже пройдено», которые велись руками,
разложить: звенья — строками в `Готово` (дата, слаг, что стало возможно),
обоснование очереди оставить прозой в `Запланировано`. Любой `##` в индексе
проверка считает секцией, и теперь `check` называет чужую секцию ошибкой.
8. Переформулировать цели ответом на **«что приложение будет уметь»**: не
«Работа со слиянием», а «Исход слияния не зависит от порядка доставки».
Свойство поведения — законная цель. Цель, которая не про приложение
(процесс, инструмент), переезжает в `Разработка`.
9. `[epic]`, если он в проекте заводился: это либо цель, либо набор задач под
общей целью. `check` назовёт его неизвестным типом.
10. Прогнать `python3 tasks.py check --dir docs/tasks --fix`: он поднимет
написание канонических секций, поставит отбивку после заголовков и сведёт
секцию в мете файлов с заголовками индексов. Секции беклога проект
переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе.
11. Переписать заголовки задач в форму действия — по мере того, как задача
попадает в работу, а не «заодно»: `check` печатает их число, а `task-form`
предложит формулировки на замену пачкой.
12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
числом**. Правила языка применяются к тому, что пишется и правится сейчас;
сплошная вычитка старых документов стоит дороже, чем даёт.
13. `docs/.pm.json`: `"canon": 3`.
## Версия 2 — 2026-08-03 ## Версия 2 — 2026-08-03
Шапка записи ADR — мета-блоком общей формы, и у статуса появился объявленный Шапка записи ADR — мета-блоком общей формы, и у статуса появился объявленный
@@ -0,0 +1,176 @@
# Язык проектных текстов
Правила для всего, что пишется словами: задачи и цели, документы канона,
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
сообщений программы пользователю — там свои конвенции проекта.
Основа — **информационный стиль** Максима Ильяхова ([учебник
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что
взято и что отброшено намеренно.
## Зачем он здесь
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
а это и есть цена, которой мы избегаем.
## Что взято
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
собственный вопрос («что это за система», «как сложено», «почему так решили»).
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
исход правки.
**Глагол вместо отглагольного существительного, действие вместо состояния.**
«Обработчик не проверяет владельца», а не «проверка владельца не
осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по
имени». Отглагольное существительное прячет того, кто действует, — а в
техническом тексте именно он и важен.
**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается
скриптом». Страдательный залог остаётся там, где деятель неизвестен или
неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх
команд.
**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до
800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а
не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит
факт. Без факта оценка — не сведение, а настроение.
**Стоп-слова.** Убирается то, что можно убрать без потери смысла:
| Что | Примеры |
| --- | --- |
| канцелярит | является, осуществляется, в целях, в рамках, данный, вышеуказанный, необходимо отметить |
| вводные-паразиты | в общем, как известно, стоит отметить, не секрет, что |
| усилители | очень, крайне, достаточно, абсолютно, максимально, полностью |
| синонимы одного качества | «понятный и простой», «быстрый и производительный» |
| неопределённое | какой-то, некоторый, соответствующий, определённый |
Проверка одна: **вычеркни слово. Смысл изменился — оставляй.**
**Одна мысль — одно предложение.** Предложение, в котором два независимых
утверждения, делится. Придаточное, которое можно вынести в отдельную фразу,
выносится.
Исключение — **поля, которым формат отвёл одно предложение**. «Зачем» в мете
задачи именно такое: оно повторяется строкой индекса, и второе предложение там
просто не поместится. Такое поле либо укладывается в одну фразу, либо
сокращается, но не делится.
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
грамматической формой, разделы одного вида — одним порядком, заголовки одного
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
ищет её.
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
столько, чтобы длинный текст можно было просматривать, а не только читать
подряд.
## Что отброшено намеренно
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
ломает причинную связь, а в решении и в задаче ценность именно в ней:
«поэтому», «иначе», «раз так» несут смысл и остаются.
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
вводные, которые не меняют смысл предложения.
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
«дописать позже», и такой текст лучше не публиковать.
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
значит называть состояние и остаток, а не пересказывать, как было интересно
разбираться.
## Англицизмы
Англицизм-калька заменяется, когда у него есть естественный русский аналог.
<!-- дом: язык-англицизмы -->
| Калька | Русский аналог |
| --- | --- |
| флоу | поток, процесс, сценарий |
| фикс, зафиксить | исправление, исправить, починить |
| чекать | проверять |
| апрув, заапрувить | согласование, согласовать |
| best-effort | по возможности |
| кейс | случай, сценарий |
| перформанс | производительность |
| матчинг, смэтчить | сопоставление, сопоставить |
| зарелизить | выпустить, выложить |
| отрефакторить | переписать, разделить, убрать второй путь |
Насильно не переводится то, что является **именем вещи**: термины технологий и
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
таблиц и команд, слаг, а также термин, у которого нет точного русского
эквивалента и который в команде уже прижился.
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
искажает смысл — остаётся термин.
<!-- /дом: язык-англицизмы -->
## Жаргон и метафоры
Система не описывается внутренними метафорами и образными ярлыками: автору они
понятны, читателю — нет. Вещь называется прямо.
<!-- дом: язык-жаргон -->
| Метафора-жаргон | Прямо |
| --- | --- |
| рычаг (кэша, отбора) | условие отбора, параметр |
| навешен не на тот счётчик | завязан не на тот счётчик |
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
| костыль | временное решение, обходной путь — и в чём именно |
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
описанием того, что происходит.**
<!-- /дом: язык-жаргон -->
## Термин, которого нет в проекте
Термин, не встречающийся ни в паспорте, ни в архитектуре, ни в конвенциях,
**вводится одной строкой или не употребляется**. Свой словарь у отдельной записи
— самый дешёвый способ сделать беклог нечитаемым для того, кто вернётся к нему
через квартал.
Заменять незнакомый термин догадкой нельзя: догадка о предметной области дороже
непонятного слова, потому что выглядит понятной.
## Порог правки
<!-- дом: порог-правки -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
перестают читать весь список, и вместе с ним пропадают настоящие находки.
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /дом: порог-правки -->
И обратное: язык правится **по ходу той операции, которая записи касается**.
Беклог не переписывают ради языка.
+14 -4
View File
@@ -29,7 +29,7 @@
# Паспорт проекта # Паспорт проекта
Зачем это и для кого. [architecture.md](architecture.md) отвечает «как Зачем это и для кого. [architecture.md](architecture.md) отвечает «как
устроено», [tasks/PLAN.md](tasks/PLAN.md) — «в каком порядке», паспорт — устроено», [tasks/ROADMAP.md](tasks/ROADMAP.md) — «в каком порядке», паспорт —
«зачем и для кого». «зачем и для кого».
## Цель ## Цель
@@ -282,9 +282,19 @@
### Триггеры профиля ### Триггеры профиля
Проектная конкретизация правила выбора профиля: какие пути и контракты означают Проектная конкретизация правила выбора профиля: что здесь считается **новым
`deep`, что здесь считается «поведением, видимым снаружи», при каком изменении понятием или структурной единицей** (поднимает прогон до `wide` и запускает
запускается независимая реализация. Уточняет умолчания конвейера, не отменяет их. архитектурный проход) и **где живут правила идентичности, слияния и разбора**
(до `deep`, запускает независимую реализацию) — перечнем узлов или capability,
поимённо. Уточняет умолчания конвейера, не отменяет их; рабочее умолчание —
`standard`.
Перечень для `deep` **производен от теста конвейера**, а не заменяет его:
правило попадает в класс, когда вариантов несколько, спека между ними не
выбирает, а неверный выбор не падает, а молча меняет смысл данных. Перечисляй
места, где этот класс здесь живёт, а не переписывай определение. Таких мест нет
вовсе — так и напиши: `deep` тогда не запускается никогда, и это законное
состояние.
### Недоступно проверке ### Недоступно проверке
+3 -3
View File
@@ -25,7 +25,7 @@ from dataclasses import dataclass, field
from pathlib import Path from pathlib import Path
from typing import NoReturn from typing import NoReturn
CANON_VERSION = 2 CANON_VERSION = 3
OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4 OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4
@@ -65,12 +65,12 @@ ALLOWED_DIRS = {"conventions", "research", "adr", "tasks"}
RETIRED = { RETIRED = {
"review-brief.md": "документы канона и есть бриф; остаток — в review.md", "review-brief.md": "документы канона и есть бриф; остаток — в review.md",
"review-journal.md": "→ docs/review.md", "review-journal.md": "→ docs/review.md",
"plan.md": "→ docs/tasks/PLAN.md", "plan.md": "→ docs/tasks/ROADMAP.md",
"conventions.md": "→ docs/conventions/", "conventions.md": "→ docs/conventions/",
"local-research.md": "→ docs/research/", "local-research.md": "→ docs/research/",
"research.md": "→ docs/research/", "research.md": "→ docs/research/",
"specs": "поведение → openspec/specs/, обзор → docs/architecture.md", "specs": "поведение → openspec/specs/, обзор → docs/architecture.md",
"drafts": "идея → задача [idea], отказ → ADR, порядок → PLAN.md", "drafts": "идея → задача [idea], отказ → ADR, порядок → ROADMAP.md",
"backlog": "→ docs/tasks/", "backlog": "→ docs/tasks/",
"review": "→ docs/review.md", "review": "→ docs/review.md",
} }
+4 -3
View File
@@ -1,6 +1,6 @@
--- ---
name: init name: init
description: Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в плане и скелет остальных документов. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon. description: "Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в роадмапе и скелет остальных документов. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon."
--- ---
# Заведение нового проекта # Заведение нового проекта
@@ -26,7 +26,7 @@ description: Завести новый проект — сессия вопро
| `passport.md` | `architecture.md` | | `passport.md` | `architecture.md` |
| `CLAUDE.md` | `database.md` | | `CLAUDE.md` | `database.md` |
| `security.md` | `conventions/` | | `security.md` | `conventions/` |
| `docs/tasks/PLAN.md` — первые цели | `research/`, `adr/` | | `docs/tasks/ROADMAP.md` — первые цели | `research/`, `adr/` |
| `docs/.pm.json` | `review.md` — журнал пуст, настройка появится с первым ревью | | `docs/.pm.json` | `review.md` — журнал пуст, настройка появится с первым ревью |
Честная строка информативна, а не «TBD»: «архитектуры пока нет: кода нет, Честная строка информативна, а не «TBD»: «архитектуры пока нет: кода нет,
@@ -48,7 +48,8 @@ description: Завести новый проект — сессия вопро
проекте нельзя откатить — деплой, выкладка наружу, перезапись данных. проекте нельзя откатить — деплой, выкладка наружу, перезапись данных.
5. **Чем краснеет гейт.** Какие проверки обязательны; что красит безусловно; 5. **Чем краснеет гейт.** Какие проверки обязательны; что красит безусловно;
чего в гейте намеренно не будет и кто тогда это гоняет. чего в гейте намеренно не будет и кто тогда это гоняет.
6. **Первые цели.** Направления, а не задачи: три-пять целей в «порядок», с 6. **Первые цели.** Возможности приложения, а не задачи: три-пять целей в
`Запланировано`, каждая — ответ на «что приложение будет уметь», с
обоснованием очереди прозой. обоснованием очереди прозой.
### Как вести ### Как вести
+2 -2
View File
@@ -1,6 +1,6 @@
--- ---
name: session name: session
description: Ритуал между спринтами и ведение самого спринта: разбор накопившихся вопросов, разбор прошедшего спринта про процесс, переоценка задач порциями, выбор цели и набор нового спринта с заморозкой. Плюс правила по ходу спринта — что врывается в замороженный набор, чем вопрос отличается от блокера, когда задача выходит из спринта, что считается сделанным и что идёт в доклад. Использовать, когда просят закрыть или начать спринт, собрать набор, разобрать вопросы, провести груминг/переоценку/ретроспективу, решить «что делать дальше» или доложить итоги. Формат и содержимое задач — скилл tasks. description: "Ритуал между спринтами и ведение самого спринта: разбор накопившихся вопросов, разбор прошедшего спринта про процесс, переоценка задач порциями, выбор цели и набор нового спринта с заморозкой. Плюс правила по ходу спринта — что врывается в замороженный набор, чем вопрос отличается от блокера, когда задача выходит из спринта, что считается сделанным и что идёт в доклад. Использовать, когда просят закрыть или начать спринт, собрать набор, разобрать вопросы, провести груминг/переоценку/ретроспективу, решить «что делать дальше» или доложить итоги. Формат и содержимое задач — скилл tasks."
--- ---
# Сессия между спринтами # Сессия между спринтами
@@ -38,7 +38,7 @@ description: Ритуал между спринтами и ведение сам
## Единицы ## Единицы
- **Цель** — то, ради чего набирается спринт. Файл `[goal]`, перечисленный в - **Цель** — то, ради чего набирается спринт. Файл `[goal]`, перечисленный в
`PLAN.md`. Цель постоянна: живёт, пока живёт направление. `ROADMAP.md`. Цель постоянна: живёт, пока живёт направление.
- **Задача** — то, что мерджится целиком и даёт видимую пользу. - **Задача** — то, что мерджится целиком и даёт видимую пользу.
- **Вопрос** — решение человека. Не останавливает начатую работу, но **блокирует - **Вопрос** — решение человека. Не останавливает начатую работу, но **блокирует
взятие** задачи в спринт. Живёт внутри файла задачи разделом «Вопросы» и тегом взятие** задачи в спринт. Живёт внутри файла задачи разделом «Вопросы» и тегом
+36 -17
View File
@@ -105,20 +105,25 @@
4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами 4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами
одного дефекта, сливаются в одну — это находка, которую интейк дать не мог. одного дефекта, сливаются в одну — это находка, которую интейк дать не мог.
5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство 5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство
репозитория в рамках, предписание процесса в теле. Список и правила — в репозитория в рамках, предписание процесса в теле, род работы, разошедшийся с
скилле `tasks`. задачей, границы вместо реализации в разделе «Затрагивает». Список и правила —
в скилле `tasks`. **Переоценка — то самое место, где беклог добирает род
работы и границы:** требовать их на входе значило бы выгонять в заметки то,
что должно лежать задачей, а к взятию в спринт они уже обязательны.
Затем — то, что решает пользователь: Затем — то, что решает пользователь:
6. **Жива ли она вообще.** Контекст мог измениться: ушла зависимость, отпал 6. **Жива ли она вообще.** Контекст мог измениться: ушла зависимость, отпал
сценарий, обошли иначе. Здесь и звучит вопрос о выкидывании. сценарий, обошли иначе. Здесь и звучит вопрос о выкидывании.
7. **Та ли цель.** Приоритетов нет, и «повысить» нечего — вместо повышения 7. **Та ли цель — и нужна ли она вообще.** Приоритетов нет, и «повысить» нечего
**смена цели** (`edit <slug> --goal <другой>`) или включение в ближайший — вместо повышения **смена цели** (`edit <slug> --goal <другой>`) или
набор. Задача, которой не находится цель, — кандидат на выход: она не попадёт включение в ближайший набор. `feature`, которой не находится цель, — кандидат
ни в один спринт. на выход: новая возможность вне цели это возможность, которой никто не
заказывал. Операционной задаче (`fix`, `chore`, `research`) цель не нужна, и
выдумывать её здесь не надо.
8. **Задача ли это по-прежнему.** Не проходит тест «готова к взятию» → `edit 8. **Задача ли это по-прежнему.** Не проходит тест «готова к взятию» → `edit
<slug> --type idea`, дальше штурм. Разрослась → `edit <slug> --type epic`, <slug> --type idea`, дальше штурм. Разрослась → это несколько задач под той
дальше декомпозиция. же целью, дальше декомпозиция.
9. **Переоценка по измеренному.** Спринт производит числа — сколько на самом 9. **Переоценка по измеренному.** Спринт производит числа — сколько на самом
деле стоит такая работа, что оказалось дороже ожидания. Эти числа меняют цену деле стоит такая работа, что оказалось дороже ожидания. Эти числа меняют цену
**других** задач, и именно здесь это применяется: задача, чья цена выросла **других** задач, и именно здесь это применяется: задача, чья цена выросла
@@ -170,21 +175,35 @@
## Шаг 4. Выбор цели и набор спринта ## Шаг 4. Выбор цели и набор спринта
1. **Покажи состояние целей**: «порядок» `PLAN.md` с обоснованием очереди, темы, и 1. **Покажи состояние проекта**: секцию `Готово` (что приложение уже умеет —
это половина ответа на «где мы»), затем `Запланировано` с обоснованием
очереди, `Направления`, и
по каждой цели-кандидату — сколько под ней задач без открытых вопросов по каждой цели-кандидату — сколько под ней задач без открытых вопросов
(`list --goal <слаг>`). Цель без готовых задач набором не станет: её сперва (`list --goal <слаг>`). Цель без готовых задач набором не станет: её сперва
надо декомпозировать. надо декомпозировать.
2. **Цель называет человек.** Это продуктовое решение, а не механика: агент 2. **Цель называет человек.** Это продуктовое решение, а не механика: агент
предлагает и объясняет, но не выбирает. предлагает и объясняет, но не выбирает.
3. **Набор собирает агент**`sprint start --goal <слаг>`, затем `sprint take 3. **Набор собирает агент**`sprint start --goal <слаг>`, затем `sprint take
…`. Скрипт не даст взять чужую цель, идею, эпик, задачу с открытым вопросом …`. Скрипт не даст взять цель, идею, задачу с чужой целью, с открытым
или без критериев приёмки. вопросом, без критериев приёмки, без рода работы или без раздела
«Затрагивает». Задача без цели вовсе (`fix`, `chore`, `research`) берётся
свободно — операционная работа входит в набор помимо его цели.
4. **Набор показывается человеку до старта работ.** Показ — это и есть момент 4. **Набор показывается человеку до старта работ.** Показ — это и есть момент
заморозки: после него набор не двигается. заморозки: после него набор не двигается. **В показе называется состав по
5. Задача, которой для взятия не хватает только критериев приёмки, дописывается роду работы** — три `fix` и ни одной `feature` под целью развития это
здесь же — 2–5 утверждений, у каждого назван оракул (меньше двух `sprint разговор про цель, а не про набор, и увидеть его надо до заморозки, а не в
take` не примет). Но если для критериев нужен ответ человека, это вопрос, и докладе по итогам.
задача в набор не идёт.
Здесь же последний дешёвый момент заметить **разнородную задачу**: раздел
«Затрагивает» показывает границы до того, как заведено предложение об
изменении. Строка, которая одна тянет задачу на ступень выше остального
перечня, — кандидат на разрез (шов — в `tasks`, `references/split.md`).
Замеченная здесь, она стоит одного `edit`; замеченная на ревью — выброшенного
предложения.
5. Задача, которой для взятия не хватает только критериев приёмки, границ или
рода, дописывается здесь же — 2–5 утверждений с оракулами, перечень
затрагиваемых границ, `--kind`. Но если для этого нужен ответ человека, это
вопрос, и задача в набор не идёт.
**Размер — ориентир, а не закон:** 5–8 задач. Можно взять больше, можно меньше — **Размер — ориентир, а не закон:** 5–8 задач. Можно взять больше, можно меньше —
набор под цель важнее круглого числа; одна крупная задача спринтом тоже бывает. набор под цель важнее круглого числа; одна крупная задача спринтом тоже бывает.
@@ -196,7 +215,7 @@
- Разбор процесса: что записано и куда. - Разбор процесса: что записано и куда.
- Изменения списком: удалено как реализованное (со ссылками), ушло без - Изменения списком: удалено как реализованное (со ссылками), ушло без
реализации (с причинами), понижено до идей, слито, сменило цель. реализации (с причинами), понижено до идей, слито, сменило цель.
- Новый спринт: цель, набор со слагами, дата. - Новый спринт: цель, набор со слагами, дата, состав по роду работы.
- **Границы покрытия**: сколько задач не трогали и какие именно секции, теги или - **Границы покрытия**: сколько задач не трогали и какие именно секции, теги или
цели остались — иначе доклад читается как «беклог разобран». цели остались — иначе доклад читается как «беклог разобран».
- `tasks.py check` после правок — результат строкой. - `tasks.py check` после правок — результат строкой.
@@ -18,10 +18,10 @@
с вопросом в файле и **без живого незакоммиченного предложения** — иначе при с вопросом в файле и **без живого незакоммиченного предложения** — иначе при
следующем взятии оно столкнётся с новым. Наработки, которые жалко терять, следующем взятии оно столкнётся с новым. Наработки, которые жалко терять,
переезжают в тело задачи текстом. переезжают в тело задачи текстом.
- **Переросла в эпик** — распознаётся **до того, как под неё заведено - **Оказалась крупнее задачи** — распознаётся **до того, как под неё заведено
предложение об изменении**, иначе его придётся выбрасывать. Помечается предложение об изменении**, иначе его придётся выбрасывать. Выходит из набора,
`[epic]`, выходит из набора, уходит на декомпозицию; спринт продолжается уходит на декомпозицию; спринт продолжается остальными, части заводятся под той
остальными, части в замороженный набор не добавляются. же целью и в замороженный набор не добавляются.
- **Отменена решением по ходу**`close <slug> --reason "<ссылка на решение>"` - **Отменена решением по ходу**`close <slug> --reason "<ссылка на решение>"`
прямо из спринта. Это редкий, но законный исход, и он называется в докладе. прямо из спринта. Это редкий, но законный исход, и он называется в докладе.
@@ -34,7 +34,7 @@ flowchart TD
take["sprint take — задача в наборе"] take["sprint take — задача в наборе"]
done["сделана<br/>close --implemented"] done["сделана<br/>close --implemented"]
out["вышла<br/>sprint drop --reason"] out["вышла<br/>sprint drop --reason"]
epic["переросла в эпик<br/>распознаётся до заведения change"] epic["крупнее задачи<br/>распознаётся до заведения change"]
cancel["отменена решением по ходу<br/>close --reason"] cancel["отменена решением по ходу<br/>close --reason"]
all{"по каждой задаче набора<br/>наступил исход?"} all{"по каждой задаче набора<br/>наступил исход?"}
harvest["урожай заводится интейком tasks"] harvest["урожай заводится интейком tasks"]
+304 -55
View File
@@ -13,10 +13,17 @@ description: Ведение задач и целей как каталога mar
прошедшего спринта → переоценка → выбор цели и набор) — это скилл `session`; и прошедшего спринта → переоценка → выбор цели и набор) — это скилл `session`; и
выполнением задачи — это пайплайн проекта. выполнением задачи — это пайплайн проекта.
## Четыре правила, из которых всё следует ## Пять правил, из которых всё следует
Ситуация не покрыта инструкцией — решай по ним. Ситуация не покрыта инструкцией — решай по ним.
0. **Цель — возможность приложения, задача — шаг к ней.** Цель отвечает на «что
приложение будет уметь», её «Завершение» — наблюдаемый признак того, что уже
умеет; задача отвечает на «что для этого нужно сделать». Оценивается проект
по **поведению**, а не по внутреннему устройству, поэтому и роадмап отвечает
не «сколько работ осталось», а «что уже умеет и чего ещё не умеет».
Свойство поведения — тоже возможность: «сообщает о своём состоянии»,
«исход слияния не зависит от порядка доставки» — законные цели.
1. **Беклог гниёт с той стороны, где его пополняют.** Заведение — самая частая 1. **Беклог гниёт с той стороны, где его пополняют.** Заведение — самая частая
операция и с худшим отказом: из одного разговора рождается пять файлов, а операция и с худшим отказом: из одного разговора рождается пять файлов, а
переоценка потом разгребает то, чего не надо было заводить. Дедупликация и переоценка потом разгребает то, чего не надо было заводить. Дедупликация и
@@ -33,11 +40,13 @@ description: Ведение задач и целей как каталога mar
3. **Причина переживает запись.** Выкинутая без причины задача вернётся через 3. **Причина переживает запись.** Выкинутая без причины задача вернётся через
квартал тем же текстом. Реализованная оставляет след в коммите — выкинутая не квартал тем же текстом. Реализованная оставляет след в коммите — выкинутая не
оставляет ничего, поэтому у неё есть `REJECTED.md`. оставляет ничего, поэтому у неё есть `REJECTED.md`.
4. **Порядка нет, есть цель.** Ни в секциях, ни списком: «что делать дальше» 4. **Порядка нет, есть цель — но цель есть не у всякой задачи.** Приоритетов,
отвечает набор спринта, а между спринтами порядок не нужен никому — брать «повысить» и «встать раньше» нет: «что делать дальше» отвечает набор спринта,
задачи вне спринта запрещает заморозка. Поэтому нет ни приоритетов, ни а между спринтами порядок не нужен никому. Цель обязательна там, где она и
«повысить», ни «встать раньше»: вместо повышения — смена цели или включение есть содержание работы, — у **новой возможности** (`kind:feature`). Починка,
в набор. техдолг и разведка служат работоспособности, а не направлению, и живут без
цели законно; в набор спринта они входят помимо его цели. Придуманная им цель
— то же враньё, от которого спасает род работы.
## Раскладка ## Раскладка
@@ -48,16 +57,45 @@ description: Ведение задач и целей как каталога mar
``` ```
docs/tasks/ docs/tasks/
items/ задачи и цели файлами, <slug>.md, слаги английские items/ задачи и цели файлами, <slug>.md, слаги английские
PLAN.md оглавление целей: порядок (значим) и темы (без порядка) ROADMAP.md состояние проекта: что уже умеет и чего ещё не умеет
BACKLOG.md что можно взять — только задачи, целей здесь нет BACKLOG.md что можно взять — только задачи, целей здесь нет
SPRINT.md текущий спринт: цель, набор, дата SPRINT.md текущий спринт: цель, набор, дата
REJECTED.md ушедшее БЕЗ реализации, с причиной и датой REJECTED.md ушедшее БЕЗ реализации, с причиной и датой
``` ```
Правило, снимающее путаницу: **`BACKLOG.md` — то, что берут; `PLAN.md` — то, Правило, снимающее путаницу: **`BACKLOG.md` — то, что берут; `ROADMAP.md` — то,
подо что берут.** Цель в спринт взять нельзя, поэтому в списке берущихся ей не подо что берут.** Цель в спринт взять нельзя, поэтому в списке берущихся ей не
место. место.
**Четыре секции роадмапа, и первая отвечает на половину вопроса:**
| Секция | Англ. | Что в ней |
| --- | --- | --- |
| `Готово` | `Done` | достигнутые цели — строкой с датой, **без ссылки на файл**: файл удалён, поведение живёт в спеках |
| `Запланировано` | `Planned` | очередь значима и обосновывается прозой рядом |
| `Направления` | `Directions` | очереди нет, тянутся долго |
| `Разработка` | `Tooling` | инструмент и процесс — не возможности приложения, и потому отдельно |
**Секции роадмапа канонические, секции беклога — нет**, и разница не в любви к
единообразию. У каждой секции роадмапа свой смысл, в первую пишет сам `close`, и
роадмап, названный по-своему, читался бы только своим автором. Секции беклога
(`Ядро`, `Инфра`) смысла не несут — это полки, и остаются делом проекта.
Отсюда три правила, которые проверяет `tasks.py check`: **состав закреплён**
(чужая секция — ошибка, а не вольность), **все четыре обязаны быть** (нет
секции — нет ответа на её часть вопроса), **язык один на весь индекс**.
`--roadmap-sections` у `init` нет: выбирать нечего.
**Заголовок секции — с прописной, после него пустая строка.** Во всех индексах
одинаково, включая секции беклога, которые проект называет сам. Написание
канонических секций правит `check --fix` (заодно и ссылку на секцию в мете
файлов: имя секции принадлежит заголовку индекса, файл на неё только
ссылается); отбивку он ставит везде.
Оговорка про `Разработка`: слово `окружение` сюда не годится — в
`architecture.md` оно уже значит боевое окружение приложения, и одно слово в двух
смыслах развело бы документы канона.
**Секции «блокеры» в беклоге нет.** Блокер — это *состояние* (спринт не может **Секции «блокеры» в беклоге нет.** Блокер — это *состояние* (спринт не может
продолжаться ни одной задачей), а не полка: он живёт ровно до ответа человека, и продолжаться ни одной задачей), а не полка: он живёт ровно до ответа человека, и
записи в такой секции не успевают жить. Следы блокера остаются вопросами в записи в такой секции не успевают жить. Следы блокера остаются вопросами в
@@ -77,15 +115,25 @@ docs/tasks/
даром: `SPRINT.md` лежит под git, `git log -p docs/tasks/SPRINT.md` отдаёт историю даром: `SPRINT.md` лежит под git, `git log -p docs/tasks/SPRINT.md` отдаёт историю
всех наборов без отдельного журнала. всех наборов без отдельного журнала.
**У достигнутой цели запись остаётся, и это единственное исключение.** Файл
удаляется так же, а строка переезжает в секцию `Готово` с датой. Причина в том,
что цель — не работа, а **возможность**: «что приложение умеет» это половина
вопроса, ради которого роадмап и открывают, и стирать её вместе с файлом значит
оставить инструмент, отвечающий только «что осталось». Вторым домом это не
становится: поведение живёт в `openspec/specs/`, а роадмап отвечает **когда и в
каком порядке оно появилось** — другой вопрос. Ссылки на файл в строке нет
намеренно: файл удалён, а битая ссылка — законная ошибка `check`.
Куда запись может переехать и какой командой — весь набор переходов: Куда запись может переехать и какой командой — весь набор переходов:
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
state "BACKLOG.md — что берут" as B state "BACKLOG.md — что берут" as B
state "PLAN.md — подо что берут" as P state "ROADMAP.md — подо что берут" as P
state "SPRINT.md — набор спринта" as S state "SPRINT.md — набор спринта" as S
state "REJECTED.md — ушла без реализации" as R state "REJECTED.md — ушла без реализации" as R
state "записи нет — реализована" as D state "записи нет — реализована" as D
state "ROADMAP.md, «умеет» — цель достигнута" as A
[*] --> B: add [*] --> B: add
[*] --> P: add --type goal [*] --> P: add --type goal
@@ -94,10 +142,13 @@ stateDiagram-v2
B --> S: sprint take B --> S: sprint take
S --> B: sprint drop --reason S --> B: sprint drop --reason
S --> D: close --implemented S --> D: close --implemented
P --> A: close --implemented
B --> R: close --reason B --> R: close --reason
S --> R: close --reason S --> R: close --reason
P --> R: close --reason
D --> B: reopen --reason D --> B: reopen --reason
R --> B: reopen --reason R --> B: reopen --reason
A --> P: reopen --reason
``` ```
Состояния здесь — **где числится строка**, а не где лежит файл: файл Состояния здесь — **где числится строка**, а не где лежит файл: файл
@@ -110,29 +161,164 @@ stateDiagram-v2
## Цели ## Цели
**Цель — такой же файл в `items/`, тип `[goal]`**, перечисленный в `PLAN.md`: **Цель — возможность приложения.** Такой же файл в `items/`, тип `[goal]`,
либо цель из секции **порядок** — там очередь значима и обоснована прозой, — либо перечисленный в `ROADMAP.md`. Формулируется ответом на вопрос **«что приложение
**тематическая**, в порядок не встающая («прочность слияния», «журнал и будет уметь»**, а не названием области работ: не «Работа с чтением», а «Чтение
пересборка»). Без второй секции половина целей была бы нигде не перечислена: данных клиентами»; не «Рефакторинг слияния», а «Исход слияния не зависит от
находки ревью не служат ничему из порядка. порядка доставки».
**Свойство поведения — тоже возможность.** «Наблюдаемость» это «приложение
сообщает о своём состоянии»; «прочность слияния» это «исход не зависит от
порядка». Такие цели законны и переформулировки в функцию не требуют — требуют
только, чтобы формулировка отвечала на «что приложение делает», а не на «какую
часть кода мы трогаем».
**Что целью не является — работа над инструментом и процессом.** Сборка,
проверки, сам этот скилл: на вопрос «что приложение будет уметь» они не
отвечают. Им
отведена отдельная секция роадмапа, чтобы они были видны в том же экране и при
этом не читались как возможности продукта.
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
тянется долго и очереди не имеет — `Направления`; не про приложение —
`Разработка`; в `Готово` кладёт сам `close`.
- **Список задач цели выводится, а не хранится.** В теле цели — зачем она и что - **Список задач цели выводится, а не хранится.** В теле цели — зачем она и что
считается её завершением; перечня задач там нет. Он был бы третьим индексом и считается её завершением; перечня задач там нет. Он был бы третьим индексом и
поехал бы на первой же закрытой задаче, а `check` про него не знает. Связь поехал бы на первой же закрытой задаче, а `check` про него не знает. Связь
однонаправленна: задача несёт тег `goal:<слаг>`, перечень даёт однонаправленна: задача несёт тег `goal:<слаг>`, перечень даёт
`tasks.py list --goal <слаг>`. `tasks.py list --goal <слаг>`.
- **Статус цели выводится.** Цель закрыта, когда у неё не осталось открытых - **Статус цели выводится.** Цель достигнута, когда у неё не осталось открытых
задач; `[x]`/`[~]` руками не ведутся, а `close` цели с живыми задачами задач; `[x]`/`[~]` руками не ведутся, а `close` цели с живыми задачами
скрипт запретит. Единственная оговорка: цель без задач неотличима — «ещё не скрипт запретит. Достижение — `close <цель> --implemented`: файл удаляется,
строка с датой переезжает в `Готово`. Ошиблись — `reopen` вернёт файл и
**снимет строку достигнутого**, чтобы роадмап не утверждал того, чего нет. Единственная оговорка: цель без задач неотличима — «ещё не
разобрана» или «всё закрыто». Различает **тег `decomposed`** в мете разобрана» или «всё закрыто». Различает **тег `decomposed`** в мете
цели: он ставится, когда цель разложена на задачи. Тег, а не строка в теле — цели: он ставится, когда цель разложена на задачи. Тег, а не строка в теле —
потому что проверяется механически: `check` **напоминает** о нём у пустой цели потому что проверяется механически: `check` **напоминает** о нём у пустой цели
(замечанием, не ошибкой — неразобранная цель это законное состояние), а `check (замечанием, не ошибкой — неразобранная цель это законное состояние), а `check
--fix` сам проставляет его цели, у которой задачи есть. --fix` сам проставляет его цели, у которой задачи есть.
- **`[goal]` и `[epic]` — разные вещи.** Цель **постоянна**: живёт, пока живёт - **Тип `[epic]` упразднён.** Он был зонтиком между целью и задачами — «задача,
направление. Эпик **временен**: это задача, которая не мерджится целиком, её которая не мерджится целиком». Зонтик теперь цель, а слишком крупный шаг просто
разбирают, и он исчезает. Два срока жизни под одним словом разъезжаются, дробится на шаги помельче под той же целью, и промежуточному типу места не
поэтому слова два. осталось. Замер подтвердил: ноль употреблений на 97 записей двух живых
проектов. Встретился в чужом беклоге — это цель либо набор задач, и `check`
назовёт его неизвестным типом.
## Род работы
**Тип записи и род работы — две оси, и путать их нельзя.** Тип отвечает «что это
за запись» (цель, идея, задача), род — «какого рода работа»: `feature`, `fix`,
`chore`, `research`. Одним значением на оба вопроса не ответить: идея бывает
*про* функцию, а цель функцией *и является*.
- **`feature`** — снаружи появляется или меняется то, чего раньше не было.
- **`fix`** — поведение расходится с заявленным, и расхождение воспроизводится.
Не воспроизводится — это `research`, а не `fix`.
- **`chore`** — обслуживание: зависимости, сборка, перенос, чистка. Наблюдаемое
поведение не меняется, и в этом всё дело: **у `chore` тест готовности слабее
честно**, а не молча. «Что станет наблюдаемо иначе» здесь отвечается
разработчику («перестанет собираться два раза», «уедет последний вызов
устаревшего API»), а не пользователю. Пока рода не было, такие задачи либо не
заводились, либо формулировались как выдуманная польза.
- **`research`** — исход работы знание, а не изменение системы: ответ на вопрос,
замер, разведка. Приёмка — записанный ответ (`docs/research/`, ADR, тело
задачи), а не изменённый код.
Дом рода — **тег `kind:<род>`**, а не префикс заголовка и не поле меты: теги
здесь единственный механизм разметки, и `list --kind fix` работает даром. Цена
известна: в строку индекса род не попадает (индексы производны), и «в наборе одни
починки» видно командой, а не глазами по `SPRINT.md`.
Словарь **закрыт**. Открытый разъедется на синонимах — `bug`, `bugfix`, `fix`,
`defect`, — и отбор по роду перестанет отвечать на свой единственный вопрос. Ни
один род не подходит — это сигнал, что в задаче их два и её надо разделить.
**Род обязателен у задачи, у цели запрещён, у идеи необязателен** — идея получает
его, когда становится задачей. Требуется он там, где по нему принимают решение:
`sprint take` без рода откажет. `check` о пропаже только **напоминает** — беклог,
заведённый до появления рода, законен, и переоформлять его «заодно» здесь не
просят.
**Род решает и то, обязательна ли цель.** `feature` без цели не бывает: новая
возможность и есть содержание цели, и если подходящей нет — либо она заводится,
либо это не `feature`. `fix`, `chore` и `research` живут без цели законно, и
`check` о них молчит: они служат работоспособности, а не направлению. Это
единственный случай, когда род что-то определяет за пределами отбора, — и
определяет он учёт, а не процесс проверки.
**Род не выбирает профиль ревью и вообще ничего не предписывает пайплайну.**
Профиль выбирается по факту изменения, а не по роду задачи: `chore` бывает
миграцией схемы, `fix` — правкой публичного контракта. Правило «предписание
процесса в теле задачи снимается» родом не отменяется, а подтверждается: он
описывает работу, а не то, как её проверять.
## Как написана задача
Три требования к тексту. Первое — про заголовок, два остальных про то, чтобы
задачу можно было **оценить, не открывая код**.
**Заголовок отвечает на вопрос своего типа.** Вопросов три, поэтому и форм три:
| Тип | Отвечает на | Пример |
| --- | --- | --- |
| цель | что приложение будет уметь | Соперником может быть компьютер |
| задача | что нужно сделать | Печатать поле одним куском кода |
| идея | о чём она | Подсказка следующего хода |
Задача — **глаголом в неопределённой форме**, перед ним допускается «не»: «Не
отбрасывать молча лишние символы в ходе», а не «Лишние символы молча
отбрасываются». Описательный заголовок называет **состояние**, а из состояния не
видно, чего от работы ждут: «Ничья объявляется, пока клетки есть» одинаково
читается и как жалоба, и как задание, — и в списке, где решают «брать или не
брать», это разные вещи. Идея формы действия не несёт **намеренно**: что делать,
ещё неизвестно, и заголовок-действие обещал бы решённость, которой нет.
Из этого же правила растёт разница индексов: роадмап — список возможностей,
беклог — список работ, и если заголовки перепутать формами, каждый из них
начинает читаться как другой.
`check` считает заголовки не в форме действия и печатает **число** в блоке
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
Годность формулировки — не машине: её смотрит
[агент вычитки](#вычитка-формулировок).
**Функции и границы, а не намерения.** Задача называет, что система начнёт
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
формат на диске, публичный тип пакета, внешний сервис. Перечень живёт разделом
«Затрагивает» (форма — [references/task-format.md](references/task-format.md)) и
требуется к взятию в спринт. Без него задача оценивается по объёму текста, а не
по объёму поверхности, — и оценка систематически занижена ровно там, где текст
короткий, а границ много. Названы **границы**, а не то, как они изменятся: план
реализации живёт в предложении об изменении, а не в задаче.
**Предметно, но без усложнения.** Текст задачи читает человек, который решает,
брать её или нет, и делает это по строке индекса и одному экрану тела.
Язык — общий для всех проектных текстов, и живёт он одним файлом:
[../canon/references/language.md](../canon/references/language.md)
(информационный стиль, применённый к задачам и документам канона; там же таблицы
англицизмов и жаргона и то, что из стиля отброшено намеренно). Задаче он даёт
четыре требования, которые нарушаются чаще прочих:
- **глагол вместо отглагольного существительного**: «обработчик не проверяет
владельца», а не «проверка владельца не осуществляется»;
- **факт вместо оценки**: «время ответа доходит до 800 мс», а не «работает
медленно». Оценка без факта рядом — настроение, а не сведение;
- **англицизм с живым русским аналогом заменяется**: не «зафиксить флоу», а
«починить порядок доставки». Имя вещи не переводится: слаг, команда, тип в
коде, `API`;
- **термин не из документов проекта вводится одной строкой** или не
употребляется. Свой словарь у задачи — самый дешёвый способ сделать беклог
нечитаемым для того, кто вернётся к нему через квартал.
И одно требование, которое есть только у задачи: **сложность формулировки — не
признак сложности работы.** Задачу, которую не удаётся сказать просто, чаще
всего не удаётся и оценить: это либо две задачи, либо идея.
Эти правила — про **язык**, а не про объём: короткая задача без границ хуже
длинной с ними.
## Инструмент (`tasks.py`) ## Инструмент (`tasks.py`)
@@ -143,15 +329,15 @@ stateDiagram-v2
``` ```
python3 $tk check --dir D # согласованность индексов + здоровье python3 $tk check --dir D # согласованность индексов + здоровье
python3 $tk check --dir D --fix # + починить дрейф (секция, заголовок, дубли, «зачем», форма меты) python3 $tk check --dir D --fix # + починить дрейф (секция, заголовок, дубли, «зачем», форма меты)
python3 $tk list --dir D [--stale] [--section S] [--type T] [--tag a,b] [--goal S] [--index …] [--questions] python3 $tk list --dir D [--stale] [--section S] [--type T] [--kind K] [--tag a,b] [--goal S] [--index …] [--questions]
python3 $tk add --dir D --slug S --title T [--type goal|idea|epic] [--section S] [--goal G] [--why «зачем»] [--tag a,b] python3 $tk add --dir D --slug S --title T [--type goal|idea] [--section S] [--goal G] [--kind K] [--why «зачем»] [--tag a,b]
python3 $tk edit S --dir D [--title T] [--why «зачем»] [--type T] [--goal G] [--add-tag a,b] [--rm-tag c] python3 $tk edit S --dir D [--title T] [--why «зачем»] [--type T] [--goal G] [--kind K] [--add-tag a,b] [--rm-tag c]
python3 $tk move S --dir D --section S [--reason R] [--after S | --first] python3 $tk move S --dir D --section S [--reason R] [--after S | --first]
python3 $tk close S --dir D --reason R # в REJECTED.md + удалить (ушла без реализации) python3 $tk close S --dir D --reason R # в REJECTED.md + удалить (ушла без реализации)
python3 $tk close S --dir D --implemented # просто удалить (реализована и закоммичена) python3 $tk close S --dir D --implemented # просто удалить (реализована и закоммичена)
python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась
python3 $tk sprint start --goal S --dir D | take S… | drop S… --reason R | close [--dissolve --reason R] python3 $tk sprint start --goal S --dir D | take S… | drop S… --reason R | close [--dissolve --reason R]
python3 $tk init --dir D [--sections …] [--plan-sections …] [--items …] [--backlog …] … python3 $tk init --dir D [--sections …] [--roadmap-sections …] [--items …] [--backlog …] …
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
``` ```
@@ -168,19 +354,20 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях. нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях.
Тип — английское ключевое слово `goal` / `idea` / `epic` / `task` (как и прочие Тип — английское ключевое слово `goal` / `idea` / `task` (как и прочие токены
токены команд); `task` префикса не несёт, остальные кодируются `[goal]`/ команд); `task` префикса не несёт, остальные кодируются `[goal]`/`[idea]` в
`[idea]`/`[epic]` в заголовке. Текст задачи при этом русский. заголовке. Текст задачи при этом русский.
**Мутации правят файл и индексы заодно** — руками строку индекса или мету **Мутации правят файл и индексы заодно** — руками строку индекса или мету
не пиши, зови `add`/`edit`/`move`/`close`/`sprint`. Смена заголовка, «зачем», типа, не пиши, зови `add`/`edit`/`move`/`close`/`sprint`. Смена заголовка, «зачем», типа,
цели и **тегов** — это `edit`: он держит H1, мету и индекс в синхроне. цели, рода работы и **тегов** — это `edit`: он держит H1, мету и индекс в синхроне.
Снятие тега — `--rm-tag` (после ответа на вопрос снимается `question`), смена Снятие тега — `--rm-tag` (после ответа на вопрос снимается `question`), смена
цели — `--goal`, он заменяет прежний `goal:*`. цели — `--goal`, рода — `--kind`; оба заменяют прежнее значение, а не добавляют
второе.
**Переезд между индексами — следствие смены типа, а не отдельная команда.** **Переезд между индексами — следствие смены типа, а не отдельная команда.**
`edit <slug> --type goal --section <часть плана>` переносит строку из `edit <slug> --type goal --section <часть роадмапа>` переносит строку из
`BACKLOG.md` в `PLAN.md` (и обратно `--type task --section <секция беклога>`); `BACKLOG.md` в `ROADMAP.md` (и обратно `--type task --section <секция беклога>`);
`move` двигает только внутри одного индекса и пишет причину. `--section` у `move` двигает только внутри одного индекса и пишет причину. `--section` у
`edit` работает **только** при таком переезде — иначе он отсылает к `move`, `edit` работает **только** при таком переезде — иначе он отсылает к `move`,
потому что смена секции без причины и есть тот дрейф, который потом никто не потому что смена секции без причины и есть тот дрейф, который потом никто не
@@ -206,16 +393,22 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
и цель, у которой есть задачи, получает тег `decomposed`. Оба случая печатаются и цель, у которой есть задачи, получает тег `decomposed`. Оба случая печатаются
поимённо. поимённо.
**Что механизировано, а что нет.** Критерии приёмки проверяются у задачи, взятой **Что механизировано, а что нет.** У задачи, взятой в набор (`sprint take` и
в набор (`sprint take` и `check` по задачам спринта): число пунктов — жёстко `check` по задачам спринта), проверяются три вещи, и у каждой своя глубина:
(меньше двух — отказ, больше пяти — замечание), наличие оракула — **эвристикой**
по слову «оракул» в пункте. Настоящий оракул от слова «оракул» машина не - **критерии приёмки** — число пунктов жёстко (меньше двух отказ, больше пяти
отличает, поэтому эвристика даёт только замечание, и в докладе это называется замечание), наличие оракула **эвристикой** по слову «оракул» в пункте;
как есть: «проверено число пунктов, годность оракулов — глазами». - **род работы** — жёстко: назван и из закрытого словаря;
- **раздел «Затрагивает»** — только **наличие непустого**. Полнота перечня машине
не видна: границу, которую забыли назвать, она от отсутствующей не отличает.
Настоящий оракул от слова «оракул» машина тоже не отличает, поэтому эвристика
даёт только замечание, и в докладе это называется как есть: «проверено число
пунктов и наличие границ, годность оракулов и полнота границ — глазами».
Формат файла, меты, слага, индексов и `REJECTED.md` Формат файла, меты, слага, индексов и `REJECTED.md`
[references/task-format.md](references/task-format.md). Там же тест «готова к [references/task-format.md](references/task-format.md). Там же тест «готова к
взятию» и требования к критериям приёмки. взятию», требования к критериям приёмки и раздел «Затрагивает».
## Сценарии ## Сценарии
@@ -231,20 +424,22 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
молча заводить нельзя). Две задачи об одном — самая дорогая находка молча заводить нельзя). Две задачи об одном — самая дорогая находка
переоценки. переоценки.
3. **Тип по тесту готовности** (см. task-format): проходит — задача, не 3. **Тип по тесту готовности** (см. task-format): проходит — задача, не
проходит — идея (`--type idea`), проходит по пользе, но не делается одним проходит — идея (`--type idea`). Не делается одним заходом — это не эпик, а
заходом — эпик (`--type epic`, сперва декомпозиция). Направление, а не несколько задач под одной целью: дроби сразу. Возможность приложения, а не
работа — цель (`--type goal`). шаг — цель (`--type goal`).
4. **Цель задачи.** У каждой задачи должен быть `--goal <слаг>`: задача вне цели 4. **Цель задачи — если род её требует.** У `feature` должен быть
не попадёт ни в один спринт. Подходящей цели нет — либо она заводится `--goal <слаг>`: новая возможность и есть содержание цели. Подходящей нет —
(`--type goal` в «темы»), либо это сигнал, что задача никому не служит и либо она заводится (`--type goal`), либо перед тобой не `feature`. У `fix`,
заводить её не надо. У идеи цели может не быть — она проставляется, когда `chore` и `research` цели может не быть вовсе, и придумывать её не надо. У
идея становится задачей. идеи цель проставляется, когда идея становится задачей.
5. `add …`, затем допиши тело редактором: одна фраза, критерии приёмки с 5. **Род работы**`--kind feature|fix|chore|research` (см. «Род работы»). Не
оракулами, рамки. «Зачем» отвечает «зачем нужна эта задача» — состояние, подходит ни один — задача не одна, разбирай.
остаток, боль, — а не пересказывает первый абзац, и пишется **для человека**: 6. `add …`, затем допиши тело редактором: одна фраза, **затрагиваемые границы**,
не «канонизация внутри транзакции», а «тело 40 МиБ держит блокировку 5 секунд, критерии приёмки с оракулами, рамки. «Зачем» отвечает «зачем нужна эта
соседние доставки уходят в отказ». задача» — состояние, остаток, боль, — а не пересказывает первый абзац, и
6. `check`. пишется **для человека**: не «канонизация внутри транзакции», а «тело 40 МиБ
держит блокировку 5 секунд, соседние доставки уходят в отказ».
7. `check`.
### Разобрать находки аудита или ревью ### Разобрать находки аудита или ревью
@@ -258,7 +453,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
### Прийти в репозиторий, где задачи уже как-то ведутся ### Прийти в репозиторий, где задачи уже как-то ведутся
Разовая операция: вывести каталог задач из старой раскладки беклога, `TODO.md`, Разовая операция: вывести каталог задач из старой раскладки беклога, `TODO.md`,
заметок или списка шагов в плане — [references/adopt.md](references/adopt.md). заметок или списка шагов роадмапа — [references/adopt.md](references/adopt.md).
Сюда же относится переименование транслитных слагов в английские: оно делается Сюда же относится переименование транслитных слагов в английские: оно делается
**одним проходом вместе с починкой перекрёстных ссылок**, а не по одному слагу. **одним проходом вместе с починкой перекрёстных ссылок**, а не по одному слагу.
@@ -271,6 +466,49 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
несколько, и у обеих есть проверяемый тест: части должны **мерджиться порознь** и несколько, и у обеих есть проверяемый тест: части должны **мерджиться порознь** и
**каждая давать видимую пользу**, а у штурма исход «выкинуть» — полноправный. **каждая давать видимую пользу**, а у штурма исход «выкинуть» — полноправный.
Там же **шов**: где резать, когда допустимых мест несколько. Коротко — по
границе, которая одна поднимает ступень ревью выше остальных; и не резать, когда
обе половины остаются в одной ступени, потому что несокращаемый костяк проверок
платится за каждую задачу отдельно.
### Вычитка: два прохода, а не один
Записи судит **не тот агент, который их написал**: самопроверка текста слабее
всего ровно там, где формулировка казалась удачной при написании. Проходов два,
и они разные по природе:
| Проход | Что смотрит | Над чем работает |
| --- | --- | --- |
| `task-form` | заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность оракулов, предписание процесса, связь со строкой «Завершения» цели | только `items/`, **открывает файл цели** |
| `doc-wording` | залог и отглагольные, оценка без факта, стоп-слова, англицизмы, жаргон, неизвестный термин | любой проектный текст, включая документы канона |
Разделены они не по охвату, а **по глубине**. Язык проверяется по словам и
фразам, поштучно; форма записи требует понять, что задача делает, и открыть
цель, на которую она ссылается. Слитый проход одну половину делает дорогой, а
вторую — поверхностной. Отсюда и разные модели.
Каждый устав отказывается от чужой половины прямо: увиденное не по своей части
идёт **строкой в границах покрытия**, а не находкой. Две проверки одного места
расходятся и начинают спорить, и разнимать их потом дороже, чем не сводить.
**Порядок — сперва `task-form`.** Его находки меняют решение «брать или не
брать», а язык — только цену чтения; и переписанный заголовок бессмысленно
вычитывать до того, как он переписан.
Зовутся они **пачкой, а не на каждую запись**: после заведения нескольких задач,
после разбора находок ревью и на переоценке. Передаётся список файлов и — если
есть — паспорт, архитектура и конвенции проекта: по ним отличается неизвестный
термин от известного.
Ни один из них ничего не правит. Оба возвращают готовые формулировки, и их
подставляет скилл: заголовок — `edit <слаг> --title …`, «зачем» —
`edit <слаг> --why …`, остальное редактором. **Заголовок и «зачем» — это то, по
чему задачу выбирают, поэтому менять их молча нельзя**: покажи предложенное
пользователю вместе с тем, что было. Правки в теле (границы, критерии, язык)
применяются сразу.
Всё, что ловит `tasks.py check`, оба не трогают намеренно.
### Гигиена полей ### Гигиена полей
Правится по ходу любой операции, которая задачи касается (но не «заодно» по Правится по ходу любой операции, которая задачи касается (но не «заодно» по
@@ -291,7 +529,18 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
снимок берётся при постановке, а не при заведении; снимок берётся при постановке, а не при заведении;
- **предписание процесса в теле** — «делать таким-то профилем ревью», «взять - **предписание процесса в теле** — «делать таким-то профилем ревью», «взять
такой-то агент»: это второй дом для правила выбора и путь понизить требования такой-то агент»: это второй дом для правила выбора и путь понизить требования
решением, принятым до проектирования. Снимается. решением, принятым до проектирования. Снимается;
- **род, разошедшийся с задачей** — задача заводилась починкой, а после разбора
оказалось, что поведение никогда и не было заявлено: это `feature`, а не `fix`.
Правится `edit <slug> --kind …`; род, оставшийся от прошлой формулировки, врёт
ровно там, где по нему отбирают;
- **границы, названные вместо реализации** — «переписать хранилище на новый
драйвер» в разделе «Затрагивает» это не граница, а замысел. Границы —
`таблица points и её миграция`, `эндпоинт POST /ingest`, `формат отпечатка на
диске`. Переписывается перечнем;
- **англицизм и термин из ниоткуда** — правится по ходу той же операции, что
касается задачи (см. «Как написана задача»). Именно по ходу: беклог не
переписывают ради языка.
## Переносимость ## Переносимость
@@ -311,7 +560,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
канон, а не по одному на каталог. Неизвестный ключ — код 3 на любой команде, канон, а не по одному на каталог. Неизвестный ключ — код 3 на любой команде,
так что лишнее слово в этом объекте останавливает работу с задачами целиком. так что лишнее слово в этом объекте останавливает работу с задачами целиком.
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество - **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
и названия — дело проекта (умолчание `ядро` / `инфра`). **В конфиге их нет** и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет**
второй список разошёлся бы с заголовками молча. второй список разошёлся бы с заголовками молча.
### Вызов из другого плагина ### Вызов из другого плагина
+5 -5
View File
@@ -12,7 +12,7 @@
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`, Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
шагов в плане проекта. шагов роадмапа проекта.
## Три правила, из которых всё следует ## Три правила, из которых всё следует
@@ -53,7 +53,7 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в - **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan` `tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика; честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
- **цели.** Шаги плана — готовые цели из **«порядка»** (очередь и обоснование у - **цели.** Шаги роадмапа — готовые цели из **«порядка»** (очередь и обоснование у
них уже есть); тематические скопления задач — **«темы»** («прочность слияния», них уже есть); тематические скопления задач — **«темы»** («прочность слияния»,
«журнал и пересборка»). Предлагаешь ты, назначает человек; «журнал и пересборка»). Предлагаешь ты, назначает человек;
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок - **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
@@ -61,15 +61,15 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
## Порядок ## Порядок
1. **Осмотрись.** Где лежат задачи, план, заметки. Каталог задач по канону — 1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
всегда `docs/tasks`. Секции беклога (`--sections`) — по умолчанию всегда `docs/tasks`. Секции беклога (`--sections`) — по умолчанию
`ядро,инфра`; если у проекта деление другое по существу, оно называется `Ядро,Инфра`; если у проекта деление другое по существу, оно называется
здесь, а не подгоняется под умолчание, и становится **заголовками `##` здесь, а не подгоняется под умолчание, и становится **заголовками `##`
индекса** — их единственным домом. В `docs/.pm.json` секции не пишутся. индекса** — их единственным домом. В `docs/.pm.json` секции не пишутся.
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два 2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
прохода дадут два несогласованных состояния. прохода дадут два несогласованных состояния.
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи; 3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
список `goals` — из шагов плана и из тем. Закрытый шаг плана целью не список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
заводится. Пустой `goal` — законный исход только у идеи. заводится. Пустой `goal` — законный исход только у идеи.
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию, 4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
@@ -41,12 +41,15 @@
заведённое и уже выкинутое. Нашлось среди живых — дописываем находку в заведённое и уже выкинутое. Нашлось среди живых — дописываем находку в
существующий файл. Нашлось в `REJECTED.md` — это сигнал: причина отказа могла существующий файл. Нашлось в `REJECTED.md` — это сигнал: причина отказа могла
устареть, выноси пользователю, а не заводи молча заново. устареть, выноси пользователю, а не заводи молча заново.
4. **Разложи по целям.** У каждой заводимой задачи должен быть `goal:<слаг>`. 4. **Разложи по целям — там, где цель нужна.** Большинство находок ревью это
Половина находок ревью не служит ничему из порядка — их цель **тематическая** `fix` и `chore`, и **цель им не требуется**: они служат работоспособности, а
(«прочность слияния», «журнал и пересборка», «наблюдаемость»). не направлению, и в спринт входят помимо его цели. Придуманная им цель —
Подходящей темы нет — заведи её целью (`add --type goal --section темы`) ровно то враньё, от которого спасает род работы.
в том же проходе: без цели задача не попадёт ни в один спринт, а значит не
будет сделана никогда. Цель обязательна у находки, которая оказалась **новой возможностью**
(`kind:feature`): нашлось поведение, которого никто не заказывал, и его надо
либо заказать целью, либо убрать. Подходящей цели нет — заведи её
(`add --type goal --section Направления`) в том же проходе.
5. **Покажи карту до создания файлов.** Кластер → задача / идея / строка в 5. **Покажи карту до создания файлов.** Кластер → задача / идея / строка в
пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из `AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
@@ -54,9 +57,14 @@
которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может
заводиться и без поштучного вопроса — но карта пользователю предъявляется заводиться и без поштучного вопроса — но карта пользователю предъявляется
всё равно. всё равно.
6. **Заводи утверждённое** через `tasks.py add`, с двумя добавками: 6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
- **тег партии**`--tag review-ГГГГ-ММ-ДД` (или `audit-<тема>`), чтобы весь - **тег партии**`--tag review-ГГГГ-ММ-ДД` (или `audit-<тема>`), чтобы весь
заход разбора поднимался одной командой `list --tag …`; заход разбора поднимался одной командой `list --tag …`;
- **род работы**`--kind`. У находок ревью он **не по умолчанию `fix`**:
починкой считается расхождение с заявленным поведением, а находка «этого
свойства никто не заказывал» — это `feature`, находка «не знаем, как
поведёт себя драйвер» — `research`. Род, розданный оптом, врёт ровно там,
где по нему потом отбирают;
- **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством. - **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством.
Без него через месяц не отличить проверенную находку от догадки. Без него через месяц не отличить проверенную находку от догадки.
7. `tasks.py check`. 7. `tasks.py check`.
+42 -17
View File
@@ -1,7 +1,7 @@
# Декомпозиция и мозговой штурм # Декомпозиция и мозговой штурм
Обе операции превращают одну запись в несколько (или в ноль). Разница во входе: Обе операции превращают одну запись в несколько (или в ноль). Разница во входе:
декомпозиция дробит **готовую задачу или эпик**, штурм прорабатывает **идею**, декомпозиция дробит **слишком крупную задачу**, штурм прорабатывает **идею**,
которая ещё не задача. которая ещё не задача.
## Тест декомпозиции ## Тест декомпозиции
@@ -11,14 +11,39 @@
1. **Мерджатся независимо.** Часть Б не требует, чтобы часть А была уже влита. 1. **Мерджатся независимо.** Часть Б не требует, чтобы часть А была уже влита.
Есть порядок «сперва А, потом Б, иначе не собрать» → это не декомпозиция, а Есть порядок «сперва А, потом Б, иначе не собрать» → это не декомпозиция, а
план реализации: шаги остаются **внутри одного файла**. план реализации: шаги остаются **внутри одного файла**.
2. **Каждая даёт видимую пользу.** Часть, полезная только в комплекте с другой, 2. **Каждая — самостоятельный шаг.** Часть, осмысленная только в комплекте с
— не самостоятельная задача. Пользу проверяй тестом «готова к взятию» другой, — не задача. Проверяй тестом «готова к взятию» (task-format): какую
(task-format): что станет наблюдаемо иначе именно от этой части и какие у неё строку «Завершения» цели двигает **именно эта часть** и какие у неё
собственные критерии приёмки. собственные критерии приёмки. У операционных частей (`fix`, `chore`,
`research`) цели может не быть — тогда достаточно собственных критериев.
Не проходит хотя бы одно — **не дроби**. Ложная декомпозиция плодит файлы, Не проходит хотя бы одно — **не дроби**. Ложная декомпозиция плодит файлы,
которые нельзя взять поодиночке, и переоценка потом склеивает их обратно. которые нельзя взять поодиночке, и переоценка потом склеивает их обратно.
## Где резать, если резать можно
Тест выше говорит, **допустим** ли разрез. Где его провести из нескольких
допустимых мест — отвечает шов.
**Шов — там, где падает ступень ревью.** Раздел «Затрагивает» перечисляет
границы; если одна строка перечня поднимает ступень выше остальных, эта часть и
режется отдельно. Пример: задача вводит новый пакет и заодно добавляет два поля в
существующий ответ. Целиком это `wide` — семь проходов по всему диффу. Разрезанная
по шву, она даёт `wide` на маленьком новом пакете и `standard` на остатке.
**Считай костяк, а не файлы.** У каждой задачи есть несокращаемые четыре прохода
(гейт, спеки, код, триаж), и они платятся за каждую. Разрез, после которого обе
половины остаются в одной ступени, делает ревью **дороже**: тот же объём
проверяется тем же составом, но костяк оплачен дважды. Отсюда правило: **резать,
когда разрез снимает дорогой проход с большей части диффа**, и не резать, когда
он просто делает файлы мельче.
**Это планирование, а не предписание процесса.** Ступень ревью выбирается по
факту изменения — тем, кто его видит, — и в тело задачи не пишется: строка
«делать профилем standard» это ровно тот второй дом правила выбора, который
гигиена полей снимает. Шов пользуется ступенью как **признаком**, что в задаче
две разнородные работы; решение о профиле остаётся за конвейером.
**Цель наследуется.** Все части несут `goal:` родителя: декомпозиция не меняет **Цель наследуется.** Все части несут `goal:` родителя: декомпозиция не меняет
того, чему работа служит. Если у части цель другая — это признак, что дробили не того, чему работа служит. Если у части цель другая — это признак, что дробили не
по той границе, либо что часть вообще из другой работы. по той границе, либо что часть вообще из другой работы.
@@ -31,21 +56,21 @@
`REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись: `REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись:
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
наследников, а не археологией git; наследников, а не археологией git;
- родитель осмыслен как зонтик → `edit <slug> --type epic`, тело — ссылки на - родитель осмыслен как **возможность**, а не как шаг → это цель. Тип на месте
задачи-части, своих шагов у него нет. **Эпик не берётся в спринт** и живёт не меняется (цель живёт в другом индексе): заводится `[goal]` в `ROADMAP.md`,
ровно до тех пор, пока не закрыта последняя часть. части получают `--goal <новый слаг>`, родитель закрывается с причиной-ссылкой.
Зонтик, который перестал быть временным и описывает направление, а не работу, — **Промежуточного зонтика между целью и задачей нет.** Тип `[epic]` упразднён:
это уже **цель**, а не эпик. Тип на месте не меняется (цель живёт в другом роль зонтика играет цель, а слишком крупный шаг дробится на шаги помельче под
индексе): заводится `[goal]` в `PLAN.md`, задачи получают `--goal <новый слаг>`, той же целью. Если частям нужен общий заголовок — значит у них общая
эпик закрывается с причиной-ссылкой. возможность, и её надо назвать целью, а не заводить временный тип.
## Когда декомпозиция случается посреди спринта ## Когда декомпозиция случается посреди спринта
Задача, которая **переросла в эпик**, распознаётся до того, как под неё заведено Задача, которая **оказалась крупнее задачи**, распознаётся до того, как под неё
предложение об изменении: иначе его придётся выбрасывать. Она помечается заведено предложение об изменении: иначе его придётся выбрасывать. Она выходит
`[epic]`, выходит из набора (`sprint drop … --reason "переросла в эпик"`), уходит из набора (`sprint drop … --reason "крупнее задачи"`), уходит на декомпозицию, а
на декомпозицию, а спринт продолжается остальными. Части заводятся сразу, но в спринт продолжается остальными. Части заводятся сразу под той же целью, но в
текущий набор **не добавляются** — набор заморожен. текущий набор **не добавляются** — набор заморожен.
## Мозговой штурм идеи ## Мозговой штурм идеи
@@ -76,7 +101,7 @@ Applicative-штурм («перечисли задачи, следующие и
- Идея/задача на входе, выбранная рамка (для штурма), задачи-наследники со - Идея/задача на входе, выбранная рамка (для штурма), задачи-наследники со
слагами, целями и секциями. слагами, целями и секциями.
- Судьба родителя: удалён / стал эпиком / стал целью / выкинут с причиной. - Судьба родителя: удалён / стал целью / выкинут с причиной.
- `tasks.py check` после правок. - `tasks.py check` после правок.
- Границы покрытия: какие постановки рассмотрены и какие сознательно отброшены — - Границы покрытия: какие постановки рассмотрены и какие сознательно отброшены —
чтобы штурм не пришлось повторять с нуля. чтобы штурм не пришлось повторять с нуля.
+120 -28
View File
@@ -11,13 +11,18 @@
```markdown ```markdown
# Тай-брейк при равной полноте # Тай-брейк при равной полноте
- **Секция:** ядро — вышла из спринта: остаток писал нерешённое в журнал - **Секция:** Ядро — вышла из спринта: остаток писал нерешённое в журнал
- **Зачем:** порядок канонических форм берёт меньшее в 96% случаев — для накопительных это систематический недосчёт - **Зачем:** порядок канонических форм берёт меньшее в 96% случаев — для накопительных это систематический недосчёт
- **Теги:** goal:merge-robustness, sprint:2026-08-03 - **Теги:** goal:merge-robustness, kind:fix, sprint:2026-08-03
При столкновении точек выигрывает более полная, но при равной полноте побеждает При столкновении точек выигрывает более полная, но при равной полноте побеждает
последняя доставка — а она систематически беднее первой. последняя доставка — а она систематически беднее первой.
## Затрагивает
Таблица `points` и её миграция; правило слияния в приёме доставки; формат
отпечатка состояния на диске. Публичного контракта не трогает.
## Критерии приёмки ## Критерии приёмки
- повторный прогон свёртки даёт тот же отпечаток состояния — оракул: команда сверки - повторный прогон свёртки даёт тот же отпечаток состояния — оракул: команда сверки
@@ -32,9 +37,15 @@
``` ```
- **Заголовок H1** — он же заголовок строки в индексе, дословно. Тип кодируется - **Заголовок H1** — он же заголовок строки в индексе, дословно. Тип кодируется
префиксом `[goal]` / `[idea]` / `[epic]`; обычная задача — без префикса. префиксом `[goal]` / `[idea]`; обычная задача — без префикса.
Отдельного поля типа **нет**: два места для одного факта разъезжаются, а Отдельного поля типа **нет**: два места для одного факта разъезжаются, а
префикс виден прямо в индексе, где и принимается решение «брать или не брать». префикс виден прямо в индексе, где и принимается решение «брать или не брать».
- **Форма заголовка — по типу записи.** Задача отвечает на «что нужно сделать»
и пишется глаголом в неопределённой форме («Печатать поле одним куском кода»,
«Не отбрасывать молча лишние символы»); цель — на «что приложение будет
уметь»; идея просто называет, о чём она. Почему так — SKILL.md, «Как написана
задача». `check` считает заголовки не в форме действия и печатает число в
здоровье; годность формулировки смотрит агент `task-form`.
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна - **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна
секция, причина после тире желательна (именно она объясняет, почему задача секция, причина после тире желательна (именно она объясняет, почему задача
здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги
@@ -47,8 +58,11 @@
лежало только в индексе, штатная починка дрейфа теряла его молча и лежало только в индексе, штатная починка дрейфа теряла его молча и
навсегда — а это единственное, по чему задачу выбирают, не открывая. навсегда — а это единственное, по чему задачу выбирают, не открывая.
- **Тело** — одна фраза «что станет наблюдаемо иначе», критерии приёмки, рамки, - **Тело** — одна фраза «что станет наблюдаемо иначе», затрагиваемые границы,
контекст, ссылки. Пишется на языке документации проекта. критерии приёмки, рамки, контекст, ссылки. Пишется на языке документации
проекта: предметно, без англицизмов, у которых есть русское слово, и без
терминов, которых нет ни в паспорте, ни в архитектуре, ни в конвенциях
(правило и его причина — в SKILL.md, раздел «Как написана задача»).
Мета **одной строкой через `·`** — прежняя форма. Она читается по-прежнему, Мета **одной строкой через `·`** — прежняя форма. Она читается по-прежнему,
`check` называет её дрейфом, `check --fix` переписывает списком; поле `Хук` `check` называет её дрейфом, `check --fix` переписывает списком; поле `Хук`
@@ -59,6 +73,36 @@
Тело — не план реализации и не спецификация: принятое и реализованное переезжает Тело — не план реализации и не спецификация: принятое и реализованное переезжает
в документацию проекта, а файл задачи удаляется. в документацию проекта, а файл задачи удаляется.
### Затрагивает
Перечень **границ**, которых изменение касается. Границей считается то, у чего
есть внешняя сторона и цена изменения:
- эндпоинт, команда, форма ответа, код ответа;
- таблица, поле, миграция, формат на диске, формат сообщения в очереди;
- публичный тип или функция пакета, конфиг и его образцы;
- внешний сервис или библиотека, чьё поведение становится нужным.
Ничего из этого не трогается — так и пишется: «границ не трогает, изменение
внутри одного узла». Это ответ, а не пустой раздел.
**Границы, а не замысел.** «Переписать хранилище на новый драйвер» — замысел;
`таблица points и её миграция`, `эндпоинт POST /ingest` — границы. Разница
проверяется вопросом «это можно назвать до того, как решено *как* делать?»: если
нет, строка описывает реализацию, и её место в предложении об изменении.
**Свойства репозитория сюда не пишутся** — по той же причине, что и в рамки:
имя таблицы стабильно, номер последней миграции протухает молча. Пишется
`таблица points и её миграция`, а не `миграция 0042`.
**Что из этого механизировано.** `check` и `sprint take` смотрят только на
**наличие непустого раздела**. Полнота перечня машине не видна: границу, которую
забыли назвать, она от отсутствующей не отличает. Раздела нет — отказ во взятии:
оценивать нечем.
**У идей раздела нет** — как и критериев: границы становятся известны, когда идея
превращается в задачу.
### Критерии приёмки ### Критерии приёмки
2–5 проверяемых утверждений **списком** `- …`, **у каждого назван оракул**. Не 2–5 проверяемых утверждений **списком** `- …`, **у каждого назван оракул**. Не
@@ -114,10 +158,14 @@
## Файл цели ## Файл цели
```markdown **Заголовок цели отвечает на «что приложение будет уметь».** Не область работ и
# [goal] Прочность слияния не имя подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от
порядка доставки». Свойство поведения — тоже возможность.
- **Секция:** темы ```markdown
# [goal] Исход слияния не зависит от порядка доставки
- **Секция:** Направления
- **Теги:** decomposed - **Теги:** decomposed
Ради чего: точки из разных доставок сходятся в один часовой объект, и сегодня Ради чего: точки из разных доставок сходятся в один часовой объект, и сегодня
@@ -125,21 +173,31 @@
## Завершение ## Завершение
Достигнута, когда исход слияния не зависит ни от порядка, ни от времени - повторная доставка тех же точек в другом порядке даёт то же состояние;
доставки, и это подтверждено повторным прогоном на живом корпусе. - накопительная метрика за сутки не уменьшается после повторной доставки;
- в логе видно, какая из двух точек выиграла и почему.
``` ```
- **Задачи цели здесь не перечисляются.** Перечень даёт - **Задачи цели здесь не перечисляются.** Перечень даёт
`tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и `tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и
поехал бы на первой же закрытой задаче. поехал бы на первой же закрытой задаче.
- **Раздел «Завершение»** — то, по чему видно, что цель достигнута. - **Раздел «Завершение» — списком, а не абзацем.** Это признаки того, что
приложение уже умеет; **на строку «Завершения» ссылается задача**, объясняя,
какую часть возможности она двигает (см. тест готовности). Абзацем такая
ссылка не берётся, поэтому список.
- **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи - **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи
закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет. закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет.
Пометка именно **тегом**, а не строкой в теле: только так она проверяется. Пометка именно **тегом**, а не строкой в теле: только так она проверяется.
`check` напоминает о нём у цели без задач замечанием — неразобранная цель `check` напоминает о нём у цели без задач замечанием — неразобранная цель
законна и зелёного прогона не ломает; `check --fix` сам ставит его цели, у законна и зелёного прогона не ломает; `check --fix` сам ставит его цели, у
которой задачи есть, а цель с тегом и без задач — прямое приглашение закрыть. которой задачи есть, а цель с тегом и без задач — прямое приглашение закрыть.
- Цель живёт в `PLAN.md` и **никогда** — в `BACKLOG.md` или `SPRINT.md`. - Цель живёт в `ROADMAP.md` и **никогда** — в `BACKLOG.md` или `SPRINT.md`.
- **Достигнутая цель не исчезает.** `close <слаг> --implemented` удаляет файл и
переносит строку в секцию `Готово` с датой:
`- 2026-08-04 \`merge-order\` — Исход слияния не зависит от порядка доставки. …`
Ссылки на файл в ней нет — файл удалён, а битая ссылка это ошибка `check`.
Поведение живёт в спеках проекта; роадмап отвечает, **когда и в каком порядке**
оно появилось.
## Слаг ## Слаг
@@ -167,8 +225,8 @@
| Файл | Что отвечает | Секции | | Файл | Что отвечает | Секции |
| --- | --- | --- | | --- | --- | --- |
| `PLAN.md` | какие есть цели, в какой очереди идут и почему | порядок (очередь значима) и темы (порядка нет) | | `ROADMAP.md` | что приложение уже умеет и чего ещё не умеет | канонические: `Готово`, `Запланировано`, `Направления`, `Разработка` (англ. `Done`, `Planned`, `Directions`, `Tooling`) |
| `BACKLOG.md` | что **можно взять** — только задачи | секции проекта (по умолчанию ядро/инфра) | | `BACKLOG.md` | что **можно взять** — только задачи | секции проекта (по умолчанию Ядро/Инфра) |
| `SPRINT.md` | какая цель и какой набор под неё | одна: «Набор» | | `SPRINT.md` | какая цель и какой набор под неё | одна: «Набор» |
| `REJECTED.md` | что ушло без реализации и почему | — | | `REJECTED.md` | что ушло без реализации и почему | — |
@@ -187,8 +245,19 @@
Постоянно пустая секция со старой семантикой «разбираются пачками» противоречила Постоянно пустая секция со старой семантикой «разбираются пачками» противоречила
бы правилу «эскалируем немедленно», поэтому `init` её не заводит, а `check` бы правилу «эскалируем немедленно», поэтому `init` её не заводит, а `check`
говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её. В секции говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её. В секции
**«порядок»** очередь значима и обосновывается прозой; двигают строку **`Запланировано`** очередь значима и обосновывается прозой; двигают строку
`move <slug> --section порядок --after <другой>`. `move <slug> --section Запланировано --after <другой>`. В секции **`Готово`**
строки не той формы, что у прочих индексов: дата, слаг, заголовок — как в
`REJECTED.md`, и по той же причине (файла уже нет, ссылаться некуда).
**Секции роадмапа закреплены** — состав, полнота и единство языка проверяются
`check`; секции беклога проект называет сам. Почему так — SKILL.md.
**Заголовок секции пишется с прописной, и после него идёт пустая строка** — во
всех индексах, включая секции беклога, имена которых выбирает проект. Написание
канонических секций и отбивку правит `check --fix`; он же сводит написание
секции в мете файла с заголовком индекса — **имя секции принадлежит заголовку**,
файл на неё лишь ссылается, и принадлежность сверяется по нижнему регистру.
Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`). Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`).
Строку руками не пишут. Строку руками не пишут.
@@ -212,7 +281,7 @@
```markdown ```markdown
- 2026-07-23 `versii-kachestvo-repaki` — Версии и качество одного тайтла. - 2026-07-23 `versii-kachestvo-repaki` — Версии и качество одного тайтла.
Причина: калибровка болей — не боль, ни разу не возникло за полгода. Причина: калибровка болей — не боль, ни разу не возникло за полгода.
Была секция: инфра. Была секция: Инфра.
``` ```
Реализованные сюда не попадают: у них остаётся коммит и документация. У Реализованные сюда не попадают: у них остаётся коммит и документация. У
@@ -227,8 +296,16 @@
Единственный механизм разметки, потому что `list --tag` уже умеет отбирать по Единственный механизм разметки, потому что `list --tag` уже умеет отбирать по
ним порцию разбора. Отдельных полей меты под это не заводим. ним порцию разбора. Отдельных полей меты под это не заводим.
- `goal:<слаг>` — цель, которой служит задача. Обязателен: задача без цели не - `goal:<слаг>` — цель, которой служит задача. Обязателен **у `kind:feature`**:
попадёт ни в один спринт. новая возможность и есть содержание цели. У `fix`, `chore` и `research` его
может не быть — они служат работоспособности, а не направлению, и в набор
спринта входят помимо его цели.
- `kind:<род>` — род работы: `feature` | `fix` | `chore` | `research`. Словарь
**закрыт**, значение ровно одно. Обязателен у задачи (без него `sprint take`
откажет), у цели запрещён, у идеи необязателен. Ставится
`add --kind` / `edit --kind`; `--kind` заменяет прежнее значение, а не
добавляет второе. Смысл рода и почему он тегом, а не префиксом — в SKILL.md,
раздел «Род работы».
- `question` — в файле есть неразобранный раздел «Вопросы». - `question` — в файле есть неразобранный раздел «Вопросы».
- `sprint:<слаг>` — задача заведена в этом спринте; по нему отбирается первая - `sprint:<слаг>` — задача заведена в этом спринте; по нему отбирается первая
порция разбора («урожай спринта»). **Ставится сам**: слаг спринта заводит порция разбора («урожай спринта»). **Ставится сам**: слаг спринта заводит
@@ -248,21 +325,36 @@
## Тест «готова к взятию» ## Тест «готова к взятию»
Задача готова, если из файла отвечаются три вопроса: Задача готова, если из файла отвечаются четыре вопроса:
1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю, 1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю,
владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет
ломаться Y при Z» — ответ. ломаться Y при Z» — ответ. **У `kind:chore` адресат — разработчик, и это
2. **По чему видно, что закончено** — критерии приёмки с оракулами. законно**: «уедет последний вызов устаревшего API» — ответ, а не отговорка.
3. **Какой цели она служит** — тег `goal:` и одна строка «почему именно этой». Род объявлен как раз затем, чтобы такие задачи не выдумывали себе
пользовательскую пользу.
2. **Каких границ это касается** — раздел «Затрагивает». Без него задачу нельзя
оценить: остаётся судить по длине текста.
3. **По чему видно, что закончено** — критерии приёмки с оракулами.
4. **Какую часть «Завершения» своей цели она двигает** — у задачи с целью.
Строкой: «двигает пункт 2 «Завершения» — накопительная метрика перестаёт
уменьшаться». Это и есть защита от задачи «отрефакторить X»: она проваливает
тест не потому, что невидима снаружи, а потому, что не находит строки, к
которой относится. Заодно видно обратное — достаточен ли набор задач для
цели: строка «Завершения», к которой не относится ни одна задача, это
незакрытая часть возможности.
Не отвечается первый или второй вопрос → это **идея** (`[idea]`), её место в **У задачи без цели** (`fix`, `chore`, `research`) вопрос не задаётся: они
штурме. Не отвечается третий → либо цель есть и не проставлена, либо задача не служат работоспособности, а не направлению.
служит ничему — тогда её не надо заводить.
Не отвечается первый, второй или третий вопрос → это **идея** (`[idea]`), её
место в штурме. Не отвечается четвёртый у `feature` → либо цель есть и не
проставлена, либо это не новая возможность.
Отвечается всё, но задача не делается одним заходом и не мерджится целиком → Отвечается всё, но задача не делается одним заходом и не мерджится целиком →
**эпик** (`[epic]`), сперва декомпозиция. Эпик временен и исчезает после это **несколько задач под одной целью**, дроби сразу. Промежуточного зонтика
разбора; цель (`[goal]`) постоянна — не путать. между целью и задачей нет: тип `[epic]` упразднён, потому что зонтиком стала
сама цель.
Тест применяется при заведении и при переоценке. К старым задачам, которых Тест применяется при заведении и при переоценке. К старым задачам, которых
операция не касается, задним числом не применяется — беклог не переоформляют операция не касается, задним числом не применяется — беклог не переоформляют
File diff suppressed because it is too large Load Diff
+1
View File
@@ -63,5 +63,6 @@ project-includes = [
"av-dev-pm/skills/canon/scripts/docs.py", "av-dev-pm/skills/canon/scripts/docs.py",
"scripts/copies.py", "scripts/copies.py",
"scripts/diagrams.py", "scripts/diagrams.py",
"scripts/frontmatter.py",
] ]
python-version = "3.12" python-version = "3.12"
+177
View File
@@ -0,0 +1,177 @@
#!/usr/bin/env python3
"""Проверка фронтматтеров скиллов и charter'ов этого репозитория.
Фронтматтер единственная часть скилла, которую читает не человек, а загрузчик:
по `name` он разрешает вызов, по `description` решает, звать ли скилл вообще.
Ошибка здесь не выглядит ошибкой. Текст остаётся читаемым, `git diff` показывает
разумную строку, а скилл либо не находится по имени, либо загружается с
обрезанным описанием и потому не срабатывает на своих же триггерах.
Ловится три класса.
**Двоеточие с пробелом в описании без кавычек.** В YAML `: ` внутри простого
скаляра начинает вложенное отображение строка «конвейер ревью: гейт, сверка»
это не текст с двоеточием, а синтаксическая ошибка. Так были написаны три
описания из четырнадцати; заметить это чтением нельзя, потому что читается оно
правильно.
**Имя, разошедшееся с каталогом.** Скилл зовётся по имени каталога, а `name`
внутри то, чем он представляется. Разъехались вызов не разрешается, и
сообщение об этом говорит «нет такого скилла», а не «имя не то».
**Цвет, не отвечающий модели.** Цвет charter'а кодирует **модель**, на которой
идёт проход, а не его роль: раскладка в
`av-dev-pipeline/skills/review-pipeline/SKILL.md`, раздел «Модель по проходу».
Правило существует ровно затем, чтобы стоимость прогона читалась взглядом по
списку агентов, и держаться вниманием оно не может: цвет ставится один раз при
заведении charter'а, а модель потом меняется калибровкой.
Коды выхода тот же словарь, что у tasks.py, docs.py, copies.py и diagrams.py:
0 все фронтматтеры в порядке
1 расхождение
2 ошибка употребления: аргументы
3 окружение: не тот каталог
4 внутренний сбой
"""
from __future__ import annotations
import argparse
import sys
from pathlib import Path
OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4
# Дом раскладки — «Модель по проходу» в review-pipeline/SKILL.md; здесь её
# механизация. Порядок цветов — порядок стоимости прогона.
PALETTE = {"sonnet": "green", "opus": "yellow", "fable": "red"}
SKILL_KEYS = {"name", "description"}
AGENT_KEYS = {"name", "description", "tools", "model", "color"}
class Sheet:
"""Разобранный фронтматтер одного файла."""
def __init__(self, path: Path, root: Path) -> None:
self.path = path
self.where = path.relative_to(root).as_posix()
self.fields: dict[str, str] = {}
self.problems: list[str] = []
# Разбор дошёл до полей. Ложь — фронтматтера нет вовсе, и спрашивать с
# него имя, набор полей и цвет бессмысленно: ответ будет один и тот же.
self.parsed = False
self._parse()
def _parse(self) -> None:
lines = self.path.read_text(encoding="utf-8").splitlines()
if not lines or lines[0].strip() != "---":
self.problems.append("нет фронтматтера: первая строка не `---`")
return
try:
end = lines.index("---", 1)
except ValueError:
self.problems.append("фронтматтер не закрыт строкой `---`")
return
self.parsed = True
for number, line in enumerate(lines[1:end], start=2):
if not line.strip():
continue
key, sep, value = line.partition(":")
if not sep or not key or key != key.strip():
self.problems.append(f"строка {number}: не `ключ: значение`")
continue
value = value.strip()
self.fields[key] = value
if value[:1] in ('"', "'"):
continue
if ": " in value:
self.problems.append(
f"строка {number}: у `{key}` двоеточие с пробелом в значении"
f" без кавычек — для YAML это вложенное отображение,"
f" а не текст. Обернуть значение в двойные кавычки"
)
def check(self, expected_name: str, required: set[str]) -> None:
missing = sorted(required - self.fields.keys())
if missing:
self.problems.append(f"нет обязательных полей: {', '.join(missing)}")
name = self.fields.get("name", "").strip("\"'")
if name and name != expected_name:
self.problems.append(
f"`name: {name}` разошлось с ожидаемым `{expected_name}`"
f" — вызов разрешается по второму"
)
model = self.fields.get("model", "").strip("\"'")
color = self.fields.get("color", "").strip("\"'")
if model and color:
if model not in PALETTE:
self.problems.append(
f"модель `{model}` не в раскладке цветов"
f" ({', '.join(sorted(PALETTE))}) — назначить ей цвет"
f" в «Модель по проходу» и здесь"
)
elif color != PALETTE[model]:
self.problems.append(
f"цвет `{color}` не отвечает модели `{model}`:"
f" по раскладке — `{PALETTE[model]}`"
)
def collect(root: Path) -> list[tuple[Sheet, str, set[str]]]:
"""Все фронтматтеры репозитория: лист, ожидаемое имя, обязательные поля."""
found: list[tuple[Sheet, str, set[str]]] = []
for plugin in sorted(root.glob("av-*/")):
for skill in sorted(plugin.glob("skills/*/SKILL.md")):
found.append((Sheet(skill, root), skill.parent.name, SKILL_KEYS))
for agent in sorted(plugin.glob("agents/*.md")):
found.append((Sheet(agent, root), agent.stem, AGENT_KEYS))
return found
def main() -> int:
ap = argparse.ArgumentParser(description="Проверка фронтматтеров.")
ap.add_argument("--dir", default=".", help="корень репозитория")
args = ap.parse_args()
root = Path(args.dir).resolve()
if not (root / ".claude-plugin").is_dir():
print(f"окружение: {root} не похож на корень репозитория"
f" (нет .claude-plugin)", file=sys.stderr)
return ENV
sheets = collect(root)
if not sheets:
print("окружение: не нашлось ни одного SKILL.md или charter'а",
file=sys.stderr)
return ENV
for sheet, expected, required in sheets:
if sheet.parsed:
sheet.check(expected, required)
skills = sum(1 for _, _, required in sheets if required is SKILL_KEYS)
print(f"фронтматтеров {len(sheets)}: скиллов {skills},"
f" charter'ов {len(sheets) - skills}")
broken = [sheet for sheet, _, _ in sheets if sheet.problems]
if broken:
print()
for sheet in broken:
for problem in sheet.problems:
print(f"ОШИБКА {sheet.where}\n {problem}")
print(f"\nИтог: с ошибками {len(broken)} из {len(sheets)}.")
return DRIFT
print("все в порядке")
return OK
if __name__ == "__main__":
try:
sys.exit(main())
except KeyboardInterrupt:
sys.exit(INTERNAL)
except Exception as e: # noqa: BLE001 — последний рубеж, код 4 по словарю
print(f"внутренний сбой ({type(e).__name__}): {e}", file=sys.stderr)
sys.exit(INTERNAL)