avandClaude Opus 5
a81dd1a5a7
Замечено при сверке документов канона с составом ступеней: три документа остались без читателя ниже wide — security.md, database.md и adr/. Проект поддерживал их, а на 90% задач не открывал никто. Причина оказалась не в переезде проходов, а в том, как описан состав прогона. Список тем нигде не был записан: он существовал побочным продуктом списка проходов. Проход уезжал в верхнюю ступень — и тема уезжала с ним беззвучно. Отчёт честно говорил «ops не запускался» и не говорил «эксплуатацию не смотрел никто», а нужно второе. Теперь тема первична, проход вторичен — это правило 0 конвейера, а прогон описывается таблицей «тема → дом → глубина → кто закрывает», и таблица есть в каждом отчёте. Тема есть документ, список открытый. Всё, что проект кладёт в docs/, становится темой ревью; запретить нельзя, разрешения не надо. Не темы ровно две: docs/tasks/ и docs/review — настройка самого конвейера, слой над темами. Отсюда главное: docs/ перестал быть документацией и стал конфигурацией конвейера. Проект настраивает проверку тем, что пишет о себе, а не отдельным файлом настроек, который разошёлся бы с документами. Ядро — requirements, autotests, conventions, architecture, security, operations; всё сверх разбирает basics, потому что именных проходов конечное число, а тем столько, сколько заведёт проект. Тема живёт файлом или каталогом, на выбор проекта: docs/security.md и docs/security/ — одно и то же. Прежде форма была задана поимённо и обосновать её было нечем; заодно в TODO висел вопрос «а если architecture.md разрастётся». Теперь ответ механический: разросся — стал каталогом с README.md, и это не смена версии. Обе формы сразу — ошибка, docs.py её ловит. Заведён review-scope, sonnet, стадия 0, до гейта: находит документы, выводит темы, назначает глубины, выбирает ступень с обоснованием. Довод оказался сильнее синхронизации документов — до сих пор профиль называл тот же оркестратор, который написал код, то есть в точке выбора глубины проверки разведённости с автором не было вовсе, а решала она под давлением «я почти закончил». Вызывающий пайплайн профиль больше не передаёт. Поднять и понизить ступень разметчик вправе одинаково, но обоснование обязательно всегда. Sonnet ему хватает потому, что вывод устроен как список: каждый файл в docs/ обязан попасть в план темой или строкой «не тема, потому что», и план сверяется с ls docs/ за секунду. Выбор ступени — суждение, но у него три независимых корректора: отрицательный тест quick, правило «спорный случай вниз» и сигнал basics о заниженной ступени. Разметчик передаёт адреса, а не пересказ. Проект однажды уже держал review-brief.md и убрал его: второй дом расходится с первым и выглядит актуальным. Пересказ в задании — тот же посредник, живущий один прогон. Исключение одно: отсутствие дома, этого проход сам дёшево не выяснит. quick и standard совпали составом и разошлись глубиной — иначе требование «нижние ступени закрывают все темы, просто не так глубоко» не выполняется. Глубин три, и они про способ доказательства, а не про старательность: сверка (открыть дом, открыть дифф, сравнить), разбор (построить сценарий рассуждением), доказательство (прогнать, померить, построить путь). Третья есть только в wide. Цена принята: это единственное место, где профиль не выводится из списка проходов, поэтому глубина объявляется в отчёте наравне со ступенью. review-code переписан, и это оказалось крупнее исходной находки: код как код не читал никто. specs сверял с требованиями, basics — с отказами окружения, architecture — с устройством, а code был проходом только по прозаическим конвенциям и прямо объявлял, что рантайм и логика не его. «Здесь ошибка в логике» не говорил вообще никто. Теперь у прохода две половины: девять классов технического дефекта (необработанная ветка отказа, пустое и нулевое, граница диапазона, перепутанный операнд, неосвобождённый ресурс, изменение под итерацией, неверно применённый интерфейс библиотеки, недостижимая ветка, «сделано соседнее») и прежняя сверка с конвенциями. Модель поднята до opus по признаку темы 35: цена пропущенной находки — дефект в проде. Канон повышен до версии 5: форма дома на выбор, открытый список тем, AGENTS.md законно лежит рядом с CLAUDE.md, «Вопросы к проходам» → «Вопросы по темам» (имя прохода переезд не переживает, тема переживает), «Недоступно проверке» — тоже по темам. docs.py переписан под темы: ловит двойной дом, принимает обе формы, перечисляет свои темы проекта вместо «файл вне канона». Побочно закрыт давний пункт TODO про каталожную форму architecture.md — решать больше нечего. Прогон от всего этого стал дороже, а не дешевле, впервые за сессию: плюс scope в голове каждого прогона, плюс code на opus, плюс basics теперь и в quick. Куплены разведённость выбора ступени, видимость непокрытых тем и технический разбор кода, которого не было вовсе. Тема 36 в DECISIONS.md, следствия 137-140. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
228 lines
17 KiB
Markdown
228 lines
17 KiB
Markdown
# Работы по итогам разбора
|
||
|
||
Порядок и обоснование — [DECISIONS.md](DECISIONS.md), тема 8. Номера в скобках —
|
||
следствия оттуда.
|
||
|
||
Замер (шаг 3) — **единственный шаг, который нельзя переставить**: он блокирует
|
||
переезд jellybit. Всё остальное можно тасовать.
|
||
|
||
## 0. Предусловие
|
||
|
||
- [x] `git push` — `092d07c..88c5d97`, 17 коммитов ушли на origin (37)
|
||
- [x] `claude plugin marketplace update av-dev-skills` — клон встал на `88c5d97`
|
||
и видит `av-dev-pm` и `av-dev-pipeline`
|
||
|
||
## 1. Репозиторий плагинов
|
||
|
||
### 1.1 Переименование
|
||
|
||
- [x] `av-dev-tasks` → `av-dev-pm`: каталог, `plugin.json`, `marketplace.json` (18)
|
||
- [x] пространство имён во всех текстах: `av-dev-tasks:session` →
|
||
`av-dev-pm:session`, включая ссылку из `task-pipeline` (18)
|
||
|
||
### 1.2 Канон — единственный дом определения
|
||
|
||
- [x] `av-dev-pm/skills/canon/references/canon.md` — раскладка, роли документов,
|
||
правило единственного дома. Читают `init`, `canon`, `docs` (AA)
|
||
- [x] `av-dev-pm/skills/canon/references/changelog.md` — журнал версий канона,
|
||
версия 1 (26)
|
||
|
||
### 1.3 Правки существующих скиллов
|
||
|
||
- [x] `tasks`: убрать слот 6 «Команда учёта задач» (33)
|
||
- [x] `tasks`: путь каталога жёсткий `docs/tasks`, убрать цепочку разрешения (F)
|
||
- [x] `tasks`: `.tasks.json` → `docs/.pm.json`, там же версия канона и путь
|
||
миграций (23, 30)
|
||
- [x] `tasks`: убрать слоты 3 «куда переезжает суть» и 5 «оракулы» — отвечает
|
||
канон и семантика гейта (тема 4)
|
||
- [x] `session`: убрать слот 7 и слот 4 «где живёт разбор процесса» (33, K)
|
||
- [x] `session`: переписать «Стимулы, которые процесс создаёт» — снятая граница
|
||
выбила опору у трёх защит (19)
|
||
|
||
### 1.4 Новые скиллы
|
||
|
||
- [x] `init` — интервью по брифу → канон нового проекта (R)
|
||
- [x] `canon` — `check` / `adopt` / `upgrade`; поглощает скилл `adopt` (R, 21, 24)
|
||
- [x] `docs` — содержимое канона: ADR из архивного `design.md`, промоут
|
||
конвенций, запись в `research/` и `review.md`, чистка `architecture.md` (X)
|
||
- [x] `docs.py` — раскладка, лишние файлы, битые ссылки, версия, плейсхолдеры,
|
||
маркеры долга; сверки миграции ↔ `database.md` и capability ↔
|
||
`architecture.md` (T, 31)
|
||
|
||
### 1.5 av-dev-pipeline
|
||
|
||
- [x] удалить скилл `project-brief` и `references/{project-brief,brief-template}.md` (13)
|
||
- [x] снять ветки деградации OpenSpec в трёх местах: `task-pipeline`,
|
||
`review-pipeline`, `task-batch` (1)
|
||
- [x] девять charter'ов: разделы брифа → пути канона; `ops`/`adversary`/`reimpl`
|
||
обязаны сшивать `research/` и `database.md` (14, 15)
|
||
- [x] `review-pipeline`: убрать бриф, поразрядная деградация по документам (16)
|
||
- [x] `task-pipeline` шаг 9 → построчный доклад по документам канона (28)
|
||
- [x] `task-pipeline`/`task-batch`: закрытие задачи вызовом скилла
|
||
`av-dev-pm:tasks`, слот убрать (32, 33)
|
||
- [x] `promote.md` шаг 3: перечень механизированного → `conventions/README.md` (29)
|
||
- [x] описание плагина: «требует OpenSpec» (2)
|
||
|
||
### 1.6 Прочее
|
||
|
||
- [x] `av-dev-backlog` — пометить устаревшим, переписать описание, чтобы не
|
||
ловило триггер (Q)
|
||
- [x] `README.md` маркетплейса — три плагина, канон, установка
|
||
- [x] `HISTORY.md` — сжать `AGENTIC-TASKS.md` до истории решений (CC)
|
||
- [x] `REMAINING.md` пересобрать: пункт 2 отменён, четыре вопроса закрыты,
|
||
калибровка стала обязательной (38)
|
||
|
||
### 1.7 Линтеры скриптов (тема 9)
|
||
|
||
- [x] `pyproject.toml`: ruff + pyrefly через `uv`, версии прибиты (DD, FF)
|
||
- [x] запрет внешних зависимостей двумя способами: `banned-api` + пустое
|
||
окружение pyrefly (EE)
|
||
- [x] `RUF001`–`RUF003` выключены, `av-dev-backlog` исключён (GG, HH)
|
||
- [x] починены 27 находок ruff и 14 pyrefly; `os` из `tasks.py` ушёл (40, 41)
|
||
- [x] раздел «Проверка скриптов» в `README.md`
|
||
|
||
### 1.8 Ревью двумя проходами (тема 10)
|
||
|
||
- [x] `reopen` берёт текст из `HEAD`, когда коммита удаления ещё нет (JJ)
|
||
- [x] шаг 11 коммитит учёт вторым коммитом; батч проверяет чистоту дерева (JJ)
|
||
- [x] фиктивный ключ `tasks.sections` убран из четырёх документов (KK)
|
||
- [x] `init` пишет конфиг в `docs/.pm.json`; `looks_like_tasks` его читает
|
||
- [x] урожай спринта заводится до `sprint close`, слаг — из его отчёта
|
||
- [x] ответ на вопрос опустошает раздел «Вопросы» — во всех трёх местах
|
||
- [x] путь отчёта триажа переживает архивацию (5 мест)
|
||
- [x] `review-specs` получил режим 3 — стык после слияния
|
||
- [x] остальные 12 находок: `sprint.md`, «9а», перечень проектных копий,
|
||
параллельность в батче, триаж в финальной сверке, триггеры профиля, 8–12
|
||
|
||
### 1.9 Ревью зависимостей между плагинами (тема 11)
|
||
|
||
- [x] опоры приёмки названы абстрактно, деградация без конвейера объявлена (MM)
|
||
- [x] ветка деградации шага 9 ходит в свой `project-facts.md` (NN)
|
||
- [x] `docs` даёт ветку «конвейера нет» для журнала и промоута
|
||
- [x] форма журнала дефектов сведена к дому, копия помечена в `changelog.md`
|
||
- [x] `specs` вернулся в читатели `docs/research/`; дом списка назначен
|
||
- [x] пайплайн не называет `items/` и `SPRINT.md` — их знает `av-dev-pm`
|
||
- [x] манифесты объявили `av-dev-pm` опциональным для конвейера (49)
|
||
|
||
### 1.10 Механическая проверка копий (тема 12)
|
||
|
||
- [x] `scripts/copies.py`: маркеры дома и копии, побайтовая сверка (OO)
|
||
- [x] строгий id, повторяемый в закрывающем маркере (PP)
|
||
- [x] помечены два контракта; «когда заводить ADR» сведён к дословному (50)
|
||
- [x] раздел «Проверка копий правил» в `README.md`, правило — в обоих домах
|
||
|
||
## 2. healthlog — первая боевая проверка
|
||
|
||
- [ ] `canon adopt`; `docs/backlog/` → `docs/tasks/`
|
||
- [ ] `architecture.md` 1662 строки → обзор, остаток маркерами (W)
|
||
- [ ] после выноса поведения — замерить остаток `architecture.md`; **решать
|
||
больше нечего**: канон 5 разрешил любой теме быть каталогом с `README.md`,
|
||
так что жмёт — заводи `docs/architecture/`, и это не смена версии
|
||
(тема 16, GGG, 65; закрыто темой 36)
|
||
- [ ] завести `security.md` с периметром первой строкой (J)
|
||
- [ ] `review-journal.md` → `review.md` + настройка конвейера (K, L)
|
||
- [ ] `conventions.md` → `conventions/`, `local-research.md` → `research/` (G)
|
||
- [ ] `plan.md` → `docs/tasks/ROADMAP.md` (E)
|
||
- [ ] завести `docs/adr/`
|
||
- [ ] `CLAUDE.md`: severity инвариантов, семантика гейта, убрать раздел
|
||
«Процесс» (M, N)
|
||
- [ ] `docs.py check` в `task gate` (V)
|
||
- [ ] почистить `openspec/config.yaml` (C)
|
||
- [ ] удалить проектные копии: `.claude/skills/healthlog-{task,review}-pipeline`
|
||
и девять `.claude/agents/healthlog-review-*.md` — они прошлого поколения и
|
||
после переезда указывают на `docs/conventions.md`, `docs/local-research.md`,
|
||
`docs/review-journal.md`, которых уже не будет
|
||
|
||
## 3. Калибровка — блокирует шаг 5
|
||
|
||
- [ ] замер на четырёх находках healthlog: скелет из `null`, откат бинаря,
|
||
канонизация в транзакции, `-1 >= -1` (1 из REMAINING, 14)
|
||
|
||
## 4. Обкатка
|
||
|
||
- [ ] один-два спринта healthlog на новом процессе
|
||
|
||
## 5. jellybit
|
||
|
||
- [ ] `BRIEF.md` → `docs/passport.md`, обновить
|
||
- [ ] `docs/specs/{recognition,review-ux,workflow}.md` — сверить с capability и
|
||
удалить как дубли (10)
|
||
- [ ] `docs/specs/architecture.md` → `docs/architecture.md`, `database.md` →
|
||
`docs/database.md`, `jellyfin-layout.md` → `docs/research/`
|
||
- [ ] `docs/review/journal.md` → `docs/review.md`
|
||
- [ ] `drafts/` растворить: roadmap → `ROADMAP.md`, conventions-backlog → записи
|
||
`research` (сырьё: тип есть, «Вопрос» пуст), logical-title-model → ADR (H)
|
||
- [ ] `docs/backlog/` → `docs/tasks/`
|
||
- [ ] удалить проектные копии скиллов и агентов (4 из REMAINING)
|
||
- [x] `av-dev-backlog` удалить из маркетплейса и снять с проекта (тема 30)
|
||
|
||
## 6. Канон версии 3 — повысить живые проекты (тема 17)
|
||
|
||
Оба проекта стоят на каноне 2 и держат `docs/tasks/PLAN.md`: healthlog 55 задач,
|
||
jellybit 43. Шаги повышения — [changelog.md](av-dev-pm/skills/canon/references/changelog.md),
|
||
запись «Версия 3»; делаются скиллом `av-dev-pm:canon` в режиме `upgrade`.
|
||
|
||
- [x] healthlog: `PLAN.md` → `ROADMAP.md`, ссылки, `"canon": 3` — сделано,
|
||
лежит в рабочем дереве проекта некоммитнутым
|
||
- [ ] jellybit: то же
|
||
- [ ] род работы и раздел «Затрагивает» — **не задним числом**: сперва то, что
|
||
идёт в ближайший набор (`sprint take` без них откажет), остальное по ходу
|
||
переоценки (PPP)
|
||
- [ ] секции роадмапа: `порядок` → `Запланировано`, `темы` → `Направления`,
|
||
завести `Готово` и `Сопровождение`; прозаические разделы healthlog («Что уже
|
||
пройдено», «Почему в таком порядке») разложить — звенья строками в
|
||
`Готово`, обоснование очереди прозой внутри `Запланировано` (тема 19, 80).
|
||
`check` теперь называет чужую секцию ошибкой, так что шаг обязателен
|
||
- [ ] переформулировать цели ответом на «что приложение будет уметь»; цели не
|
||
про приложение («Процесс и качество разработки» в jellybit) — в
|
||
`Сопровождение`
|
||
- [ ] `check --fix` на обоих: поднимет написание канонических секций, поставит
|
||
отбивку после заголовков и сведёт секцию в мете файлов с заголовками.
|
||
Секции беклога переименовать руками — имена выбирал проект (тема 20, ККК)
|
||
- [ ] заголовки задач в форму действия — **не задним числом**: по мере попадания
|
||
задачи в работу. `check` печатает их число, `task-form` предложит
|
||
формулировки пачкой (тема 20, ЕЕЕ)
|
||
|
||
**Канон 4** — сверх того (changelog, запись «Версия 4»):
|
||
|
||
- [ ] healthlog: `## Разработка` → `## Сопровождение`, поле «Секция» в целях этой
|
||
секции, `check --fix` (переставит `Готово` вниз и поправит отбивку),
|
||
`"canon": 4`
|
||
- [ ] jellybit едет сразу на 4: `Готово` заводить **последней**, секцию
|
||
сопровождения — сразу с новым именем, переставлять дважды не нужно
|
||
- [ ] типы: `check --fix` переведёт `kind:`/`[goal]`/`[idea]` в поле «Тип», снимет
|
||
тег, поставит эмодзи, переименует «Секция» → «Категория» у задач и снесёт
|
||
сырьё в конец категорий — **за один проход, вместе с порядком секций**
|
||
- [ ] разобрать `НЕОДНОЗНАЧНО` после `--fix`: записи без типа (заведены до
|
||
появления рода работы) машина не угадывает — `edit <слаг> --type …`
|
||
- [ ] имена файлов: `docs.py check` назовёт кириллицу, не-kebab-case и форму
|
||
имени ADR. Переименование ADR — **перенос ссылок одним проходом**: слаг
|
||
стоит в `adr/README.md`, в `architecture.md` и в чужих документах
|
||
- [ ] первый прогон `doc-consistency` на живом проекте — правило единственного
|
||
дома до сих пор не проверял никто, урожай ожидается крупный; разбирать
|
||
порциями
|
||
- [ ] `doc-code-drift` — на ближайшей сессии между спринтами, с разделом
|
||
запретов `CLAUDE.md` на входе
|
||
- [ ] новые обязательные разделы — **не задним числом**: `Воспроизведение` у
|
||
каждого `fix` и `Вопрос` + `Куда ляжет ответ` у каждого `research` пишутся
|
||
по мере того, как задача идёт в набор (`sprint take` без них откажет).
|
||
Сколько записей готово к взятию, печатает блок здоровья `check`
|
||
- [ ] `docs/review.md`, «Триггеры профиля» — переписать целиком: снести перечень
|
||
мест для `deep` (профиль упразднён), а оставшийся перевести на новое
|
||
правило — `wide` это крупное или незнакомое изменение, 5–10% задач, плюс
|
||
отдельный список мелкого для `quick`. Там же две честные строки в
|
||
«перестали проверять сознательно»: форма решения (снят проход независимой
|
||
реализации) и всё, что требует запуска (меряющие проходы только в `wide`)
|
||
|
||
**Канон 5** — сверх того (changelog, запись «Версия 5»):
|
||
|
||
- [ ] `docs/review.md`: «Вопросы к проходам» → **«Вопросы по темам»**, каждый
|
||
вопрос переадресовать теме вместо имени прохода (`requirements`,
|
||
`autotests`, `conventions`, `architecture`, `security`, `operations` плюс
|
||
свои). «Недоступно проверке» — тоже разнести по темам
|
||
- [ ] проверить, не просился ли в `docs/` документ, который раньше считался
|
||
лишним: теперь он законен и **становится темой ревью**. Это единственный
|
||
способ добавить проверку, которой в конвейере нет
|
||
- [ ] `"canon": 5` в `docs/.pm.json` обоих проектов; форму домов не трогать —
|
||
обе законны
|