Files

T

init заводит openspec сам; конфиг стал слотом канона

Каталог openspec/ был предпосылкой, о которой канон говорил, но за которой не
следил. openspec/specs/ объявлен домом темы requirements, config.yaml описан
абзацем — а заводилось всё руками, и не проверялось ничего. Новый проект выходил
из init с полным каноном документов и без каталога, без которого не работают ни
opsx:propose, ни ревью дизайна, ни сверка требований.

Теперь init делает openspec init --tools claude шагом 3, до первого документа, а
adopt заводит его тем же способом, если на переводимом проекте его нет. Команда
названа поимённо в трёх местах — скилле, каноне и отказе docs.py: отказ без
команды заставляет искать её в другом месте.

Файл из коробки оказался хуже отсутствующего, и потому проверяется машиной.
openspec init кладёт config.yaml, где context и rules — закомментированный пример
на английском. Такой файл читается как настроенный: он есть, он валиден, имя
правильное. Работает он как пустой, и узнаётся это по уже написанному
предложению — на другом языке, с capability по имени пакета, без единого SHALL.
docs.py проверяет четыре вещи, каждая про молчащий пробел: каталог есть; имя
именно config.yaml (config.yml OpenSpec не читает и об этом не сообщает); context
и rules.specs не остались примером, а правила называют SHALL; context называет
passport и CLAUDE.md. Последние два обязательны по порядку работы: предложение
пишется до того, как кто-либо откроет docs/, и без этих строк его пишут, не зная
ни границы домена, ни инвариантов.

Форма конфига записана скелетом и сформулирована разрезом: утверждение, которое
можно опровергнуть, открыв другой файл проекта, — пересказ; строка, которая
говорит, какой файл открыть, — ссылка. Машина этот разрез не проверяет, отличить
одно от другого она не умеет; он отдан doc-consistency отдельным абзацем правила
«один факт — один дом», и config.yaml добавлен ему во вход. Место второго дома
там самое частое: context читается при порождении каждого артефакта, туда удобно
дописать «чтобы агент знал», и так заводятся копии инвариантов, конвенций,
состава гейта и правил ревью.

Образец лёг в канон, а не в конвейер, как планировало решение C: форма документа
принадлежит владельцу канона документов, конвейер её читатель. Иначе
av-dev-pipeline завёл бы описание файла, который заводит и проверяет av-dev-pm.

Канон повышен до версии 7 с записью, выполнимой upgrade: завести openspec,
привести config.yaml к скелету, вычистить из context пересказ, проверить имя
файла, поднять номер в .pm.json. Проверка прогнана на четырёх фикстурах — свежий
openspec init, два живых проекта и пустой каталог; отличает все четыре случая.
Решение — 47.

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

2026-08-07 11:59:01 +03:00

9.7 KiB

Raw Blame History

name, description

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

name

description

init

Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в роадмапе и скелет остальных документов. Заводит и OpenSpec (openspec init) с настроенным openspec/config.yaml — дом темы requirements, без которого не работают ни propose, ни ревью. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл 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` — журнал пуст, настройка появится с первым ревью
`openspec/config.yaml`

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

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

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

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

Как вести

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

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

Прочитай бриф целиком. Выпиши, на какие блоки интервью ответ уже есть.
Проведи интервью итерациями по ≤3 вопроса.
Заведи OpenSpec: openspec init --tools claude. Каталог openspec/ — часть канона, а не соседняя технология: в нём дом темы requirements, и без него не работают ни opsx:propose, ни ревью дизайна, ни сверка требований. Команда кладёт ещё .claude/skills/openspec-* и .claude/commands/opsx/* — это её нормальная работа, не трогай их.
Заведи docs/.pm.json с текущей версией канона.
Напиши заполняемые документы. Бриф переезжает в passport.md и отдельным файлом не остаётся: два дома для одного замысла разойдутся на первом же уточнении.
Заведи скелет остальных по скелетам — каждый с честной строкой.
Заполни openspec/config.yaml по тем же скелетам. Файл из коробки — закомментированный пример на английском; он заменяется целиком, потому что нетронутый выглядит настроенным, а работает как пустой. Пиши туда только то, что нужно в момент порождения артефакта: язык, правила именования capability, придирки валидатора и адреса docs/passport.md и CLAUDE.md. Инварианты, конвенции и правило ревью не пересказывай — у них есть дома, и второй дом разойдётся с первым молча.
Каталог задач и первые цели — вызови скилл av-dev-pm:tasks: он владеет форматом целей и задач.
docs.py check из скилла canon — до отсутствия дрейфа. Замечания о незаполненных плейсхолдерах остаются: их закрывает не init, а работа.
Покажи человеку, что получилось, и отдельным списком — что выведено из брифа, что предположено, что осталось неизвестным. Правят по этим строкам.

Что дальше

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

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

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

9.7 KiB Raw Blame History Unescape Escape