avandClaude Opus 5
a79266cfcb
Каталог 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>
111 lines
9.7 KiB
Markdown
111 lines
9.7 KiB
Markdown
---
|
||
name: init
|
||
description: "Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром, первые цели в роадмапе и скелет остальных документов. Заводит и OpenSpec (openspec init) с настроенным openspec/config.yaml — дом темы requirements, без которого не работают ни propose, ни ревью. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл canon."
|
||
---
|
||
|
||
# Заведение нового проекта
|
||
|
||
Вход — свободный текст «что мне нужно и почему». Выход — канон документов, с
|
||
которого дальше работают все остальные скиллы.
|
||
|
||
**Определение канона — [канон](../canon/references/canon.md).** Прочитай его до
|
||
первого вопроса: интервью идёт по слотам канона, а не по вкусу. Что класть в
|
||
каждый файл — [скелеты](../canon/references/skeletons.md); не выдумывай заглушки
|
||
своей формы, `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»: «архитектуры пока нет: кода нет,
|
||
заводится первой задачей». Проход читает её как факт.
|
||
|
||
## Порядок интервью — зависимость, а не удобство
|
||
|
||
Каждый блок опирается на ответ предыдущего; переставлять нельзя.
|
||
|
||
1. **Цель и потребители.** Ради чего это; кто пользуется — список закрытый, и
|
||
он определяет, что считать нужным, а что интересным.
|
||
2. **Чем это НЕ является и мера успеха.** Граница домена — критерий, по
|
||
которому потом судят в теме `architecture` о переносе понятия. Мера — по чему
|
||
поймём, что удалось.
|
||
3. **Периметр и недоверенный вход.** Открыт наружу или контур доверенный; что
|
||
приходит извне и каким каналом; что чувствительнее чего. Контур ещё не
|
||
развёрнут — назови **оба** периметра, целевой и сегодняшний.
|
||
4. **Стек, хранилище, необратимое.** Чем пишем и почему; где данные; что в этом
|
||
проекте нельзя откатить — деплой, выкладка наружу, перезапись данных.
|
||
5. **Чем краснеет гейт.** Какие проверки обязательны; что красит безусловно;
|
||
чего в гейте намеренно не будет и кто тогда это гоняет.
|
||
6. **Первые цели.** Возможности приложения, а не задачи: три-пять целей в
|
||
`Запланировано`, каждая — ответ на «что приложение будет уметь», с
|
||
обоснованием очереди прозой.
|
||
|
||
### Как вести
|
||
|
||
- **Не больше трёх вопросов за итерацию** (`AskUserQuestion`), рекомендация
|
||
первым вариантом. Между итерациями применяй уже решённое.
|
||
- **Сперва вычитай ответы из брифа.** Если ответ уже есть в тексте, вопрос не
|
||
задавай — покажи своё прочтение и спроси, верно ли.
|
||
- **Не выдумывай четыре вещи:** периметр, что необратимо, измеренные числа и
|
||
адресата дорогой проверки. Их из замысла не вывести. Не сказано — пиши
|
||
«неизвестно» с пометкой, что ждёт ответа.
|
||
- **Развилка замысла — человеку, механика — сама.** Имена файлов, слаги, порядок
|
||
строк не выноси.
|
||
|
||
## Порядок работы
|
||
|
||
1. Прочитай бриф целиком. Выпиши, на какие блоки интервью ответ уже есть.
|
||
2. Проведи интервью итерациями по ≤3 вопроса.
|
||
3. **Заведи OpenSpec: `openspec init --tools claude`.** Каталог `openspec/` —
|
||
часть канона, а не соседняя технология: в нём дом темы `requirements`, и без
|
||
него не работают ни `opsx:propose`, ни ревью дизайна, ни сверка требований.
|
||
Команда кладёт ещё `.claude/skills/openspec-*` и `.claude/commands/opsx/*` —
|
||
это её нормальная работа, не трогай их.
|
||
4. Заведи `docs/.pm.json` с текущей версией канона.
|
||
5. Напиши заполняемые документы. **Бриф переезжает в `passport.md`** и
|
||
отдельным файлом не остаётся: два дома для одного замысла разойдутся на
|
||
первом же уточнении.
|
||
6. Заведи скелет остальных по [скелетам](../canon/references/skeletons.md) —
|
||
каждый с честной строкой.
|
||
7. **Заполни `openspec/config.yaml`** по тем же скелетам. Файл из коробки —
|
||
закомментированный пример на английском; он **заменяется целиком**, потому что
|
||
нетронутый выглядит настроенным, а работает как пустой. Пиши туда только то,
|
||
что нужно **в момент порождения артефакта**: язык, правила именования
|
||
capability, придирки валидатора и **адреса** `docs/passport.md` и `CLAUDE.md`.
|
||
Инварианты, конвенции и правило ревью не пересказывай — у них есть дома, и
|
||
второй дом разойдётся с первым молча.
|
||
8. Каталог задач и первые цели — **вызови скилл `av-dev-pm:tasks`**: он владеет
|
||
форматом целей и задач.
|
||
9. `docs.py check` из скилла `canon` — до отсутствия дрейфа. Замечания о
|
||
незаполненных плейсхолдерах остаются: их закрывает не `init`, а работа.
|
||
10. Покажи человеку, что получилось, и **отдельным списком** — что выведено из
|
||
брифа, что предположено, что осталось неизвестным. Правят по этим строкам.
|
||
|
||
## Что дальше
|
||
|
||
- Содержимое канона по ходу разработки ведёт скилл `docs`.
|
||
- Раскладку проверяет `canon check`.
|
||
- Первую задачу берёт пайплайн проекта; `architecture.md` и `conventions/`
|
||
наполняются его шагом синка, а не заранее.
|
||
|
||
## Чего этот скилл не делает
|
||
|
||
- **Не проектирует систему.** Архитектура выводится из кода, а не наоборот.
|
||
- **Не пишет код** и не заводит сборку.
|
||
- **Не переводит существующий проект** — это `canon adopt`. Признак: в
|
||
репозитории уже есть документация или беклог в какой-то раскладке.
|
||
- **Не решает за человека**, что важно: цель, границы и периметр — его ответы.
|