разбор находок doc-consistency: остатки модели типов и копии в ссылки
Первый прогон агента — по репозиторию, который его же и содержит. Два прохода, 17 находок, все подтверждены по файлам. Пять находок — остатки прежней модели типов в файлах, до которых я не дошёл двумя коммитами раньше. adopt.md держал имена секций роадмапа канона 2 («порядка», «темы») и «пустой goal законен только у идеи»; from-review.md и TODO.md — упразднённый [idea]; task-batch в другом плагине — «задачи-идеи». Правку модели я вёл от документов, которые менял, а не от тех, что на них ссылаются: grep по упразднённому слову дал бы все пять за минуту. Самая дорогая находка оказалась моей и свежей. Таблица типов в canon.md объявляла цель у fix запрещённой, а tasks/SKILL.md и task-fix.md — необязательной; код на стороне вторых. Копия разошлась с домом за один день, обе половины писал один проход. Поправлено не значение, а причина: canon.md дважды объявлял, что фиксирует только словарь типов, — значит колонкам «разделы» и «цель» в нём не место. Осталась таблица из двух колонок и ссылка на дом схемы. Перечень «чем держат проект» пересказывался втроём и разъехался: «метрики и логи» против «мониторинга», «проверки» есть в двух из трёх. При этом tasks/SKILL.md ссылался на дом рядом с собственным пересказом — ссылка не мешает копии разойтись, если копия всё равно стоит. Перечень остался в canon.md, два места ссылаются. README пересказывал раскладку канона блоком кода, и копия была уже неполна — не хватало путей, чьё отсутствие docs.py считает нарушением. Заменено ссылкой. Там же измеренное число из DECISIONS III заменено ссылкой на решение. REMAINING дублировал два отмеченных сделанными пункта TODO и держал счётчики, которые обязан двигать человек: «двенадцати тем и 16 коммитов» (стало 28 и 52), «три неизмеренных изменения» (стало больше). Счётчики отменены как класс, причина записана в шапку. Открытый вопрос про парный статус ADR переформулирован: судья появился, открыт остался охват. Три противоречия вне av-dev-pm: --roadmap-sections перечислен среди флагов init прозой того же файла, объявляющей, что его нет; review-ops берёт журнал docs/review.md и тут же объявляет историю инцидентов принципиально недоступной; «честный предел» конвейера отменял целиком документ docs/research/. Плюс битый якорь ссылки на раздел вычитки. Находка про Co-Authored-By снята как неверная: агент прочитал av-dev-git/skills/commit/SKILL.md как описание практики этого репозитория, а это продукт, уезжающий в чужие проекты. Устав агента не различает «документ про нас» и «документ про то, что мы производим» — остаток записан в REMAINING, в устав пока не дописан. DECISIONS тема 29 (ЧЧШШ–ЮЮЯЯ, следствия 109–113). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1978,3 +1978,66 @@ ADR, запискам разведки и сообщениям коммитов
|
|||||||
показывал закрывающие маркеры как `<!-- /дом -->`, а требовал
|
показывал закрывающие маркеры как `<!-- /дом -->`, а требовал
|
||||||
`<!-- /дом: <id> -->`; нашлось это первой же попыткой ими воспользоваться.
|
`<!-- /дом: <id> -->`; нашлось это первой же попыткой ими воспользоваться.
|
||||||
Пример в докстроке — тот же образец, что плейсхолдер в схеме.
|
Пример в докстроке — тот же образец, что плейсхолдер в схеме.
|
||||||
|
|
||||||
|
## 29. Обкатка `doc-consistency` на самом dev-skills (2026-08-05)
|
||||||
|
|
||||||
|
Первый прогон агента — по репозиторию, который его же и содержит. Два прохода
|
||||||
|
(av-dev-pm; пайплайн плюс верхний уровень), 17 находок, все подтверждены по
|
||||||
|
файлам.
|
||||||
|
|
||||||
|
**ЧЧШШ. Агент нашёл ровно тот класс, ради которого заводился, и в свежей
|
||||||
|
работе.** Пять находок — остатки прежней модели типов в файлах, которые я не
|
||||||
|
дошёл поправить двумя коммитами раньше: `adopt.md` держал имена секций **канона
|
||||||
|
2**, `from-review.md` и `TODO.md` — упразднённый `[idea]`, `task-batch` в другом
|
||||||
|
плагине — «задачи-идеи». Правку модели я вёл от документов, которые менял, а не
|
||||||
|
от документов, которые на них ссылаются, — и обратный обход не сделал ни разу.
|
||||||
|
|
||||||
|
**ЩЩЪЪ. Самая дорогая находка была моей и свежей.** Таблица типов в `canon.md`
|
||||||
|
объявляла цель у `fix` запрещённой, а `tasks/SKILL.md` и `task-fix.md` —
|
||||||
|
необязательной; код на стороне вторых. Копия разошлась с домом **за один
|
||||||
|
день** — я написал обе половины в одном коммите. Это и есть цена второго дома в
|
||||||
|
чистом виде: не «когда-нибудь разойдётся», а «разошлось прежде, чем высохли
|
||||||
|
чернила».
|
||||||
|
|
||||||
|
Исход не «поправить значение», а **убрать причину**: `canon.md` дважды объявлял,
|
||||||
|
что фиксирует только словарь типов, — значит колонкам «разделы» и «цель» в нём
|
||||||
|
не место. Осталась таблица из двух колонок и ссылка на дом схемы.
|
||||||
|
|
||||||
|
**ЫЫЬЬ. Копии перечня «чем держат проект» разъехались втроём.** `canon.md`,
|
||||||
|
`tasks/SKILL.md` и `task-goal.md` пересказывали его своими словами: «метрики и
|
||||||
|
логи» против «мониторинга», «проверки» есть в двух из трёх. При этом
|
||||||
|
`tasks/SKILL.md` **ссылался на дом рядом с собственным пересказом** — ссылка не
|
||||||
|
мешает копии разойтись, если копия всё равно стоит.
|
||||||
|
|
||||||
|
**ЭЭЮЮ. Находка про коммиты снята как неверная, и это дефект самого агента.**
|
||||||
|
Он прочитал `av-dev-git/skills/commit/SKILL.md` («без `Co-Authored-By`») как
|
||||||
|
описание практики этого репозитория и предъявил 38 коммитов с трейлером. Но
|
||||||
|
dev-skills — **маркетплейс плагинов**: скилл коммита здесь продукт, уезжающий в
|
||||||
|
чужие проекты, а не правило, которому подчиняется сам репозиторий. Устав агента
|
||||||
|
не различает «документ описывает этот репозиторий» и «документ описывает то, что
|
||||||
|
репозиторий производит».
|
||||||
|
|
||||||
|
**ЮЮЯЯ. Счётчики в документах отменены как класс.** `REMAINING.md` держал «после
|
||||||
|
разбора двенадцати тем и 16 коммитов» (стало 28 и 52) и «три неизмеренных
|
||||||
|
изменения подряд» (стало больше). Оба числа обязан двигать человек, и оба
|
||||||
|
отстали молча. Заменены на формулировки, которые не надо поддерживать, и в шапку
|
||||||
|
записана причина.
|
||||||
|
|
||||||
|
### Что из этого следует
|
||||||
|
|
||||||
|
109. **Правка модели идёт по обратным ссылкам, а не по изменённым файлам.**
|
||||||
|
Меняешь дом — обойди тех, кто на него ссылается: `grep` по упразднённому
|
||||||
|
слову дал бы все пять остатков за минуту. Это дешевле любого агента и
|
||||||
|
должно идти до него.
|
||||||
|
110. **Ссылка на дом не отменяет копию, стоящую рядом.** Проверять надо не
|
||||||
|
«есть ли ссылка», а «есть ли пересказ»; `tasks/SKILL.md` имел и то и другое.
|
||||||
|
111. **Копия расходится с домом в пределах одного коммита.** Прежняя оценка
|
||||||
|
(«разойдётся на первой правке») занижена: расхождение возникает при
|
||||||
|
написании, если оба места пишет один проход.
|
||||||
|
112. **Агент, читающий репозиторий-продукт, обязан различать «про нас» и «про
|
||||||
|
то, что мы производим».** Иначе он предъявляет продукту практику его
|
||||||
|
потребителя. Устав `doc-consistency` этого различения не содержит — остаток
|
||||||
|
записан в REMAINING.
|
||||||
|
113. **Число в документе — обязанность, которую никто не берёт.** Счётчик тем,
|
||||||
|
коммитов, правок протухает молча; формулировка без числа дешевле его
|
||||||
|
сопровождения.
|
||||||
|
|||||||
@@ -72,29 +72,17 @@ flowchart TB
|
|||||||
## Канон документов проекта
|
## Канон документов проекта
|
||||||
|
|
||||||
Все проекты приводятся к одной раскладке — так проще ориентироваться, когда
|
Все проекты приводятся к одной раскладке — так проще ориентироваться, когда
|
||||||
проектов много, и рядом OpenSpec тоже держит строгую структуру. Определение —
|
проектов много, и рядом OpenSpec тоже держит строгую структуру. `CLAUDE.md` плюс
|
||||||
[av-dev-pm/skills/canon/references/canon.md](av-dev-pm/skills/canon/references/canon.md).
|
`docs/` (паспорт, архитектура, база, безопасность, конвенции, разведка, ADR,
|
||||||
|
ревью, задачи) и `openspec/` — **раскладка целиком, роли документов и правило
|
||||||
|
единственного дома живут одним домом**:
|
||||||
|
[canon.md](av-dev-pm/skills/canon/references/canon.md). Здесь она не
|
||||||
|
пересказывается: копия перечня путей уже расходилась с домом, и как раз в
|
||||||
|
обязательных — в ней не хватало путей, чьё отсутствие `docs.py check` считает
|
||||||
|
нарушением.
|
||||||
|
|
||||||
```
|
**Отдельного файла-брифа для ревью нет.** Проходы читают документы канона
|
||||||
CLAUDE.md инварианты с severity, команды, семантика гейта
|
напрямую; карта «что нужно проходу → где лежит» —
|
||||||
docs/
|
|
||||||
.pm.json версия канона и пути для проверок
|
|
||||||
passport.md зачем и для кого; чем НЕ является
|
|
||||||
architecture.md как сложено — обзор; окружение и эксплуатация
|
|
||||||
database.md схема хранилища; настройки с числовым значением
|
|
||||||
security.md периметр; недоверенный вход; что вне модели
|
|
||||||
conventions/ как пишем код + что уже механизировано
|
|
||||||
research/ что показала реальность; числа с провенансом
|
|
||||||
adr/ почему — промоут поверх архивных design.md
|
|
||||||
review.md настройка конвейера + журнал дефектов
|
|
||||||
tasks/ роадмап (что умеет), беклог, спринт, отклонённое
|
|
||||||
openspec/
|
|
||||||
specs/<capability>/spec.md что система делает — нормативно
|
|
||||||
changes/archive/ архив изменений с design.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Отдельного файла-брифа для ревью нет.** Проходы читают эти документы напрямую;
|
|
||||||
карта «что нужно проходу → где лежит» —
|
|
||||||
[project-facts.md](av-dev-pipeline/skills/review-pipeline/references/project-facts.md).
|
[project-facts.md](av-dev-pipeline/skills/review-pipeline/references/project-facts.md).
|
||||||
|
|
||||||
Прийти в старый проект и перевести его на канон — `/av-dev-pm:canon`. Канон
|
Прийти в старый проект и перевести его на канон — `/av-dev-pm:canon`. Канон
|
||||||
@@ -277,7 +265,8 @@ uv run python scripts/frontmatter.py # 0 в порядке, 1 расхожд
|
|||||||
- **двоеточие с пробелом в описании без кавычек.** Для YAML `: ` внутри
|
- **двоеточие с пробелом в описании без кавычек.** Для YAML `: ` внутри
|
||||||
простого скаляра начинает вложенное отображение, так что «конвейер ревью: гейт,
|
простого скаляра начинает вложенное отображение, так что «конвейер ревью: гейт,
|
||||||
сверка…» — это не текст с двоеточием, а синтаксическая ошибка. Так было
|
сверка…» — это не текст с двоеточием, а синтаксическая ошибка. Так было
|
||||||
написано три описания из четырнадцати, и читались они правильно;
|
написано часть описаний плагинов, и читались они правильно — замер и разбор
|
||||||
|
в [DECISIONS.md](DECISIONS.md), решение III;
|
||||||
- **`name`, разошедшееся с именем каталога скилла или файла charter'а.** Вызов
|
- **`name`, разошедшееся с именем каталога скилла или файла charter'а.** Вызов
|
||||||
разрешается по каталогу, а сообщение о промахе говорит «нет такого скилла»,
|
разрешается по каталогу, а сообщение о промахе говорит «нет такого скилла»,
|
||||||
а не «имя не то»;
|
а не «имя не то»;
|
||||||
|
|||||||
+26
-19
@@ -1,7 +1,8 @@
|
|||||||
# Остатки, открытые вопросы и принятые пределы
|
# Остатки, открытые вопросы и принятые пределы
|
||||||
|
|
||||||
Состояние на 2026-08-03, после разбора двенадцати тем и 16 коммитов реализации
|
Состояние пересобирается по ходу работы; счётчика тем и коммитов здесь нет
|
||||||
(`ad1779b` … `885981c`).
|
намеренно — он протухает молча, а двигать его некому. Что и когда решено —
|
||||||
|
[DECISIONS.md](DECISIONS.md), записи датированы.
|
||||||
|
|
||||||
План работ — [TODO.md](TODO.md). Решения с причинами — [DECISIONS.md](DECISIONS.md).
|
План работ — [TODO.md](TODO.md). Решения с причинами — [DECISIONS.md](DECISIONS.md).
|
||||||
Здесь то, что **не** является работой из плана: незакрытые риски, честно принятые
|
Здесь то, что **не** является работой из плана: незакрытые риски, честно принятые
|
||||||
@@ -9,16 +10,16 @@
|
|||||||
|
|
||||||
## Главный незакрытый риск
|
## Главный незакрытый риск
|
||||||
|
|
||||||
**Калибровка не сделана, а charter'ы переписаны трижды.**
|
**Калибровка не сделана, а уставы проходов с тех пор переписывались не раз.**
|
||||||
|
|
||||||
Первый раз девять charter'ов правили при выносе в плагин: предмет проверки
|
Правки шли волнами: вынос в плагин (предмет проверки заменён ссылкой на раздел
|
||||||
заменили ссылкой на раздел брифа. `references/calibration.md` требует при такой
|
брифа), переход на пути документов канона, две правки по находкам ревью, граф
|
||||||
правке замерить, помогла ли она, — **замера не было**. Второй раз их переписали
|
порядка, ступень `wide`, пересмотр триггеров ступени.
|
||||||
коммитом `9cef452`: ссылка на раздел брифа заменена путём документа канона.
|
`references/calibration.md` требует при каждой такой правке замерить, помогла ли
|
||||||
Третий — коммитами `0eab075` и следующим, по находкам ревью: `adversary`, `ops`,
|
она, — **ни одного замера не было**. Числа правок здесь нет намеренно: счётчик
|
||||||
`reimpl`, `rubric` и `triage` правились ещё раз.
|
пришлось бы двигать вручную, и он уже однажды отстал.
|
||||||
|
|
||||||
**Три неизмеренных изменения подряд** в том самом месте, где присваивается
|
**Неизмеренные изменения копятся** в том самом месте, где присваивается
|
||||||
severity. Пробы готовы и синтетических не нужно — четыре реальные находки
|
severity. Пробы готовы и синтетических не нужно — четыре реальные находки
|
||||||
прошедшей сессии healthlog:
|
прошедшей сессии healthlog:
|
||||||
|
|
||||||
@@ -35,17 +36,15 @@ severity. Пробы готовы и синтетических не нужно
|
|||||||
но работает ли обязанность, не проверено. Оркестратор реагирует на severity,
|
но работает ли обязанность, не проверено. Оркестратор реагирует на severity,
|
||||||
поэтому цена — не «не найдём», а **«найдём и не починим»**.
|
поэтому цена — не «не найдём», а **«найдём и не починим»**.
|
||||||
|
|
||||||
Замер стоит перед переездом jellybit и блокирует его (решение 39).
|
Сама работа — [TODO.md](TODO.md), раздел 3; здесь только цена: замер стоит
|
||||||
|
перед переездом jellybit и блокирует его (решение 39), а ожидаемый исход уже
|
||||||
|
назван выше.
|
||||||
|
|
||||||
## Что ещё не сделано
|
## Что ещё не сделано
|
||||||
|
|
||||||
Список работ — в [TODO.md](TODO.md). Здесь только то, что стоит держать в голове
|
Список работ — в [TODO.md](TODO.md). Здесь только то, что стоит держать в голове
|
||||||
отдельно:
|
отдельно:
|
||||||
|
|
||||||
- **Плагины отправлены, но ни к одному проекту не подключены.** 17 коммитов
|
|
||||||
ушли на origin, клон маркетплейса обновлён до `88c5d97` и видит `av-dev-pm`
|
|
||||||
и `av-dev-pipeline` — то есть подключать теперь есть что. Первым делом это
|
|
||||||
делает healthlog, по разделу 2 плана.
|
|
||||||
- **Ни один скилл не прогонялся на живом проекте.** `docs.py` прогнан на
|
- **Ни один скилл не прогонялся на живом проекте.** `docs.py` прогнан на
|
||||||
healthlog и jellybit в режиме `check` и находит осмысленный дрейф; `init`,
|
healthlog и jellybit в режиме `check` и находит осмысленный дрейф; `init`,
|
||||||
`canon adopt`, `canon upgrade` и скилл `docs` не исполнялись ни разу.
|
`canon adopt`, `canon upgrade` и скилл `docs` не исполнялись ни разу.
|
||||||
@@ -57,14 +56,22 @@ severity. Пробы готовы и синтетических не нужно
|
|||||||
|
|
||||||
## Открытые вопросы
|
## Открытые вопросы
|
||||||
|
|
||||||
|
**`doc-consistency` не различает «про нас» и «про то, что мы производим».**
|
||||||
|
Первый прогон на самом dev-skills предъявил репозиторию правило из
|
||||||
|
`av-dev-git/skills/commit/SKILL.md` — а это продукт, уезжающий в чужие проекты,
|
||||||
|
а не правило, которому подчиняется маркетплейс. На проекте под каноном такой
|
||||||
|
путаницы нет (там документы описывают сам проект), поэтому в устав это пока не
|
||||||
|
дописано: сперва посмотреть, встретится ли класс ещё раз.
|
||||||
|
|
||||||
**Как проверять, что канон не разошёлся с проектами после `upgrade`.** `canon
|
**Как проверять, что канон не разошёлся с проектами после `upgrade`.** `canon
|
||||||
check` сверяет версию, но не то, что миграционные записи journal'а применены
|
check` сверяет версию, но не то, что миграционные записи journal'а применены
|
||||||
верно. Проект может нести `"canon": 2` и не иметь того, что версия 2 требовала.
|
верно. Проект может нести `"canon": 2` и не иметь того, что версия 2 требовала.
|
||||||
|
|
||||||
**Форма ADR при пересмотре решения.** Правило «старая запись получает статус
|
**Форма ADR при пересмотре решения.** Парный статус («старая запись получает
|
||||||
`заменено на`» требует, чтобы кто-то заметил, что новое решение отменяет старое.
|
`заменено на`») судит агент `doc-consistency` — правило 6 его устава. Открытым
|
||||||
Механической проверки нет, а принуждённое отрицание на шаге синка спрашивает про
|
остаётся не это, а охват: агент зовётся на синке по документам, которых синк
|
||||||
`adr/` вообще, а не «не отменяет ли это что-то из существующего».
|
касался, и пересмотр, отменяющий решение из документа, к которому не
|
||||||
|
притрагивались, он не увидит. Механической проверки по-прежнему нет.
|
||||||
|
|
||||||
**Что делать с `av-dev-backlog` после перевода jellybit.** Помечен устаревшим и
|
**Что делать с `av-dev-backlog` после перевода jellybit.** Помечен устаревшим и
|
||||||
переписан так, чтобы не ловить триггер. Удалять его из маркетплейса или оставить
|
переписан так, чтобы не ловить триггер. Удалять его из маркетплейса или оставить
|
||||||
|
|||||||
@@ -151,8 +151,8 @@
|
|||||||
- [ ] `docs/specs/architecture.md` → `docs/architecture.md`, `database.md` →
|
- [ ] `docs/specs/architecture.md` → `docs/architecture.md`, `database.md` →
|
||||||
`docs/database.md`, `jellyfin-layout.md` → `docs/research/`
|
`docs/database.md`, `jellyfin-layout.md` → `docs/research/`
|
||||||
- [ ] `docs/review/journal.md` → `docs/review.md`
|
- [ ] `docs/review/journal.md` → `docs/review.md`
|
||||||
- [ ] `drafts/` растворить: roadmap → `ROADMAP.md`, conventions-backlog → задачи
|
- [ ] `drafts/` растворить: roadmap → `ROADMAP.md`, conventions-backlog → записи
|
||||||
`[idea]`, logical-title-model → ADR (H)
|
`research` (сырьё: тип есть, «Вопрос» пуст), logical-title-model → ADR (H)
|
||||||
- [ ] `docs/backlog/` → `docs/tasks/`
|
- [ ] `docs/backlog/` → `docs/tasks/`
|
||||||
- [ ] удалить проектные копии скиллов и агентов (4 из REMAINING)
|
- [ ] удалить проектные копии скиллов и агентов (4 из REMAINING)
|
||||||
- [ ] `av-dev-backlog` удалить из маркетплейса
|
- [ ] `av-dev-backlog` удалить из маркетплейса
|
||||||
|
|||||||
@@ -145,7 +145,8 @@ color: green
|
|||||||
## Чего этот проход принципиально не может поймать
|
## Чего этот проход принципиально не может поймать
|
||||||
|
|
||||||
- Реальный профиль нагрузки и реальные размеры данных на проде.
|
- Реальный профиль нагрузки и реальные размеры данных на проде.
|
||||||
- Историю инцидентов: что уже ломалось и по какой причине.
|
- Историю инцидентов **сверх записанного в `docs/review.md`**: инцидент, не
|
||||||
|
попавший в журнал, для тебя не существует.
|
||||||
- Поведение внешних систем в их конкретных версиях и настройках.
|
- Поведение внешних систем в их конкретных версиях и настройках.
|
||||||
- Дефекты, проявляющиеся только на настоящих данных владельца.
|
- Дефекты, проявляющиеся только на настоящих данных владельца.
|
||||||
|
|
||||||
|
|||||||
@@ -699,7 +699,8 @@ flowchart TD
|
|||||||
Независимо от проекта недоступно:
|
Независимо от проекта недоступно:
|
||||||
|
|
||||||
- поведение внешних систем в их будущих версиях;
|
- поведение внешних систем в их будущих версиях;
|
||||||
- реальный профиль нагрузки и то, что на самом деле лежит в данных;
|
- реальный профиль нагрузки; и то, что на самом деле лежит в данных, — **сверх
|
||||||
|
того, что снято с провенансом в `docs/research/`**;
|
||||||
- завязка внешних потребителей на текущую форму ответа;
|
- завязка внешних потребителей на текущую форму ответа;
|
||||||
- суждение «этой функциональности не должно существовать».
|
- суждение «этой функциональности не должно существовать».
|
||||||
|
|
||||||
|
|||||||
@@ -88,8 +88,9 @@ description: Проводит несколько задач разом — пл
|
|||||||
### 1. Прочитать набор
|
### 1. Прочитать набор
|
||||||
|
|
||||||
Набор задан списком (слаги, файлы, описания) — прочитай файл каждой задачи и
|
Набор задан списком (слаги, файлы, описания) — прочитай файл каждой задачи и
|
||||||
связанные спеки и черновики. Задачи-идеи включаются, но помни: сабагент проведёт
|
связанные спеки и черновики. Сырьё (в терминах `av-dev-pm` — запись типа
|
||||||
их сперва через `opsx:explore`, это тяжелее и чаще упирается в вопрос.
|
`research` с пустым разделом «Вопрос») включается, но помни: сабагент проведёт
|
||||||
|
его сперва через `opsx:explore`, это тяжелее и чаще упирается в вопрос.
|
||||||
|
|
||||||
### 2. Спланировать порядок и пересечения (автономно)
|
### 2. Спланировать порядок и пересечения (автономно)
|
||||||
|
|
||||||
|
|||||||
@@ -265,13 +265,21 @@ kebab-case.** Причина не эстетическая: имя файла с
|
|||||||
поле меты `Тип` первой строкой; эмодзи в заголовке от него производна. Словарь
|
поле меты `Тип` первой строкой; эмодзи в заголовке от него производна. Словарь
|
||||||
закрыт:
|
закрыт:
|
||||||
|
|
||||||
| Тип | Что это | Обязательные разделы | Цель |
|
| Тип | Что это |
|
||||||
| --- | --- | --- | --- |
|
| --- | --- |
|
||||||
| 🎯 `goal` | возможность приложения | `Завершение` | — |
|
| 🎯 `goal` | возможность приложения |
|
||||||
| ✨ `feature` | снаружи появляется то, чего не было | `Затрагивает`, `Критерии приёмки` | обязательна |
|
| ✨ `feature` | снаружи появляется то, чего не было |
|
||||||
| 🐞 `fix` | поведение расходится с заявленным | `Воспроизведение`, `Затрагивает`, `Критерии приёмки` | нет |
|
| 🐞 `fix` | поведение расходится с заявленным |
|
||||||
| 🧹 `chore` | обслуживание, поведение не меняется | `Затрагивает`, `Критерии приёмки` | нет |
|
| 🧹 `chore` | обслуживание, поведение не меняется |
|
||||||
| 🔬 `research` | исход — знание, а не изменение | `Вопрос`, `Куда ляжет ответ` | нет |
|
| 🔬 `research` | исход — знание, а не изменение |
|
||||||
|
|
||||||
|
**Схемы записи здесь нет намеренно.** Какие разделы тип требует, нужна ли ему
|
||||||
|
цель и берётся ли он в спринт — скилл `tasks`: сводка в его
|
||||||
|
[SKILL.md](../../tasks/SKILL.md), раздел «Тип записи», подробно — по файлу на
|
||||||
|
тип в `tasks/references/task-<тип>.md`. Канон фиксирует **словарь**, потому что
|
||||||
|
от него зависит, читается ли проект как продукт; схема — механика ведения задач,
|
||||||
|
и второй её экземпляр разошёлся бы с первым (он и разошёлся: канон успел
|
||||||
|
объявить цель у `fix` запрещённой, хотя она там необязательна).
|
||||||
|
|
||||||
Схема требуется **к взятию в спринт**, а не к заведению: беклог пополняется чаще,
|
Схема требуется **к взятию в спринт**, а не к заведению: беклог пополняется чаще,
|
||||||
чем разбирается, и требование на входе выгоняло бы в заметки то, что должно
|
чем разбирается, и требование на входе выгоняло бы в заметки то, что должно
|
||||||
@@ -282,9 +290,7 @@ kebab-case.** Причина не эстетическая: имя файла с
|
|||||||
род работы, и называется оно **`research` без раздела «Вопрос»**. Такая запись в
|
род работы, и называется оно **`research` без раздела «Вопрос»**. Такая запись в
|
||||||
спринт не берётся и лежит в конце своей категории.
|
спринт не берётся и лежит в конце своей категории.
|
||||||
|
|
||||||
Раскладку, форму записи и алгоритм работы над каждым типом держит скилл `tasks`
|
Раскладку, форму записи и алгоритм работы над каждым типом держит скилл `tasks`.
|
||||||
(`references/task-<тип>.md`); канон фиксирует только словарь типов и то, от чего
|
|
||||||
зависит, читается ли проект как продукт.
|
|
||||||
|
|
||||||
### `CLAUDE.md`
|
### `CLAUDE.md`
|
||||||
|
|
||||||
|
|||||||
@@ -193,9 +193,9 @@ stateDiagram-v2
|
|||||||
только, чтобы формулировка отвечала на «что приложение делает», а не на «какую
|
только, чтобы формулировка отвечала на «что приложение делает», а не на «какую
|
||||||
часть кода мы трогаем».
|
часть кода мы трогаем».
|
||||||
|
|
||||||
**Что целью не является — работа, которой держат проект.** Сборка, проверки,
|
**Что целью не является — работа, которой держат проект.** Состав перечислен
|
||||||
сам этот скилл, а также выкладка, мониторинг и дежурство: на вопрос «что
|
[в каноне](../canon/references/canon.md), раздел «Сопровождение и эксплуатация»;
|
||||||
приложение будет уметь» они не отвечают. Им отведена отдельная секция роадмапа,
|
на вопрос «что приложение будет уметь» ничто из него не отвечает. Им отведена отдельная секция роадмапа,
|
||||||
чтобы они были видны в том же экране и при этом не читались как возможности
|
чтобы они были видны в том же экране и при этом не читались как возможности
|
||||||
продукта.
|
продукта.
|
||||||
|
|
||||||
@@ -205,12 +205,12 @@ stateDiagram-v2
|
|||||||
наблюдаем мы. Одна и та же наблюдаемость попадает в разные секции, и это верно —
|
наблюдаем мы. Одна и та же наблюдаемость попадает в разные секции, и это верно —
|
||||||
секции отвечают на разные вопросы.
|
секции отвечают на разные вопросы.
|
||||||
|
|
||||||
**Сопровождение и эксплуатация — целое и часть**, а не синонимы: сопровождение
|
**Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема
|
||||||
это всё, чем держат проект (инструмент, процесс, выкладка, метрики и логи,
|
живёт ещё в двух местах канона: разделе «Эксплуатация» в `architecture.md` и
|
||||||
инфраструктура, дежурство), эксплуатация — работа системы на проде. Та же тема
|
эксплуатационном проходе ревью. Словарь у всех трёх общий и живёт одним домом —
|
||||||
живёт ещё в двух местах канона — разделе «Эксплуатация» в `architecture.md` и
|
|
||||||
эксплуатационном проходе ревью, — и словарь у всех трёх общий:
|
|
||||||
[canon.md](../canon/references/canon.md), раздел «Сопровождение и эксплуатация».
|
[canon.md](../canon/references/canon.md), раздел «Сопровождение и эксплуатация».
|
||||||
|
Пересказывать его здесь нельзя: три перечня «чем держат проект» уже разъезжались
|
||||||
|
на «метриках и логах» против «мониторинга».
|
||||||
|
|
||||||
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
||||||
тянется долго и очереди не имеет — `Направления`; не про приложение, а про то,
|
тянется долго и очереди не имеет — `Направления`; не про приложение, а про то,
|
||||||
@@ -315,7 +315,7 @@ stateDiagram-v2
|
|||||||
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
|
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
|
||||||
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
|
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
|
||||||
Годность формулировки — не машине: её смотрит
|
Годность формулировки — не машине: её смотрит
|
||||||
[агент вычитки](#вычитка-формулировок).
|
[агент вычитки](#вычитка-два-прохода-а-не-один).
|
||||||
|
|
||||||
**Функции и границы, а не намерения.** Задача называет, что система начнёт
|
**Функции и границы, а не намерения.** Задача называет, что система начнёт
|
||||||
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
|
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
|
||||||
@@ -370,7 +370,7 @@ python3 $tk close S --dir D --reason R # в REJECTED.md + удалить (
|
|||||||
python3 $tk close S --dir D --implemented # просто удалить (реализована и закоммичена)
|
python3 $tk close S --dir D --implemented # просто удалить (реализована и закоммичена)
|
||||||
python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась
|
python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась
|
||||||
python3 $tk sprint start --goal S --dir D | take S… | drop S… --reason R | close [--dissolve --reason R]
|
python3 $tk sprint start --goal S --dir D | take S… | drop S… --reason R | close [--dissolve --reason R]
|
||||||
python3 $tk init --dir D [--sections …] [--roadmap-sections …] [--items …] [--backlog …] …
|
python3 $tk init --dir D [--sections …] [--items …] [--backlog …] …
|
||||||
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
|
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -53,8 +53,9 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
|||||||
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
||||||
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
||||||
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
||||||
- **цели.** Шаги роадмапа — готовые цели из **«порядка»** (очередь и обоснование у
|
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
|
||||||
них уже есть); тематические скопления задач — **«темы»** («прочность слияния»,
|
обоснование у них уже есть); тематические скопления задач — цели в
|
||||||
|
**`Направления`** («прочность слияния»,
|
||||||
«журнал и пересборка»). Предлагаешь ты, назначает человек;
|
«журнал и пересборка»). Предлагаешь ты, назначает человек;
|
||||||
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
||||||
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
||||||
@@ -70,7 +71,8 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
|||||||
прохода дадут два несогласованных состояния.
|
прохода дадут два несогласованных состояния.
|
||||||
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
|
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
|
||||||
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
|
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
|
||||||
заводится. Пустой `goal` — законный исход только у идеи.
|
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
|
||||||
|
работоспособности, а не направлению; у `feature` цель обязательна.
|
||||||
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
||||||
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
|
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
|
||||||
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
|
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
|
||||||
|
|||||||
@@ -86,7 +86,8 @@
|
|||||||
- **находка, ломающая уже идущий спринт**, — не интейк вовсе: см. правило
|
- **находка, ломающая уже идущий спринт**, — не интейк вовсе: см. правило
|
||||||
вторжения в скилле `session`. В беклог она падает, только если врываться не
|
вторжения в скилле `session`. В беклог она падает, только если врываться не
|
||||||
положено;
|
положено;
|
||||||
- **низкая уверенность или нет свидетельства** → идея;
|
- **низкая уверенность или нет свидетельства** → сырьё (`research` с пустым
|
||||||
|
разделом «Вопрос»);
|
||||||
- **мелочь** → строка в пакетный файл;
|
- **мелочь** → строка в пакетный файл;
|
||||||
- **уже починено / развилка решена сейчас** → ничего.
|
- **уже починено / развилка решена сейчас** → ничего.
|
||||||
|
|
||||||
@@ -108,7 +109,7 @@
|
|||||||
|
|
||||||
- Источник (какое ревью/аудит, сколько находок на входе).
|
- Источник (какое ревью/аудит, сколько находок на входе).
|
||||||
- Свёрнуто в задачи: N кластеров из M находок, со слагами, целями и тегом партии.
|
- Свёрнуто в задачи: N кластеров из M находок, со слагами, целями и тегом партии.
|
||||||
- Что не заведено и почему: починено инлайн, уже заведено, ушло в идеи, в
|
- Что не заведено и почему: починено инлайн, уже заведено, стало сырьём, ушло в
|
||||||
`REJECTED.md`.
|
`REJECTED.md`.
|
||||||
- Поимённая сверка: находок на входе N, исход есть у N.
|
- Поимённая сверка: находок на входе N, исход есть у N.
|
||||||
- `tasks.py check`.
|
- `tasks.py check`.
|
||||||
|
|||||||
@@ -36,10 +36,12 @@
|
|||||||
|
|
||||||
## Алгоритм
|
## Алгоритм
|
||||||
|
|
||||||
1. **Проверить, что это возможность, а не работа.** Сборка, проверки, выкладка,
|
1. **Проверить, что это возможность, а не работа.** Работа, которой держат
|
||||||
мониторинг, дежурство на вопрос «что приложение будет уметь» не отвечают. Им
|
проект, на вопрос «что приложение будет уметь» не отвечает; состав перечислен
|
||||||
отведена секция `Сопровождение` — там они видны в том же экране и не читаются
|
[в каноне](../../canon/references/canon.md), раздел «Сопровождение и
|
||||||
как обещание продукта. Граница проходит по тому, **кто наблюдает**:
|
эксплуатация». Ей отведена секция `Сопровождение` — там она видна в том же
|
||||||
|
экране и не читается как обещание продукта. Граница проходит по тому,
|
||||||
|
**кто наблюдает**:
|
||||||
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
|
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
|
||||||
состояние на одном экране» — сопровождение.
|
состояние на одном экране» — сопровождение.
|
||||||
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
|
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
|
||||||
|
|||||||
Reference in New Issue
Block a user