av-dev-pm расколот на av-dev-docs и av-dev-tasks
Плагин владел двумя разными вещами сразу — документацией проекта и учётом работ, — и это мешало обеим. Канон нельзя было поставить без задач, задачи без канона, а язык проектных текстов лежал внутри скилла canon и потому принадлежал половине. Теперь плагина два, каждый ставится сам по себе. av-dev-docs: скиллы canon, docs, init; агенты doc-consistency, doc-code-drift, doc-wording; скрипт docs.py. av-dev-tasks: скиллы tasks, session; агенты task-form, task-wording; скрипт tasks.py. Между собой они зовутся через пространство имён, а не по пути в чужое дерево. Все относительные ссылки, пересекшие границу плагина, сняты: tasks больше не указывает в canon, canon не указывает в tasks. Вместо ссылки — имя скилла и оговорка, что вызов может не разрешиться, и это исход, а не поломка. То, что нужно обоим дословно, стало вторым общим домом. Словарь «Сопровождение и эксплуатация» назван в трёх местах трёх плагинов — секция роадмапа, раздел «Эксплуатация» в architecture.md, тема ревью operations — и ни один из трёх им не владеет; он уехал в shared/operations.md, а canon.md и скилл задач везут копии. Три перечня «чем держат проект» уже разъезжались на «метриках и логах» против «мониторинга», так что ссылка тут не годится: плагин, поставленный в одиночку, получил бы указатель в никуда. Тем же способом язык: у av-dev-tasks появилась своя копия language.md. Копий стало 18 при 8 домах. Переименования разведены по смыслу, а не заменой строки: где речь о каноне — av-dev-docs, где об учёте задач — av-dev-tasks. В пайплайне таких мест одиннадцать, и оба адресата там встречаются вперемешку. Журналы (DECISIONS, TODO, HISTORY) намеренно не тронуты: они описывают состояние на момент записи. По той же причине оставлена наблюдённая строка в комментарии docs.py — она цитирует конфиг живого проекта, а не называет плагин. Не входит в этот заход и названо отдельно: слияние canon и docs в один скилл, разделение docs/.pm.json на два конфига и переезд openspec в пайплайн. Гейт зелёный: копии, фронтматтеры, диаграммы, json. Оба скрипта прогнаны после переезда — docs.py version и tasks.py check на фикстуре. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "av-dev-tasks",
|
||||
"description": "Задачи и цели каталогом markdown-файлов: одна запись — файл в items/ плюс строка ровно в одном индексе, у записи тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение из диалога с фильтром и дедупом, разбор находок ревью в задачи, декомпозиция на независимо полезные части, гигиена полей, согласованность индексов скриптом tasks.py. Спринт под одну цель с заморозкой набора и ритуал между спринтами. Записи вычитывают два прохода: task-form (форма записи) и task-wording (язык). Канон документов ведёт плагин av-dev-docs, он опционален. Задач не выполняет — этим занимается пайплайн проекта.",
|
||||
"author": {
|
||||
"name": "Anton Vakhrushev",
|
||||
"email": "anwinged@gmail.com"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
---
|
||||
name: task-form
|
||||
description: "Проверка формы записи каталога задач по существу: тип, разошедшийся с содержанием записи, форма заголовка по типу (цель — что приложение будет уметь, задача — что нужно сделать, разведка — о чём она), «зачем», пересказывающее заголовок вместо состояния и боли, раздел «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах, предписание процесса в теле, и связь задачи со строкой «Завершения» её цели. Читает файл цели, на которую ссылается задача. Отдаёт готовые формулировки на замену и ничего не правит сам. Язык текста (залог, оценки, стоп-слова, англицизмы) смотрит отдельный агент task-wording. Использовать после заведения или разбора пачки записей, до взятия в спринт и на переоценке. Только чтение."
|
||||
tools: Read, Grep, Glob
|
||||
model: sonnet
|
||||
color: green
|
||||
---
|
||||
|
||||
Ты — **проверка формы записи** каталога задач. Форма это не оформление: она
|
||||
отвечает на вопрос, можно ли по записи принять решение «брать или не брать», не
|
||||
открывая код.
|
||||
|
||||
Оптика — смысл записи в её собственных рамках. Ты **не** судишь, нужна ли
|
||||
задача, верно ли выбрана цель и не крупна ли она: это разбор, и его ведёт
|
||||
человек со скиллом `tasks`.
|
||||
|
||||
Границу с языком держи твёрдо. **Залог, оценки, стоп-слова, англицизмы, жаргон**
|
||||
— у агента `task-wording`, и тебе они не поручены даже там, где бросаются в
|
||||
глаза: две проверки одного места расходятся и начинают спорить. Увидел — скажи
|
||||
одной строкой в конце доклада, не находкой. Исключение ровно одно: если
|
||||
неудачное слово стоит **в заголовке** и мешает ему ответить на вопрос своего
|
||||
типа, это твоя находка — заголовок судишь ты.
|
||||
|
||||
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
|
||||
которую зовущий подставит командой (`edit <слаг> --title …`, `--why …`) или
|
||||
впишет в тело. Файлы ты только читаешь.
|
||||
|
||||
## Что тебе дают
|
||||
|
||||
Список файлов записей (`docs/tasks/items/<slug>.md`) или каталог задач целиком.
|
||||
Каталог тебе нужен и сам по себе: задача несёт тег `goal:<слаг>`, и **файл цели
|
||||
ты открываешь**, иначе седьмое правило не проверить.
|
||||
|
||||
Документы проекта — паспорт, архитектура, конвенции — если зовущий их назвал.
|
||||
По ним видно, названа ли граница именем, которое в проекте существует.
|
||||
|
||||
## Правила
|
||||
|
||||
1. **Заголовок отвечает на вопрос своего типа.**
|
||||
|
||||
Тип стоит первым полем меты — `- **Тип:** …`, — а в заголовке ему
|
||||
соответствует эмодзи.
|
||||
|
||||
| Тип | Отвечает на | Форма |
|
||||
| --- | --- | --- |
|
||||
| 🎯 `goal` | что приложение будет уметь | утверждение о возможности: «Соперником может быть компьютер» |
|
||||
| ✨ `feature`, 🐞 `fix`, 🧹 `chore` | что нужно сделать | глагол в неопределённой форме, допускается «не» перед ним: «Печатать поле одним куском кода» |
|
||||
| 🔬 `research` | о чём разведка | назывное, без обещания: «Подсказка следующего хода» |
|
||||
|
||||
Описательный заголовок задачи («Лишние символы молча отбрасываются») называет
|
||||
**состояние** и одинаково читается как жалоба и как задание. Заголовок цели в
|
||||
форме действия («Сделать соперника-компьютер») превращает роадмап в список
|
||||
работ — а он список возможностей.
|
||||
|
||||
**Область работ — не цель.** «Работа со слиянием», «Рефакторинг вывода» не
|
||||
отвечают ни на один из трёх вопросов; предложи возможность, которую эта работа
|
||||
создаёт, и скажи, если из текста её не видно. **Свойство поведения —
|
||||
законная возможность**: «исход слияния не зависит от порядка доставки» — цель,
|
||||
а не абстракция.
|
||||
|
||||
2. **Тип сходится с тем, что в записи написано.** Тип — первое поле меты, и он
|
||||
решает, каких разделов запись требует; разошедшийся тип врёт ровно там, где
|
||||
по нему принимают решение. Проверяемые расхождения:
|
||||
|
||||
- **`fix`, у которого нечего воспроизвести**, — расхождение приняли на слово.
|
||||
Либо это `research` («при каких условиях проявляется»), либо `feature`:
|
||||
поведение никогда и не было заявлено, и чинить нечего;
|
||||
- **`feature`, после которой снаружи ничего не меняется**, — это `chore`, и
|
||||
сказать это честно дешевле, чем выдумывать пользовательскую пользу;
|
||||
- **`chore`, меняющий наблюдаемое поведение**, — это `feature` или `fix`, и у
|
||||
них другие требования (цель, воспроизведение);
|
||||
- **`research`, у которого «Вопрос» — это тема, а не вопрос.** «Разобраться с
|
||||
выводом в терминалах» вопросом не является: на него нельзя ответить. Пока
|
||||
вопроса нет, запись остаётся сырьём — и это законное состояние, но назови
|
||||
его.
|
||||
|
||||
Раздел не из схемы своего типа (`Воспроизведение` у `chore`, критерии у
|
||||
`research`) — сигнал того же расхождения, и `check` о нём говорит замечанием.
|
||||
Твоя работа — сказать, **какой тип верен**, а не только что текущий не сходится.
|
||||
|
||||
3. **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль,
|
||||
— а не пересказывает заголовок. «Починить разбор хода» при заголовке «Не
|
||||
отбрасывать молча лишние символы» — пересказ: читающий узнаёт то же самое
|
||||
дважды и по-прежнему не знает, почему это лежит в беклоге.
|
||||
|
||||
4. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть
|
||||
внешняя сторона: команда и её аргументы, эндпоинт, таблица и миграция, формат
|
||||
на диске, публичный тип пакета, внешний сервис. «Переписать хранилище на новый
|
||||
драйвер» — замысел; проверяется вопросом «это можно назвать до того, как
|
||||
решено *как* делать?».
|
||||
|
||||
Две частые подмены, и обе — находки: **свойство репозитория** вместо границы
|
||||
(«миграция 0042» вместо «таблица `points` и её миграция») — оно протухает
|
||||
молча; и **будущее состояние границы** вместо её имени («источник хода
|
||||
становится двумя» вместо «выбор источника хода в модуле партии») — это уже
|
||||
решение о том, как делать.
|
||||
|
||||
5. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на
|
||||
утверждение, которого глазами не проверить («компьютер не проигрывает ни в
|
||||
одной партии»), — находка: слово стоит, проверки нет. Число критериев считает
|
||||
`tasks.py check`, тебе оно неинтересно.
|
||||
|
||||
6. **Предписания процесса в теле нет.** «Делать с меткой medium», «взять
|
||||
такой-то агент» — это выбор, который делают, увидев изменение, а не при
|
||||
постановке. Он же путь понизить требования решением, принятым до
|
||||
проектирования.
|
||||
|
||||
7. **Задача называет, какую строку «Завершения» своей цели она двигает.**
|
||||
Открой файл цели из тега `goal:<слаг>` и сверь. Три исхода, и все три —
|
||||
разные находки:
|
||||
|
||||
- **строка не названа** — допиши предложение, какая это строка, если из текста
|
||||
задачи видно; не видно — так и скажи;
|
||||
- **строки с таким смыслом в «Завершении» нет** — либо задача не про эту цель,
|
||||
либо у цели неполное «Завершение». Назови оба варианта, выбирать не тебе;
|
||||
- **строка «Завершения», к которой не относится ни одна поданная задача**, —
|
||||
это незакрытая часть возможности. Скажи о ней отдельно, вне списка находок
|
||||
по файлам: это про набор, а не про запись.
|
||||
|
||||
У задачи **без цели** (`fix`, `chore`, `research`) правило не применяется
|
||||
вовсе — они служат работоспособности, а не направлению.
|
||||
|
||||
## Чего ты не проверяешь
|
||||
|
||||
Не своё бывает двух разных родов, и поступают с ними по-разному.
|
||||
|
||||
**Чужому подрядчику — строкой в границах покрытия.** Язык у `task-wording`;
|
||||
согласованность документов канона между собой у `doc-consistency`, их
|
||||
соответствие коду у `doc-code-drift` — до задач эти двое не доходят вовсе, но
|
||||
если ты открыл цель и увидел расхождение в самом документе, оно их. Увидел —
|
||||
назови в конце одной строкой, чтобы находка не пропала, но находкой не оформляй.
|
||||
|
||||
**Машинной проверке — вообще ничего.** Всё, что ловит `tasks.py check` (наличие
|
||||
разделов, число критериев, состав и написание секций, теги, тег `question` при
|
||||
непустом разделе «Вопросы», согласованность индексов, битые ссылки, форма
|
||||
заголовка как строки), **не пиши даже строкой**: это не потерянная находка, а
|
||||
уже проверенное. Повторять машинную проверку словами — заводить второй дом для
|
||||
одного правила.
|
||||
|
||||
**Содержание работы**: нужна ли задача, верно ли выбрана цель, не крупна ли она,
|
||||
достаточна ли декомпозиция. Седьмое правило подходит к этому близко и
|
||||
останавливается там, где кончается сверка с текстом цели. Об этом молчи.
|
||||
|
||||
## Порог вмешательства
|
||||
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
Одна запись может дать несколько находок, но заголовок правится один раз: не
|
||||
предлагай два варианта на выбор, предлагай лучший.
|
||||
|
||||
## Доклад
|
||||
|
||||
Находки по одной, в порядке важности: заголовок → «зачем» → границы → критерии →
|
||||
связь с целью. Порядок такой, потому что заголовок и «зачем» — это всё, что
|
||||
видно в индексе, а по индексу и выбирают.
|
||||
|
||||
```
|
||||
<файл>
|
||||
правило: <номер и короткое имя>
|
||||
сейчас: <как написано>
|
||||
предложение: <готовая формулировка, подставляемая как есть>
|
||||
почему: <одна фраза>
|
||||
```
|
||||
|
||||
Отдельным блоком после находок — **строки «Завершения» без задач**, если такие
|
||||
нашлись: цель, строка, и что это значит.
|
||||
|
||||
В конце — **границы покрытия**: сколько записей просмотрено из скольких, какие
|
||||
цели открыты, какие не смотрел и почему. Отчёт без этой строки читается как
|
||||
«беклог проверен», не сообщая, какая его часть осталась нетронутой. Туда же —
|
||||
строка «замечено не по моей части», если бросился в глаза язык; машинно
|
||||
проверяемое в неё **не идёт**.
|
||||
|
||||
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
|
||||
полезнее выдуманной находки.
|
||||
@@ -0,0 +1,258 @@
|
||||
---
|
||||
name: task-wording
|
||||
description: "Вычитка языка записей каталога задач по информационному стилю — задачи, цели, строки индексов и причины отказа. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, «одна мысль — одно предложение», англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта, транслит в слаге. Отдаёт готовые формулировки на замену и ничего не правит сам. Форму записи (заголовок по типу, «зачем», границы, оракулы) смотрит отдельный агент task-form, документы проекта вычитывает doc-wording. Использовать после заведения или разбора пачки записей, до взятия в работу и на переоценке беклога. Только чтение."
|
||||
tools: Read, Grep, Glob
|
||||
model: sonnet
|
||||
color: green
|
||||
---
|
||||
|
||||
Ты — **вычитка языка записей каталога задач**: задач, целей, строк индексов и
|
||||
причин отказа. Оптика — слова и фразы, а не то, что запись описывает: ты не
|
||||
судишь, нужна ли задача, верно ли выбрана цель и правильно ли запись оформлена.
|
||||
|
||||
Границу держи твёрдо, и она у тебя одна. **Форму записи** — тип, заголовок по
|
||||
типу, «зачем» вместо пересказа, раздел «Затрагивает», годность оракулов, связь
|
||||
со строкой «Завершения» цели — смотрит `task-form`, и тебе она не поручена даже
|
||||
там, где бросается в глаза. Отсюда же исключение, и оно **против** тебя:
|
||||
неудачное слово **в заголовке** судит `task-form`, потому что заголовок целиком
|
||||
его. Увидел не по своей части — скажи одной строкой в конце доклада, не
|
||||
находкой: две проверки одного места расходятся и начинают спорить.
|
||||
|
||||
**Документы проекта — не твои**: их язык вычитывает `doc-wording`. Ты их
|
||||
читаешь, но только как словарь — по ним проверяется, известен ли термин.
|
||||
|
||||
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
|
||||
которую зовущий подставит командой (`edit <слаг> --title …`, `edit <слаг>
|
||||
--why …`) или впишет редактором. Файлы ты только читаешь.
|
||||
|
||||
## Что тебе дают
|
||||
|
||||
Список записей или каталог задач: файлы `items/<slug>.md`, а с ними — индексы
|
||||
(`BACKLOG.md`, `ROADMAP.md`, `REJECTED.md`), где та же запись представлена
|
||||
строкой. **Строка индекса вычитывается наравне с файлом**: по ней запись
|
||||
выбирают, не открывая тела, и «зачем» в ней повторяется дословно.
|
||||
|
||||
Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура,
|
||||
конвенции: по ним проверяется, известен ли термин. **Не назвали — считай
|
||||
известными только те слова, что встречаются в других поданных записях**, и
|
||||
говори об этом в границах покрытия.
|
||||
|
||||
## Правила
|
||||
|
||||
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
|
||||
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
|
||||
|
||||
<!-- копия: язык-правила из shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
### Что из этих правил докладывается особым образом
|
||||
|
||||
**Правило 4, поля меты.** «Зачем» по формату — одно предложение, потому что
|
||||
повторяется строкой индекса. Предложить разбить его надвое — находка **против**
|
||||
формата, а не по нему; тесно — предлагай сокращение.
|
||||
|
||||
**Правило 8, неизвестный термин.** Своей догадки не подставляй — ты не знаешь
|
||||
предметную область. Пиши «термин «X» не встречается ни в документах, ни в других
|
||||
поданных записях — введи строкой или назови известным словом». Свой словарь у
|
||||
отдельной задачи — самый дешёвый способ сделать беклог нечитаемым тому, кто
|
||||
вернётся к нему через квартал.
|
||||
|
||||
**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py` —
|
||||
про них молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и
|
||||
ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовый
|
||||
английский слаг на замену плюс напоминание, что переименование это перенос
|
||||
ссылок одним проходом, а не правка одного файла.
|
||||
|
||||
## Чего ты не проверяешь
|
||||
|
||||
Не своё бывает двух разных родов, и поступают с ними по-разному.
|
||||
|
||||
**Чужому подрядчику — строкой в границах покрытия.** Форма записи у `task-form`;
|
||||
язык документов проекта у `doc-wording`; их согласованность между собой у
|
||||
`doc-consistency`, соответствие коду у `doc-code-drift` — до записей эти двое не
|
||||
доходят вовсе, но если ты открыл документ как словарь и увидел расхождение в нём
|
||||
самом, оно их. Увидел — назови в конце одной строкой, чтобы находка не пропала,
|
||||
но находкой не оформляй.
|
||||
|
||||
**Машинной проверке — вообще ничего.** Всё, что ловит `tasks.py check` (состав и
|
||||
написание секций, наличие разделов своего типа, число критериев, теги, тег
|
||||
`question` при непустом разделе «Вопросы», согласованность файлов с индексами,
|
||||
битые ссылки), **не пиши даже строкой**: это не потерянная находка, а уже
|
||||
проверенное. Повторять машинную проверку словами — заводить второй дом для
|
||||
одного правила.
|
||||
|
||||
**Содержание работы**: нужна ли задача, верно ли выбрана цель, не крупна ли она,
|
||||
достаточна ли декомпозиция. Это разбор, и его ведёт человек со скиллом `tasks`.
|
||||
|
||||
**Полезное действие, параллельность и работающий заголовок** — тоже не твои.
|
||||
Они в доктрине языка, судит их человек: находка по ним требует увидеть текст
|
||||
целиком, а не фразу.
|
||||
|
||||
## Порог вмешательства
|
||||
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
Одна запись может дать несколько находок, но каждое место правится один раз: не
|
||||
предлагай два варианта на выбор, предлагай лучший.
|
||||
|
||||
## Доклад
|
||||
|
||||
<!-- копия: вычитка-доклад из shared/language.md -->
|
||||
|
||||
Находки по одной, в порядке важности: залог и оценки → жаргон и англицизмы →
|
||||
стоп-слова. Первые меняют, **что** читатель понимает; последние — только сколько
|
||||
он на это тратит.
|
||||
|
||||
```
|
||||
<файл>
|
||||
правило: <номер и короткое имя>
|
||||
сейчас: <как написано>
|
||||
предложение: <готовая формулировка, подставляемая как есть>
|
||||
почему: <одна фраза>
|
||||
```
|
||||
|
||||
В конце — **границы покрытия**: сколько файлов просмотрено из скольких, какие не
|
||||
смотрел и почему, и по чему проверялись термины (документы проекта названы или
|
||||
нет). Отчёт без этой строки читается как «всё вычитано», не сообщая, какая часть
|
||||
осталась нетронутой. Туда же — строка «замечено не по моей части»; машинно
|
||||
проверяемое в неё **не идёт**.
|
||||
|
||||
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
|
||||
полезнее выдуманной находки.
|
||||
|
||||
<!-- /копия: вычитка-доклад -->
|
||||
|
||||
**Находку в заголовке или в «зачем» отмечай особо.** По ним запись выбирают, и
|
||||
подставляются они командой, а не редактором: зовущий обязан показать
|
||||
предложенное человеку вместе с тем, что было. Прочие правки в теле применяются
|
||||
сразу.
|
||||
@@ -0,0 +1,304 @@
|
||||
---
|
||||
name: session
|
||||
description: "Ритуал между спринтами и ведение самого спринта: разбор накопившихся вопросов, разбор прошедшего спринта про процесс, переоценка задач порциями, выбор цели (или решение, что спринт без цели) и набор нового спринта с заморозкой. Плюс правила по ходу спринта — что врывается в замороженный набор, чем вопрос отличается от блокера, когда задача выходит из спринта, что считается сделанным и что идёт в доклад. Использовать, когда просят закрыть или начать спринт, собрать набор, разобрать вопросы, провести груминг/переоценку/ретроспективу, решить «что делать дальше» или доложить итоги, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое задач — скилл tasks."
|
||||
---
|
||||
|
||||
# Сессия между спринтами
|
||||
|
||||
Работа идёт спринтами: **набор задач, замороженный до конца спринта** — обычно
|
||||
под одну цель, но бывает и без неё. Между спринтами — одна сессия из четырёх шагов. Этот скилл владеет
|
||||
**ритуалом**: как сессия проводится и как спринт ведётся. Форматом и содержимым
|
||||
задач владеет скилл `tasks`, выполнением задачи — пайплайн проекта.
|
||||
|
||||
## Почему не Scrum
|
||||
|
||||
Терминология близка — спринт, груминг, определение готовности, ретроспектива, —
|
||||
и это удобно: не нужно изобретать слова. Но добрая половина Scrum существует
|
||||
ради синхронизации людей, которых здесь нет.
|
||||
|
||||
**Не берём:** тайм-бокс (спринт ограничен объёмом, а не временем), velocity и
|
||||
оценки в очках, ежедневный стендап (стендап — это и есть диалог), планирование
|
||||
отдельно от груминга (владелец беклога один), роль скрам-мастера.
|
||||
|
||||
**Берём:** цель спринта, заморозку набора, определение готовности, груминг —
|
||||
каждое потому, что снимает решение, которое иначе принимается заново каждый раз.
|
||||
**Ретроспективу берём содержанием, но не отдельным ритуалом:** она шаг той же
|
||||
сессии. Процесс личный, синхронизировать некого, а отдельная встреча ради трёх
|
||||
вопросов — та самая плата ритуалом без выгоды.
|
||||
|
||||
## Роли
|
||||
|
||||
**Человек** выбирает цель спринта — **или решает, что этот спринт без цели**, —
|
||||
разбирает вопросы, держит право на необратимое и на истину в самих данных.
|
||||
|
||||
**Агент — оркестрация.** Он собирает набор под названную цель, ставит задачи,
|
||||
принимает отчёты и докладывает. Кто именно делает задачу — исполнитель, сабагент,
|
||||
пайплайн — дело проекта; сессия про это не знает и знать не должна.
|
||||
|
||||
## Единицы
|
||||
|
||||
- **Цель** — то, ради чего набирается спринт. Файл типа `goal` (🎯),
|
||||
перечисленный в `ROADMAP.md`. Цель постоянна: живёт, пока живёт направление, —
|
||||
и уходит вместе с ним, если замысел оказался неверен (порядок отмены — в
|
||||
[tasks](../tasks/references/task-goal.md#отменённая-цель--сперва-задачи-потом-цель)).
|
||||
- **Задача** — то, что мерджится целиком и даёт видимую пользу.
|
||||
- **Вопрос** — решение человека. Не останавливает начатую работу, но **блокирует
|
||||
взятие** задачи в спринт. Живёт внутри файла задачи разделом «Вопросы» и тегом
|
||||
`question`.
|
||||
- **Блокер** — состояние, когда спринт не может продолжаться **ни одной**
|
||||
задачей.
|
||||
- **Спринт** — набор задач, замороженный до его конца. Под одной целью — или
|
||||
**без цели вовсе**, законно: багфикс, техдолг, спринт здоровья. Такой набор
|
||||
собран по работоспособности, а не по направлению, и заводится явно
|
||||
(`sprint start --no-goal`).
|
||||
|
||||
## Вопрос, блокер, необратимое
|
||||
|
||||
| | Что это | Когда спрашиваем | Что останавливает |
|
||||
| --- | --- | --- | --- |
|
||||
| **Вопрос** | решение человека | на сессии, пачкой | взятие задачи в спринт |
|
||||
| **Блокер** | спринт не может продолжаться ни одной задачей | немедленно | всё |
|
||||
|
||||
Право на **необратимое** — третье и отдельное: что именно необратимо, называет
|
||||
`CLAUDE.md` проекта, и спрашивается оно всегда, независимо от спринта.
|
||||
|
||||
**Блокер определяется исходом, а не одновременностью.** Встали разом или
|
||||
высыпались из спринта по одной — если продолжать нечем, это блокер: спринт
|
||||
распускается (`sprint close --dissolve --reason …`), человек спрашивается
|
||||
немедленно. Иначе спринт, из которого задачи вышли поштучно, выглядел бы штатно
|
||||
завершённым, а вопросы тихо ждали бы сессии.
|
||||
|
||||
**Отличать вопрос от застревания.** Правило про остаток принадлежит управлению
|
||||
задачами: оно решает, **сделана задача или вышла**, а это исход планирования, не
|
||||
исполнения. **Ниже канонический текст; пайплайн проекта на него ссылается, а не
|
||||
пересказывает** — два экземпляра одного правила разъезжаются, и разъезжаются
|
||||
незаметно, потому что расхождение видно только на редком входе.
|
||||
|
||||
> Есть остаток, который доводится без ответа, — задача продолжается, вопрос
|
||||
> записывается в файл. Остатка нет — задача выходит из спринта.
|
||||
|
||||
С двумя оговорками, без которых тест ошибается:
|
||||
|
||||
> **Остаток, который материализует нерешённое** — записывает в хранилище,
|
||||
> журнал, витрину **или наружу** состояние, зависящее от неотвеченного вопроса,
|
||||
> — **не остаток**. Решение поднимается до начала записи: откатить запись
|
||||
> дороже, чем подождать ответ, а иногда невозможно. «Наружу» — часть правила, а
|
||||
> не пример: выкладка, публикация и отправка данных третьей стороне не
|
||||
> откатываются тем более.
|
||||
|
||||
> **Пол для остатка:** остаток, из которого пропала польза, названная в «зачем», —
|
||||
> это не сделанная задача, а вышедшая из спринта.
|
||||
|
||||
## Заморозка набора
|
||||
|
||||
**Целей не больше одной.** Названа цель — набор служит ей: задача под чужой
|
||||
целью в спринт не попадает, даже если взять удобно (`sprint take` это и
|
||||
запрещает). **Задача с открытым вопросом в набор не берётся** — это верно всегда.
|
||||
|
||||
**Спринт без цели — законный случай, а не недосмотр.** Багфикс, техдолг,
|
||||
здоровье: работа на работоспособность, а не на направление. Цель не названа —
|
||||
сверять нечего, и в такой набор идёт что угодно готовое к взятию, в том числе
|
||||
задачи под разными целями. Заводится он **явно**, `sprint start --no-goal`:
|
||||
забытый флаг и решение человека иначе неотличимы, а это решение продуктовое.
|
||||
Взамен проверки цели остаётся доклад — спринт без цели **называется таковым и
|
||||
объясняется** одной строкой.
|
||||
|
||||
**Новая работа падает в беклог, а не в идущий спринт.** Решение «врываться или
|
||||
отложить» принимается один раз правилом, а не заново каждый раз. Врывается
|
||||
только два класса:
|
||||
|
||||
1. **Необратимый ущерб** — потеря, порча или утечка данных: то, что не чинится
|
||||
доделкой потом.
|
||||
2. **Сломан общий станок** — красная проверка, на которой стоит определение
|
||||
готовности **всех** задач набора. Это не новая работа, а починка того, на чём
|
||||
делается вся остальная.
|
||||
|
||||
Что в проекте считается необратимым ущербом и что — общим станком, называет
|
||||
`CLAUDE.md` проекта. Не названо — спрашиваем человека, а не решаем сами.
|
||||
|
||||
**Конец спринта** — когда каждая задача набора либо сделана, либо вышла с
|
||||
записанной причиной. Не «все сделаны»: иначе одна застрявшая задача держит
|
||||
спринт бесконечно. Пустой набор закрывается `sprint close` — скрипт не даст
|
||||
закрыть непустой.
|
||||
|
||||
Ведение спринта целиком — исходы задачи, определение готовности, приёмка,
|
||||
доклад — [references/sprint.md](references/sprint.md).
|
||||
|
||||
## Сессия: четыре шага в этом порядке
|
||||
|
||||
Это зависимость, а не список.
|
||||
|
||||
1. **Разбор вопросов.**
|
||||
2. **Разбор прошедшего спринта — про процесс, а не про задачи.** Здесь же оба
|
||||
судьи документов канона на весь канон разом, раз в спринт: `doc-consistency`
|
||||
(документы между собой) и `doc-code-drift` (документы против кода).
|
||||
3. **Переоценка задач** порциями.
|
||||
4. **Выбор цели и набор спринта.** Цель называет человек — либо называет, что
|
||||
этот спринт без цели; набор собирает агент и показывает **до старта работ**.
|
||||
|
||||
Рёбра подписаны тем, что ломается при их нарушении:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
check["tasks.py check (+ --fix)<br/>результат — строкой в доклад"]
|
||||
s1["1. Разбор вопросов<br/>пачкой, не больше трёх за раз"]
|
||||
s2["2. Разбор прошедшего спринта<br/>про процесс → docs/review.md"]
|
||||
s3["3. Переоценка задач порциями"]
|
||||
s4["4. Цель называет человек,<br/>набор собирает агент"]
|
||||
sprint["спринт: набор заморожен"]
|
||||
|
||||
check --> s1
|
||||
s1 --> s2
|
||||
s2 --> s3
|
||||
s1 -->|"неотвеченный вопрос → переоценка вслепую"| s3
|
||||
s3 -->|"без переоценки набор берётся из протухшего"| s4
|
||||
s4 --> sprint
|
||||
```
|
||||
|
||||
Схема — **сводка**: процедура каждого шага в
|
||||
[references/cadence.md](references/cadence.md), и при расхождении прав текст.
|
||||
|
||||
## Вернулся, а спринт открыт
|
||||
|
||||
Сессия — ритуал **между** спринтами, и шаг 1 предполагает только что закрытый.
|
||||
Вход после перерыва другой, и начинается он не с шага, а с вопроса, свой ли ещё
|
||||
набор:
|
||||
|
||||
1. `tasks.py check` — блок здоровья скажет состояние спринта, число готовых к
|
||||
взятию и залежавшихся; при расхождении раскладки `--fix`.
|
||||
2. Прочитать `SPRINT.md`: цель (или запись, что её нет), состав, дата начала.
|
||||
3. **Развилка, и решает её человек.** Набор всё ещё твой — продолжай спринт, ни
|
||||
сессии, ни переоценки не нужно, они между спринтами. Взялся перечитывать,
|
||||
зачем эти задачи собраны вместе, — набор протух:
|
||||
`sprint close --dissolve --reason …`, недоделанное возвращается в беклог,
|
||||
дальше обычная сессия с шага 1.
|
||||
|
||||
Порога в неделях нет намеренно — почему, в
|
||||
[references/sprint.md](references/sprint.md), «Протухший набор».
|
||||
Середины у развилки тоже нет: «доделаю пару штук и решу» — это работа по набору,
|
||||
которого ты уже не понимаешь.
|
||||
|
||||
Процедура каждого шага, размер и отбор порции, храповик на залежавшихся, формат
|
||||
интерактива и доклад — [references/cadence.md](references/cadence.md).
|
||||
|
||||
## Инструмент
|
||||
|
||||
Тот же `tasks.py`, что у скилла `tasks` — оба скилла в одном плагине, путь
|
||||
общий: `tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"`. Сессии нужны
|
||||
прежде всего:
|
||||
|
||||
```
|
||||
python3 $tk check --dir D # с этого начинается любая сессия
|
||||
python3 $tk list --dir D --questions # шаг 1: что накопилось
|
||||
python3 $tk list --dir D --tag sprint:<слаг> # шаг 3: урожай спринта, первая порция
|
||||
python3 $tk list --dir D --stale # шаг 3: дальше по залежалости
|
||||
python3 $tk list --dir D --goal <слаг> # шаг 4: кандидаты под названную цель
|
||||
python3 $tk sprint start --dir D --goal <слаг> # шаг 4: заводит и слаг спринта
|
||||
python3 $tk sprint start --dir D --no-goal # шаг 4: набор без цели, явным флагом
|
||||
python3 $tk sprint take --dir D <слаг> … # шаг 4: набор
|
||||
python3 $tk sprint close --dir D # конец спринта; --dissolve при блокере
|
||||
python3 $tk reopen <слаг> --dir D --reason … # приёмка не сошлась после закрытия
|
||||
```
|
||||
|
||||
`D` — каталог задач проекта, по канону всегда `docs/tasks`; `--dir` передаётся
|
||||
явно каждой командой. Вызов из чужого контекста описан в скилле `tasks`
|
||||
(«Переносимость»). **Коды выхода** — там же: 1 это дрейф в беклоге, 3 это
|
||||
«каталога нет», и ветвиться на них надо по-разному.
|
||||
|
||||
**Слаг спринта заводит `sprint start`** (по умолчанию — дата) и пишет его в
|
||||
`SPRINT.md`; всё заведённое **при открытом спринте** помечается `sprint:<слаг>`
|
||||
автоматически. Поэтому «первая порция — урожай прошедшего спринта» работает без
|
||||
чьей-либо памяти — но ровно до команды `sprint close`, которая `SPRINT.md`
|
||||
очищает. Отсюда порядок: **урожай заводится до закрытия, слаг для сессии берётся
|
||||
из отчёта `sprint close`** ([references/sprint.md](references/sprint.md)).
|
||||
|
||||
Правки задач делаются мутациями (`edit`, `move`, `close`), а не редактором:
|
||||
руками правится только тело файла. Это правило скилла `tasks`, здесь оно не
|
||||
пересказывается.
|
||||
|
||||
## Стимулы, которые процесс создаёт
|
||||
|
||||
Правило, которое можно обойти в свою пользу, будет обойдено.
|
||||
|
||||
**Приёмщик и исполнитель здесь совпадают, и это надо назвать вслух.** Задачу
|
||||
закрывает и двигает по индексам агент-оркестратор — тот же, кто её и сделал.
|
||||
Прежде границу держала механика: моста между плагинами не было, и закрыть задачу
|
||||
пайплайн физически не мог. Теперь мост есть, и защита у трёх обходов ниже —
|
||||
**только текстовая**. Опоры, которые остались настоящими:
|
||||
|
||||
- **независимый отчёт ревью** — артефакт, написанный не исполнителем; по нему
|
||||
сверяют состав прогона и урожай. Где он лежит, знает пайплайн проекта; при
|
||||
конвейере `av-dev-pipeline` это отчёт триажа в
|
||||
`openspec/changes/archive/<id>/review/` (до архивации — `changes/<id>/review/`);
|
||||
- **`SPRINT.md` под git** — `git log -p` показывает, что и когда было закрыто.
|
||||
Работает, только если закрытие **закоммичено**: удаление файла задачи и правка
|
||||
индекса, оставшиеся в рабочем дереве, никакой истории не образуют;
|
||||
- **`reopen <слаг> --reason`** — закрытие не окончательно. Приёмка человеком на
|
||||
сессии его отменяет, и это штатная операция, а не скандал.
|
||||
|
||||
Известные обходы:
|
||||
|
||||
- **Скрыть блокер** — он останавливает всё и выглядит как провал исполнителя.
|
||||
Защита: тест про остаток плюс прямая запись, что **объявление блокера
|
||||
неудачей не считается**.
|
||||
- **Не записать вопрос** на задаче-кандидате, чтобы не вычеркнуть её из
|
||||
ближайшего набора. Защита: вопросы кандидатов разбираются на той же сессии
|
||||
**вне очереди порции**.
|
||||
- **Занизить критерии приёмки**, раз они пол. Защита ослаблена: правит их тот же,
|
||||
кто по ним отчитывается. Остаётся требование, что расхождение критериев с
|
||||
сутью — **дефект критериев, о котором сообщают, а не молча дорабатывают**, и
|
||||
переоценка на сессии, где критерии видит человек.
|
||||
- **Сжать задачу до остатка** и отчитаться «сделана». Защита ослаблена там же.
|
||||
Пол для остатка — польза, названная в «зачем»; проверяет его человек при приёмке,
|
||||
и `reopen` — его инструмент.
|
||||
- **Объявить спринт без цели**, чтобы не задавать человеку продуктовый вопрос:
|
||||
набор без цели берёт что угодно, и собрать его можно молча. Защита: цели нет
|
||||
— это **ответ человека, а не умолчание** (`--no-goal` спрашивается так же, как
|
||||
цель), плюс строка доклада, называющая спринт бесцельным и объясняющая почему.
|
||||
Два бесцельных спринта подряд — предмет разбора процесса, а не мелочь.
|
||||
- **Занизить урожай** — не заводить найденное по ходу. Защита: поимённая сверка
|
||||
с **сохранённым независимым отчётом**, а не с прозой исполнителя. Каждая
|
||||
отложенная находка имеет либо слаг, либо строку «не заведена: причина».
|
||||
Нулевой урожай при непустом отчёте виден сразу.
|
||||
|
||||
**Проект без конвейера ревью — независимого отчёта нет, и это надо сказать, а не
|
||||
обойти молча.** Задачи делались руками или чужим пайплайном, сверять урожай не с
|
||||
чем: остаётся проза исполнителя, то есть тот же взгляд, что и у автора. Тогда
|
||||
защита от занижения урожая **снята**, и доклад спринта обязан нести строку «урожай
|
||||
сверялся с отчётом исполнителя — независимого отчёта в проекте нет». Дальше это
|
||||
решение человека: завести конвейер, принимать выборочной перепроверкой или
|
||||
согласиться с ценой. Молчание здесь хуже любого из трёх исходов.
|
||||
|
||||
Стимулы внутри пайплайна задачи (занизить требования к проверке, пропустить
|
||||
проход) принадлежат ему и защищены там же.
|
||||
|
||||
## Слоты проекта
|
||||
|
||||
Сессия не знает ни языка, ни сборки, ни CI. На часть проектного отвечает своей
|
||||
структурой канон документов (его ведёт плагин `av-dev-docs`): разбор процесса
|
||||
(шаг 2) живёт в `docs/review.md`, оракулы и «чем краснеет безусловно» — в
|
||||
семантике гейта в `CLAUDE.md`. Пути известны, ссылки в чужое дерево нет: канон
|
||||
ставится отдельно, а без него оба файла всё равно читаются по имени. Остальное проект **дописывает в `CLAUDE.md`**:
|
||||
|
||||
1. **Пайплайн задачи** — чем задача выполняется и что входит в его определение
|
||||
готовности. Сессия требует только форму: пайплайн пройден + критерии приёмки
|
||||
проверены поимённо.
|
||||
2. **Общий станок** — какая проверка, покраснев, врывается в замороженный
|
||||
спринт.
|
||||
3. **Необратимое** — что спрашивается у человека всегда (тот же слот, что у
|
||||
скилла `tasks`; дом один).
|
||||
4. **Ориентир по размеру спринта**, если он замерялся. Умолчание — 5–8 задач, и
|
||||
это **ориентир, а не закон**.
|
||||
|
||||
Слота «куда копируются критерии приёмки» здесь нет намеренно: на него отвечает
|
||||
**пайплайн проекта** — он переносит критерии в описание изменения, когда его
|
||||
заводит. Проект без пайплайна называет своё место сам, в слоте 1.
|
||||
|
||||
Числа проекта (сколько задач в спринте, сколько времени на задачу, каков прирост
|
||||
беклога) — предмет шага 2, а не константы этого скилла.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
Не пишет код и не выполняет задачи. Не заводит и не переоформляет задачи сам по
|
||||
себе — формат и содержимое ведёт `tasks` (сессия зовёт его операции). Не решает
|
||||
за человека, какая цель следующая. Не двигает набор идущего спринта.
|
||||
@@ -0,0 +1,277 @@
|
||||
# Сессия: четыре шага
|
||||
|
||||
Одна сессия между спринтами. Порядок шагов — **зависимость, а не список**:
|
||||
переоценивать задачи, не разобрав вопросы, значит переоценивать вслепую; набирать
|
||||
спринт, не переоценив, значит набирать из протухшего.
|
||||
|
||||
Начинается сессия с `tasks.py check` (и `check --fix`, если дрейф накопился) —
|
||||
результат идёт строкой в доклад.
|
||||
|
||||
## Шаг 1. Разбор вопросов
|
||||
|
||||
`tasks.py list --questions` — всё, что накопилось. Вопрос это решение человека,
|
||||
и разбирается он **пачкой**, а не по одному, как только возник: по одному —
|
||||
это дёрганье, пачкой — это сессия.
|
||||
|
||||
Порядок по каждому вопросу:
|
||||
|
||||
1. **Проверь, не отвечен ли он уже** — решением, документом, соседним
|
||||
изменением, самим ходом прошедшего спринта. Отвеченный вопрос не выносится
|
||||
человеку: это самая частая находка и она не требует ничьего решения.
|
||||
2. **Сформулируй развилку** с вариантами и последствием каждого, рекомендация —
|
||||
первым вариантом.
|
||||
3. **Вынеси пачкой** через `AskUserQuestion`, не больше трёх за раз.
|
||||
4. **Запиши ответ в тело задачи, опустоши раздел «Вопросы»**, сними тег
|
||||
(`edit <slug> --rm-tag question`), **перепиши «зачем»**: «Решено:
|
||||
…» на вопрос «почему это лежит в беклоге» уже не отвечает. Опустошение
|
||||
раздела — не уборка, а условие взятия: правило и причина в скилле `tasks`,
|
||||
[references/task-format.md](../../tasks/references/task-format.md).
|
||||
|
||||
**Вопросы на задачах-кандидатах разбираются вне очереди порции** — здесь же, на
|
||||
этой сессии, даже если сама задача в порцию переоценки не попала. Иначе правило
|
||||
«задача с открытым вопросом в набор не берётся» создаёт стимул вопрос не
|
||||
записывать, лишь бы не вычеркнуть задачу из ближайшего спринта.
|
||||
|
||||
## Шаг 2. Разбор прошедшего спринта — про процесс, а не про задачи
|
||||
|
||||
Не «что мы сделали» (это доклад спринта, он уже был), а:
|
||||
|
||||
- **что сломалось в процессе и почему не поймали** — промах, доехавший до конца;
|
||||
- **что оказалось дороже, чем выглядело при заведении** — не число, а сам факт и
|
||||
причина: чего не было видно в постановке;
|
||||
- **какие правила не сработали или сработали не так** — в том числе правила
|
||||
этого плагина.
|
||||
|
||||
Замеров процесс не ведёт намеренно: оценки в очках и velocity не взяты
|
||||
(«[Почему не Scrum](../SKILL.md#почему-не-scrum)»), а спринт ограничен объёмом, а
|
||||
не временем — сравнивать «сколько заняло» не с чем. Разбор здесь качественный, и
|
||||
это не упущение.
|
||||
|
||||
**Артефакт обязателен.** Вывод, оставшийся в контексте сессии, не существует:
|
||||
следующая сессия его не увидит. Дом у него один и известен из канона —
|
||||
**`docs/review.md`**: вывод про конвейер и про то, что перестали проверять, идёт
|
||||
в раздел настройки, вывод про воспроизведённый дефект — в журнал. Решение с
|
||||
долгим следом — в `docs/adr/`.
|
||||
|
||||
Отдельным ритуалом ретроспектива не выделяется: процесс личный,
|
||||
синхронизировать некого.
|
||||
|
||||
**Здесь же зовутся оба судьи документов** — на весь канон разом, а не на пачку,
|
||||
отобранную работой:
|
||||
|
||||
- **`doc-consistency`** — согласованность документов между собой и с openspec:
|
||||
факт в двух домах, прямое противоречие, поведение в `architecture.md` вместо
|
||||
спек, ADR без парного статуса при замене, число без провенанса;
|
||||
- **`doc-code-drift`** — сверка с кодом по закрытому перечню фактов: имя основной
|
||||
ветки, команды, пути, внешние зависимости поимённо, настройки с числовым
|
||||
значением, единые точки проекта, capability.
|
||||
|
||||
Раз в спринт, а не чаще. Дорог из них по-настоящему первый — `doc-consistency`
|
||||
на `opus`: он сличает утверждения двух документов, и это суждение. Второй с
|
||||
недавних пор на `sonnet` — у него закрытый перечень фактов и команда на каждый, —
|
||||
но он читает репозиторий целиком, и дешёвым от смены модели не стал. Но и не
|
||||
реже — **спринт это ровно то, что двигает код и документы**:
|
||||
переименованная цель сборки, ушедшая зависимость, второй способ делать то, что
|
||||
обзор объявил единственным; факт, дописанный в `architecture.md`, уже живущий в
|
||||
`CLAUDE.md`. Протухшее и раздвоившееся неотличимо от свежего, и по нему принимают
|
||||
решения, пока кто-нибудь не наткнётся.
|
||||
|
||||
**Пачка — весь канон, и это не расточительство, а охват.** Когда пачку отбирала
|
||||
работа, без присмотра оставалось ровно то, чего работа не касалась: правка,
|
||||
отменившая решение, живёт в одном документе, а парный статус нужен в другом.
|
||||
Канон мал, раз в спринт он читается целиком.
|
||||
|
||||
Находки обоих — обычный материал переоценки: строка на замену идёт в документ
|
||||
сразу, работа больше чем на абзац становится задачей типа `chore`. **Позвал —
|
||||
скажи в докладе, кого именно позвал, и приложи границы покрытия**; не позвал —
|
||||
скажи и это, иначе доклад читается как «сверено».
|
||||
|
||||
## Шаг 3. Переоценка задач
|
||||
|
||||
Цель — выкинуть то, что перестало быть задачей, и вернуть остальному честное
|
||||
состояние. Не «пересмотреть всё», а «пересмотреть порцию до конца».
|
||||
|
||||
### Порция и правило остановки
|
||||
|
||||
Тридцать задач за один заход — это усталость и штамповка: последние десять
|
||||
получат «оставить» не потому, что живы, а потому, что сессия затянулась.
|
||||
|
||||
- **5–8 задач за порцию.** Размер обоснован усталостью, а не пропускной
|
||||
способностью, и менять его не надо — **надо брать несколько порций за
|
||||
сессию**.
|
||||
- **Сколько порций:** не меньше `⌈урожай прошедшего спринта / 8⌉`. Урожай — это
|
||||
задачи, заведённые за спринт; при урожае в 15 это две-три порции.
|
||||
- **Отбор порций по порядку:**
|
||||
1. **урожай спринта** — `list --tag sprint:<слаг>`: свежезаведённое ещё не
|
||||
проходило ни одной проверки на нужность. Тег на задачах проставлен
|
||||
автоматически при заведении — руками не метят и не вспоминают. **Слаг
|
||||
берётся из отчёта `sprint close`, а не из `SPRINT.md`:** сессия идёт после
|
||||
закрытия, а закрытие этот файл очищает;
|
||||
2. дальше **по залежалости** — `list --stale`;
|
||||
3. по потребности — одна секция целиком, один тег (партия ревью), одна цель
|
||||
(`--goal`), список от пользователя.
|
||||
- **Останавливайся на границе порции**, даже если «ещё чуть-чуть осталось».
|
||||
Между порциями — промежуточный доклад.
|
||||
|
||||
### Что делать с каждой задачей
|
||||
|
||||
Сперва то, что не требует ничьего решения:
|
||||
|
||||
1. **Проверь, не сделано ли уже.** Задача, реализованная попутно в соседнем
|
||||
изменении, — самая частая находка. Смотри код, документацию, историю коммитов
|
||||
по ключевым словам. Удаление «как реализованной» деструктивно и без следа
|
||||
(в `REJECTED.md` реализованные не пишутся), поэтому порог улики жёсткий:
|
||||
`close <slug> --implemented` только имея **конкретный коммит или строку
|
||||
документа**, закрывающие задачу, и ссылка идёт в доклад. Есть лишь косвенные
|
||||
признаки — не удаляй сам, вынеси в пачку вопросов. Сделана частично → задача
|
||||
сжимается до остатка: тело правишь редактором, заголовок и «зачем» — через
|
||||
`edit`.
|
||||
2. **Проверь, не отменена ли решением.** Документ, ADR или архивное изменение
|
||||
мог закрыть вопрос иначе — тогда `close <slug> --reason "<ссылка на
|
||||
решение>"`. Задача закрывается не только коммитом.
|
||||
3. **Проверь пересечения.** Две задачи об одном — содержимое в одну, вторую
|
||||
`close <slug> --reason "слита с <другой-слаг>"`. Смотри **шире порции**:
|
||||
интейк дедуплицирует новое против существующего, но никогда не
|
||||
пересматривает уже лежащее, и две задачи с одной причиной могут лежать рядом
|
||||
месяцами.
|
||||
4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами
|
||||
одного дефекта, сливаются в одну — это находка, которую интейк дать не мог.
|
||||
5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство
|
||||
репозитория в рамках, предписание процесса в теле, тип, разошедшийся с
|
||||
задачей, границы вместо реализации в разделе «Затрагивает». Список и правила —
|
||||
в скилле `tasks`. **Переоценка — то самое место, где беклог добирает тип и
|
||||
разделы его схемы:** требовать их на входе значило бы выгонять в заметки то,
|
||||
что должно лежать задачей, а к взятию в спринт они уже обязательны. Блок
|
||||
здоровья `check` печатает, сколько записей готово к взятию, — по этому числу
|
||||
и видно, добрала переоценка или нет.
|
||||
|
||||
Затем — то, что решает пользователь:
|
||||
|
||||
6. **Жива ли она вообще.** Контекст мог измениться: ушла зависимость, отпал
|
||||
сценарий, обошли иначе. Здесь и звучит вопрос, выкидывать ли.
|
||||
7. **Та ли цель — и нужна ли она вообще.** Приоритетов нет, и «повысить» нечего
|
||||
— вместо повышения задача **меняет цель** (`edit <slug> --goal <другой>`) или
|
||||
входит в ближайший набор. `feature`, которой не находится цель, — кандидат
|
||||
на выход: новая возможность вне цели это возможность, которой никто не
|
||||
заказывал. Операционной задаче (`fix`, `chore`, `research`) цель не нужна, и
|
||||
выдумывать её здесь не надо.
|
||||
|
||||
**Отменяется и сама цель** — когда замысел оказался неверен, а не когда
|
||||
задача выбрала не ту. Тогда порция расширяется до всех задач этой цели: каждую
|
||||
либо закрыть своей причиной, либо перевесить на другую цель, и только потом
|
||||
закрыть цель. Порядок и почему он такой —
|
||||
[task-goal.md](../../tasks/references/task-goal.md#отменённая-цель--сперва-задачи-потом-цель).
|
||||
Здесь этому и место: отмена цели это разбор её задач, а разбор задач — этот
|
||||
шаг.
|
||||
8. **Задача ли это по-прежнему.** Не проходит тест «готова к взятию» → `edit
|
||||
<slug> --type research` и опустошённый раздел «Вопрос», то есть сырьё; дальше
|
||||
штурм. Разрослась → это несколько задач под той же целью, дальше
|
||||
декомпозиция.
|
||||
9. **Переоценка по пройденному.** Прошедший спринт показывает, чего на самом
|
||||
деле стоит такая работа. Это меняет цену **других** задач, и именно здесь
|
||||
применяется: задача, оказавшаяся заметно дороже, чем думалось, при прежней
|
||||
пользе — кандидат на выход. Судит человек по тому, что помнит о прошедшем
|
||||
спринте; замеров процесс не ведёт и оценок не хранит.
|
||||
|
||||
### Храповик на залежавшихся
|
||||
|
||||
Сильно залежавшаяся задача — сигнал сама по себе: её либо ни разу не собирались
|
||||
делать, либо нечем взять. Измеряй наблюдаемым — датой последней правки из git
|
||||
(`list --stale` ставит такие первыми); счётчик «сколько сессий пережила» нигде
|
||||
не хранится.
|
||||
|
||||
Задача из верхних строк `--stale`, которую и этот заход оставляет без изменений,
|
||||
**либо двигается (меняет цель, идёт в набор, уходит с причиной), либо остаётся с
|
||||
явно записанной причиной**, почему её держим (`move <slug> --section <та же>
|
||||
--reason …`). Молчаливое «оставить как есть» на давно неподвижной задаче — это
|
||||
решение не принимать решение; запись причины превращает его в осознанное и не
|
||||
даёт тому же вопросу всплыть на следующей сессии.
|
||||
|
||||
### Интерактив
|
||||
|
||||
- Вопросы — через `AskUserQuestion`, **не больше трёх за раз**. Порция в 5–8
|
||||
задач обычно даёт больше трёх суждений — тогда веди несколько итераций по ≤3,
|
||||
а не по одному на задачу и не одним перегруженным запросом.
|
||||
- К каждому варианту — **предварительное суждение, рекомендация первым
|
||||
вариантом**: «предлагаю выкинуть, потому что …». Пользователю дешевле
|
||||
возразить, чем судить с нуля.
|
||||
- Всё, что решается фактом (сделано / отменено / дублируется), решай сам и
|
||||
показывай списком в докладе, а не выноси в вопросы.
|
||||
|
||||
Пример одной итерации — три залежавшихся задачи, механику по ним уже разобрали:
|
||||
|
||||
> **Переоценка: 3 залежавшихся (порция по `--stale`)**
|
||||
>
|
||||
> 1. `versii-kachestvo-repaki` — версии и качество одного тайтла
|
||||
> - Выкинуть *(рекомендую)* — помечена «не боль», за полгода ни разу не возникла
|
||||
> - Оставить под целью `nadyozhnost-razdach`
|
||||
> - Перевести под цель `kachestvo-mediateki` — там она первая в очереди
|
||||
> 2. `backup-sqlite` — бэкап базы
|
||||
> - Оставить под текущей целью *(рекомендую)* — не сработала, но риск реальный
|
||||
> - Взять в ближайший набор — без бэкапа ретеншн опасен
|
||||
> - Выкинуть
|
||||
> 3. `guessit-sputnik` — вынести распознавание в сервис-спутник
|
||||
> - Понизить до сырья (`--type research`) *(рекомендую)* — не проходит тест «готова к взятию»
|
||||
> - Оставить задачей
|
||||
|
||||
Каждый вариант несёт причину — ту самую, что уедет в `--reason`. Ответы применяй
|
||||
сразу и, если в порции осталось ещё, следующей итерацией показывай следующие ≤3.
|
||||
|
||||
## Шаг 4. Выбор цели и набор спринта
|
||||
|
||||
1. **Покажи состояние проекта**: секцию `Готово` (что приложение уже умеет —
|
||||
это половина ответа на «где мы»), затем `Запланировано` с обоснованием
|
||||
очереди, `Направления`, и
|
||||
по каждой цели-кандидату — сколько под ней задач без открытых вопросов
|
||||
(`list --goal <слаг>`). Цель без готовых задач набором не станет: её сперва
|
||||
надо декомпозировать.
|
||||
2. **Цель называет человек** — либо называет, что цели не будет. Это
|
||||
продуктовое решение, а не механика: агент предлагает и объясняет, но не
|
||||
выбирает. **Оба ответа законны**, и «без цели» — такой же ответ, как слаг:
|
||||
спринт бывает под багфикс, под техдолг, под здоровье проекта. Спрашивается он
|
||||
так же, как цель, и в отдельный вопрос не выносится: это один и тот же вопрос
|
||||
«подо что набираем».
|
||||
3. **Набор собирает агент** — `sprint start --goal <слаг>` (или `sprint start
|
||||
--no-goal`), затем `sprint take …`. Скрипт не даст взять цель, задачу с чужой
|
||||
целью, с открытым вопросом, без типа и **без разделов, которых требует её
|
||||
тип** (у `fix` это в том числе `Воспроизведение`, у `research` — `Вопрос` и
|
||||
`Куда ляжет ответ`, и сырьё поэтому не берётся вовсе). Задача без цели (`fix`,
|
||||
`chore`, `research`) берётся свободно — операционная работа входит в набор
|
||||
помимо его цели. **В спринте без цели чужой цели нет вовсе**: сверять не с
|
||||
чем, берётся что угодно готовое, и единственной защитой остаётся показ набора
|
||||
человеку.
|
||||
4. **Набор показывается человеку до старта работ.** Показ — это и есть момент
|
||||
заморозки: после него набор не двигается. **В показе называется состав по
|
||||
типам** — три `fix` и ни одной `feature` под целью развития это разговор про
|
||||
цель, а не про набор, и увидеть его надо до заморозки, а не в докладе по
|
||||
итогам. **У набора без цели показ — единственная проверка состава**: скрипту
|
||||
там отказывать не по чему, и «что угодно готовое» превращается в осмысленный
|
||||
набор только глазами человека.
|
||||
|
||||
Здесь же последний дешёвый момент заметить **разнородную задачу**: раздел
|
||||
«Затрагивает» показывает границы до того, как заведено предложение об
|
||||
изменении. Строка, которая одна тянет задачу на метку выше остального
|
||||
перечня, — кандидат на разрез (шов — в `tasks`, `references/split.md`).
|
||||
Замеченная здесь, она стоит одного `edit`; замеченная на ревью — выброшенного
|
||||
предложения.
|
||||
5. Задача, которой для взятия не хватает только разделов её типа, дописывается
|
||||
здесь же — критерии с оракулами, перечень границ, шаги воспроизведения. Но
|
||||
если для этого нужен ответ человека, это вопрос, и задача в набор не идёт.
|
||||
|
||||
**Размер — ориентир, а не закон:** 5–8 задач. Можно взять больше, можно меньше —
|
||||
набор под цель важнее круглого числа; одна крупная задача спринтом тоже бывает.
|
||||
|
||||
## Доклад сессии
|
||||
|
||||
- Что просмотрено: N из M, сколько порций, по какому признаку отобраны.
|
||||
- Вопросы: разобрано N, из них отвечено без человека N, снято тегов N.
|
||||
- Разбор процесса: что записано и куда.
|
||||
- Сверка документов с кодом: звался ли `doc-code-drift`, что проверено из
|
||||
названного, что разошлось.
|
||||
- Изменения списком: удалено как реализованное (со ссылками), ушло без
|
||||
реализации (с причинами), понижено до сырья, слито, сменило тип или цель.
|
||||
- Новый спринт: цель — **или строка «без цели» с объяснением, почему** (багфикс,
|
||||
техдолг, здоровье), — набор со слагами, дата, состав по типам.
|
||||
- **Границы покрытия**: сколько задач не трогали и какие именно секции, теги или
|
||||
цели остались — иначе доклад читается как «беклог разобран».
|
||||
- `tasks.py check` после правок — результат строкой.
|
||||
@@ -0,0 +1,199 @@
|
||||
# Ведение спринта
|
||||
|
||||
Спринт — набор задач, замороженный до его конца: под одну цель или **без цели**
|
||||
(багфикс, техдолг, здоровье — это законно, `sprint start --no-goal`). Здесь то,
|
||||
что происходит **внутри** спринта: как задача заканчивается, что считается сделанным,
|
||||
кто принимает и что идёт в доклад. Как спринт набирается — шаг 4 в
|
||||
[cadence.md](cadence.md).
|
||||
|
||||
## Наблюдаемые исходы задачи
|
||||
|
||||
Как они достигаются — дело пайплайна проекта. Сессия знает только исход и его
|
||||
след.
|
||||
|
||||
- **Сделана** — по определению готовности ниже. `close <slug> --implemented`:
|
||||
файл и строка удаляются, следом остаётся коммит. **Закрывает агент-оркестратор
|
||||
последним шагом пайплайна, после коммита; приёмка человеком идёт позже и
|
||||
отменяется `reopen`** — см. «Кто и когда закрывает».
|
||||
- **Вышла из спринта** — `sprint drop <slug> --reason …`: возвращается в беклог
|
||||
с вопросом в файле и **без живого незакоммиченного предложения** — иначе при
|
||||
следующем взятии оно столкнётся с новым. Наработки, которые жалко терять,
|
||||
переезжают в тело задачи текстом.
|
||||
- **Оказалась крупнее задачи** — распознаётся **до того, как под неё заведено
|
||||
предложение об изменении**, иначе его придётся выбрасывать. Выходит из набора,
|
||||
уходит на декомпозицию; спринт продолжается остальными, части заводятся под той
|
||||
же целью (у спринта без цели — без неё) и в замороженный набор не добавляются.
|
||||
- **Отменена решением по ходу** — `close <slug> --reason "<ссылка на решение>"`
|
||||
прямо из спринта. Это редкий, но законный исход, и он называется в докладе.
|
||||
|
||||
**Конец спринта** — когда по каждой задаче набора наступил один из исходов. Не
|
||||
«все сделаны»: иначе одна застрявшая задача держит спринт бесконечно. Затем
|
||||
`sprint close`.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
take["sprint take — задача в наборе"]
|
||||
done["сделана<br/>close --implemented"]
|
||||
out["вышла<br/>sprint drop --reason"]
|
||||
epic["крупнее задачи<br/>распознаётся до заведения change"]
|
||||
cancel["отменена решением по ходу<br/>close --reason"]
|
||||
all{"по каждой задаче набора<br/>наступил исход?"}
|
||||
harvest["урожай заводится интейком tasks"]
|
||||
close["sprint close"]
|
||||
dissolve["sprint close --dissolve --reason<br/>недоделанное — в беклог"]
|
||||
|
||||
take --> done
|
||||
take --> out
|
||||
take --> epic
|
||||
take --> cancel
|
||||
done --> all
|
||||
out --> all
|
||||
epic --> all
|
||||
cancel --> all
|
||||
all -->|да| harvest
|
||||
harvest -->|"тег sprint: ставится, пока SPRINT.md не очищен"| close
|
||||
take -->|"продолжать нечем ни одной задачей — блокер"| dissolve
|
||||
done -->|"приёмка не сошлась: reopen --reason"| take
|
||||
```
|
||||
|
||||
Два ребра на схеме — те, где порядок обязателен и нарушается молча: **урожай до
|
||||
`sprint close`** (после команды автотег уже не поставится) и **блокер в обход
|
||||
исходов** (спринт распускается, а не ждёт).
|
||||
|
||||
Схема — **сводка**: определение готовности и правила приёмки ниже, и при
|
||||
расхождении прав текст.
|
||||
|
||||
**Урожай заводится при закрытии спринта, а не при закрытии задачи.** Это
|
||||
обязанность закрывающего: пройти по спискам находок от исполнителей и завести
|
||||
недостающее интейком скилла `tasks` — с дедупликацией и картой человеку. Заводимое
|
||||
метится тегом спринта само (`sprint:<слаг>`), поэтому первая порция следующей
|
||||
сессии поднимается одной командой `list --tag sprint:<слаг>`. Спринт, закрытый
|
||||
без этого шага, оставляет находки жить в отчётах — то есть нигде.
|
||||
|
||||
**Порядок здесь обязателен: урожай заводится ДО команды `sprint close`.**
|
||||
Автотег ставится по слагу из `SPRINT.md`, а `sprint close` этот файл очищает;
|
||||
заведённое после команды остаётся без тега и в первую порцию следующей сессии
|
||||
не попадёт — молча, потому что пустой `list --tag` выглядит как «урожая не
|
||||
было». Если так уже вышло, тег ставится руками: `add … --tag sprint:<слаг>`,
|
||||
слаг берётся из отчёта `sprint close`.
|
||||
|
||||
**Провал спринта.** Сработал блокер — спринт распускается (`sprint close
|
||||
--dissolve --reason …`), недоделанное возвращается в беклог, новый набор
|
||||
делается после ответа человека. Спринт не «ждёт»: ждать может человек, а
|
||||
замороженный набор, который нельзя двигать, только мешает.
|
||||
|
||||
**Протухший набор — второй законный повод роспуска.** Работа стояла, и человек
|
||||
вернулся к спринту, состав которого уже не держит в голове. Тем же роспуском:
|
||||
`sprint close --dissolve --reason "работа стояла с <когда>"`, недоделанное в
|
||||
беклог, новый набор — после переоценки, а не поверх старого.
|
||||
|
||||
Порога в неделях нет и не будет: счётчик простоя пришлось бы вести руками, а
|
||||
решает всё равно человек. Признак — не срок, а **что набор перестал быть твоим**:
|
||||
взялся перечитывать, зачем эти задачи вместе, — он протух. Заморозка тут не
|
||||
мешает, она запрещает *двигать* набор, а не распустить его целиком.
|
||||
|
||||
## Определение готовности
|
||||
|
||||
Задача засчитывается сделанной, когда верно **всё**:
|
||||
|
||||
1. **Пайплайн задачи пройден до конца** — со своим определением готовности, за
|
||||
которое отвечает проект: проверки, состав ревью, документация, коммит. Здесь
|
||||
оно не пересказывается и не подменяется — **форма фиксирована, содержание
|
||||
даёт `CLAUDE.md` проекта**. Пайплайна нет, задача сделана руками — условие
|
||||
читается как «проверки проекта зелёные и изменение влито».
|
||||
2. **Критерии приёмки проверены поимённо** — каждый со своим оракулом, исход по
|
||||
каждому назван. Это единственное, что добавляет управление задачами: пайплайн
|
||||
отвечает «сделано по правилам», критерии — «сделано то, что заказывали».
|
||||
3. **Находки по ходу отданы списком** — исполнитель обязан их **назвать**
|
||||
(каждую, с пометкой «заведена / не заведена: причина»), но **не обязан
|
||||
заводить**: заведение интерактивно — оно требует дедупликации против беклога
|
||||
и кладбища, а ещё решений человека. Обязанность **завести урожай** — на
|
||||
закрытии спринта, ниже. Иначе автономный исполнитель оказался бы разом и
|
||||
обязан завести задачи, и не вправе сделать это в одиночку.
|
||||
|
||||
### Кто и когда закрывает
|
||||
|
||||
**Задачу закрывает агент-оркестратор — тот же, кто её и сделал**, последним шагом
|
||||
пайплайна, после коммита. Порядок:
|
||||
|
||||
1. пайплайн доводит задачу до коммита;
|
||||
2. **после коммита** зовёт `Skill av-dev-tasks:tasks` и закрывает задачу
|
||||
(`close <slug> --implemented`); строка уходит из `SPRINT.md`;
|
||||
3. **докладывает исход и по каждому критерию — оракул и наблюдаемый исход.**
|
||||
Это доклад приёмщику, а не отметка «принято».
|
||||
|
||||
**Приёмщик и исполнитель здесь совпадают, и это принято сознательно** — цена
|
||||
названа в `SKILL.md`, раздел «Стимулы». Поэтому закрытие **не окончательно**, а
|
||||
доклад по критериям — не формальность: он единственное, по чему приёмка вообще
|
||||
возможна.
|
||||
|
||||
**Порядок «коммит, потом закрытие» обязателен.** Закрытие удаляет файл задачи;
|
||||
упавший коммит после закрытия оставил бы задачу закрытой без единого следа
|
||||
работы.
|
||||
|
||||
**Само закрытие тоже коммитится, отдельным коммитом.** Удаление файла задачи и
|
||||
правка индекса — правки в рабочем дереве; пока они не в истории, `SPRINT.md`
|
||||
ничего не показывает, а `reopen` восстанавливает текст из `HEAD` в узком окне:
|
||||
его закроет первый посторонний коммит. Сообщение про учёт, а не про
|
||||
работу: `закрыта задача <slug>`.
|
||||
|
||||
**Дорога назад существует и обязана быть названа.** Человек на сессии сверил
|
||||
критерии, и приёмка не сошлась — `tasks.py reopen <slug> --reason "приёмка не
|
||||
сошлась: …"`:
|
||||
файл восстанавливается из истории git, строка возвращается в набор идущего
|
||||
спринта (или в беклог, если спринта нет), строка кладбища снимается. Тело
|
||||
восстанавливается **на момент удаления** — всё, что было дописано позже, живёт
|
||||
только в коммите задачи, и это называется в докладе.
|
||||
|
||||
### Кто и по чему принимает
|
||||
|
||||
Три условия, без которых пункт про критерии не исполняется никем:
|
||||
|
||||
1. **Критерии переживают файл задачи.** Файл удаляется при закрытии, поэтому
|
||||
критерии копируются туда, где их увидит приёмщик. Куда именно — **отвечает
|
||||
пайплайн проекта, а не слот в `CLAUDE.md`**: он переносит их в `tasks.md`
|
||||
изменения, когда заводит change. Проект без пайплайна называет своё место
|
||||
сам.
|
||||
2. **Принимает человек на сессии, а не отдельный агент.** Исполнитель и приёмщик
|
||||
в момент закрытия **не разведены** (решение о снятии и его
|
||||
цена — в `SKILL.md`, «Стимулы»). Опоры остались три: **сохранённый независимый
|
||||
отчёт ревью** (при конвейере `av-dev-pipeline` — отчёт триажа в
|
||||
`openspec/changes/archive/<id>/review/`, до архивации — `changes/<id>/review/`),
|
||||
`SPRINT.md` под git и `reopen`. Переоценка на сессии и есть момент, когда
|
||||
критерии видит не исполнитель. **Конвейера ревью в проекте нет — первой опоры
|
||||
нет тоже**, и это называется строкой доклада, а не обходится молча
|
||||
(`SKILL.md`, «Стимулы»).
|
||||
3. **Расхождение — дефект критериев.** Приёмщик правит критерии и возвращает
|
||||
задачу исполнителю **в этом же спринте**: ответ есть, остаток есть, по тесту
|
||||
про остаток это не выход из спринта.
|
||||
|
||||
## Что врывается в замороженный набор
|
||||
|
||||
Только два класса — правило и его обоснование в SKILL.md. Здесь механика:
|
||||
|
||||
- вторжение **не добавляет** задачу в набор: `SPRINT.md` остаётся тем набором,
|
||||
который заморозили и показали. Внеплановая работа делается и называется в
|
||||
докладе отдельной строкой «внеплановое: что и почему»;
|
||||
- если внеплановое требует больше пары часов, честнее распустить спринт, чем
|
||||
делать вид, что набор соблюдается;
|
||||
- всё остальное падает в беклог через обычный интейк и ждёт сессии.
|
||||
|
||||
## Доклад в конце спринта
|
||||
|
||||
Проверяемые якоря, а не пересказ:
|
||||
|
||||
- **Цель спринта** — или строка «спринт без цели» с тем, чем он был (багфикс,
|
||||
техдолг, здоровье): у бесцельного набора это единственное место, где состав
|
||||
вообще объясняется. И по каждой задаче набора: **хеш коммита**, дословный
|
||||
исход проверок проекта, **исход по каждому критерию приёмки**.
|
||||
- **Какие развилки решались** и чем обоснованы.
|
||||
- **Урожай:** сколько задач заведено, какие вопросы накопились, что вышло из
|
||||
спринта и почему, что было внеплановым.
|
||||
- **Поимённая сверка урожая** с независимыми отчётами ревью: каждая отложенная
|
||||
находка имеет либо слаг, либо строку «не заведена: причина». Нулевой урожай при
|
||||
непустом отчёте — сигнал, а не благополучие. **Отчётов нет** (проект без
|
||||
конвейера ревью) — сверять не с чем, и строка доклада говорит именно это, а не
|
||||
«сверено».
|
||||
- **Созрела ли порция для сессии.** Решение звать — человека, напоминание —
|
||||
обязанность агента: `⌈урожай / 8⌉` порций.
|
||||
- **Границы покрытия** сжатой строкой: что в этом спринте не проверялось вовсе.
|
||||
@@ -0,0 +1,688 @@
|
||||
---
|
||||
name: tasks
|
||||
description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Ритуал между спринтами — скилл session. Не реализует задачи — этим занимается пайплайн проекта.
|
||||
---
|
||||
|
||||
# Задачи
|
||||
|
||||
Задачи — каталог markdown-файлов. Одна запись = один файл `items/<slug>.md` плюс
|
||||
строка **ровно в одном** индексе. Скилл владеет **форматом и содержимым**:
|
||||
заводит, редактирует, закрывает, разбирает находки ревью, дробит, штурмует сырьё.
|
||||
|
||||
Чем он **не** владеет: ритуалом между спринтами (разбор вопросов → разбор
|
||||
прошедшего спринта → переоценка → выбор цели и набор) — это скилл `session`; и
|
||||
выполнением задачи — это пайплайн проекта.
|
||||
|
||||
## Шесть правил, из которых всё следует
|
||||
|
||||
Ситуация не покрыта инструкцией — решай по ним.
|
||||
|
||||
0. **Цель — возможность приложения, задача — шаг к ней.** Цель отвечает на «что
|
||||
приложение будет уметь», её «Завершение» — наблюдаемый признак того, что уже
|
||||
умеет; задача отвечает на «что для этого нужно сделать». Оценивается проект
|
||||
по **поведению**, а не по внутреннему устройству, поэтому и роадмап отвечает
|
||||
не «сколько работ осталось», а «что уже умеет и чего ещё не умеет».
|
||||
Свойство поведения — тоже возможность: «сообщает о своём состоянии»,
|
||||
«исход слияния не зависит от порядка доставки» — законные цели.
|
||||
1. **Беклог гниёт с той стороны, где его пополняют.** Заведение — самая частая
|
||||
операция и с худшим отказом: из одного разговора рождается пять файлов, а
|
||||
переоценка потом разгребает то, чего не надо было заводить. Дедупликация и
|
||||
фильтр на входе дешевле любой чистки. Заводим только то, что **не делаем
|
||||
сейчас** и о потере чего пожалеем.
|
||||
2. **Файл — источник истины, индексы производны.** Разошлись — неправы индексы.
|
||||
Согласованность механизируема и проверяется командой, а не вниманием: всё,
|
||||
что ловит `tasks.py check`, не должно попадать ни в чек-лист, ни в промпт.
|
||||
Поэтому **«зачем» живёт в мете файла**, а строка индекса его лишь
|
||||
повторяет: пока поле лежало только в индексе, восстановление пропавшей
|
||||
строки теряло его молча и навсегда. Единственное исключение намеренное: **в каком
|
||||
индексе лежит задача, знают индексы** — «в спринте» это свойство спринта, а
|
||||
не файла, поля-состояния нет.
|
||||
3. **Причина переживает запись.** Выкинутая без причины задача вернётся через
|
||||
квартал тем же текстом. Реализованная оставляет след в коммите — выкинутая не
|
||||
оставляет ничего, поэтому у неё есть `REJECTED.md`.
|
||||
4. **Порядка нет, есть цель — но цель есть не у всякой задачи.** Приоритетов,
|
||||
«повысить» и «встать раньше» нет: «что делать дальше» отвечает набор спринта,
|
||||
а между спринтами порядок не нужен никому. Цель обязательна там, где она и
|
||||
есть содержание работы, — у **новой возможности** (`feature`). Починка,
|
||||
техдолг и разведка служат работоспособности, а не направлению, и живут без
|
||||
цели законно; в набор спринта они входят помимо его цели. Придуманная им цель
|
||||
— то же враньё, от которого спасает тип.
|
||||
|
||||
Единственный порядок, который в беклоге всё-таки есть, **производен от типа**,
|
||||
а не назначен человеком: **сырьё** (`research` без раздела «Вопрос») стоит в
|
||||
конце своей категории. Его не берут, и между берущимся оно каждый раз требует
|
||||
открыть файл, чтобы это понять. Раз порядок выводится, его проверяет машина —
|
||||
и приоритетом он не становится.
|
||||
5. **Тип решает, что с записью можно делать.** Тип — единственная ось и первое
|
||||
поле меты: от него зависит, какие разделы обязательны в теле, нужна ли цель,
|
||||
берётся ли запись в спринт и в каком индексе живёт её строка. Словарь закрыт;
|
||||
ни один тип не подошёл — значит, в записи их два, и её надо разделить.
|
||||
|
||||
## Раскладка
|
||||
|
||||
Каталог задач — **`docs/tasks`, жёстко**: это часть канона документов, и
|
||||
подгоняется под него проект, а не наоборот. Канон ведёт другой плагин
|
||||
(`av-dev-docs`), и **путь известен скиллу сам** — ссылки в чужое дерево здесь
|
||||
нет намеренно: скилл работает и там, где того плагина не поставили.
|
||||
|
||||
```
|
||||
docs/tasks/
|
||||
items/ задачи и цели файлами, <slug>.md, слаги английские
|
||||
ROADMAP.md состояние проекта: что уже умеет и чего ещё не умеет
|
||||
BACKLOG.md что можно взять — только задачи, целей здесь нет
|
||||
SPRINT.md текущий спринт: цель (или её отсутствие), набор, дата
|
||||
REJECTED.md ушедшее БЕЗ реализации, с причиной и датой
|
||||
```
|
||||
|
||||
Правило, снимающее путаницу: **`BACKLOG.md` — то, что берут; `ROADMAP.md` — то,
|
||||
подо что берут.** Цель в спринт взять нельзя, поэтому в списке берущихся ей не
|
||||
место.
|
||||
|
||||
**Четыре секции роадмапа, и последняя отвечает на половину вопроса:**
|
||||
|
||||
| Секция | Англ. | Что в ней |
|
||||
| --- | --- | --- |
|
||||
| `Запланировано` | `Planned` | очередь значима и обосновывается прозой рядом |
|
||||
| `Направления` | `Directions` | очереди нет, тянутся долго |
|
||||
| `Сопровождение` | `Operations` | чем держат проект: инструмент, процесс, эксплуатация — не возможности приложения, и потому отдельно |
|
||||
| `Готово` | `Done` | достигнутые цели — строкой с датой, **без ссылки на файл**: файл удалён, поведение живёт в спеках |
|
||||
|
||||
**Порядок тоже канонический, и `Готово` стоит последним не из скромности.**
|
||||
Достигнутое **копится**: через год этой секции больше, чем всех остальных
|
||||
вместе. Стоя первой, она отодвигает за экран ровно то, ради чего роадмап
|
||||
открывают чаще всего, — что делается сейчас и что дальше. Порядок проверяет
|
||||
`check`, переставляет `check --fix`.
|
||||
|
||||
**Секции роадмапа канонические, категории беклога — нет**, и разница не в любви к
|
||||
единообразию. У каждой секции роадмапа свой смысл, в достигнутое пишет сам `close`, и
|
||||
роадмап, названный по-своему, читался бы только своим автором. Категории беклога
|
||||
(`Ядро`, `Инфра`) смысла не несут — это полки домена, и остаются делом проекта.
|
||||
Отсюда и разные имена поля меты: у цели **Секция** (часть роадмапа — состояние
|
||||
очереди), у задачи **Категория** (полка, в которую она вернётся из спринта).
|
||||
|
||||
Отсюда четыре правила, которые проверяет `tasks.py check`: **состав закреплён**
|
||||
(чужая секция — ошибка, а не вольность), **все четыре обязаны быть** (нет
|
||||
секции — нет ответа на её часть вопроса), **язык один на весь индекс**, **порядок
|
||||
канонический**. `--roadmap-sections` у `init` нет: выбирать нечего.
|
||||
|
||||
**Заголовок секции отбит пустой строкой с обеих сторон и написан с прописной.**
|
||||
Во всех индексах одинаково, включая категории беклога, которые проект называет сам.
|
||||
Написание канонических секций правит `check --fix` (заодно и ссылку на секцию в
|
||||
мете файлов: имя секции принадлежит заголовку индекса, файл на неё только
|
||||
ссылается); отбивку и порядок он правит везде.
|
||||
|
||||
Оговорка про `Сопровождение`: слово `окружение` сюда не годится — в
|
||||
`architecture.md` оно уже значит боевое окружение приложения, и одно слово в двух
|
||||
смыслах развело бы документы канона. А `Разработка`, стоявшая тут раньше,
|
||||
называла слишком много: роадмап **весь** про разработку, и секция с таким именем
|
||||
не отличалась от остальных ничем.
|
||||
|
||||
**Секции «блокеры» в беклоге нет.** Блокер — это *состояние* (спринт не может
|
||||
продолжаться ни одной задачей), а не полка: он живёт ровно до ответа человека, и
|
||||
записи в такой секции не успевают жить. Следы блокера остаются вопросами в
|
||||
файлах задач распущенного спринта. Постоянно пустая секция со старой семантикой
|
||||
«разбираются пачками» противоречила бы правилу «блокер эскалируется немедленно»,
|
||||
поэтому `init` её заводить отказывается, а `check` о ней говорит. **Проекту,
|
||||
который переезжает с такой секцией, её надо удалить** — это единственное место,
|
||||
где это сказано.
|
||||
|
||||
**Задача живёт в одном индексе за раз.** Взята в спринт — строка переезжает из
|
||||
`BACKLOG.md` в `SPRINT.md`; вышла — обратно. Файл в `items/` при этом **не
|
||||
двигается**: он и есть запись, индексы лишь показывают, где она числится.
|
||||
|
||||
**У сделанной задачи записи не остаётся** — файл и строка удаляются (`close
|
||||
--implemented`). Ей хватает коммита и документации проекта; вторая запись была
|
||||
бы вторым домом для того же факта. Вопрос «что было в спринте N» отвечается
|
||||
даром: `SPRINT.md` лежит под git, `git log -p docs/tasks/SPRINT.md` отдаёт историю
|
||||
всех наборов без отдельного журнала.
|
||||
|
||||
**У достигнутой цели запись остаётся, и это единственное исключение.** Файл
|
||||
удаляется так же, а строка переезжает в секцию `Готово` с датой. Причина в том,
|
||||
что цель — не работа, а **возможность**: «что приложение умеет» это половина
|
||||
вопроса, ради которого роадмап и открывают, и стирать её вместе с файлом значит
|
||||
оставить инструмент, отвечающий только «что осталось». Вторым домом это не
|
||||
становится: поведение живёт в `openspec/specs/`, а роадмап отвечает **когда и в
|
||||
каком порядке оно появилось** — другой вопрос. Ссылки на файл в строке нет
|
||||
намеренно: файл удалён, а битая ссылка — законная ошибка `check`.
|
||||
|
||||
Куда запись может переехать и какой командой — весь набор переходов:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state "BACKLOG.md — что берут" as B
|
||||
state "ROADMAP.md — подо что берут" as P
|
||||
state "SPRINT.md — набор спринта" as S
|
||||
state "REJECTED.md — ушла без реализации" as R
|
||||
state "записи нет — реализована" as D
|
||||
state "ROADMAP.md, «умеет» — цель достигнута" as A
|
||||
|
||||
[*] --> B: add --type feature|fix|chore|research
|
||||
[*] --> P: add --type goal
|
||||
B --> P: edit --type goal --section
|
||||
P --> B: edit --type feature|fix|chore|research --section
|
||||
B --> S: sprint take
|
||||
S --> B: sprint drop --reason
|
||||
S --> D: close --implemented
|
||||
P --> A: close --implemented
|
||||
B --> R: close --reason
|
||||
S --> R: close --reason
|
||||
P --> R: close --reason
|
||||
D --> B: reopen --reason
|
||||
R --> B: reopen --reason
|
||||
A --> P: reopen --reason
|
||||
```
|
||||
|
||||
Состояния здесь — **где числится строка**, а не где лежит файл: файл
|
||||
`items/<slug>.md` не двигается ни на одном переходе. Стрелок «руками» на схеме
|
||||
нет намеренно — каждый переход это команда, и другого способа его совершить не
|
||||
существует.
|
||||
|
||||
Схема — **сводка**: условия и оговорки живут в тексте разделов, и при
|
||||
расхождении прав текст.
|
||||
|
||||
## Цели
|
||||
|
||||
**Цель — возможность приложения.** Такой же файл в `items/`, тип `goal` (🎯),
|
||||
перечисленный в `ROADMAP.md`. Формулируется ответом на вопрос **«что приложение
|
||||
будет уметь»**, а не названием области работ: не «Работа с чтением», а «Чтение
|
||||
данных клиентами»; не «Рефакторинг слияния», а «Исход слияния не зависит от
|
||||
порядка доставки».
|
||||
|
||||
**Свойство поведения — тоже возможность.** «Наблюдаемость» это «приложение
|
||||
сообщает о своём состоянии»; «прочность слияния» это «исход не зависит от
|
||||
порядка». Такие цели законны и переформулировки в функцию не требуют — требуют
|
||||
только, чтобы формулировка отвечала на «что приложение делает», а не на «какую
|
||||
часть кода мы трогаем».
|
||||
|
||||
**Целью не становится работа, которой держат проект.** Состав перечислен
|
||||
[в словаре сопровождения](references/operations.md);
|
||||
на вопрос «что приложение будет уметь» ничто из него не отвечает. Им отведена отдельная секция роадмапа,
|
||||
чтобы они были видны в том же экране и при этом не читались как возможности
|
||||
продукта.
|
||||
|
||||
**Граница проходит по тому, кто наблюдает, а не по теме.** «Приложение сообщает
|
||||
о своём состоянии» — возможность: наблюдает пользователь сервиса, и цели место
|
||||
среди прочих. «Дежурный видит состояние на одном экране» — сопровождение:
|
||||
наблюдаем мы. Одна и та же наблюдаемость попадает в разные секции, и это верно —
|
||||
секции отвечают на разные вопросы.
|
||||
|
||||
**Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема
|
||||
живёт ещё в двух местах: разделе «Эксплуатация» в `architecture.md` и теме ревью
|
||||
`operations`. Словарь у всех трёх общий, дом у него один — `shared/operations.md`
|
||||
в репозитории плагинов, — а здесь лежит дословная копия:
|
||||
[references/operations.md](references/operations.md). Пересказывать его своими
|
||||
словами нельзя: три перечня «чем держат проект» уже разъезжались на «метриках и
|
||||
логах» против «мониторинга».
|
||||
|
||||
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; не про приложение, а про то,
|
||||
чем его держат, — `Сопровождение`; в `Готово` кладёт сам `close`.
|
||||
|
||||
- **Список задач цели выводится, а не хранится.** В теле цели — зачем она и что
|
||||
считается её завершением; перечня задач там нет. Он был бы третьим индексом и
|
||||
поехал бы на первой же закрытой задаче, а `check` про него не знает. Связь
|
||||
однонаправленна: задача несёт тег `goal:<слаг>`, перечень даёт
|
||||
`tasks.py list --goal <слаг>`.
|
||||
- **Статус цели выводится.** Цель достигнута, когда у неё не осталось открытых
|
||||
задач; `[x]`/`[~]` руками не ведутся, а `close` цели с живыми задачами
|
||||
скрипт запретит. Достижение — `close <цель> --implemented`: файл удаляется,
|
||||
строка с датой переезжает в `Готово`. Ошиблись — `reopen` вернёт файл и
|
||||
**снимет строку достигнутого**, чтобы роадмап не утверждал того, чего нет. Единственная оговорка: цель без задач неотличима — «ещё не
|
||||
разобрана» или «всё закрыто». Различает **тег `decomposed`** в мете
|
||||
цели: он ставится, когда цель разложена на задачи. Тег, а не строка в теле —
|
||||
потому что проверяется механически: `check` **напоминает** о нём у пустой цели
|
||||
(замечанием, не ошибкой — неразобранная цель это законное состояние), а `check
|
||||
--fix` сам проставляет его цели, у которой задачи есть.
|
||||
- **Тип `[epic]` упразднён.** Он был зонтиком между целью и задачами — «задача,
|
||||
которая не мерджится целиком». Зонтик теперь цель, а слишком крупный шаг просто
|
||||
дробится на шаги помельче под той же целью, и промежуточному типу места не
|
||||
осталось. Замер подтвердил: ноль употреблений на 97 записей двух живых
|
||||
проектов. Встретился в чужом беклоге — это цель либо набор задач, и `check`
|
||||
назовёт его неизвестным типом.
|
||||
|
||||
## Тип записи
|
||||
|
||||
**Тип — единственная ось, и он решает, что с записью можно делать.** Дом типа —
|
||||
**поле меты `Тип` первой строкой**; эмодзи в заголовке H1 от него производна, её
|
||||
ставит `add` и чинит `check --fix`.
|
||||
|
||||
| Тип | Обязательные разделы | Цель | В спринт | Устав |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 🎯 `goal` | `Завершение` | — | нет | [task-goal.md](references/task-goal.md) |
|
||||
| ✨ `feature` | `Затрагивает`, `Критерии приёмки` | **обязательна** | да | [task-feature.md](references/task-feature.md) |
|
||||
| 🐞 `fix` | `Воспроизведение`, `Затрагивает`, `Критерии приёмки` | необязательна | да | [task-fix.md](references/task-fix.md) |
|
||||
| 🧹 `chore` | `Затрагивает`, `Критерии приёмки` | нет | да | [task-chore.md](references/task-chore.md) |
|
||||
| 🔬 `research` | `Вопрос`, `Куда ляжет ответ` | нет | да | [task-research.md](references/task-research.md) |
|
||||
|
||||
Сверх обязательных у любой задачи допустимы `Рамки` и `Вопросы`. Раздел не из
|
||||
схемы своего типа — **замечание, а не ошибка**: свой раздел законная вольность
|
||||
проекта, но `Воспроизведение` у `chore` почти всегда значит, что тип проставлен
|
||||
не тот, и сказать об этом стоит, не запрещая.
|
||||
|
||||
**Осей было две, и ортогональность у них была фальшивой.** Тип записи
|
||||
(`goal`/`idea`/`task`) и род работы (`kind:<род>` тегом) давали двенадцать клеток
|
||||
произведения, из которых законны были шесть: у цели род запрещён, у задачи
|
||||
обязателен, у идеи пуст. Плюс алгоритм работы крепится не к `task`, а к `fix` и
|
||||
`research` — то есть к роду. Оси схлопнуты, тег `kind:` упразднён.
|
||||
|
||||
**Тип `idea` упразднён вместе с ними.** Он значил не род работы, а **состояние
|
||||
незаполненности** — «первый, второй или третий вопрос теста готовности не
|
||||
отвечается», — а состояние типом быть не может: оно меняется по мере того, как
|
||||
запись дописывают, а тип меняют командой. Теперь это состояние называется честно:
|
||||
`research` без раздела «Вопрос» — **сырьё**. В спринт не берётся ровно как
|
||||
прежняя идея, лежит в конце своей категории и отбирается `list --raw`.
|
||||
|
||||
Словарь **закрыт**. Открытый разъедется на синонимах — `bug`, `bugfix`, `fix`,
|
||||
`defect`, — и отбор по типу перестанет отвечать на свой единственный вопрос. Ни
|
||||
один тип не подходит — это сигнал, что в задаче их два и её надо разделить.
|
||||
|
||||
**Требуется тип там, где по нему принимают решение:** `sprint take` без типа
|
||||
откажет, потому что не знает, каких разделов требовать. `check` о пропаже только
|
||||
**напоминает** — беклог, заведённый до появления типа, законен, и переоформлять
|
||||
его «заодно» здесь не просят.
|
||||
|
||||
**Тип не выбирает метку ревью и вообще ничего не предписывает пайплайну.**
|
||||
Профиль выбирается по факту изменения, а не по типу задачи: `chore` бывает
|
||||
миграцией схемы, `fix` — правкой публичного контракта. Правило «предписание
|
||||
процесса в теле задачи снимается» типом не отменяется, а подтверждается: он
|
||||
описывает работу, а не то, как её проверять.
|
||||
|
||||
## Как написана задача
|
||||
|
||||
Три требования к тексту. Первое — про заголовок, два остальных про то, чтобы
|
||||
задачу можно было **оценить, не открывая код**.
|
||||
|
||||
**Заголовок отвечает на вопрос своего типа.** Вопросов три, поэтому и форм три:
|
||||
|
||||
| Тип | Отвечает на | Пример |
|
||||
| --- | --- | --- |
|
||||
| 🎯 `goal` | что приложение будет уметь | Соперником может быть компьютер |
|
||||
| ✨ `feature`, 🐞 `fix`, 🧹 `chore` | что нужно сделать | Печатать поле одним куском кода |
|
||||
| 🔬 `research` | о чём разведка | Подсказка следующего хода |
|
||||
|
||||
Задача — **глаголом в неопределённой форме**, перед ним допускается «не»: «Не
|
||||
отбрасывать молча лишние символы в ходе», а не «Лишние символы молча
|
||||
отбрасываются». Описательный заголовок называет **состояние**, а из состояния не
|
||||
видно, чего от работы ждут: «Ничья объявляется, пока клетки есть» одинаково
|
||||
читается и как жалоба, и как задание, — и в списке, где решают «брать или не
|
||||
брать», это разные вещи. `research` формы действия не несёт **намеренно**: её
|
||||
исход знание, а что делать — ещё неизвестно, и заголовок-действие обещал бы
|
||||
решённость, которой нет.
|
||||
|
||||
Из этого же правила растёт разница индексов: роадмап — список возможностей,
|
||||
беклог — список работ, и если заголовки перепутать формами, каждый из них
|
||||
начинает читаться как другой.
|
||||
|
||||
`check` считает заголовки не в форме действия и печатает **число** в блоке
|
||||
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
|
||||
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
|
||||
Годность формулировки — не машине: её смотрит
|
||||
[агент вычитки](#вычитка-два-прохода-а-не-один).
|
||||
|
||||
**Функции и границы, а не намерения.** Задача называет, что система начнёт
|
||||
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
|
||||
формат на диске, публичный тип пакета, внешний сервис. Перечень живёт разделом
|
||||
«Затрагивает» (форма — [references/task-format.md](references/task-format.md)) и
|
||||
требуется к взятию в спринт. Без него задача оценивается по объёму текста, а не
|
||||
по объёму поверхности, — и оценка систематически занижена ровно там, где текст
|
||||
короткий, а границ много. Названы **границы**, а не то, как они изменятся: план
|
||||
реализации живёт в предложении об изменении, а не в задаче.
|
||||
|
||||
**Предметно, но без усложнения.** Текст задачи читает человек, который решает,
|
||||
брать её или нет, и делает это по строке индекса и одному экрану тела.
|
||||
|
||||
Язык — общий для всех проектных текстов, и дом у него один,
|
||||
`shared/language.md` в репозитории плагинов; здесь лежит дословная копия:
|
||||
[references/language.md](references/language.md) (информационный стиль,
|
||||
применённый к задачам и документам канона; там же таблицы англицизмов и жаргона
|
||||
и то, что из стиля отброшено намеренно). Задаче он даёт четыре требования,
|
||||
которые нарушаются чаще прочих:
|
||||
|
||||
- **глагол вместо отглагольного существительного**: «обработчик не проверяет
|
||||
владельца», а не «проверка владельца не осуществляется»;
|
||||
- **факт вместо оценки**: «время ответа доходит до 800 мс», а не «работает
|
||||
медленно». Оценка без факта рядом — настроение, а не сведение;
|
||||
- **англицизм с живым русским аналогом заменяется**: не «зафиксить флоу», а
|
||||
«починить порядок доставки». Имя вещи не переводится: слаг, команда, тип в
|
||||
коде, `API`;
|
||||
- **термин не из документов проекта вводится одной строкой** или не
|
||||
употребляется. Свой словарь у задачи — самый дешёвый способ сделать беклог
|
||||
нечитаемым для того, кто вернётся к нему через квартал.
|
||||
|
||||
И одно требование, которое есть только у задачи: **сложность формулировки — не
|
||||
признак сложности работы.** Задачу, которую не удаётся сказать просто, чаще
|
||||
всего не удаётся и оценить: это либо две задачи, либо сырьё.
|
||||
|
||||
Эти правила — про **язык**, а не про объём: короткая задача без границ хуже
|
||||
длинной с ними.
|
||||
|
||||
## Инструмент (`tasks.py`)
|
||||
|
||||
Пусть `tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"`, а `D` —
|
||||
`docs/tasks` от корня проекта. `--dir` стоит в примерах намеренно: вызов из
|
||||
подкаталога — обычное дело.
|
||||
|
||||
```
|
||||
python3 $tk check --dir D # согласованность индексов + здоровье
|
||||
python3 $tk check --dir D --fix # + починить дрейф (тип, эмодзи, место, заголовок, дубли, «зачем», форма меты)
|
||||
python3 $tk list --dir D [--stale] [--section S] [--type T] [--tag a,b] [--goal S] [--raw] [--index …] [--questions]
|
||||
python3 $tk add --dir D --slug S --title T --type goal|feature|fix|chore|research [--section S] [--goal G] [--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 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 --implemented # просто удалить (реализована и закоммичена)
|
||||
python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась
|
||||
python3 $tk sprint start (--goal S | --no-goal) --dir D | take S… | drop S… --reason R | close [--dissolve --reason R]
|
||||
python3 $tk init --dir D [--sections …] [--items …] [--backlog …] …
|
||||
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
|
||||
```
|
||||
|
||||
**Коды выхода — единый словарь; на нём ветвятся скиллы, а не на тексте вывода:**
|
||||
|
||||
| Код | Что случилось | Что делать |
|
||||
| --- | --- | --- |
|
||||
| 0 | сошлось / сделано | дальше по сценарию |
|
||||
| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу |
|
||||
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `docs/.pm.json`, повтор не поможет |
|
||||
| 4 | внутренний сбой | дефект скрипта, доложить |
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
|
||||
нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях.
|
||||
|
||||
Тип — английское ключевое слово `goal` / `feature` / `fix` / `chore` /
|
||||
`research` (как и прочие токены команд), у `add` **обязательное**: без него
|
||||
неизвестно, какой шаблон тела класть. Текст задачи при этом русский, а эмодзи в
|
||||
заголовке ставит скрипт.
|
||||
|
||||
**Мутации правят файл и индексы заодно** — руками строку индекса или мету
|
||||
не пиши, зови `add`/`edit`/`move`/`close`/`sprint`. Смена заголовка, «зачем», типа,
|
||||
цели и **тегов** — это `edit`: он держит H1 (вместе с эмодзи), мету и индекс
|
||||
согласованными. Снятие тега — `--rm-tag` (после ответа на вопрос снимается
|
||||
`question`), смена цели — `--goal`, типа — `--type`; оба заменяют прежнее
|
||||
значение, а не добавляют второе.
|
||||
|
||||
**Переезд между индексами — следствие смены типа, а не отдельная команда.**
|
||||
`edit <slug> --type goal --section <часть роадмапа>` переносит строку из
|
||||
`BACKLOG.md` в `ROADMAP.md` (и обратно — задачным типом плюс
|
||||
`--section <категория беклога>`);
|
||||
`move` двигает только внутри одного индекса и пишет причину. `--section` у
|
||||
`edit` работает **только** при таком переезде — иначе он отсылает к `move`,
|
||||
потому что смена секции без причины и есть тот дрейф, который потом никто не
|
||||
объяснит. Задача в наборе спринта тип не меняет вовсе: сперва `sprint drop`.
|
||||
|
||||
Тело задачи скрипт не трогает:
|
||||
`add` кладёт заголовок, мета-блок и шаблон с подсказками, тело дописываешь
|
||||
редактором (пока плейсхолдер на месте, `check` напоминает).
|
||||
|
||||
`check` — единственный судья согласованности; что именно он ловит, скажет его
|
||||
вывод, здесь не пересказываем. Гоняй его **в начале сессии** и **после каждой
|
||||
правки**, даже если правил мутациями: дрейф мог накопиться раньше. Накопившееся
|
||||
чини `check --fix` — он детерминированно правит то, где истина однозначна (тип в
|
||||
своё поле, эмодзи заголовка, имя поля места, секция, заголовок, дубли, «зачем» из
|
||||
индекса в файл, старая форма меты, пометка `decomposed` у цели с задачами, сырьё
|
||||
в конец категории), а неоднозначное (задача сразу в двух индексах, нечего
|
||||
восстанавливать, **тип, которого неоткуда взять**) печатает отдельной пометкой
|
||||
`НЕОДНОЗНАЧНО` — это тебе, и это идёт строкой доклада. **Ссылка на исчезнувший
|
||||
файл в пометку не попадает:** `--fix` её просто не трогает, и она остаётся
|
||||
`ОШИБКА` обычного `check` — то есть видна, но в докладе её надо назвать отдельно.
|
||||
|
||||
`--fix` правит **и файлы** — там, где источник ровно один и выбирать не из чего:
|
||||
тип переезжает из прежнего дома (тег `kind:`, префикс `[goal]`/`[idea]`) в поле
|
||||
меты, заголовок получает эмодзи, поле места — имя по типу, «зачем», оставшееся
|
||||
только в индексе, переезжает в мету, цель с задачами получает `decomposed`.
|
||||
Каждый случай печатается поимённо.
|
||||
|
||||
**Тип, который не выводится ниоткуда, `--fix` не угадывает.** `feature` от
|
||||
`chore` машина не отличает, и подставленное наугад значение врало бы ровно там,
|
||||
где по нему принимают решение. Такие записи идут в `НЕОДНОЗНАЧНО`, и тип им
|
||||
проставляет человек — `edit <слаг> --type …`.
|
||||
|
||||
**Что механизировано, а что нет.** У задачи, взятой в набор (`sprint take` и
|
||||
`check` по задачам спринта), проверяется схема её типа, и у каждой части своя
|
||||
глубина:
|
||||
|
||||
- **тип** — жёстко: назван и из закрытого словаря;
|
||||
- **критерии приёмки** (`feature`, `fix`, `chore`) — число пунктов жёстко
|
||||
(меньше двух отказ, больше пяти замечание), наличие оракула **эвристикой** по
|
||||
слову «оракул» в пункте;
|
||||
- **прочие разделы схемы** (`Затрагивает`, `Воспроизведение`, `Вопрос`,
|
||||
`Куда ляжет ответ`, `Завершение`) — только **наличие непустого**. Содержимое
|
||||
машине не видно: границу, которую забыли назвать, она от отсутствующей не
|
||||
отличает, а шаги, по которым ничего не воспроизводится, — от годных.
|
||||
|
||||
Настоящий оракул от слова «оракул» машина тоже не отличает, поэтому эвристика
|
||||
даёт только замечание, и в докладе это называется как есть: «проверено наличие
|
||||
разделов своего типа и число критериев, годность оракулов и полнота границ —
|
||||
глазами».
|
||||
|
||||
Формат записи, меты, слага, индексов и `REJECTED.md` —
|
||||
[references/task-format.md](references/task-format.md); там же тест «готова к
|
||||
взятию». Схема и алгоритм каждого типа — по файлу на тип:
|
||||
[goal](references/task-goal.md) · [feature](references/task-feature.md) ·
|
||||
[fix](references/task-fix.md) · [chore](references/task-chore.md) ·
|
||||
[research](references/task-research.md).
|
||||
|
||||
## Сценарии
|
||||
|
||||
### Завести запись из диалога
|
||||
|
||||
1. **Фильтр.** Делаем прямо сейчас — не заводим. Не пожалеем о потере — не
|
||||
заводим. Родилось три кандидата — покажи их и спроси, какие заводить: молча
|
||||
заведённая пачка и есть тот самый отказ из правила 1.
|
||||
2. **Дедуп.** `list` плюс поиск по слагам, полю «зачем» и телам (`grep -ril`),
|
||||
**включая `REJECTED.md`**. Нашлось среди живых — **дописываем в существующий
|
||||
файл**, а не заводим соседний. Нашлось в `REJECTED.md` — покажи пользователю
|
||||
ту строку и что изменилось с момента отказа (`add` предупредит и сам, но
|
||||
молча заводить нельзя). Две задачи об одном — самая дорогая находка
|
||||
переоценки.
|
||||
3. **Тип** — `--type` обязателен, и он же первое содержательное решение:
|
||||
|
||||
- возможность приложения, а не шаг к ней → `goal`;
|
||||
- снаружи появляется то, чего не было → `feature`;
|
||||
- поведение расходится с заявленным и **воспроизводится** → `fix`
|
||||
(не воспроизводится → `research`);
|
||||
- обслуживание, наблюдаемое поведение не меняется → `chore`;
|
||||
- исход — знание, а не изменение системы → `research`.
|
||||
|
||||
Не подходит ни один — в записи их два, разбирай. Не проходит тест готовности
|
||||
(см. task-format) — это **сырьё**: `--type research`, раздел «Вопрос» пока
|
||||
пуст, место в конце категории. Не делается одним заходом — это не эпик, а
|
||||
несколько задач под одной целью: дроби сразу.
|
||||
4. **Цель — если тип её требует.** У `feature` должен быть `--goal <слаг>`:
|
||||
новая возможность и есть содержание цели. Подходящей нет — либо она
|
||||
заводится (`--type goal`), либо перед тобой не `feature`. У `fix`, `chore` и
|
||||
`research` цели может не быть вовсе, и придумывать её не надо.
|
||||
5. `add …`, затем допиши тело редактором **по схеме своего типа** — шаблон её
|
||||
уже разложил, устав типа объясняет каждый раздел. «Зачем» отвечает «зачем
|
||||
нужна эта задача» — состояние, остаток, боль, — а не пересказывает первый
|
||||
абзац, и пишется **для человека**: не «канонизация внутри транзакции», а
|
||||
«тело 40 МиБ держит блокировку 5 секунд, соседние доставки уходят в отказ».
|
||||
6. `check`.
|
||||
|
||||
### Разобрать находки аудита или ревью
|
||||
|
||||
Ревью и аудиты — тоже источник задач, но с опасностью, зеркальной диалогу: не
|
||||
пять файлов из одной мысли, а сорок файлов из сорока сырых находок. Защита та
|
||||
же, что в самом ревью: кластеризация по причине, дедуп против живых и
|
||||
`REJECTED.md`, находка без свидетельства → сырьё (`research`), а не задача, и карта кластеров
|
||||
пользователю до создания файлов. Порядок, отображение серьёзности и привязка к
|
||||
целям — [references/from-review.md](references/from-review.md).
|
||||
|
||||
### Прийти в репозиторий, где задачи уже как-то ведутся
|
||||
|
||||
Разовая операция: вывести каталог задач из старой раскладки беклога, `TODO.md`,
|
||||
заметок или списка шагов роадмапа — [references/adopt.md](references/adopt.md).
|
||||
Сюда же относится переименование транслитных слагов в английские: оно делается
|
||||
**одним проходом вместе с починкой перекрёстных ссылок**, а не по одному слагу.
|
||||
|
||||
Если переводить надо не только задачи, а весь `docs/` — это скилл
|
||||
`av-dev-docs:canon`, и он зовёт этот сценарий сам на своём шаге.
|
||||
|
||||
### Декомпозиция и штурм сырья
|
||||
|
||||
[references/split.md](references/split.md). Обе операции превращают одну запись в
|
||||
несколько, и у обеих есть проверяемый тест: части должны **мерджиться порознь** и
|
||||
**каждая давать видимую пользу**, а у штурма исход «выкинуть» — полноправный.
|
||||
|
||||
Там же **шов**: где резать, когда допустимых мест несколько. Коротко — по
|
||||
границе, которая одна поднимает метку ревью выше остальных; и не резать, когда
|
||||
обе половины остаются в одной метке, потому что несокращаемый костяк проверок
|
||||
платится за каждую задачу отдельно.
|
||||
|
||||
### Вычитка: два прохода, а не один
|
||||
|
||||
Записи судит **не тот агент, который их написал**: самопроверка текста слабее
|
||||
всего ровно там, где формулировка казалась удачной при написании. Проходов два,
|
||||
и они разные по природе:
|
||||
|
||||
| Проход | Что смотрит | Над чем работает |
|
||||
| --- | --- | --- |
|
||||
| `task-form` | заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность оракулов, предписание процесса, связь со строкой «Завершения» цели | только `items/`, **открывает файл цели** |
|
||||
| `task-wording` | залог и отглагольные, оценка без факта, стоп-слова, англицизмы, жаргон, неизвестный термин, транслит в слаге | `items/` и строки индексов; документы проекта — только как словарь |
|
||||
|
||||
Разделены они не по охвату, а **по глубине**. Язык проверяется по словам и
|
||||
фразам, поштучно; форма записи требует понять, что задача делает, и открыть
|
||||
цель, на которую она ссылается. Слитый проход одну половину делает дорогой, а
|
||||
вторую — поверхностной.
|
||||
|
||||
Модель у обоих одна, `sonnet`, и это не отменяет разреза. Оба судят по
|
||||
**записанному правилу** — семь пунктов формы против правил языка, — а их находка
|
||||
приходит готовой формулировкой, которую читает и отклоняет человек, а не молча
|
||||
реализует оркестратор. Ошибка здесь стоит строки чтения, и платить за неё верхней
|
||||
моделью не за что.
|
||||
|
||||
Каждый устав отказывается от чужой половины прямо: увиденное не по своей части
|
||||
идёт **строкой в границах покрытия**, а не находкой. Две проверки одного места
|
||||
расходятся и начинают спорить, и разнимать их потом дороже, чем не сводить.
|
||||
|
||||
**Порядок — сперва `task-form`.** Его находки меняют решение «брать или не
|
||||
брать», а язык — только цену чтения; и переписанный заголовок бессмысленно
|
||||
вычитывать до того, как он переписан.
|
||||
|
||||
Зовутся они **пачкой, а не на каждую запись**: после заведения нескольких задач,
|
||||
после разбора находок ревью и на переоценке. Передаётся список файлов и — если
|
||||
есть — паспорт, архитектура и конвенции проекта: по ним отличается неизвестный
|
||||
термин от известного.
|
||||
|
||||
Ни один из них ничего не правит. Оба возвращают готовые формулировки, и их
|
||||
подставляет скилл: заголовок — `edit <слаг> --title …`, «зачем» —
|
||||
`edit <слаг> --why …`, остальное редактором. **Заголовок и «зачем» — это то, по
|
||||
чему задачу выбирают, поэтому менять их молча нельзя**: покажи предложенное
|
||||
пользователю вместе с тем, что было. Правки в теле (границы, критерии, язык)
|
||||
применяются сразу.
|
||||
|
||||
Всё, что ловит `tasks.py check`, оба не трогают намеренно.
|
||||
|
||||
### Гигиена полей
|
||||
|
||||
Правится по ходу любой операции, которая задачи касается (но не «заодно» по
|
||||
всему беклогу):
|
||||
|
||||
- **протухшее «зачем»** — задача изменилась, а поле отвечает на старый вопрос;
|
||||
особенно после ответа на вопрос задачи: «Решено: …» на «почему это лежит в
|
||||
беклоге» уже не отвечает. Переписывается `edit <slug> --why …` — он правит
|
||||
мету файла и строку индекса заодно;
|
||||
- **вопрос, застрявший в прозе** — вынимается в раздел «Вопросы» плюс тег
|
||||
`question` (`edit --add-tag question`), иначе он не виден ни `list
|
||||
--questions`, ни правилу «задача с открытым вопросом в набор не берётся»;
|
||||
- **тег, который некому снять** — `question` после ответа снимается `edit
|
||||
--rm-tag question` вместе с записью ответа в тело **и опустошением раздела
|
||||
«Вопросы»**: судит раздел, а не тег (`references/task-format.md`);
|
||||
- **свойство репозитория в рамках** — номер миграции, хеш, версия зависимости:
|
||||
в лежалой задаче протухает молча и становится ложной рамкой. Снимается;
|
||||
снимок берётся при постановке, а не при заведении;
|
||||
- **предписание процесса в теле** — «делать с такой-то меткой ревью», «взять
|
||||
такой-то агент»: это второй дом для правила выбора и путь понизить требования
|
||||
решением, принятым до проектирования. Снимается;
|
||||
- **тип, разошедшийся с задачей** — задача заводилась починкой, а после разбора
|
||||
оказалось, что поведение никогда и не было заявлено: это `feature`, а не `fix`.
|
||||
Правится `edit <slug> --type …`; тип, оставшийся от прошлой формулировки, врёт
|
||||
ровно там, где по нему отбирают, **и требует не тех разделов**: у брошенного
|
||||
`fix` останется «Воспроизведение», которого нечем заполнить;
|
||||
- **сырьё, у которого появился вопрос** — разведка обросла формулировкой, но
|
||||
раздел «Вопрос» так и пуст: она числится сырьём и в спринт не берётся.
|
||||
Записывается вопрос, и `check --fix` поднимает строку из конца категории;
|
||||
- **границы, названные вместо реализации** — «переписать хранилище на новый
|
||||
драйвер» в разделе «Затрагивает» это не граница, а замысел. Границы —
|
||||
`таблица points и её миграция`, `эндпоинт POST /ingest`, `формат отпечатка на
|
||||
диске`. Переписывается перечнем;
|
||||
- **англицизм и термин из ниоткуда** — правится по ходу той же операции, что
|
||||
касается задачи (см. «Как написана задача»). Именно по ходу: беклог не
|
||||
переписывают ради языка.
|
||||
|
||||
## Переносимость
|
||||
|
||||
Скилл независим от **языка программирования, сборки, CI и трекера**: он ничего
|
||||
не знает ни про Go, ни про npm, ни про конкретный багтрекер — задачи для него
|
||||
просто каталог markdown. Текст задач — русский (язык документации проекта);
|
||||
зашита только латиница слага. OpenSpec ему тоже не нужен.
|
||||
|
||||
- **Каталог задач — `docs/tasks`, жёстко**, и `--dir` передаётся явно всегда:
|
||||
раскладка канона одинакова во всех проектах, и искать больше нечего. Каталога
|
||||
нет — код 3 и вопрос человеку; `init` заводит его **только** когда проект
|
||||
действительно новый, а перевод чужой раскладки делает `av-dev-docs:canon`.
|
||||
У скрипта поиск вверх по дереву ещё жив — он для непереведённых проектов, и
|
||||
полагаться на него скилл не должен: молча найденный чужой каталог это дрейф.
|
||||
- **Настройки живут в `docs/.pm.json`**, ключ `tasks`: **имена** файлов и
|
||||
заголовков, и только если они отличаются от умолчания. Один конфиг на весь
|
||||
канон, а не по одному на каталог. Неизвестный ключ — код 3 на любой команде,
|
||||
так что лишнее слово в этом объекте останавливает работу с задачами целиком.
|
||||
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
|
||||
и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет** —
|
||||
второй список разошёлся бы с заголовками молча.
|
||||
|
||||
### Вызов из другого плагина
|
||||
|
||||
`$CLAUDE_PLUGIN_ROOT` раскрывается **только внутри своего плагина**: пайплайн
|
||||
задачи, конвейер ревью и любой другой чужой контекст до `tasks.py` по этой
|
||||
переменной не дотянутся. Мост — **вызов скилла через пространство имён**, а не
|
||||
путь:
|
||||
|
||||
> Чужой контекст зовёт `Skill av-dev-tasks:tasks` и называет, что нужно сделать
|
||||
> («закрой задачу `<слаг>`, реализована»). Скилл разрешает свой
|
||||
> `$CLAUDE_PLUGIN_ROOT` сам. Путь наружу не выносится вовсе.
|
||||
|
||||
Плагина в проекте нет — вызов не разрешится, и вызывающий **не выдумывает путь и
|
||||
не правит индекс руками**, а сообщает в докладе, что учёт задач остаётся за
|
||||
владельцем.
|
||||
|
||||
## Слоты проекта
|
||||
|
||||
Почти всё, что скиллу нужно знать о проекте, отвечает канон структурой: куда
|
||||
переезжает суть реализованной задачи — `openspec/specs`, `adr/`, архив change;
|
||||
какие в проекте оракулы — семантика гейта в `CLAUDE.md`. Отдельными слотами
|
||||
остаётся то, чего из раскладки не вывести. **Проект дописывает в `CLAUDE.md`**:
|
||||
|
||||
1. **Что такое «сделана»** — чем задача выполняется (пайплайн проекта) и что
|
||||
входит в его определение готовности. Скилл требует лишь **форму**: пайплайн
|
||||
проекта пройден + критерии приёмки проверены поимённо.
|
||||
2. **Что считается необратимым** и потому спрашивается у человека всегда
|
||||
(деплой, выкладка наружу, удаление или перезапись данных).
|
||||
|
||||
Ни того ни другого скилл не угадывает: не нашёл — спрашивает пользователя, а не
|
||||
подставляет умолчание.
|
||||
|
||||
## Общее для всех сценариев
|
||||
|
||||
- **Развилки — пользователю.** Через `AskUserQuestion`, с уже сформулированным
|
||||
предварительным суждением (**рекомендация — первым вариантом**). Что выкинуть,
|
||||
под какую цель отнести, какая рамка разведки верна — решение пользователя. Слаг,
|
||||
формулировка, порядок строк в индексе — механика, делаем сами.
|
||||
- **Не больше трёх вопросов за раз.** Пачка длиннее трёх тяжела для ответа;
|
||||
решений больше — веди **несколько итераций** диалога по ≤3, а не один
|
||||
перегруженный запрос. Между итерациями применяй уже решённое.
|
||||
- **Границы покрытия в отчёте.** Любая сессия разбора, штурма или интейка
|
||||
заканчивается строкой «просмотрено N из M, не трогали — …». Отчёт без неё
|
||||
сообщает «беклог разобран», не сообщая, какая его часть осталась нетронутой.
|
||||
- **Ничего не удаляем молча.** Файл исчезает только через `close` — `--reason`
|
||||
(ушла без реализации) или `--implemented` (реализована). Прямого `rm` нет.
|
||||
- **Слаги английские**, kebab-case, не транслит: `tie-break-equal-completeness`,
|
||||
а не `taj-brejk-pri-ravnoj-polnote`. Заголовки, тела и «зачем» — русские.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
Не пишет код, не заводит спеки и предложения об изменении, не берёт задачу в
|
||||
работу — этим занимается пайплайн проекта. Не ведёт спринт и не проводит сессию
|
||||
между спринтами — это `session`. Не решает за пользователя, что важно. Не
|
||||
переоформляет существующие задачи «заодно»: правится то, чего касается операция.
|
||||
@@ -0,0 +1,125 @@
|
||||
# Адаптация каталога задач
|
||||
|
||||
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
|
||||
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
|
||||
после неё проект живёт скиллами `tasks` и `session`.
|
||||
|
||||
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
|
||||
`av-dev-docs:canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
|
||||
форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается,
|
||||
когда переводить надо **только** задачи.
|
||||
|
||||
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
|
||||
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
|
||||
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
|
||||
шагов роадмапа проекта.
|
||||
|
||||
## Три правила, из которых всё следует
|
||||
|
||||
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
|
||||
разложилось по целям и **что не разложилось**, — и только после подтверждения
|
||||
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
|
||||
массовое заведение записей без подтверждения — самый дорогой отказ, потому
|
||||
что разгребает его потом переоценка.
|
||||
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
|
||||
сохраняются, кладбище переносится строка в строку. Переименование слага —
|
||||
не правка, а **перенос ссылок**: он делается одним проходом вместе с
|
||||
переименованием, иначе останутся битые ссылки, которых никто не проверяет.
|
||||
3. **Что не классифицировалось — назвать поимённо.** Проглоченный пункт
|
||||
выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад
|
||||
целиком, с причиной по каждому пункту.
|
||||
|
||||
## Форма: карта — суждение — запись
|
||||
|
||||
Механику несёт `tasks.py adopt`, суждение — ты. Разделено ровно по границе
|
||||
«машина умеет / не умеет»:
|
||||
|
||||
```
|
||||
tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"
|
||||
|
||||
python3 $tk adopt scan --from docs/backlog docs/plan.md TODO.md \
|
||||
--target docs/tasks --out tasks-adopt-plan.json # только чтение
|
||||
python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
||||
--refs docs openspec CLAUDE.md README.md # запись
|
||||
```
|
||||
|
||||
`scan` ничего не пишет, кроме карты: он распознаёт раскладку, собирает записи,
|
||||
поля «зачем», причины, кладбище, помечает похожее на транслит и на открытый вопрос в
|
||||
прозе, и **называет поимённо** то, что не разложилось. `apply` пишет каталог
|
||||
целиком одним проходом и чинит перекрёстные ссылки.
|
||||
|
||||
Между ними — твоя работа, которую машина не сделает:
|
||||
|
||||
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
||||
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
||||
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
||||
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
|
||||
обоснование у них уже есть); тематические скопления задач — цели в
|
||||
**`Направления`** («прочность слияния»,
|
||||
«журнал и пересборка»). Предлагаешь ты, назначает человек;
|
||||
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
||||
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
||||
|
||||
## Порядок
|
||||
|
||||
1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
|
||||
всегда `docs/tasks`. Секции беклога (`--sections`) — по умолчанию
|
||||
`Ядро,Инфра`; если у проекта деление другое по существу, оно называется
|
||||
здесь, а не подгоняется под умолчание, и становится **заголовками `##`
|
||||
индекса** — их единственным домом. В `docs/.pm.json` секции не пишутся.
|
||||
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
|
||||
прохода дадут два несогласованных состояния.
|
||||
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
|
||||
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
|
||||
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
|
||||
работоспособности, а не направлению; у `feature` цель обязательна.
|
||||
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
||||
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
|
||||
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
|
||||
разложилось». Массовые механические решения (слаги, порядок строк) не
|
||||
выносятся — это механика.
|
||||
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
|
||||
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
|
||||
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
|
||||
6. **`tasks.py check`** и доклад.
|
||||
|
||||
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
|
||||
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
|
||||
всё это отказ до того, как на диске появился хотя бы один файл.
|
||||
|
||||
## Переходное состояние — объявляется, а не заминается
|
||||
|
||||
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
|
||||
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
|
||||
быть названо, иначе следующий агент примет пустой беклог за поломку.
|
||||
|
||||
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
|
||||
`check`) и сколько без критериев (`check` их ошибкой не считает, но `sprint
|
||||
take` такую задачу не возьмёт). Закрывается это **порциями переоценки** — шаг 3
|
||||
скилла `session`, 5–8 задач за порцию: проставить цели, превратить «готово,
|
||||
когда» в критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы».
|
||||
|
||||
Готовность к первому спринту — не «`check` зелёный», а «есть 2–5 критериев хотя
|
||||
бы у набора под одну цель».
|
||||
|
||||
## Чего адаптация не делает
|
||||
|
||||
- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
|
||||
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
|
||||
- **Не переписывает подписи ссылок.** `[docs/backlog](docs/tasks/BACKLOG.md)` —
|
||||
цель поправлена, текст остался; это правится глазами, и таких мест немного.
|
||||
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
|
||||
нет. Придуманная цель хуже отсутствующей: под неё соберут спринт.
|
||||
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
|
||||
- Сколько записей перенесено, сколько целей заведено (порядок / темы) и откуда
|
||||
каждая выведена.
|
||||
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
|
||||
файлах — числом, а не «поправлены ссылки».
|
||||
- **Не разложилось**: поимённо, с причиной.
|
||||
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
|
||||
сколько порций закрывается.
|
||||
- `tasks.py check` — результат строкой.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Задачи из аудита и ревью
|
||||
|
||||
Ревью и аудиты — код-ревью, архитектурный проход, аудит безопасности, любой
|
||||
разбор другим агентом — порождают находки, часть которых становится задачами.
|
||||
Это отдельный интейк со своей опасностью, **зеркальной** интейку из диалога.
|
||||
|
||||
- Интейк из диалога грешит переполнением: из одной мысли рождается пять файлов.
|
||||
- Интейк из ревью грешит сваливанием: сорок сырых находок превращаются в сорок
|
||||
файлов. Беклог раздувается, а следующая переоценка склеивает их обратно.
|
||||
|
||||
Защита от сваливания — та же, что в самом ревью: **кластеризация по причине, а
|
||||
не файл-на-находку.** Если у ревью был триаж — половина работы уже сделана, бери
|
||||
его выход. Если нет — триажируй сам, прежде чем заводить.
|
||||
|
||||
## Находка агента — не задача
|
||||
|
||||
Мнение агента — **гипотеза, пока у неё нет свидетельства** (падающий тест,
|
||||
воспроизводимый шаг, положение руководства). Согласие нескольких находок само по себе
|
||||
достоверность не повышает: это один источник, высказавшийся несколько раз.
|
||||
|
||||
Отсюда фильтр входа, поверх обычного «не делаем сейчас + пожалеем о потере»:
|
||||
|
||||
- **Находка со свидетельством**, отложенная к исполнению → **задача**.
|
||||
Свидетельство и последствие переносим в тело — это её «почему», то самое, что
|
||||
переживает запись.
|
||||
- **Находка без свидетельства / низкой уверенности** → **сырьё**: `research`, у
|
||||
которого раздел «Вопрос» и есть недостающее свидетельство («при каких условиях
|
||||
это воспроизводится»). Не `fix`: без `Воспроизведения` его в спринт не
|
||||
возьмут, и правильно — чинить нечего, пока непонятно, что ломается. Судьба
|
||||
сырья — штурм, где либо найдётся подтверждение, либо оно уедет в
|
||||
`REJECTED.md`.
|
||||
- **Уже починено по ходу ревью** → **ничего**. Починенное не заводим.
|
||||
- **Развилка, решённая при ревью** → ничего; решённая «потом» → задача с
|
||||
вопросом в разделе «Вопросы» и тегом `question`.
|
||||
|
||||
## Порядок
|
||||
|
||||
1. **Возьми выход триажа, а не сырые находки.** Сырой отчёт — это симптомы до
|
||||
дедупликации; в нём одна причина размазана по нескольким строкам.
|
||||
2. **Кластеризуй по причине.** Пять находок об одном отсутствующем инварианте —
|
||||
одна задача, а не пять. Класс мелочи (nits, косметика) — **один пакетный
|
||||
файл** со списком пунктов, а не файл на каждую запятую.
|
||||
3. **Дедуп против живых задач и `REJECTED.md`.** Аудит переоткрывает уже
|
||||
заведённое и уже выкинутое. Нашлось среди живых — дописываем находку в
|
||||
существующий файл. Нашлось в `REJECTED.md` — это сигнал: причина отказа могла
|
||||
устареть, выноси пользователю, а не заводи молча заново.
|
||||
4. **Разложи по целям — там, где цель нужна.** Большинство находок ревью это
|
||||
`fix` и `chore`, и **цель им не требуется**: они служат работоспособности, а
|
||||
не направлению, и в спринт входят помимо его цели. Придуманная им цель —
|
||||
ровно то враньё, от которого спасает тип.
|
||||
|
||||
Цель обязательна у находки, которая оказалась **новой возможностью**
|
||||
(`feature`): нашлось поведение, которого никто не заказывал, и его надо
|
||||
либо заказать целью, либо убрать. Подходящей цели нет — заведи её
|
||||
(`add --type goal --section Направления`) в том же проходе.
|
||||
5. **Покажи карту до создания файлов.** Кластер → задача / сырьё / строка в
|
||||
пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через
|
||||
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
|
||||
диалога: массовое заведение файлов без подтверждения — ровно тот отказ, ради
|
||||
которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может
|
||||
заводиться и без поштучного вопроса — но карта пользователю предъявляется
|
||||
всё равно.
|
||||
6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
|
||||
- **тег партии** — `--tag review-ГГГГ-ММ-ДД` (или `audit-<slug>`), чтобы весь
|
||||
заход разбора поднимался одной командой `list --tag …`;
|
||||
- **тип** — `--type`, и он **не по умолчанию `fix`**: починкой считается
|
||||
расхождение с заявленным поведением, а находка «этого свойства никто не
|
||||
заказывал» — это `feature`, находка «не знаем, как поведёт себя драйвер» —
|
||||
`research`. Тип, розданный оптом, врёт ровно там, где по нему потом
|
||||
отбирают, **и требует не тех разделов**: каждому `fix` придётся заполнить
|
||||
`Воспроизведение`, а у находки без свидетельства его нет;
|
||||
- **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством.
|
||||
Без него через месяц не отличить проверенную находку от догадки.
|
||||
7. `tasks.py check`.
|
||||
|
||||
## Куда девается серьёзность, если приоритетов нет
|
||||
|
||||
Приоритетов нет, и отображать серьёзность некуда — но **выкидывать её нельзя**.
|
||||
Правило замены:
|
||||
|
||||
- **тяжёлая находка со свидетельством** → задача под ту цель, которой она
|
||||
угрожает, и **кандидат в ближайший набор**: серьёзность здесь превращается в
|
||||
довод при выборе цели следующего спринта, а не в уровень в файле. Довод
|
||||
записывается причиной в мете (`--reason`), иначе к моменту набора его
|
||||
никто не вспомнит;
|
||||
- **находка, ломающая уже идущий спринт**, — не интейк вовсе: см. правило
|
||||
вторжения в скилле `session`. В беклог она падает, только если врываться не
|
||||
положено;
|
||||
- **низкая уверенность или нет свидетельства** → сырьё (`research` с пустым
|
||||
разделом «Вопрос»);
|
||||
- **мелочь** → строка в пакетный файл;
|
||||
- **уже починено / развилка решена сейчас** → ничего.
|
||||
|
||||
Словарей серьёзности много, и отображать их механически не на что: при сомнении
|
||||
— вопрос пользователю, а не догадка.
|
||||
|
||||
## Поимённая сверка
|
||||
|
||||
Интейк считается выполненным, только если **каждая** находка триажа получила
|
||||
исход: слаг заведённой задачи, ссылку на существующую, строку пакетного файла
|
||||
или запись «не заведена: причина». Нулевой урожай при непустом отчёте триажа
|
||||
виден сразу — и это единственный способ отличить «находок не было» от «не стал
|
||||
заводить». Список составляет не тот, кто отчитывается о заведении.
|
||||
|
||||
Границы покрытия отчёта — то, что ревью проверить **не смогло**, — не находки и
|
||||
в задачи не идут: у них нет предмета. Их место в докладе, не в беклоге.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Источник (какое ревью/аудит, сколько находок на входе).
|
||||
- Свёрнуто в задачи: N кластеров из M находок, со слагами, целями и тегом партии.
|
||||
- Что не заведено и почему: починено инлайн, уже заведено, стало сырьём, ушло в
|
||||
`REJECTED.md`.
|
||||
- Поимённая сверка: находок на входе N, исход есть у N.
|
||||
- `tasks.py check`.
|
||||
@@ -0,0 +1,211 @@
|
||||
# Язык проектных текстов
|
||||
|
||||
**Копия.** Дом — `shared/language.md` в репозитории плагинов; язык общий для
|
||||
документов канона и для задач, и потому не принадлежит ни одному плагину.
|
||||
Правится дом, а не этот файл: расхождение ловит `copies.py` на гейте коммита.
|
||||
|
||||
<!-- копия: язык-доктрина из shared/language.md -->
|
||||
|
||||
Правила — для всего, что пишется словами: задачи и цели, документы канона,
|
||||
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
||||
сообщений программы пользователю — там свои конвенции проекта.
|
||||
|
||||
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
||||
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком.
|
||||
|
||||
## Зачем он здесь
|
||||
|
||||
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
|
||||
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
|
||||
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
|
||||
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
|
||||
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
||||
а это и есть цена, которой мы избегаем.
|
||||
|
||||
## Что взято сверх правил вычитки
|
||||
|
||||
Эти три требования судит человек, а не проход вычитки: находка по ним требует
|
||||
увидеть текст целиком, а не фразу.
|
||||
|
||||
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
||||
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
||||
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
|
||||
собственный вопрос («что это за система», «как сложено», «почему так решили»).
|
||||
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
||||
исход правки.
|
||||
|
||||
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
||||
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
||||
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
||||
ищет её.
|
||||
|
||||
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
|
||||
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
|
||||
столько, чтобы длинный текст можно было просматривать, а не только читать
|
||||
подряд.
|
||||
|
||||
## Что отброшено намеренно
|
||||
|
||||
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
|
||||
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
|
||||
|
||||
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
|
||||
ломает причинную связь, а в решении и в задаче ценность именно в ней:
|
||||
«поэтому», «иначе», «раз так» несут смысл и остаются.
|
||||
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
|
||||
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
|
||||
вводные, которые не меняют смысл предложения.
|
||||
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
|
||||
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
|
||||
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
|
||||
«дописать позже», и такой текст лучше не публиковать.
|
||||
|
||||
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
|
||||
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
<!-- /копия: язык-доктрина -->
|
||||
|
||||
## Правила
|
||||
|
||||
<!-- копия: язык-правила из shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство). Каждое было латинизмом или калькой при живом
|
||||
русском слове, и каждое к моменту снятия жило в трёх-шести файлах разом — то
|
||||
есть выглядело словарём, не будучи им.
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- копия: порог-правки из shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Сопровождение и эксплуатация
|
||||
|
||||
**Копия.** Дом — `shared/operations.md` в репозитории плагинов. Словарь общий для
|
||||
роадмапа, архитектуры и темы ревью `operations`, и не принадлежит ни одному из
|
||||
трёх — правится дом, а не этот файл.
|
||||
|
||||
Скиллу задач он нужен для секции `Сопровождение` в `ROADMAP.md`: она отвечает не
|
||||
на «что приложение будет уметь», а на «чем его держат», и путать эти два вопроса
|
||||
нельзя.
|
||||
|
||||
<!-- копия: сопровождение-словарь из shared/operations.md -->
|
||||
|
||||
Одна тема живёт в трёх местах, и путать их слова нельзя.
|
||||
|
||||
**Сопровождение** — всё, чем держат проект: инструмент и сборка, процесс,
|
||||
выкладка, метрики и логи, инфраструктура, дежурство. **Эксплуатация** — его
|
||||
часть: работа системы на проде. Целое и часть, и никогда наоборот.
|
||||
|
||||
| Место | Уровень | Что там |
|
||||
| --- | --- | --- |
|
||||
| `ROADMAP.md`, секция `Сопровождение` | план | **работы**, которые собираемся делать: цели и их задачи |
|
||||
| `architecture.md`, раздел «Эксплуатация» | состояние | **как устроено сейчас**: где работает, что рядом, кто перезапускает |
|
||||
| тема ревью `operations` | оптика | **чем проверяем**: «это упало через неделю на проде» |
|
||||
|
||||
Слово **«поддержка» не употребляется вовсе** — в нём слышится помощь
|
||||
пользователю, а это другая работа.
|
||||
|
||||
**Граница с возможностями проходит по тому, кто наблюдает.** «Приложение
|
||||
сообщает о своём состоянии» — возможность приложения, её место среди прочих
|
||||
целей: наблюдает пользователь сервиса. «Дежурный видит состояние на одном
|
||||
экране» — сопровождение: наблюдаем мы. Одни и те же метрики попадают в разные
|
||||
секции роадмапа, и это верно — секции отвечают на разные вопросы.
|
||||
|
||||
<!-- /копия: сопровождение-словарь -->
|
||||
@@ -0,0 +1,113 @@
|
||||
# Декомпозиция и мозговой штурм
|
||||
|
||||
Обе операции превращают одну запись в несколько (или в ноль). Разница во входе:
|
||||
декомпозиция дробит **слишком крупную задачу**, штурм прорабатывает **идею**,
|
||||
которая ещё не задача.
|
||||
|
||||
## Тест декомпозиции
|
||||
|
||||
Задачу можно дробить, только если части удовлетворяют **обоим** условиям:
|
||||
|
||||
1. **Мерджатся независимо.** Часть Б не требует, чтобы часть А была уже влита.
|
||||
Есть порядок «сперва А, потом Б, иначе не собрать» → это не декомпозиция, а
|
||||
план реализации: шаги остаются **внутри одного файла**.
|
||||
2. **Каждая — самостоятельный шаг.** Часть, осмысленная только в комплекте с
|
||||
другой, — не задача. Проверяй тестом «готова к взятию» (task-format): какую
|
||||
строку «Завершения» цели двигает **именно эта часть** и какие у неё
|
||||
собственные критерии приёмки. У операционных частей (`fix`, `chore`,
|
||||
`research`) цели может не быть — тогда достаточно собственных критериев.
|
||||
|
||||
Не проходит хотя бы одно — **не дроби**. Ложная декомпозиция плодит файлы,
|
||||
которые нельзя взять поодиночке, и переоценка потом склеивает их обратно.
|
||||
|
||||
## Где резать, если резать можно
|
||||
|
||||
Тест выше говорит, **допустим** ли разрез. Где его провести из нескольких
|
||||
допустимых мест — отвечает шов.
|
||||
|
||||
**Шов — там, где падает метка ревью.** Раздел «Затрагивает» перечисляет
|
||||
границы; если одна строка перечня поднимает метку выше остальных, эта часть и
|
||||
режется отдельно. Пример: задача перекладывает несколько узлов разом и заодно
|
||||
добавляет два поля в существующий ответ. Целиком это `large` — семь проходов по
|
||||
всему диффу, включая два, что держат машину и идут цепочкой. Разрезанная по шву,
|
||||
она даёт `large` на маленькой переложенной части и `medium` на остатке.
|
||||
|
||||
**Считай костяк, а не файлы.** У каждой задачи есть несокращаемые четыре прохода
|
||||
(гейт, спеки, код, триаж), и они платятся за каждую. Разрез, после которого обе
|
||||
половины остаются в одной метке, делает ревью **дороже**: тот же объём
|
||||
проверяется тем же составом, но костяк оплачен дважды. Отсюда правило: **резать,
|
||||
когда разрез снимает дорогой проход с большей части диффа**, и не резать, когда
|
||||
он просто делает файлы мельче.
|
||||
|
||||
**Это планирование, а не предписание процесса.** Метка ревью выбирается по
|
||||
факту изменения — тем, кто его видит, — и в тело задачи не пишется: строка
|
||||
«делать с меткой medium» это ровно тот второй дом правила выбора, который
|
||||
гигиена полей снимает. Шов пользуется меткой как **признаком**, что в задаче
|
||||
две разнородные работы; решение о метке остаётся за конвейером.
|
||||
|
||||
**Цель наследуется.** Все части несут `goal:` родителя: декомпозиция не меняет
|
||||
того, чему работа служит. Если у части цель другая — это признак, что дробили не
|
||||
по той границе, либо что часть вообще из другой работы.
|
||||
|
||||
## Что делать с родителем
|
||||
|
||||
После разделения родитель **не остаётся** третьей висящей строкой:
|
||||
|
||||
- части полностью замещают его → `close <slug> --reason "разложена на a, b"`.
|
||||
`REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись:
|
||||
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
|
||||
наследников, а не археологией git;
|
||||
- родитель осмыслен как **возможность**, а не как шаг → это цель. Тип на месте
|
||||
не меняется (цель живёт в другом индексе): заводится `--type goal` в `ROADMAP.md`,
|
||||
части получают `--goal <новый слаг>`, родитель закрывается с причиной-ссылкой.
|
||||
|
||||
**Промежуточного зонтика между целью и задачей нет.** Тип `epic` упразднён:
|
||||
роль зонтика играет цель, а слишком крупный шаг дробится на шаги помельче под
|
||||
той же целью. Если частям нужен общий заголовок — значит у них общая
|
||||
возможность, и её надо назвать целью, а не заводить временный тип.
|
||||
|
||||
## Когда декомпозиция случается посреди спринта
|
||||
|
||||
Задача, которая **оказалась крупнее задачи**, распознаётся до того, как под неё
|
||||
заведено предложение об изменении: иначе его придётся выбрасывать. Она выходит
|
||||
из набора (`sprint drop … --reason "крупнее задачи"`), уходит на декомпозицию, а
|
||||
спринт продолжается остальными. Части заводятся сразу под той же целью, но в
|
||||
текущий набор **не добавляются** — набор заморожен.
|
||||
|
||||
## Мозговой штурм сырья
|
||||
|
||||
Сырьё — запись типа `research`, у которой раздел «Вопрос» пуст: она не проходит
|
||||
тест «готова к взятию», потому что неясно, что именно делаем. Штурм проясняет —
|
||||
и это **generative-операция, а не applicative**.
|
||||
|
||||
Исход штурма и есть заполненный «Вопрос» (тогда разведку можно брать в спринт)
|
||||
или набор задач с типами, которые из ответа следуют. Третий законный исход —
|
||||
`close --reason`.
|
||||
|
||||
Applicative-штурм («перечисли задачи, следующие из идеи») выдаёт очевидное:
|
||||
перечисляется то, что уже видно в формулировке. Ценное — на уровень выше.
|
||||
|
||||
1. **Сперва — формы, а не задачи.** Предложи **три разные постановки** идеи и
|
||||
назови **компромисс каждой**: что она даёт, чем платит, что оставляет за
|
||||
бортом. Если получилась одна постановка — штурм не состоялся, это
|
||||
applicative.
|
||||
2. **Вынеси формы пользователю** через `AskUserQuestion` с компромиссами. Рамку
|
||||
выбирает он: это продуктовое решение, не механика.
|
||||
3. **Назови цель.** Выбранная форма служит цели — существующей или новой. Идея,
|
||||
для которой цель не находится, скорее всего уезжает в `REJECTED.md`, а не
|
||||
заводится задачей.
|
||||
4. **Только выбранную форму** дроби по тесту декомпозиции выше и проставь
|
||||
критерии приёмки: без них наследники останутся идеями под другим именем.
|
||||
|
||||
**«Выкинуть» — полноправный исход штурма, а не его неудача.** Проработка, честно
|
||||
показавшая, что пользы нет или она несоразмерна цене, — это результат: идея
|
||||
уезжает с этой самой причиной, и та причина гасит её повторное появление.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Идея/задача на входе, выбранная рамка (для штурма), задачи-наследники со
|
||||
слагами, целями и секциями.
|
||||
- Судьба родителя: удалён / стал целью / выкинут с причиной.
|
||||
- `tasks.py check` после правок.
|
||||
- Границы покрытия: какие постановки рассмотрены и какие сознательно отброшены —
|
||||
чтобы штурм не пришлось повторять с нуля.
|
||||
@@ -0,0 +1,60 @@
|
||||
# 🧹 `chore` — обслуживание, наблюдаемое поведение не меняется
|
||||
|
||||
Зависимости, сборка, перенос, чистка, оснастка. Отвечает на **«что нужно
|
||||
сделать»**, глаголом в неопределённой форме.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать |
|
||||
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | нет: цель — это возможность, а здесь её не появляется |
|
||||
| Индекс | `BACKLOG.md` → `SPRINT.md` |
|
||||
| Берётся в спринт | да |
|
||||
|
||||
## Адресат — разработчик, и это законно
|
||||
|
||||
Тест готовности спрашивает «что станет наблюдаемо иначе». У `chore` ответ
|
||||
адресован **разработчику**, а не пользователю: «перестанет собираться два раза»,
|
||||
«уедет последний вызов устаревшего API», «проверки гоняются одной командой».
|
||||
Это ответ, а не отговорка.
|
||||
|
||||
**У `chore` тест готовности слабее честно, а не молча.** Пока типа не было,
|
||||
такие задачи либо не заводились вовсе, либо формулировались как выдуманная
|
||||
пользовательская польза — и то и другое хуже, чем сказать прямо, для кого работа.
|
||||
|
||||
Отсюда же граница: если после задачи меняется то, что видит пользователь, — это
|
||||
не `chore`. Тип, оставшийся от первой формулировки, врёт ровно там, где по нему
|
||||
отбирают.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Проверить, что поведение не меняется.** Меняется — это `feature` или `fix`,
|
||||
и у неё другие требования (цель, воспроизведение).
|
||||
2. **Назвать, что перестанет мешать** — одной фразой, адресуясь разработчику.
|
||||
«Прибраться в модуле X» — не ответ: непонятно, что изменится.
|
||||
3. **Назвать границы** в `Затрагивает`. У обслуживания они часто не в коде:
|
||||
конфиг и его образцы, версия зависимости, команда сборки, файл CI. Границей
|
||||
считается то, у чего есть внешняя сторона и цена изменения.
|
||||
4. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У `chore`
|
||||
оракул обычно самый дешёвый из всех типов: команда, которая раньше падала
|
||||
или требовала трёх шагов, теперь отрабатывает одним.
|
||||
5. **Проверить, что это не «заодно».** Обслуживание любит склеиваться в пачку
|
||||
(«обновить зависимости и переписать сборку и убрать мёртвый код»). Не
|
||||
мерджится порознь — это несколько задач ([split.md](split.md)).
|
||||
6. **Цель не проставлять.** `chore` служит работоспособности, а не направлению,
|
||||
и в набор спринта входит помимо его цели. Работа по сопровождению проекта
|
||||
при этом видна в роадмапе — секцией `Сопровождение`, но целью не становится.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` и `sprint take` смотрят на **наличие непустого** `Затрагивает` и на
|
||||
**число** критериев — ровно то же, что у `feature`. Разница между типами здесь не
|
||||
в строгости проверки, а в том, **кому адресован ответ** на «что станет
|
||||
наблюдаемо иначе», — и это судит человек.
|
||||
@@ -0,0 +1,63 @@
|
||||
# ✨ `feature` — снаружи появляется то, чего не было
|
||||
|
||||
Задача, после которой наблюдаемое поведение меняется в сторону новой
|
||||
возможности. Отвечает на **«что нужно сделать»** и пишется глаголом в
|
||||
неопределённой форме.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать («Печатать поле одним куском кода») |
|
||||
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | **обязательна** |
|
||||
| Индекс | `BACKLOG.md` → `SPRINT.md` |
|
||||
| Берётся в спринт | да |
|
||||
|
||||
**Цель обязательна, и это единственный тип, у которого так.** Новая возможность
|
||||
и есть содержание цели: подходящей нет — либо она заводится, либо перед тобой не
|
||||
`feature`. `sprint take` без цели откажет.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Найти цель или завести её.** Задача без цели, названная функцией, — самый
|
||||
частый способ пронести в беклог работу, которой никто не заказывал.
|
||||
2. **Назвать границы** в разделе `Затрагивает`: эндпоинт или команда, таблица и
|
||||
миграция, формат на диске, публичный тип пакета, внешний сервис. Названы
|
||||
**границы, а не замысел**: «переписать хранилище на новый драйвер» — замысел,
|
||||
`таблица points и её миграция` — граница. Проверяется вопросом «это можно
|
||||
назвать до того, как решено *как* делать?».
|
||||
3. **Написать критерии приёмки** — 2–5 проверяемых утверждений списком, у
|
||||
каждого назван оракул. Не «работает корректно», а «повторный прогон даёт тот
|
||||
же отпечаток — оракул: команда сверки».
|
||||
4. **Сказать, какую строку «Завершения» цели задача двигает.** Одной строкой в
|
||||
теле. Это защита от задачи «отрефакторить X»: она проваливается не потому,
|
||||
что невидима снаружи, а потому, что не находит строки, к которой относится.
|
||||
5. **Проверить, что задача одна.** Отвечается всё, но задача не делается одним
|
||||
заходом и не мерджится целиком — это несколько задач под одной целью, дроби
|
||||
сразу ([split.md](split.md)). Промежуточного зонтика между целью и задачей
|
||||
нет.
|
||||
6. **Реализация** — дело пайплайна проекта, не этого скилла. Закрывается
|
||||
`close <слаг> --implemented`: файл и строка удаляются, суть переезжает в
|
||||
`openspec/specs/` и документацию.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` и `sprint take` смотрят на **наличие непустого** раздела `Затрагивает`,
|
||||
на **число** критериев (меньше двух — отказ, больше пяти — замечание) и на цель.
|
||||
Наличие оракула проверяется **эвристикой** — словом «оракул» в пункте.
|
||||
|
||||
Полнота перечня границ машине не видна: границу, которую забыли назвать, она от
|
||||
отсутствующей не отличает. Настоящий оракул от слова «оракул» тоже не отличает.
|
||||
Поэтому в докладе это называется как есть: «проверено число пунктов и наличие
|
||||
границ, годность оракулов и полнота границ — глазами».
|
||||
|
||||
**Критерии — пол, но расхождение с ними есть дефект критериев.** Видишь, что
|
||||
критерии закрыты, а суть задачи не достигнута — **правь критерии и возвращай
|
||||
задачу**, а не держи невидимое сверх-требование: иначе исполнитель никогда не
|
||||
знает, закончил ли, и мотивирован занижать критерии заранее.
|
||||
@@ -0,0 +1,70 @@
|
||||
# 🐞 `fix` — поведение расходится с заявленным
|
||||
|
||||
Задача о расхождении между тем, что система делает, и тем, что про неё заявлено
|
||||
— в спеке, в инварианте `CLAUDE.md`, в критериях закрытой задачи. Отвечает на
|
||||
**«что нужно сделать»**, глаголом в неопределённой форме, перед ним допускается
|
||||
«не»: «Не отбрасывать молча лишние символы в ходе».
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать |
|
||||
| Обязательные разделы | **`Воспроизведение`**, `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | необязательна |
|
||||
| Индекс | `BACKLOG.md` → `SPRINT.md` |
|
||||
| Берётся в спринт | да |
|
||||
|
||||
## `Воспроизведение` — раздел, которого нет у других типов
|
||||
|
||||
**Не воспроизводится — это `research`, а не `fix`.** Правило было записано и
|
||||
раньше, но проверять его было нечем, и «починки» без единого шага повторения
|
||||
уходили в спринт наравне с остальными. Раздел делает правило проверяемым: он
|
||||
называет, **что сделать, чтобы расхождение проявилось, и что при этом видно
|
||||
вместо ожидаемого**.
|
||||
|
||||
Пишется двумя частями, обе обязательны по смыслу:
|
||||
|
||||
- **шаги или вход** — команда, запрос, файл, последовательность действий;
|
||||
- **что видно и что ожидалось** — «ввод `а1б2` ходит в `a1`, а должен быть
|
||||
отвергнут с ошибкой».
|
||||
|
||||
Это не критерии приёмки и не дублирует их: воспроизведение описывает **сегодня**,
|
||||
критерии — **завтра**. Пропущенное воспроизведение чаще всего означает одно из
|
||||
двух: расхождение приняли на слово, или его вообще нет, а есть недовольство
|
||||
поведением — и тогда это `feature`, а не `fix`.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Воспроизвести.** Не удаётся — это `research`: заведи вопрос «при каких
|
||||
условиях проявляется» и не притворяйся, что чинить есть что.
|
||||
2. **Найти, чему поведение противоречит.** Спека, инвариант, критерий закрытой
|
||||
задачи. Не противоречит ничему — это `feature`: поведение никогда и не было
|
||||
заявлено, а тип, оставшийся от первой формулировки, врёт ровно там, где по
|
||||
нему отбирают.
|
||||
3. **Записать воспроизведение** — шаги и наблюдаемое против ожидаемого.
|
||||
4. **Назвать границы** в `Затрагивает`: починка часто трогает больше, чем
|
||||
кажется по объёму текста, и оценка систематически занижена именно здесь.
|
||||
5. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У починки
|
||||
почти всегда есть парный критерий: **прежнее поведение не сломалось**
|
||||
(«ввод `а1` принимается по-прежнему»). Без него починка чинит одно и ломает
|
||||
соседнее.
|
||||
6. **Цель не выдумывать.** `fix` служит работоспособности, а не направлению, и в
|
||||
набор спринта входит помимо его цели. Придуманная цель — то же враньё, от
|
||||
которого спасает тип.
|
||||
7. **Записать дефект в журнал** `docs/review.md` с пометкой «проскочил / пойман
|
||||
ревью». Проскочившие — проверочный набор для калибровки конвейера; пойманные с
|
||||
оракулом — лучшая опора для прохода ревью: проектные, воспроизводимые,
|
||||
однажды оказавшиеся правдой.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` и `sprint take` смотрят на **наличие непустого** `Воспроизведения` и
|
||||
`Затрагивает` и на **число** критериев. Годность воспроизведения — человеку:
|
||||
шаги, по которым ничего не воспроизводится, машина от годных не отличает, и
|
||||
делать вид, что проверено больше проверенного, хуже, чем не проверять вовсе.
|
||||
@@ -0,0 +1,425 @@
|
||||
# Формат записей и индексов
|
||||
|
||||
Заголовок, мета-блок и строку индекса ставит `tasks.py add` — руками их не
|
||||
пишут. Этот файл описывает **общую форму** любой записи и то, что проверяет
|
||||
`check`; тело дописывает агент.
|
||||
|
||||
Чем разделы тела отличаются от типа к типу, какой алгоритм у каждого типа и что
|
||||
у него обязательно — **отдельным файлом на тип**:
|
||||
|
||||
| Тип | Файл | Одной строкой |
|
||||
| --- | --- | --- |
|
||||
| 🎯 `goal` | [task-goal.md](task-goal.md) | возможность приложения |
|
||||
| ✨ `feature` | [task-feature.md](task-feature.md) | снаружи появляется то, чего не было |
|
||||
| 🐞 `fix` | [task-fix.md](task-fix.md) | поведение расходится с заявленным |
|
||||
| 🧹 `chore` | [task-chore.md](task-chore.md) | обслуживание, поведение не меняется |
|
||||
| 🔬 `research` | [task-research.md](task-research.md) | исход — знание, а не изменение |
|
||||
|
||||
## Файл записи
|
||||
|
||||
`items/<slug>.md`:
|
||||
|
||||
```markdown
|
||||
# 🐞 Не отбрасывать молча лишние символы в ходе
|
||||
|
||||
- **Тип:** fix
|
||||
- **Категория:** Ядро — вышла из спринта: остаток писал нерешённое в журнал
|
||||
- **Зачем:** ввод «а1б2» ходит в a1 — игрок не видит, что ошибся, и винит игру
|
||||
- **Теги:** goal:merge-robustness, sprint:2026-08-03
|
||||
|
||||
Разбор хода читает первые два символа и молча выбрасывает остаток строки.
|
||||
|
||||
## Воспроизведение
|
||||
|
||||
Ввести `а1б2` в свой ход: программа ходит в `a1` и ничего не сообщает.
|
||||
Ожидалось — отказ с ошибкой разбора.
|
||||
|
||||
## Затрагивает
|
||||
|
||||
Разбор строки хода; текст ошибки в выводе партии. Формат сохранения партии
|
||||
не трогается.
|
||||
|
||||
## Критерии приёмки
|
||||
|
||||
- ввод «а1б2» отвергается с ошибкой — оракул: тест разбора
|
||||
- ввод «а1» принимается по-прежнему — оракул: тест разбора
|
||||
|
||||
## Рамки
|
||||
|
||||
Схема не трогается; данные только читаются; перезапуск допустим.
|
||||
|
||||
Связано: решение о канонической форме содержимого.
|
||||
```
|
||||
|
||||
- **Заголовок H1** — он же заголовок строки в индексе, дословно. Начинается
|
||||
**эмодзи типа**, и она **производна**: её ставит `add` и чинит `check --fix`
|
||||
по полю меты. Второго дома у типа нет — эмодзи это его отображение, как
|
||||
строка индекса это отображение файла.
|
||||
- **Форма заголовка — по типу.** Цель отвечает на «что приложение будет уметь»;
|
||||
`feature`, `fix` и `chore` — на «что нужно сделать», глаголом в неопределённой
|
||||
форме, перед ним допускается «не»; `research` называет предмет разведки и
|
||||
формы действия **не несёт намеренно**. Почему так — SKILL.md, «Как написана
|
||||
задача». `check` считает заголовки не в форме действия и печатает число в
|
||||
здоровье; годность формулировки смотрит агент `task-form`.
|
||||
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательны
|
||||
**тип** и **место**, причина после тире желательна (именно она объясняет,
|
||||
почему задача здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и
|
||||
теги необязательны. Нераспознанные поля сохраняются: скрипт правит свои и не
|
||||
трогает чужие.
|
||||
- **Тип — первым полем.** Он решает, что у записи вообще может быть: какие
|
||||
разделы обязательны, нужна ли цель, берётся ли она в спринт, — и читается
|
||||
раньше всего остального. Словарь **закрыт**: `goal` | `feature` | `fix` |
|
||||
`chore` | `research`. Не подходит ни один — это сигнал, что в записи их два и
|
||||
её надо разделить.
|
||||
- **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль.
|
||||
Не пересказ задачи: пересказ уже есть по ссылке. Живёт здесь, а не только в
|
||||
индексе: строка индекса его повторяет и производна от него, `check` сверяет,
|
||||
`check --fix` восстанавливает пропавшую строку **вместе с ним**. Пока поле
|
||||
лежало только в индексе, штатная починка дрейфа теряла его молча и
|
||||
навсегда — а это единственное, по чему задачу выбирают, не открывая.
|
||||
- **Тело** — одна фраза «что станет наблюдаемо иначе», дальше разделы по схеме
|
||||
типа. Пишется на языке документации проекта: предметно, без англицизмов, у
|
||||
которых есть русское слово, и без терминов, которых нет ни в паспорте, ни в
|
||||
архитектуре, ни в конвенциях (правило и его причина — в SKILL.md, раздел «Как
|
||||
написана задача»).
|
||||
|
||||
Тело — не план реализации и не спецификация: принятое и реализованное переезжает
|
||||
в документацию проекта, а файл задачи удаляется.
|
||||
|
||||
### Поле места: «Категория» и «Секция»
|
||||
|
||||
Поле называет, **где числится строка**, и имя у него **зависит от типа**:
|
||||
|
||||
| Тип | Поле | Значения | Что это |
|
||||
| --- | --- | --- | --- |
|
||||
| `goal` | **Секция** | `Запланировано`, `Направления`, `Сопровождение` | часть роадмапа: состояние очереди |
|
||||
| прочие | **Категория** | секции беклога проекта (`Ядро`, `Инфра`, …) | полка домена, в которую задача вернётся из спринта |
|
||||
|
||||
Разные имена потому, что это **разные вещи**. У задачи поле переживает спринт:
|
||||
`sprint drop` возвращает её именно туда. У цели оно называет не полку, а место в
|
||||
очереди работ. Одно имя на два смысла их и смешивало; `check` называет
|
||||
несовпадение дрейфом, `check --fix` переименовывает.
|
||||
|
||||
Имя самого места принадлежит **заголовку индекса** — файл на него лишь
|
||||
ссылается, и принадлежность сверяется по нижнему регистру.
|
||||
|
||||
### Прежние формы, которые читаются, но не пишутся
|
||||
|
||||
Всё это `check` называет дрейфом, а `check --fix` переписывает:
|
||||
|
||||
| Было | Стало |
|
||||
| --- | --- |
|
||||
| префикс `[goal]` / `[idea]` в H1 | поле **Тип** + эмодзи в H1; `[idea]` → `research` |
|
||||
| тег `kind:<род>` | поле **Тип** (род работы стал типом) |
|
||||
| поле **Секция** у задачи | поле **Категория** |
|
||||
| поле **Хук** | поле **Зачем** |
|
||||
| мета одной строкой через `·` | мета списком, поле на строку |
|
||||
|
||||
Единственное, чего `--fix` не делает сам, — **проставить тип записи, у которой
|
||||
его неоткуда взять**: `feature` от `chore` машина не отличает, и подставленное
|
||||
наугад значение врало бы ровно там, где по нему принимают решение. Такие записи
|
||||
он называет поимённо пометкой `НЕОДНОЗНАЧНО`.
|
||||
|
||||
### Затрагивает
|
||||
|
||||
Перечень **границ**, которых изменение касается. Границей считается то, у чего
|
||||
есть внешняя сторона и цена изменения:
|
||||
|
||||
- эндпоинт, команда, форма ответа, код ответа;
|
||||
- таблица, поле, миграция, формат на диске, формат сообщения в очереди;
|
||||
- публичный тип или функция пакета, конфиг и его образцы;
|
||||
- внешний сервис или библиотека, чьё поведение становится нужным.
|
||||
|
||||
Ничего из этого не трогается — так и пишется: «границ не трогает, изменение
|
||||
внутри одного узла». Это ответ, а не пустой раздел.
|
||||
|
||||
**Границы, а не замысел.** «Переписать хранилище на новый драйвер» — замысел;
|
||||
`таблица points и её миграция`, `эндпоинт POST /ingest` — границы. Разница
|
||||
проверяется вопросом «это можно назвать до того, как решено *как* делать?»: если
|
||||
нет, строка описывает реализацию, и её место в предложении об изменении.
|
||||
|
||||
**Свойства репозитория сюда не пишутся** — по той же причине, что и в рамки:
|
||||
имя таблицы стабильно, номер последней миграции протухает молча. Пишется
|
||||
`таблица points и её миграция`, а не `миграция 0042`.
|
||||
|
||||
**Что из этого механизировано.** `check` и `sprint take` смотрят только на
|
||||
**наличие непустого раздела**. Полнота перечня машине не видна: границу, которую
|
||||
забыли назвать, она от отсутствующей не отличает. Раздела нет — отказ во взятии:
|
||||
оценивать нечем.
|
||||
|
||||
**У `goal` и `research` раздела нет** — у первой границы называют её задачи, у
|
||||
второй они становятся известны, когда из разведки родятся задачи.
|
||||
|
||||
### Критерии приёмки
|
||||
|
||||
2–5 проверяемых утверждений **списком** `- …`, **у каждого назван оракул**. Не
|
||||
«работает корректно», а «повторный прогон даёт тот же отпечаток — оракул:
|
||||
команда сверки». Это не второе определение готовности, а проектная
|
||||
конкретизация вопроса «по чему видно, что закончено» из теста готовности ниже:
|
||||
там сказано «признак завершённости», здесь — «признак плюс чем проверяется».
|
||||
|
||||
**Что из этого механизировано.** `check` и `sprint take` считают пункты: меньше
|
||||
двух — отказ («— работает» одной строкой больше не проходит), больше пяти —
|
||||
замечание, обычно это признак, что задача крупнее задачи. Наличие оракула
|
||||
проверяется **эвристикой** — словом «оракул» в пункте, — и потому даёт только
|
||||
замечание: настоящий оракул от слова «оракул» машина не отличает, и делать вид,
|
||||
что проверено больше проверенного, хуже, чем не проверять вовсе.
|
||||
|
||||
**У `research` критериев нет** — её приёмка это записанный ответ, и описывается
|
||||
она разделами «Вопрос» и «Куда ляжет ответ». **У `goal` их заменяет
|
||||
«Завершение».**
|
||||
|
||||
**Критерии — пол, но расхождение с ними есть дефект критериев.** Если приёмщик
|
||||
видит, что критерии закрыты, а суть задачи не достигнута, он **правит критерии и
|
||||
возвращает задачу исполнителю**, а не держит невидимое сверх-требование. Иначе
|
||||
исполнитель никогда не знает, закончил ли, и мотивирован занижать критерии
|
||||
заранее.
|
||||
|
||||
### Рамки
|
||||
|
||||
Одна строка: чего касаться нельзя, что перезапускается, что считается
|
||||
необратимым, трогается ли схема данных. Раздел **допустим у любого типа задачи и
|
||||
ни у одного не обязателен**. **Свойства репозитория сюда не пишутся** — номер
|
||||
последней миграции, версия зависимости, хеш: в лежалой задаче они протухают
|
||||
молча и становятся ложной рамкой. Снимок берётся при постановке, а не при
|
||||
заведении.
|
||||
|
||||
### Вопросы
|
||||
|
||||
Неразобранное решение человека живёт разделом `## Вопросы` **плюс тегом
|
||||
`question`**. Раздел без тега или тег без раздела — дрейф, `check` о нём скажет.
|
||||
|
||||
Раздел `Вопросы` (о решении человека) и раздел `Вопрос` у `research` (предмет
|
||||
разведки) — **разные вещи и разные слова**: первый блокирует взятие, второй его
|
||||
разрешает.
|
||||
|
||||
**Судит факт, а не метка.** Отказ во взятии даёт **непустой раздел «Вопросы»**,
|
||||
независимо от того, стоит ли тег: иначе забывший тег проходил бы, а поставивший
|
||||
спотыкался — стимул ровно обратный записанному правилу. Тег производен: он нужен
|
||||
отбору снаружи файла (`list --questions`, `list --tag question`), и его
|
||||
отсутствие при непустом разделе — замечание, а не лазейка. Тег без раздела тоже
|
||||
отказ, но с другим советом: либо вопрос записан не туда, либо тег пора снять.
|
||||
|
||||
**Ответ на вопрос — три правки, и первая обязательна.** Раздел «Вопросы»
|
||||
опустошается: ответ переезжает в тело решением, а не остаётся вопросом рядом с
|
||||
ответом. Затем снимается тег (`edit <slug> --rm-tag question`) и переписывается
|
||||
«зачем»: «Решено: …» на вопрос «зачем нужна эта задача» уже не отвечает.
|
||||
|
||||
**Порядок именно такой, потому что судит раздел, а не тег.** `sprint take`
|
||||
смотрит в непустой раздел и откажет взять задачу даже со снятым тегом, а `check`
|
||||
на снятый тег при непустом разделе посоветует тег вернуть. Снять тег, не
|
||||
опустошив раздел, — значит закольцевать себя между двумя советами.
|
||||
|
||||
## Файл цели
|
||||
|
||||
Форма та же, разделы и алгоритм — [task-goal.md](task-goal.md).
|
||||
|
||||
```markdown
|
||||
# 🎯 Исход слияния не зависит от порядка доставки
|
||||
|
||||
- **Тип:** goal
|
||||
- **Секция:** Направления
|
||||
- **Теги:** decomposed
|
||||
|
||||
Ради чего: точки из разных доставок сходятся в один часовой объект, и сегодня
|
||||
исход столкновения зависит от порядка доставки, а не от содержания.
|
||||
|
||||
## Завершение
|
||||
|
||||
- повторная доставка тех же точек в другом порядке даёт то же состояние;
|
||||
- накопительная метрика за сутки не уменьшается после повторной доставки;
|
||||
- в логе видно, какая из двух точек выиграла и почему.
|
||||
```
|
||||
|
||||
- **Задачи цели здесь не перечисляются.** Перечень даёт
|
||||
`tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и
|
||||
поехал бы на первой же закрытой задаче.
|
||||
- **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи
|
||||
закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет.
|
||||
Пометка именно **тегом**, а не строкой в теле: только так она проверяется.
|
||||
`check` напоминает о нём у цели без задач замечанием — неразобранная цель
|
||||
законна и зелёного прогона не ломает; `check --fix` сам ставит его цели, у
|
||||
которой задачи есть, а цель с тегом и без задач — прямое приглашение закрыть.
|
||||
- Цель живёт в `ROADMAP.md` и **никогда** — в `BACKLOG.md` или `SPRINT.md`.
|
||||
- **Достигнутая цель не исчезает.** `close <слаг> --implemented` удаляет файл и
|
||||
переносит строку в секцию `Готово` с датой:
|
||||
`- 2026-08-04 \`merge-order\` — Исход слияния не зависит от порядка доставки. …`
|
||||
Ссылки на файл в ней нет — файл удалён, а битая ссылка это ошибка `check`.
|
||||
Поведение живёт в спеках проекта; роадмап отвечает, **когда и в каком порядке**
|
||||
оно появилось.
|
||||
|
||||
## Слаг
|
||||
|
||||
Латиница и цифры, kebab-case, без ведущих, хвостовых и двойных дефисов
|
||||
(`foo-bar`, не `-foo`, `a--b`). Именуется **по сути, а не по текущей
|
||||
формулировке**: заголовок будет переписан при переоценке, а слаг стоит в ссылках
|
||||
из других задач, коммитов и черновиков. **Транслита не заводим** —
|
||||
`tie-break-equal-completeness`, а не `taj-brejk-pri-ravnoj-polnote`: транслит
|
||||
нечитаем для того, кто ищет по смыслу, и не сокращается.
|
||||
|
||||
Переименование слага — не правка, а перенос ссылок: делается одним атомарным
|
||||
проходом по всем местам, где слаг упомянут, иначе останутся битые ссылки,
|
||||
которых никто не проверяет.
|
||||
|
||||
## Индексы
|
||||
|
||||
Строка везде одной формы:
|
||||
|
||||
```markdown
|
||||
- [🐞 Заголовок дословно](items/slug.md) — зачем
|
||||
```
|
||||
|
||||
«Зачем» отвечает на «зачем нужна эта задача» одним предложением: состояние,
|
||||
остаток, боль. Пересказ первого абзаца бесполезен — он уже есть по ссылке.
|
||||
Эмодзи внутри квадратных скобок не украшение: заголовок копируется **дословно**,
|
||||
и тип виден там, где решают «брать или не брать».
|
||||
|
||||
| Файл | Что отвечает | Секции |
|
||||
| --- | --- | --- |
|
||||
| `ROADMAP.md` | что приложение уже умеет и чего ещё не умеет | канонические и в этом порядке: `Запланировано`, `Направления`, `Сопровождение`, `Готово` (англ. `Planned`, `Directions`, `Operations`, `Done`) |
|
||||
| `BACKLOG.md` | что **можно взять** — только задачи | категории проекта (по умолчанию Ядро/Инфра) |
|
||||
| `SPRINT.md` | какая цель (или что её нет) и какой набор заморожен | одна: «Набор» |
|
||||
| `REJECTED.md` | что ушло без реализации и почему | — |
|
||||
|
||||
Шапку `SPRINT.md` пишет `sprint start` — **тем же мета-блоком, что у задачи**:
|
||||
поле на строку, `- **Цель:** [Заголовок](items/slug.md)`, `- **Начат:**` датой,
|
||||
`- **Спринт:**` слагом, которым метится урожай. У спринта без цели
|
||||
(`sprint start --no-goal`) поле «Цель» остаётся на месте и пишется прозой без
|
||||
ссылки — «не названа»: **«цели нет» и «цель потерялась» обязаны различаться**.
|
||||
Поэтому и признак «спринт идёт» — слаг, а не цель: слаг есть у любого спринта,
|
||||
без него нечем метить урожай. Прежняя форма (три поля одной
|
||||
строкой через `·`) читается по-прежнему и уходит сама: файл переписывается на
|
||||
следующем `sprint start` и очищается на `sprint close`.
|
||||
|
||||
Секции — **единственные заголовки `##` в индексе**: любой другой `##` в
|
||||
преамбуле проверка сочтёт секцией.
|
||||
|
||||
**Порядка «по важности» внутри секции беклога нет** — «что делать дальше»
|
||||
отвечает набор спринта. Единственный порядок, который есть, **производен от типа
|
||||
и заполненности**: **сырьё** (`research` без раздела «Вопрос») стоит в конце
|
||||
своей секции, потому что его не берут, и между берущимся оно каждый раз требует
|
||||
открыть файл, чтобы это понять. Проверяет `check`, переставляет `check --fix`,
|
||||
и человек этот порядок не назначает — иначе он был бы приоритетом, которого
|
||||
здесь нет.
|
||||
|
||||
**Секции «блокеры» среди них нет.** Блокер — состояние, а не полка: он живёт до
|
||||
ответа человека, а следы остаются вопросами в файлах задач распущенного спринта.
|
||||
Постоянно пустая секция со старой семантикой «разбираются пачками» противоречила
|
||||
бы правилу «эскалируем немедленно», поэтому `init` её не заводит, а `check`
|
||||
говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её. В секции
|
||||
**`Запланировано`** очередь значима и обосновывается прозой; двигают строку
|
||||
`move <slug> --section Запланировано --after <другой>`. В секции **`Готово`**
|
||||
строки не той формы, что у прочих индексов: дата, слаг, заголовок — как в
|
||||
`REJECTED.md`, и по той же причине (файла уже нет, ссылаться некуда).
|
||||
|
||||
**Секции роадмапа закреплены** — состав, полнота, единство языка и **порядок**
|
||||
проверяются `check`; категории беклога проект называет сам. Почему так —
|
||||
SKILL.md. Порядок закреплён потому, что `Готово` копится: стоя первым,
|
||||
достигнутое отодвигает за экран то, ради чего роадмап открывают чаще всего.
|
||||
|
||||
**Заголовок секции пишется с прописной и отбивается пустой строкой с обеих
|
||||
сторон** — во всех индексах, включая категории беклога, имена которых выбирает
|
||||
проект. Написание канонических секций и отбивку правит `check --fix`; он же
|
||||
сводит написание места в мете файла с заголовком индекса.
|
||||
|
||||
Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`).
|
||||
Строку руками не пишут.
|
||||
|
||||
Отсюда же ответ на «а если оборвётся посередине». Мутация сперва проверяет всё
|
||||
и складывает правки, и только потом пишет: сначала все временные файлы, потом
|
||||
переименования подряд. Полной транзакции на несколько файлов файловая система не
|
||||
даёт, но окно сжато до цепочки переименований, а **всё, что в нём может
|
||||
разъехаться, — производное**: файлы целы, индексы восстанавливает `check --fix`.
|
||||
Поэтому отказ на второй задаче из пяти не оставляет первую переписанной при
|
||||
нетронутых индексах.
|
||||
|
||||
`SPRINT.md` и есть артефакт заморозки: без него набор существует только в
|
||||
контексте сессии, и нарушение заморозки ненаблюдаемо.
|
||||
|
||||
## `REJECTED.md`
|
||||
|
||||
Туда уходит задача, покинувшая беклог **без реализации**. Строку пишет
|
||||
`tasks.py close --reason`, а `check` следит за форматом:
|
||||
|
||||
```markdown
|
||||
- 2026-07-23 `versii-kachestvo-repaki` — Версии и качество одного тайтла.
|
||||
Причина: калибровка болей — не боль, ни разу не возникло за полгода.
|
||||
Была секция: Инфра.
|
||||
```
|
||||
|
||||
Реализованные сюда не попадают: у них остаётся коммит и документация. У
|
||||
выкинутой не остаётся ничего — и через квартал она возвращается тем же текстом.
|
||||
Это первое место, куда смотрит дедупликация при заведении.
|
||||
|
||||
Запись не запрещает завести задачу заново: изменился контекст — заводим и
|
||||
ссылаемся на строку, объясняя, что изменилось.
|
||||
|
||||
## Теги
|
||||
|
||||
Разметка сверх типа. Тип полем, потому что он один и обязателен; теги — потому
|
||||
что их много и `list --tag` уже умеет отбирать по ним порцию разбора.
|
||||
|
||||
- `goal:<слаг>` — цель, которой служит задача. Обязателен **у `feature`**:
|
||||
новая возможность и есть содержание цели. У `fix`, `chore` и `research` его
|
||||
может не быть — они служат работоспособности, а не направлению, и в набор
|
||||
спринта входят помимо его цели.
|
||||
- `question` — в файле есть неразобранный раздел «Вопросы».
|
||||
- `sprint:<слаг>` — задача заведена в этом спринте; по нему отбирается первая
|
||||
порция разбора («урожай спринта»). **Ставится сам**: слаг спринта заводит
|
||||
`sprint start` (по умолчанию — дата начала, он же пишется в `SPRINT.md`), и
|
||||
`add` при открытом спринте помечает заводимое. Тег, который надо помнить
|
||||
ставить руками, не ставится никогда — а на нём висит правило «первая порция
|
||||
разбора — урожай прошедшего спринта».
|
||||
- `decomposed` — на цели: разложена на задачи (см. «Файл цели»).
|
||||
|
||||
Тега `kind:<род>` больше нет: род работы стал типом. Оставшийся в файле `check`
|
||||
называет дрейфом, а `check --fix` снимает, перенеся значение в поле «Тип».
|
||||
|
||||
Отбор — `list --tag a,b`: перечисленные через запятую теги требуются **все
|
||||
сразу** (это И, не ИЛИ). Тег, которого нет ни у одной задачи, `list` называет
|
||||
вслух: молчаливый ноль читается как «таких задач нет», а чаще это опечатка.
|
||||
|
||||
Свои теги проект заводит свободно (партия ревью `review-ГГГГ-ММ-ДД`, тема,
|
||||
источник) — словарь не фиксирован. В индексы теги не выносим: индексы
|
||||
производны, отбор делает `list --tag`, а не глаза.
|
||||
|
||||
## Тест «готова к взятию»
|
||||
|
||||
Задача готова, если из файла отвечаются четыре вопроса. Первый и четвёртый —
|
||||
общие, второй и третий у каждого типа свои и перечислены в его файле.
|
||||
|
||||
1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю,
|
||||
владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет
|
||||
ломаться Y при Z» — ответ. **У `chore` адресат — разработчик, и это
|
||||
законно**: «уедет последний вызов устаревшего API» — ответ, а не отговорка.
|
||||
Тип объявлен как раз затем, чтобы такие задачи не выдумывали себе
|
||||
пользовательскую пользу.
|
||||
2. **Что известно про сегодня** — то, что тип требует знать до работы:
|
||||
у `fix` это `Воспроизведение`, у `research` — `Вопрос`, у `feature` и
|
||||
`chore` — `Затрагивает`.
|
||||
3. **По чему видно, что закончено** — критерии приёмки с оракулами;
|
||||
у `research` вместо них `Куда ляжет ответ`.
|
||||
4. **Какую часть «Завершения» своей цели она двигает** — у задачи с целью.
|
||||
Строкой: «двигает пункт 2 «Завершения» — накопительная метрика перестаёт
|
||||
уменьшаться». Это и есть защита от задачи «отрефакторить X»: она проваливает
|
||||
тест не потому, что невидима снаружи, а потому, что не находит строки, к
|
||||
которой относится. Заодно видно обратное — достаточен ли набор задач для
|
||||
цели: строка «Завершения», к которой не относится ни одна задача, это
|
||||
незакрытая часть возможности.
|
||||
|
||||
**У задачи без цели** (`fix`, `chore`, `research`) вопрос не задаётся: они
|
||||
служат работоспособности, а не направлению.
|
||||
|
||||
Не отвечается первый, второй или третий вопрос → это ещё не задача, а **сырьё**:
|
||||
тип `research` без раздела «Вопрос», место — конец секции, работа над ним —
|
||||
штурм. Не отвечается четвёртый у `feature` → либо цель есть и не проставлена,
|
||||
либо это не новая возможность.
|
||||
|
||||
Отвечается всё, но задача не делается одним заходом и не мерджится целиком →
|
||||
это **несколько задач под одной целью**, дроби сразу. Промежуточного зонтика
|
||||
между целью и задачей нет: тип `[epic]` упразднён, потому что зонтиком стала
|
||||
сама цель.
|
||||
|
||||
Тест применяется при заведении и при переоценке. К старым задачам, которых
|
||||
операция не касается, задним числом не применяется — беклог не переоформляют
|
||||
«заодно».
|
||||
@@ -0,0 +1,93 @@
|
||||
# 🎯 `goal` — возможность приложения
|
||||
|
||||
Цель отвечает на **«что приложение будет уметь»**. Не область работ и не имя
|
||||
подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от порядка
|
||||
доставки». Свойство поведения — тоже возможность.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что приложение будет уметь |
|
||||
| Обязательные разделы | `Завершение` |
|
||||
| Допустимые сверх того | — |
|
||||
| Поле места | **Секция** — часть роадмапа |
|
||||
| Цель (`goal:<слаг>`) | запрещена: цель и есть цель |
|
||||
| Индекс | `ROADMAP.md`, и никогда `BACKLOG.md` или `SPRINT.md` |
|
||||
| Берётся в спринт | нет — берутся её задачи |
|
||||
|
||||
Поле места у цели называется **«Секция»**, а не «Категория», и это не разнобой:
|
||||
у задачи оно называет полку домена, в которую она вернётся из спринта, а у цели
|
||||
— часть роадмапа, то есть состояние очереди. Одно имя на два смысла их и
|
||||
смешивало.
|
||||
|
||||
## «Завершение» — списком, а не абзацем
|
||||
|
||||
Это признаки того, что приложение **уже умеет**, и на строки этого раздела
|
||||
ссылаются задачи цели: «двигает пункт 2 «Завершения» — накопительная метрика
|
||||
перестаёт уменьшаться». Абзацем такая ссылка не берётся, поэтому список.
|
||||
|
||||
Отсюда же читается обратное и более полезное: **строка «Завершения», к которой
|
||||
не относится ни одна задача, — незакрытая часть возможности**. Достаточность
|
||||
набора задач видна из самой цели, а не из чьей-то памяти.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Проверить, что это возможность, а не работа.** Работа, которой держат
|
||||
проект, на вопрос «что приложение будет уметь» не отвечает; состав перечислен
|
||||
[в словаре сопровождения](operations.md). Ей отведена секция
|
||||
`Сопровождение` — там она видна в том же
|
||||
экране и не читается как обещание продукта. Граница проходит по тому,
|
||||
**кто наблюдает**:
|
||||
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
|
||||
состояние на одном экране» — сопровождение.
|
||||
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; про то, чем держат проект,
|
||||
— `Сопровождение`. В `Готово` кладёт сам `close`.
|
||||
3. **Написать «Завершение»** — 2–5 наблюдаемых признаков списком. Пишутся до
|
||||
декомпозиции: иначе задачи придумают себе цель задним числом.
|
||||
4. **Разложить на задачи** и проставить им `goal:<слаг>`. Перечень задач в теле
|
||||
цели **не хранится** — он был бы третьим индексом и поехал бы на первой же
|
||||
закрытой задаче; выводит `tasks.py list --goal <слаг>`.
|
||||
5. **Пометить `decomposed`.** Тег отличает «ещё не разобрана» от «все задачи
|
||||
закрыты» — два состояния с одним внешним признаком. `check --fix` ставит его
|
||||
сам цели, у которой задачи есть.
|
||||
6. **Закрыть достигнутой** — `close <слаг> --implemented`, когда не осталось
|
||||
открытых задач. Файл удаляется, строка с датой переезжает в `Готово`. Скрипт
|
||||
откажет, если задачи ещё живы.
|
||||
|
||||
## Отменённая цель — сперва задачи, потом цель
|
||||
|
||||
Замысел бывает неверен, и цель отменяют, не достигнув. Порядок обратный
|
||||
завершению и держится тем же запретом: цель, закрытая поверх живых задач,
|
||||
оставила бы их сиротами, и `close` этого не даст.
|
||||
|
||||
1. **Разобрать её задачи поштучно.** Задача, теряющая смысл вместе с целью, —
|
||||
`close <slug> --reason "<почему>"`; задача, переживающая цель, — `edit <slug>
|
||||
--goal <другая>`. **Причина обязательна и пишется своя каждой:** «цель
|
||||
отменена» это не причина, а пересказ команды, и в `REJECTED.md` от него нет
|
||||
пользы через квартал.
|
||||
2. **Закрыть саму цель** — `close <слаг> --reason "<почему замысел отменён>"`.
|
||||
Файл удаляется, строка с причиной и датой уходит в `REJECTED.md`. В `Готово`
|
||||
не попадает: `Готово` отвечает «что приложение умеет», а отменённая цель не
|
||||
умеет ничего.
|
||||
|
||||
**Место этому — переоценка на сессии, а не отдельный заход.** Отмена цели значит
|
||||
разбор всех её задач, а разбор задач и есть шаг 3 сессии
|
||||
([cadence.md](../../session/references/cadence.md), пункт 7). Отменять на ходу,
|
||||
между делом, — верный способ закрыть скопом то, что стоило перевесить.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` считает цели, различает разобранные и пустые, ставит `decomposed`,
|
||||
запрещает закрыть цель с живыми задачами и держит `Секцию` в согласии с
|
||||
заголовком роадмапа. **Годность формулировки — не машине**: «возможность это или
|
||||
область работ» решает [агент вычитки](../SKILL.md#вычитка-два-прохода-а-не-один).
|
||||
|
||||
Достигнутая цель **не исчезает**: «что приложение умеет» — половина вопроса, ради
|
||||
которого роадмап открывают. Вторым домом поведения роадмап при этом не
|
||||
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
|
||||
**когда и в каком порядке** оно появилось.
|
||||
@@ -0,0 +1,83 @@
|
||||
# 🔬 `research` — исход работы знание, а не изменение системы
|
||||
|
||||
Ответ на вопрос, замер, разведка, проработка сырой мысли. Приёмка — **записанный
|
||||
ответ**, а не изменённый код.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | о чём разведка (предмет, а не действие) |
|
||||
| Обязательные разделы | `Вопрос`, `Куда ляжет ответ` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | нет |
|
||||
| Индекс | `BACKLOG.md` → `SPRINT.md` |
|
||||
| Берётся в спринт | да — **но только с заполненным «Вопросом»** |
|
||||
|
||||
**Критериев приёмки у `research` нет, и это не поблажка.** Критерии в форме
|
||||
«оракул: тест» разведке натянуты: проверять нечего, пока ответа нет. Её приёмка
|
||||
описывается раздельно — вопрос, на который отвечаем, и место, куда ляжет ответ.
|
||||
|
||||
**Заголовок формы действия не несёт намеренно.** Что делать, ещё неизвестно, и
|
||||
заголовок-действие обещал бы решённость, которой нет. «Подсказка следующего
|
||||
хода», а не «Сделать подсказку следующего хода».
|
||||
|
||||
## Этот тип вобрал прежний `[idea]`
|
||||
|
||||
Тип `idea` упразднён. Он значил не род работы, а **состояние незаполненности** —
|
||||
«первый, второй или третий вопрос теста готовности не отвечается», — а состояние
|
||||
типом быть не может: оно меняется по мере того, как запись дописывают, а тип
|
||||
меняют командой.
|
||||
|
||||
Теперь это состояние называется честно: **`research` без раздела «Вопрос» — это
|
||||
сырьё**.
|
||||
|
||||
| | сырьё | разведка |
|
||||
| --- | --- | --- |
|
||||
| Раздел `Вопрос` | пуст или отсутствует | заполнен |
|
||||
| `sprint take` | отказ | берёт |
|
||||
| Место в секции беклога | **конец**, `check --fix` сносит туда сам | среди прочих |
|
||||
| `tasks.py list --raw` | показывает | нет |
|
||||
|
||||
Порядка «по важности» в беклоге по-прежнему нет. Этот порядок **производен от
|
||||
типа и заполненности**, а не назначен человеком, — потому его и проверяет машина,
|
||||
и потому он не противоречит правилу «порядка нет, есть цель».
|
||||
|
||||
Сырьём заводится и **сырая функция**: «Подсказка следующего хода» — ещё не
|
||||
`feature`, потому что неизвестно, что именно делать. Работа над ней — думание, и
|
||||
её исход — либо задачи, либо отказ.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Записать вопрос одной фразой.** Не тему, а вопрос: не «Разобраться с
|
||||
выводом в терминалах», а «Какими символами рамки печатаются одинаково в
|
||||
Терминале, iTerm и `tmux`». Вопроса ещё нет — запись заводится сырьём и
|
||||
лежит в конце секции, пока вопрос не появится.
|
||||
2. **Назвать, куда ляжет ответ**: `docs/research/<slug>.md`, ADR, тело этой
|
||||
задачи. Место называется **заранее**, иначе ответ остаётся в переписке, а
|
||||
через квартал разведку заказывают заново.
|
||||
3. **Ограничить рамками**, если разведка может утечь: сколько времени, какие
|
||||
источники, что заведомо вне.
|
||||
4. **Провести разведку** и **записать ответ по названному адресу**. Числа — с
|
||||
провенансом: с командой или условиями, которыми получены. Число без источника
|
||||
проход ревью обязан читать как условие, а не как замер.
|
||||
5. **Разложить исход на задачи** — если он их родил. Разведка кончается одним из
|
||||
трёх: заведены задачи, записано знание, отказ. **Отказ — полноправный исход**:
|
||||
«проверили, не проблема» экономит спринт.
|
||||
6. **Закрыть** — `close <слаг> --implemented`, когда ответ записан. Файл
|
||||
удаляется: запись ответа и есть след, второго не нужно. Ушла без ответа —
|
||||
`close --reason`, и строка уезжает в `REJECTED.md`.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` и `sprint take` смотрят на **наличие непустых** разделов `Вопрос` и
|
||||
`Куда ляжет ответ`, считают сырьё отдельной строкой здоровья и держат его в конце
|
||||
секции. Годность вопроса — человеку: «вопрос это или тема» машина не различает,
|
||||
и `check` о годности молчит намеренно.
|
||||
|
||||
Штурм сырья, дробление исхода на задачи и тест «части мерджатся порознь» —
|
||||
[split.md](split.md).
|
||||
Executable
+3458
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user