Files

T

канон версии 3: роадмап, род работы, границы задачи

Три изменения одной версией, потому что все три про одно — можно ли
оценить задачу, не открывая код.

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

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

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

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

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-04 16:49:58 +03:00

8.0 KiB

Raw Blame History

name, description

name	description
init	Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в роадмапе и скелет остальных документов. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon.

name

description

init

Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в роадмапе и скелет остальных документов. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon.

Заведение нового проекта

Вход — свободный текст «что мне нужно и почему». Выход — канон документов, с которого дальше работают все остальные скиллы.

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

Что `init` физически не может произвести

В новом репозитории нет кода, а architecture.md, database.md, conventions/ и research/ выводятся из него. Их сочинение на старте — это проектирование вперёд реальности, и оно протухнет раньше первой задачи.

Поэтому init заполняет то, что человек знает до первой строки кода:

Заполняется	Остаётся скелетом с честной строкой
`passport.md`	`architecture.md`
`CLAUDE.md`	`database.md`
`security.md`	`conventions/`
`docs/tasks/ROADMAP.md` — первые цели	`research/`, `adr/`
`docs/.pm.json`	`review.md` — журнал пуст, настройка появится с первым ревью

Честная строка информативна, а не «TBD»: «архитектуры пока нет: кода нет, заводится первой задачей». Проход читает её как факт.

Порядок интервью — зависимость, а не удобство

Каждый блок опирается на ответ предыдущего; переставлять нельзя.

Цель и потребители. Ради чего это; кто пользуется — список закрытый, и он определяет, что считать нужным, а что интересным.
Чем это НЕ является и мера успеха. Граница домена — критерий, по которому архитектурный проход потом судит о переносе понятия. Мера — по чему поймём, что удалось.
Периметр и недоверенный вход. Открыт наружу или контур доверенный; что приходит извне и каким каналом; что чувствительнее чего. Контур ещё не развёрнут — назови оба периметра, целевой и сегодняшний.
Стек, хранилище, необратимое. Чем пишем и почему; где данные; что в этом проекте нельзя откатить — деплой, выкладка наружу, перезапись данных.
Чем краснеет гейт. Какие проверки обязательны; что красит безусловно; чего в гейте намеренно не будет и кто тогда это гоняет.
Первые цели. Направления, а не задачи: три-пять целей в «порядок», с обоснованием очереди прозой.

Как вести

Не больше трёх вопросов за итерацию (AskUserQuestion), рекомендация первым вариантом. Между итерациями применяй уже решённое.
Сперва вычитай ответы из брифа. Вопрос, ответ на который в тексте уже есть, задавать не надо — покажи своё прочтение и спроси, верно ли.
Не выдумывай четыре вещи: периметр, что необратимо, измеренные числа и адресата дорогой проверки. Их из замысла не вывести. Не сказано — пиши «неизвестно» с пометкой, что ждёт ответа.
Развилка замысла — человеку, механика — сама. Имена файлов, слаги, порядок строк не выносятся.

Порядок работы

Прочитай бриф целиком. Выпиши, на какие блоки интервью ответ уже есть.
Проведи интервью итерациями по ≤3 вопроса.
Заведи docs/.pm.json с текущей версией канона.
Напиши заполняемые документы. Бриф переезжает в passport.md и отдельным файлом не остаётся: два дома для одного замысла разойдутся на первом же уточнении.
Заведи скелет остальных по скелетам — каждый с честной строкой.
Каталог задач и первые цели — вызови скилл av-dev-pm:tasks: он владеет форматом целей и задач.
docs.py check из скилла canon — до отсутствия дрейфа. Замечания о незаполненных плейсхолдерах остаются: их закрывает не init, а работа.
Покажи человеку, что получилось, и отдельным списком — что выведено из брифа, что предположено, что осталось неизвестным. Правят по этим строкам.

Что дальше

Содержимое канона по ходу разработки ведёт скилл docs.
Раскладку проверяет canon check.
Первую задачу берёт пайплайн проекта; architecture.md и conventions/ наполняются его шагом синка, а не заранее.

Чего этот скилл не делает

Не проектирует систему. Архитектура выводится из кода, а не наоборот.
Не пишет код и не заводит сборку.
Не переводит существующий проект — это canon adopt. Признак: в репозитории уже есть документация или беклог в какой-то раскладке.
Не решает за человека, что важно: цель, границы и периметр — его ответы.

8.0 KiB Raw Blame History Unescape Escape