av
de12a4d8a3
Каталоги, агенты и общие дома переехали в av-dev/; скиллы названы по прежнему плагину — doc-*, task-*, code-*, с двумя смысловыми именами вместо тавтологии: doc-sync вместо docs, task-track вместо tasks. Манифесты сведены к двум плагинам. Пространства имён вызовов и пути внутри дерева переписаны машинно; проза, которая называет прежние плагины отдельными, идёт следующим шагом.
157 lines
14 KiB
Markdown
157 lines
14 KiB
Markdown
---
|
||
name: doc-init
|
||
description: "Завести новый проект — сессия вопросов и ответов по свободному описанию замысла, из которой рождается первичная документация по канону av-dev: паспорт, CLAUDE.md с инвариантами и командами, модель угроз с периметром и скелет остальных документов; первые цели собирает интервью, а записывает их вызовом скилла av-dev:task-track — роадмап принадлежит плагину задач. OpenSpec заводит не сам, а вызовом скилла av-dev:code-openspec — каталог принадлежит конвейеру; плагина конвейера нет — шаг пропускается строкой доклада. Использовать, когда начинают новый проект с нуля, когда есть только текст «что мне нужно и почему» и надо превратить его в рабочую документацию, когда просят провести стартовое интервью по брифу. Проект, где документация уже как-то ведётся, переводит скилл 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/.docs.json` | `research/`, `adr/` |
|
||
| | `review.md` — журнал пуст, настройка появится с первым ревью |
|
||
|
||
Честная строка информативна, а не «TBD»: «архитектуры пока нет: кода нет,
|
||
заводится первой задачей». Проход читает её как факт.
|
||
|
||
**`tasks/ROADMAP.md` в таблице нет намеренно.** Первые цели `init` собирает
|
||
интервью (блок 6), но записывает их не он: каталогом задач и формой целей владеет
|
||
`av-dev:task-track`, и это шаг 7. Плагина нет — цели остаются списком в докладе,
|
||
роадмапа в проекте не появляется, и это говорится строкой.
|
||
|
||
## Порядок интервью — зависимость, а не удобство
|
||
|
||
Каждый блок опирается на ответ предыдущего; переставлять нельзя.
|
||
|
||
1. **Цель и потребители.** Ради чего это; кто пользуется — список закрытый, и
|
||
он определяет, что считать нужным, а что интересным.
|
||
2. **Чем это НЕ является и мера успеха.** Граница домена — критерий, по
|
||
которому потом судят в теме `architecture` о переносе понятия. Мера — по чему
|
||
поймём, что удалось.
|
||
3. **Периметр и недоверенный вход.** Открыт наружу или контур доверенный; что
|
||
приходит извне и каким каналом; что чувствительнее чего. Контур ещё не
|
||
развёрнут — назови **оба** периметра, целевой и сегодняшний.
|
||
4. **Стек, хранилище, необратимое.** Чем пишем и почему; где данные; что в этом
|
||
проекте нельзя откатить — деплой, выкладка наружу, перезапись данных.
|
||
5. **Чем краснеет гейт.** Какие проверки обязательны; что красит безусловно;
|
||
чего в гейте намеренно не будет и кто тогда это гоняет.
|
||
6. **Первые цели.** Возможности приложения, а не задачи: три-пять целей в
|
||
`Запланировано`, каждая — ответ на «что приложение будет уметь», с
|
||
обоснованием очереди прозой.
|
||
|
||
### Как вести
|
||
|
||
- **Не больше трёх вопросов за итерацию** (`AskUserQuestion`), рекомендация
|
||
первым вариантом. Между итерациями применяй уже решённое.
|
||
- **Сперва вычитай ответы из брифа.** Если ответ уже есть в тексте, вопрос не
|
||
задавай — покажи своё прочтение и спроси, верно ли.
|
||
- **Не выдумывай четыре вещи:** периметр, что необратимо, измеренные числа и
|
||
адресата дорогой проверки. Их из замысла не вывести. Не сказано — пиши
|
||
«неизвестно» с пометкой, что ждёт ответа.
|
||
- **Развилка замысла — человеку, механика — сама.** Имена файлов, слаги, порядок
|
||
строк не выноси.
|
||
|
||
## Обращение к соседним плагинам
|
||
|
||
Два шага порядка работы — вызовы чужого: OpenSpec заводит конвейер, каталог задач
|
||
ведёт плагин задач. Ни того, ни другого `init` не делает руками.
|
||
|
||
**Копия.** Дом правила — `shared/plugin-boundary.md` в репозитории плагинов.
|
||
Правится дом, а не этот файл.
|
||
|
||
<!-- копия: граница-плагинов из av-dev/shared/plugin-boundary.md -->
|
||
|
||
Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на
|
||
месте.
|
||
|
||
**Чужой скилл зовётся полным именем** — `av-dev:doc-canon`, `av-dev:task-track`,
|
||
`av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную копию
|
||
из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении.
|
||
|
||
**Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт
|
||
только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо
|
||
откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он
|
||
прочитает его сам.
|
||
|
||
**Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови
|
||
строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя,
|
||
пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже.
|
||
|
||
**Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня
|
||
установленных плагинов проект не ведёт — он разошёлся бы с действительностью
|
||
молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.docs.json` —
|
||
канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер.
|
||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||
|
||
<!-- /копия: граница-плагинов -->
|
||
|
||
Чем оборачивается отсутствие каждого — на самих шагах 3 и 7. Заведение проекта
|
||
из-за этого не останавливается: проект без конвейера и без учёта задач законен.
|
||
|
||
## Порядок работы
|
||
|
||
1. Прочитай бриф целиком. Выпиши, на какие блоки интервью ответ уже есть.
|
||
2. Проведи интервью итерациями по ≤3 вопроса.
|
||
3. **OpenSpec — вызови Skill `av-dev:code-openspec`.** Он заводит каталог и
|
||
заменяет пример в `config.yaml` настройкой. Делается это **до первого
|
||
документа**: без `openspec/` не работают ни `opsx:propose`, ни ревью дизайна,
|
||
ни сверка требований. Каталог принадлежит конвейеру, а не канону, поэтому
|
||
здесь только вызов — ни команды, ни формы файла `init` не знает.
|
||
|
||
**Вызов не разрешился** — проект без конвейера живёт без OpenSpec законно:
|
||
строка доклада, и дальше; `docs.py check` о каталоге тоже промолчит.
|
||
4. Заведи `docs/.docs.json` с текущей версией канона — число берётся из
|
||
`docs.py version`, а не из памяти.
|
||
5. Напиши заполняемые документы. **Бриф переезжает в `passport.md`** и
|
||
отдельным файлом не остаётся: два дома для одного замысла разойдутся на
|
||
первом же уточнении.
|
||
6. Заведи скелет остальных по [скелетам](../canon/references/skeletons.md) —
|
||
каждый с честной строкой.
|
||
7. Каталог задач и первые цели — **вызови скилл `av-dev:task-track`**: он владеет
|
||
форматом целей и задач. Не разрешился — учёт задач остаётся владельцу, и это
|
||
тоже строка доклада.
|
||
8. `docs.py check` из скилла `canon` — до отсутствия дрейфа. Замечания о
|
||
незаполненных плейсхолдерах остаются: их закрывает не `init`, а работа.
|
||
9. **Вычитай написанное — агент `doc-wording`**, по пачке заполненных документов
|
||
(`passport.md`, `CLAUDE.md`, `security.md`). Здесь он нужен сильнее, чем где
|
||
бы то ни было: весь текст сочинён только что и по свободному брифу человека, а
|
||
бриф — это как раз залог, оценки без факта и жаргон. Скелеты с честной строкой
|
||
в пачку не клади, вычитывать в них нечего. Находки — готовые формулировки,
|
||
подставляешь их ты.
|
||
10. Покажи человеку, что получилось, и **отдельным списком** — что выведено из
|
||
брифа, что предположено, что осталось неизвестным. Правят по этим строкам.
|
||
|
||
## Что дальше
|
||
|
||
- Содержимое канона по ходу разработки ведёт скилл `docs`.
|
||
- Раскладку проверяет `canon check`.
|
||
- Первую задачу берёт конвейер проекта; `architecture.md` и `conventions/`
|
||
наполняются его шагом синка, а не заранее.
|
||
|
||
## Чего этот скилл не делает
|
||
|
||
- **Не проектирует систему.** Архитектура выводится из кода, а не наоборот.
|
||
- **Не пишет код** и не заводит сборку.
|
||
- **Не переводит существующий проект** — это `canon adopt`. Признак: в
|
||
репозитории уже есть документация или беклог в какой-то раскладке.
|
||
- **Не решает за человека**, что важно: цель, границы и периметр — его ответы.
|