avandClaude Opus 5
ef0183b06b
готово | запланировано | направления | разработка, англ. done | planned | directions | tooling. Из четырёх предложенных имён отвергнуто одно, и по проверяемой причине: «окружение» уже занято — в architecture.md это боевое окружение приложения, «где работает, что рядом, кто перезапускает», и одно слово в двух смыслах развело бы документы канона. Секции роадмапа стали каноническими, в отличие от секций беклога, и разница выведена, а не назначена: у каждой секции роадмапа своя семантика, в первую пишет сам close, и роадмап, названный по-своему, читался бы только своим автором. Секции беклога — полки, смысла не несут, остаются делом проекта. check проверяет три вещи: состав закреплён (чужая секция — ошибка), все четыре обязаны быть, язык один на весь индекс. Проверено на том случае, ради которого правило и заводилось: «Что уже пройдено», которую healthlog вёл руками, теперь называется ошибкой поимённо. Оба языка прогнаны вживую, включая close в английский роадмап. Ключа tasks.achieved_section не появилось — секция достигнутого опознаётся по каноническому имени в любом из языков; --roadmap-sections у init упразднён, выбирать больше нечего. Названные вслух компромиссы: «готово» слегка тянет в трекерную рамку «состояние работы», тогда как секция про возможность — перевесила читаемость; цель в «запланировано» может быть уже наполовину построена, это очередь, а не «не начато», «в работе» живёт в SPRINT.md. DECISIONS 19: ГГГ переписан, добавлен ДДД, следствие 78 заменено. TODO 7 закрыт. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
159 lines
13 KiB
Markdown
159 lines
13 KiB
Markdown
# Журнал версий канона
|
||
|
||
Одна запись на версию. Проект знает свою версию из `docs/.pm.json`; `canon
|
||
upgrade` идёт по записям снизу вверх от версии проекта до текущей и делает то,
|
||
что в них названо.
|
||
|
||
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
||
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
||
`upgrade`.
|
||
|
||
Версия — целое число. Обратной совместимости у канона нет: есть «приведён» и «не
|
||
приведён».
|
||
|
||
---
|
||
|
||
## Версия 3 — 2026-08-04
|
||
|
||
Роадмап стал **состоянием проекта**, а не очередью работ: цель — возможность
|
||
приложения, задача — шаг к ней, достигнутое из роадмапа не исчезает. Плюс род
|
||
работы, раздел «Затрагивает» и новое умолчание профиля ревью. Раскладка меняется
|
||
в одном файле, но переименование и смена секций тянут за собой ссылки, поэтому
|
||
шаги делаются одним заходом.
|
||
|
||
**Что добавилось:**
|
||
|
||
1. **Род работы** — тег `kind:<род>` в мете задачи, словарь закрыт:
|
||
`feature` | `fix` | `chore` | `research`. Обязателен у задачи, у цели
|
||
запрещён. `sprint take` без него отказывает, `check` о пропаже напоминает
|
||
замечанием. Определение — [canon.md](canon.md), раздел `tasks/`; смысл и
|
||
причина, почему тегом, — в SKILL.md скилла `tasks`, раздел «Род работы».
|
||
2. **Раздел «Затрагивает»** в теле задачи — перечень границ, которых изменение
|
||
касается (эндпоинт, таблица и миграция, формат на диске, публичный тип). Как
|
||
и критерии приёмки, требуется к взятию в спринт, а не к заведению.
|
||
3. **Секции роадмапа** — четыре вместо двух и **канонические**, в отличие от
|
||
секций беклога: `готово` (достигнутые цели строкой с датой, без ссылки на
|
||
файл), `запланировано` (очередь значима), `направления` (очереди нет),
|
||
`разработка` (инструмент и процесс, не возможности приложения). Английский
|
||
вариант — `done` | `planned` | `directions` | `tooling`, один язык на весь
|
||
индекс. Переименованию проектом не подлежат: у каждой свой смысл, и в первую
|
||
пишет сам `close`; `tasks.py check` проверяет состав.
|
||
4. **Умолчание профиля ревью сменилось** — это не раскладка, но проектный текст
|
||
под него уже написан. `standard` стал рабочим умолчанием: миграция схемы,
|
||
публичный контракт и инвариант ступень больше **не** поднимают, `wide`
|
||
означает новое понятие или структурную единицу. Подраздел «Триггеры профиля»
|
||
в `docs/review.md` остаётся на месте, но его содержимое надо перечитать.
|
||
|
||
**Что переехало:** `docs/tasks/PLAN.md` → `docs/tasks/ROADMAP.md`; достигнутая
|
||
цель — из небытия в секцию `готово`: `close <цель> --implemented` удаляет файл, но
|
||
**оставляет строку с датой**. Прежде роадмап отвечал только «что осталось», и
|
||
половину его вопроса вели прозой руками. Вместе с
|
||
файлом переименован ключ конфига `tasks.plan` → `tasks.roadmap` и токены
|
||
команд: `--index plan` → `--index roadmap`, `init --plan-sections` →
|
||
`--roadmap-sections`, `init --plan` → `--roadmap`. Старый ключ в
|
||
`docs/.pm.json` не игнорируется молча — `tasks.py` останавливается и называет
|
||
переименование.
|
||
|
||
**Что удалено:** тип `[epic]`. Он был зонтиком между целью и задачами; зонтиком
|
||
стала цель, а слишком крупный шаг дробится на шаги помельче под ней. Ноль
|
||
употреблений на 97 записей двух живых проектов.
|
||
|
||
**Что сделать проекту:**
|
||
|
||
1. `git mv docs/tasks/PLAN.md docs/tasks/ROADMAP.md`.
|
||
2. Починить ссылки на прежнее имя: `grep -rn 'PLAN\.md' docs/ CLAUDE.md` —
|
||
заголовок самого файла («# План» → «# Роадмап»), строка в `docs/tasks/BACKLOG.md`,
|
||
упоминания в `docs/passport.md` и в телах задач.
|
||
3. `docs/.pm.json`: ключ `tasks.plan`, если он там был, — в `tasks.roadmap`.
|
||
4. Проставить род работы живым задачам: `python3 tasks.py check --dir docs/tasks`
|
||
перечислит те, у кого его нет. Задним числом весь беклог не переоформляется —
|
||
род нужен к взятию, так что порядок такой: сперва то, что берётся в ближайший
|
||
спринт, остальное по ходу переоценки.
|
||
5. Дописать раздел «Затрагивает» — тем же порядком и по той же причине: сперва
|
||
набор спринта, остальное по мере того, как задача попадает в работу.
|
||
6. Перечитать «Триггеры профиля» в `docs/review.md`: строки вида «миграция →
|
||
`deep`» теперь дублируют умолчание с обратным знаком. Оставить там только то,
|
||
что для этого проекта считается **новым понятием** и **правилом
|
||
идентичности**, — и убрать остальное, иначе проект возвращает себе прежнюю
|
||
частоту полного набора уточнением.
|
||
7. Переименовать секции роадмапа: `порядок` → `запланировано`, `темы` →
|
||
`направления`; завести `готово` **первой** и `разработка` последней.
|
||
Прозаические разделы вроде «Что уже пройдено», которые велись руками,
|
||
разложить: звенья — строками в `готово` (дата, слаг, что стало возможно),
|
||
обоснование очереди оставить прозой в `запланировано`. Любой `##` в индексе
|
||
проверка считает секцией, и теперь `check` называет чужую секцию ошибкой.
|
||
8. Переформулировать цели ответом на **«что приложение будет уметь»**: не
|
||
«Работа со слиянием», а «Исход слияния не зависит от порядка доставки».
|
||
Свойство поведения — законная цель. Цель, которая не про приложение
|
||
(процесс, инструмент), переезжает в `разработка`.
|
||
9. `[epic]`, если он в проекте заводился: это либо цель, либо набор задач под
|
||
общей целью. `check` назовёт его неизвестным типом.
|
||
10. `docs/.pm.json`: `"canon": 3`.
|
||
|
||
## Версия 2 — 2026-08-03
|
||
|
||
Шапка записи ADR — мета-блоком общей формы, и у статуса появился объявленный
|
||
дом. Раскладка не менялась: правка касается одного шаблона.
|
||
|
||
**Что добавилось:** поле `- **Статус:**` в шапке `docs/adr/template.md` —
|
||
`заменено на ADR-…` либо `устарело`, у активной записи поля нет. Правило
|
||
«старая запись получает статус» было и раньше ([canon.md](canon.md), `adr/`),
|
||
но места под него шаблон не отводил: каждая запись изобретала своё, а колонка
|
||
«Статус» таблицы `adr/README.md` брала его оттуда, где он у каждого свой.
|
||
|
||
**Что переехало:** поля `Дата` и `Источник` в шаблоне стали жирными
|
||
(`- **Дата:**`, `- **Источник:**`) — та же форма, что у меты задачи и у записи
|
||
журнала дефектов: поле на строку, имя жирным.
|
||
|
||
**Что удалено:** ничего.
|
||
|
||
**Что сделать проекту:**
|
||
|
||
1. Привести `docs/adr/template.md` к скелету версии 2
|
||
([skeletons.md](skeletons.md), раздел `docs/adr/template.md`).
|
||
2. В существующих записях `docs/adr/ADR-*.md`: жирным поля шапки; если статус
|
||
записан прозой или заголовком — перенести его полем `- **Статус:**` в шапку
|
||
и сверить с колонкой «Статус» таблицы в `docs/adr/README.md`.
|
||
3. `docs/.pm.json`: `"canon": 2`.
|
||
|
||
## Версия 1 — 2026-08-03
|
||
|
||
Первая версия. Проект любой прежней раскладки приводится к ней скиллом `canon`
|
||
в режиме `adopt`, а не `upgrade`.
|
||
|
||
**Что вводится:** раскладка целиком — см. [canon.md](canon.md).
|
||
|
||
**Что сделать проекту, который приходит из свободной раскладки:**
|
||
|
||
1. `docs/.pm.json` с `{"canon": 1}` и путём миграций, если БД есть.
|
||
2. Скелет канона целиком; незаполненное — одной честной строкой.
|
||
3. `docs/specs/` разобрать: поведение — в `openspec/specs/`, обзор — в
|
||
`docs/architecture.md`, знание о чужих системах — в `docs/research/`.
|
||
Дубли capability удалить, сверив поимённо.
|
||
4. `docs/plan.md` → `docs/tasks/PLAN.md`, шаги плана — целями в «порядок».
|
||
5. `BRIEF.md` → `docs/passport.md`.
|
||
6. `docs/backlog/` → `docs/tasks/`.
|
||
7. `docs/review-journal.md` или `docs/review/journal.md` → `docs/review.md`,
|
||
плюс раздел настройки конвейера.
|
||
8. `docs/drafts/` растворить: идея → задача `[idea]`, намеренный отказ → ADR,
|
||
порядок работ → `PLAN.md`.
|
||
9. `docs/review-brief.md`, если заводился, удалить: его разделы разошлись по
|
||
документам канона.
|
||
10. `conventions.md` → `conventions/`, `local-research.md` → `research/`.
|
||
11. Завести `docs/security.md` с периметром первой строкой и `docs/adr/`.
|
||
12. В `CLAUDE.md`: severity рядом с каждым инвариантом; семантика гейта (чем
|
||
краснеет безусловно, где логи, чего в нём нет и кто тогда гоняет дорогое);
|
||
**имя основной ветки**; запреты с путями; где `testdata` и куда писать
|
||
временное; **что считается необратимым**; общий станок; ориентир по размеру
|
||
спринта. Убрать раздел «Процесс», если он пересказывает пайплайн.
|
||
13. В `openspec/config.yaml` оставить только нужды генерации и ссылки.
|
||
14. Добавить шаг `docs.py check` в гейт проекта.
|
||
|
||
**Копии правил в шаблонах, которые версия 1 уносит в проект** — их правка в
|
||
каноне обязана появляться здесь отдельной версией:
|
||
|
||
| Что копируется | Дом определения |
|
||
| --- | --- |
|
||
| форма записи журнала дефектов в `docs/review.md` | `av-dev-pipeline/skills/review-pipeline/references/review-journal.md` |
|
||
| правило заведения ADR в `docs/adr/README.md` | [canon.md](canon.md), раздел `adr/` |
|