слияние: три плагина стали одним av-dev, скиллы получили префиксы
Каталоги, агенты и общие дома переехали в av-dev/; скиллы названы по прежнему плагину — doc-*, task-*, code-*, с двумя смысловыми именами вместо тавтологии: doc-sync вместо docs, task-track вместо tasks. Манифесты сведены к двум плагинам. Пространства имён вызовов и пути внутри дерева переписаны машинно; проза, которая называет прежние плагины отдельными, идёт следующим шагом.
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
---
|
||||
name: code-openspec
|
||||
description: "Завести и настроить OpenSpec в проекте — openspec init --tools claude, замена закомментированного примера в openspec/config.yaml на настройку канонической формы (язык, правила именования capability, придирки валидатора, адреса паспорта и CLAUDE.md), проверка формы своим скриптом openspec.py (имя файла, схема, незаменённый пример, адреса документов, ключи rules против артефактов схемы) и сверка слепка с живой версией инструмента. Использовать, когда в проекте нет каталога openspec/, когда config.yaml остался примером из коробки, когда заводят новый проект или переводят чужой и дошли до шага OpenSpec, а также когда конвейер отказался работать без источника требований. Каталог openspec нужен именно конвейеру: без него не работают ни opsx:propose, ни ревью дизайна, ни сверка требований."
|
||||
---
|
||||
|
||||
# OpenSpec в проекте
|
||||
|
||||
Каталог `openspec/` — **предпосылка конвейера**, а не канона документов. Без него
|
||||
не работают ни `opsx:propose`, ни ревью дизайна, ни `review-specs`: у требований
|
||||
не остаётся дома. Поэтому заводит и настраивает его этот плагин — тот, кто по
|
||||
OpenSpec и работает.
|
||||
|
||||
Канон документов о файле не высказывается вовсе: `docs.py` его не открывает и об
|
||||
его отсутствии молчит. Проект без конвейера живёт без OpenSpec законно, и
|
||||
проверять там нечего. За каноном остаётся одно — **единственный дом**: не
|
||||
пересказан ли в `context` документ, у которого есть свой файл. Это суждение, а не
|
||||
форма, и смотрит его агент.
|
||||
|
||||
## Два шага, и второй важнее первого
|
||||
|
||||
**1. Завести.**
|
||||
|
||||
```
|
||||
openspec init --tools claude
|
||||
```
|
||||
|
||||
Команда кладёт ещё `.claude/skills/openspec-*` и `.claude/commands/opsx/*` — это
|
||||
её нормальная работа, не трогай их.
|
||||
|
||||
**2. Заменить пример.** `openspec init` кладёт `config.yaml`, где `context` и
|
||||
`rules` — закомментированный пример на английском. **Файл из коробки хуже
|
||||
отсутствующего:** он есть, он валиден, имя правильное, — и читается как
|
||||
настроенный, работая как пустой. Узнаётся это по уже написанному предложению: на
|
||||
другом языке, с capability по имени пакета, без единого `SHALL`.
|
||||
|
||||
Пример **заменяется целиком** по образцу:
|
||||
[references/config-skeleton.md](references/config-skeleton.md).
|
||||
|
||||
## Что туда пишут, а что нет
|
||||
|
||||
**Это маршрутизатор, а не второй дом фактов.** Внутрь идёт ровно то, что нужно
|
||||
**в момент порождения артефакта** и чего в этот момент ещё никто не открыл: язык,
|
||||
правила именования capability, придирки валидатора и **адреса** документов
|
||||
проекта.
|
||||
|
||||
Сюда же — **требования к форме `proposal` и `design`**, на которых стоит чекпоинт
|
||||
скилла `av-dev:code-resolve`: объяснение человеку собирается из этих двух
|
||||
артефактов, и требование к ним обязано применяться в момент, когда их пишут, а не
|
||||
вспоминаться шагом позже. Образец их содержит.
|
||||
|
||||
Пересказ паспорта, инвариантов, конвенций и правил ревью сюда **не переносится**.
|
||||
Место для второго дома здесь самое частое: `context` читается при порождении
|
||||
каждого артефакта, туда удобно дописать «чтобы агент знал», и так заводятся копии
|
||||
инвариантов, состава гейта и правил выбора метки. Расходятся они молча, а
|
||||
замечают это в уже написанном предложении.
|
||||
|
||||
Разрез, по которому отличают одно от другого: **утверждение, которое можно
|
||||
опровергнуть, открыв другой файл проекта, — пересказ; строка, которая говорит,
|
||||
какой файл открыть, — ссылка.** Машина этот разрез не проверяет; его смотрит
|
||||
агент `doc-consistency` из плагина канона, когда тот подключён.
|
||||
|
||||
Два адреса обязательны — `docs/passport.md` и `CLAUDE.md`: предложение пишется до
|
||||
того, как кто-либо откроет `docs/`, и без них его пишут, не зная ни границы
|
||||
домена, ни инвариантов. Отсутствие адреса к **существующему** документу
|
||||
`openspec.py check` называет отказом; документа нет в проекте — нет и требования.
|
||||
|
||||
## Инструмент
|
||||
|
||||
```
|
||||
os="$CLAUDE_PLUGIN_ROOT/skills/openspec/scripts/openspec.py"
|
||||
|
||||
python3 $os check --dir <корень> # форма config.yaml в проекте
|
||||
python3 $os form # слепок формы против живого OpenSpec
|
||||
```
|
||||
|
||||
**Коды выхода — общий словарь скриптов av-dev:** 0 сошлось, 1 дрейф, 2 ошибка
|
||||
употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте.
|
||||
Различать 1 и 3 обязательно: «форма разошлась» — рабочая ситуация, «openspec не
|
||||
отвечает» — нерабочая.
|
||||
|
||||
`check` проверяет форму, и каждая проверка — про молчащий пробел, а не про вкус:
|
||||
каталог есть; имя именно `config.yaml` (`config.yml` OpenSpec не читает и об этом
|
||||
не сообщает); ключ `schema` называет ту схему, для которой форма описана;
|
||||
`context` и `rules.specs` не остались примером, **а `SHALL` назван именно внутри
|
||||
`rules.specs`** (в `context` он стоит и в образце, поэтому греп по файлу здесь
|
||||
ничего не значит); `context` называет паспорт и `CLAUDE.md`; ключи под `rules:` —
|
||||
имена артефактов схемы, а не свободные слова. Числа проверок здесь нет намеренно:
|
||||
оно протухает от каждой добавленной.
|
||||
|
||||
**Адреса требуются только к тем документам, которые в проекте есть.** Канон
|
||||
документов ставится отдельным плагином и может быть не подключён; требовать
|
||||
ссылку на несуществующий файл значит требовать битую ссылку. Нет
|
||||
`docs/passport.md` — проверка по нему идёт строкой «не проверялось», и там же
|
||||
сказано, что без канона конвейер работает вслепую.
|
||||
|
||||
### Форма сверяется с живым инструментом
|
||||
|
||||
Схема (`spec-driven`) и перечень артефактов (`proposal`, `specs`, `design`,
|
||||
`tasks`) — **состояние чужого инструмента**, а не наше решение. OpenSpec
|
||||
переименует артефакт: правила под прежним именем перестанут применяться, конфиг
|
||||
останется выглядеть написанным, и молчат при этом все три стороны.
|
||||
|
||||
Сторож — сравнение версий. `check` каждым прогоном спрашивает `openspec
|
||||
--version` (десятые доли секунды) и сравнивает `major.minor` с той версией, на
|
||||
которой форма сверялась; разошлось — **замечание**, не отказ, с именем команды.
|
||||
Патч-версия в сравнение не берётся намеренно: формы она не меняет, а нагоняй на
|
||||
каждый багфикс приучает пролистывать весь блок.
|
||||
|
||||
Перепроверяет `openspec.py form`: он спрашивает `openspec templates --json`, то
|
||||
есть перечень артефактов текущей схемы, и печатает, что разошлось с константами.
|
||||
Дорогой вызов вынесен из `check` сознательно — он стоит втрое дороже опроса
|
||||
версии, а ответ меняется только вместе с версией. **Чинится расхождение в
|
||||
плагине, а не в проекте:** константы скрипта, образец
|
||||
[references/config-skeleton.md](references/config-skeleton.md) и запись в журнал
|
||||
версий канона.
|
||||
|
||||
## Кто зовёт этот скилл
|
||||
|
||||
- `av-dev:doc-init` — шагом заведения нового проекта, до первого документа;
|
||||
- `av-dev:doc-canon` в режиме `adopt` — если на переводимом проекте каталога нет
|
||||
или `config.yaml` остался примером;
|
||||
- `av-dev:code-resolve` и `av-dev:code-review` — не вызовом по ходу, а отсылкой:
|
||||
OpenSpec у обоих жёсткая предпосылка, и на проекте без каталога оба посылают
|
||||
сюда вместо того, чтобы заводить его руками;
|
||||
- человек — когда конвейер отказался работать без источника требований.
|
||||
|
||||
**Копия.** Дом правила — `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` — конвейер.
|
||||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||||
|
||||
<!-- /копия: граница-плагинов -->
|
||||
|
||||
Здесь это значит: вызов не разрешился — плагина конвейера в проекте нет, и тогда
|
||||
OpenSpec заводит человек командой выше.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не пишет спеки и предложения.** Это `opsx:propose` и конвейер задачи.
|
||||
- **Не ведёт документы канона** — их дом плагин `av-dev-docs`, и адреса в
|
||||
`context` только на них ссылаются.
|
||||
- **Не чинит расхождение формы с версией OpenSpec в проекте.** Оно чинится в
|
||||
плагине: константы скрипта, образец здесь, запись в журнал версий канона.
|
||||
- **Не судит, ссылается `context` на документы или пересказывает их.** Машине
|
||||
этот разрез не виден; его смотрит агент `doc-consistency` из плагина канона.
|
||||
Плагина нет — эту проверку не делает никто, и так и скажи.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Образец `openspec/config.yaml`
|
||||
|
||||
Каталог `openspec/` заводится командой — `openspec init --tools claude`, — и она
|
||||
кладёт `config.yaml` с закомментированным примером внутри. Пример **заменяется
|
||||
целиком**: нетронутый файл выглядит настроенным, а работает как пустой.
|
||||
|
||||
**Это маршрутизатор, а не второй дом фактов.** Сюда пишут ровно то, что нужно
|
||||
**в момент порождения артефакта** и чего в этот момент ещё никто не открыл:
|
||||
язык, правила именования capability, придирки валидатора и **адреса** документов
|
||||
канона. Пересказ паспорта, инвариантов, конвенций и правил ревью сюда не
|
||||
переносится: расходится он молча, а замечают это в уже написанном предложении.
|
||||
|
||||
```yaml
|
||||
schema: spec-driven
|
||||
|
||||
context: |
|
||||
Language: Russian
|
||||
Пиши на русском, но:
|
||||
- Структурные заголовки оставляй на английском:
|
||||
## ADDED/MODIFIED/REMOVED Requirements, ### Requirement:, #### Scenario:
|
||||
- Ключевые слова GIVEN/WHEN/THEN и RFC 2119 (SHALL/MUST/SHOULD) — на английском
|
||||
- Технические термины, пути и код — на английском
|
||||
|
||||
Имена capabilities:
|
||||
- Capability — это ПОВЕДЕНИЕ или домен системы, а не пакет кода (совпадение с
|
||||
именем пакета допустимо, но не критерий).
|
||||
- Существительное, понятное без знания кода: ingest, parsing, storage,
|
||||
read-api. НЕ store/httpapi — это реализация.
|
||||
- Гранулярность по принципу «требования меняются вместе». Дробить, когда в
|
||||
одной спеке смешиваются разные заботы. Переименовать дёшево (RENAMED
|
||||
Requirements) — не дроби преждевременно в маленьком проекте.
|
||||
|
||||
RFC 2119 — требование валидатора, не стиль:
|
||||
- Каждое ### Requirement ОБЯЗАНО содержать литерал SHALL или MUST, иначе
|
||||
`openspec validate` падает. Поэтому эти слова и WHEN/THEN не русифицируем.
|
||||
|
||||
Что это за проект — читай перед предложением, а не отсюда:
|
||||
- docs/passport.md — цель, её граница (чем проект НЕ является), потребители,
|
||||
типовые сценарии, референсы;
|
||||
- CLAUDE.md — инварианты с severity и семантика гейта;
|
||||
- docs/architecture.md — устройство; docs/security.md — периметр;
|
||||
docs/adr/ — почему решено так; docs/research/ — что уже измерено.
|
||||
Пересказа этих документов здесь нет намеренно: второй дом факта расходится с
|
||||
первым молча, и заметно это становится в предложении, которое уже написано.
|
||||
|
||||
Ревью: правило выбора метки и состав проходов здесь не пересказываем — их дом
|
||||
скилл av-dev:code-review, проектная настройка — docs/review.md.
|
||||
|
||||
Конвенции кода: механизированное проверяет гейт, прозой остаётся
|
||||
docs/conventions/. Ни состав шагов гейта, ни перечень конвенций здесь не
|
||||
пересказываем: и то и другое растёт по ходу задач.
|
||||
|
||||
Развилка или блокер — сперва prior art. Готовые решения смотрим в референсах
|
||||
паспорта, отвергаем — с названной причиной, и причина идёт в design.md этого
|
||||
же изменения.
|
||||
|
||||
rules:
|
||||
proposal:
|
||||
- Capabilities называй по поведению или домену системы, не по пакету кода
|
||||
- "Why и What Changes — языком домена из docs/passport.md: без SHALL, без имён модулей и функций там, где вещь называется по-русски"
|
||||
design:
|
||||
- "Назови рассмотренные варианты и причину отказа от каждого — из них потом пишется ADR"
|
||||
- "Решение объясняется через то, что человек увидит иначе, а не через устройство кода"
|
||||
specs:
|
||||
# Кавычки обязательны: без них YAML обрежет строку на первом '#'.
|
||||
- "Каждое ### Requirement обязано содержать SHALL или MUST (иначе валидация падает)"
|
||||
- "Сценарий — ровно #### (четыре решётки); три или список молча теряются"
|
||||
- "SHALL/MUST должно стоять в ПЕРВОМ абзаце требования: валидатор смотрит только его"
|
||||
- "Заголовки и WHEN/THEN/GIVEN — на английском, остальной текст на русском"
|
||||
tasks:
|
||||
- "Критерии приёмки задачи — отдельным блоком и дословно: файл задачи закрытие удалит, критерии обязаны его пережить"
|
||||
- "Рубрика ревью дизайна, если оно её дало, идёт в тот же блок: приёмка судится по одному списку, а не по двум"
|
||||
- "Шаг плана формулируется проверяемо — по нему видно «сделано / не сделано» без суждения"
|
||||
```
|
||||
|
||||
**Четыре правила для `specs` сняты отказами валидатора, а не выведены из
|
||||
документации** — потому и записаны дословно: без них каждое второе предложение
|
||||
узнаёт их падением `openspec validate --strict`.
|
||||
|
||||
**Правила для `proposal` и `design` держат чекпоинт скилла
|
||||
`av-dev:code-resolve`.** Там работа останавливается и человеку объясняют, в
|
||||
чём проблема и как её решают, — а объяснение **собирается из этих двух
|
||||
артефактов**, а не сочиняется заново: третий пересказ одного и того же разошёлся
|
||||
бы с обоими. Требование поэтому стоит здесь, в момент порождения артефакта, а не
|
||||
в скилле, который спохватится позже. `design.md` при этом ещё и **сырьё для
|
||||
ADR** — отвергнутый вариант с названной причиной и есть половина будущей записи.
|
||||
|
||||
**Правила для `tasks` держит тот же скилл, и по той же причине — момент
|
||||
порождения.** `tasks.md` — единственное, что переживает задачу: файл задачи
|
||||
закрытие удаляет, а приёмка потом судится по критериям, которые в него
|
||||
скопированы. Туда же ложится рубрика ревью дизайна, если оно её дало. Записанное
|
||||
в момент порождения не приходится вспоминать шагом позже, когда артефакт уже
|
||||
написан. Блок `context` проект
|
||||
дополняет своим (стек, разведка, особенности домена), но **адреса паспорта и
|
||||
`CLAUDE.md` обязательны** — отсутствие адреса к существующему документу
|
||||
`openspec.py check` называет отказом.
|
||||
|
||||
**Ключи под `rules:` — имена артефактов схемы**, а не свободные слова:
|
||||
`proposal`, `specs`, `design`, `tasks`. Правило под чужим именем не применяется
|
||||
и об этом не сообщает, поэтому `rules.spec` вместо `rules.specs` даёт конфиг,
|
||||
выглядящий написанным и не работающий; `openspec.py check` такой ключ называет.
|
||||
Перечень артефактов задаёт OpenSpec, а не мы, — за его актуальностью следит
|
||||
`openspec.py form`.
|
||||
@@ -0,0 +1,404 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Форма `openspec/config.yaml`: проверка проекта и сверка слепка с инструментом.
|
||||
|
||||
Каталог `openspec/` — предпосылка **конвейера**, а не канона документов: без него
|
||||
не работают ни `opsx:propose`, ни ревью дизайна, ни сверка требований. Поэтому и
|
||||
проверка формы живёт здесь, рядом со скиллом, который каталог заводит. Раньше она
|
||||
жила в `docs.py` плагина канона, и у файла было два владельца: один заводит,
|
||||
другой проверяет.
|
||||
|
||||
Проверяется то, что **молчит при поломке**. Файл из коробки хуже отсутствующего:
|
||||
`openspec init` кладёт `config.yaml`, где `context` и `rules` — закомментированный
|
||||
пример на английском. Он есть, он валиден, имя правильное — и читается как
|
||||
настроенный, работая как пустой. Узнаётся это по уже написанному предложению.
|
||||
|
||||
Разбираем текстом, а не YAML-парсером: у скриптов ноль внешних зависимостей, а
|
||||
PyYAML в стандартной библиотеке нет. Всё проверяемое различимо построчно,
|
||||
комментарии отброшены, ключи верхнего уровня стоят в первой колонке.
|
||||
|
||||
Коды выхода — общий словарь скриптов av-dev:
|
||||
0 сошлось
|
||||
1 дрейф: форма разошлась с ожидаемой
|
||||
2 ошибка употребления: аргументы
|
||||
3 окружение: не тот каталог, инструмент не отвечает
|
||||
4 внутренний сбой
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import NoReturn
|
||||
|
||||
OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4
|
||||
|
||||
# Команда заведения. Названа поимённо потому, что её печатает отказ, а отказ без
|
||||
# команды заставляет искать её в другом месте.
|
||||
OPENSPEC_INIT = "openspec init --tools claude"
|
||||
|
||||
# Адреса, которые обязан назвать блок context. Не пересказ документов, а именно
|
||||
# ссылки: предложение пишется до того, как кто-либо откроет docs/, и без этих
|
||||
# двух строк его пишут, не зная ни границы домена, ни инвариантов. Список
|
||||
# короткий намеренно — длинный превращает context во второй дом фактов.
|
||||
#
|
||||
# Третий элемент — путь, по которому проверяется, есть ли документ в проекте
|
||||
# вообще. Канон документов ставится отдельным плагином и может быть не подключён;
|
||||
# требовать ссылку на файл, которого нет, значит требовать битую ссылку.
|
||||
OPENSPEC_POINTERS = [
|
||||
("passport", "docs/passport.md",
|
||||
"граница домена и «чем НЕ является» останутся непрочитанными"),
|
||||
("CLAUDE.md", "CLAUDE.md",
|
||||
"инварианты и семантика гейта останутся непрочитанными"),
|
||||
]
|
||||
|
||||
# --- Слепок чужого инструмента ----------------------------------------------
|
||||
#
|
||||
# Схема, перечень артефактов и версия, на которой это проверено, живут в OpenSpec
|
||||
# и меняются без нашего участия; здесь они записаны, чтобы проверка шла без
|
||||
# запуска node на каждом прогоне.
|
||||
#
|
||||
# Слепок стареет, и потому есть кто это замечает: `check` сравнивает major.minor
|
||||
# установленного OpenSpec с OPENSPEC_CHECKED и, если они разошлись, говорит
|
||||
# замечанием «форма не перепроверена». Перепроверяет команда `form` — она
|
||||
# спрашивает сам инструмент и печатает, что разошлось. Патч-версия сравнением
|
||||
# намеренно не берётся: форма конфига в ней не меняется, а замечание на каждый
|
||||
# багфикс приучило бы пролистывать весь блок.
|
||||
OPENSPEC_CHECKED = "1.5"
|
||||
OPENSPEC_SCHEMA = "spec-driven"
|
||||
|
||||
# Артефакты схемы. Ключ `rules:` адресуется артефакту, и адресованный
|
||||
# несуществующему **молча не действует** — ровно тот класс, ради которого вся
|
||||
# проверка и заведена.
|
||||
OPENSPEC_ARTIFACTS = ("proposal", "specs", "design", "tasks")
|
||||
|
||||
|
||||
@dataclass
|
||||
class Report:
|
||||
errors: list[str] = field(default_factory=list)
|
||||
notes: list[str] = field(default_factory=list)
|
||||
skipped: list[str] = field(default_factory=list)
|
||||
|
||||
def error(self, msg: str) -> None:
|
||||
self.errors.append(msg)
|
||||
|
||||
def note(self, msg: str) -> None:
|
||||
self.notes.append(msg)
|
||||
|
||||
def skip(self, msg: str) -> None:
|
||||
self.skipped.append(msg)
|
||||
|
||||
|
||||
def fail(code: int, msg: str) -> NoReturn:
|
||||
print(msg, file=sys.stderr)
|
||||
sys.exit(code)
|
||||
|
||||
|
||||
def openspec_cli(args: list[str]) -> str | None:
|
||||
"""Спросить сам инструмент. None — его нет или он не ответил."""
|
||||
try:
|
||||
out = subprocess.run(
|
||||
["openspec", *args], capture_output=True, text=True, timeout=30
|
||||
)
|
||||
except (FileNotFoundError, OSError, subprocess.SubprocessError):
|
||||
return None
|
||||
return out.stdout.strip() if out.returncode == 0 else None
|
||||
|
||||
|
||||
def rules_keys(live: str) -> list[str]:
|
||||
"""Имена артефактов, которым адресованы правила, — и только они.
|
||||
|
||||
Идём от строки `rules:` до следующего ключа нулевой колонки, а не ищем
|
||||
отступ по всему файлу: блок `context: |` — литеральный скаляр, внутри него
|
||||
строки вида «Language: Russian» и «av-dev:code-review» выглядят
|
||||
ключами и дали бы находку на ровном месте. Проверено на живом конфиге,
|
||||
который так и падал.
|
||||
"""
|
||||
out: list[str] = []
|
||||
inside = False
|
||||
for line in live.splitlines():
|
||||
if not line.strip():
|
||||
continue
|
||||
if not line[0].isspace():
|
||||
inside = line.startswith("rules:")
|
||||
continue
|
||||
if not inside:
|
||||
continue
|
||||
m = re.fullmatch(r" ([A-Za-z_-]+):\s*", line)
|
||||
if m:
|
||||
out.append(m.group(1))
|
||||
return out
|
||||
|
||||
|
||||
def rules_block(live: str, name: str) -> str:
|
||||
"""Строки правил, адресованных одному артефакту.
|
||||
|
||||
Обход тот же, что у `rules_keys`, и по той же причине: искать по всему файлу
|
||||
нельзя. Литеральный скаляр `context` называет `SHALL` уже в образце, поэтому
|
||||
проверка «правила называют SHALL» грепом по файлу проходила при **пустом**
|
||||
`rules.specs` — то есть молчала ровно в том случае, ради которого написана.
|
||||
"""
|
||||
out: list[str] = []
|
||||
in_rules = False
|
||||
in_name = False
|
||||
for line in live.splitlines():
|
||||
if not line.strip():
|
||||
continue
|
||||
if not line[0].isspace():
|
||||
in_rules = line.startswith("rules:")
|
||||
in_name = False
|
||||
continue
|
||||
if not in_rules:
|
||||
continue
|
||||
m = re.fullmatch(r" ([A-Za-z_-]+):\s*", line)
|
||||
if m:
|
||||
in_name = m.group(1) == name
|
||||
continue
|
||||
if in_name:
|
||||
out.append(line)
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def check_form(root: Path, rep: Report) -> None:
|
||||
"""Настройка заведена и не осталась примером из коробки."""
|
||||
os_dir = root / "openspec"
|
||||
if not os_dir.is_dir():
|
||||
# Здесь это отказ, а не «неприменимо»: скрипт принадлежит конвейеру, а
|
||||
# конвейер без OpenSpec не работает вовсе. Тот же вопрос со стороны
|
||||
# канона документов звучит иначе, и `docs.py` отвечает на него молчанием.
|
||||
rep.error(
|
||||
"нет openspec/ — там дом темы requirements (openspec/specs/) и "
|
||||
f"настройка генерации артефактов; заводится `{OPENSPEC_INIT}`"
|
||||
)
|
||||
return
|
||||
|
||||
if (os_dir / "config.yml").is_file():
|
||||
rep.error(
|
||||
"openspec/config.yml — читается только config.yaml, и этот файл "
|
||||
"останется незамеченным: настройка будет пустой, а выглядеть будет "
|
||||
"заполненной"
|
||||
)
|
||||
|
||||
path = os_dir / "config.yaml"
|
||||
if not path.is_file():
|
||||
rep.error(
|
||||
"нет openspec/config.yaml — язык, правила именования capability и "
|
||||
"придирки валидатора будут заново угадываться на каждом предложении"
|
||||
)
|
||||
return
|
||||
|
||||
text = path.read_text(encoding="utf-8")
|
||||
live = "\n".join(
|
||||
line for line in text.splitlines() if not line.lstrip().startswith("#")
|
||||
)
|
||||
keys = set(re.findall(r"(?m)^([A-Za-z_]+):", live))
|
||||
|
||||
schema = re.search(r"(?m)^schema:\s*(\S+)", live)
|
||||
if schema is None:
|
||||
rep.error(
|
||||
f"в openspec/config.yaml нет ключа schema — ожидается {OPENSPEC_SCHEMA}"
|
||||
)
|
||||
elif schema.group(1) != OPENSPEC_SCHEMA:
|
||||
rep.error(
|
||||
f"schema в openspec/config.yaml — {schema.group(1)}, а форма описана "
|
||||
f"для {OPENSPEC_SCHEMA}"
|
||||
)
|
||||
|
||||
if "context" not in keys:
|
||||
rep.error(
|
||||
"в openspec/config.yaml нет ключа context: файл остался примером из "
|
||||
"коробки — предложение пишется без языка, правил именования "
|
||||
"capability и адресов документов проекта"
|
||||
)
|
||||
else:
|
||||
for pointer, where, why in OPENSPEC_POINTERS:
|
||||
if not (root / where).exists():
|
||||
rep.skip(
|
||||
f"{where} в проекте нет — ссылка на него в context не "
|
||||
f"требуется. Документы канона ведёт отдельный плагин "
|
||||
f"(av-dev-docs), и без него конвейер работает вслепую"
|
||||
)
|
||||
continue
|
||||
if pointer not in live:
|
||||
rep.error(f"openspec/config.yaml не называет {pointer} — {why}")
|
||||
|
||||
if "rules" not in keys or "specs" not in rules_keys(live):
|
||||
rep.error(
|
||||
"в openspec/config.yaml нет rules.specs — придирки валидатора "
|
||||
"нигде не записаны, и каждое предложение узнаёт их отказом"
|
||||
)
|
||||
elif "SHALL" not in rules_block(live, "specs"):
|
||||
rep.error(
|
||||
"rules.specs в openspec/config.yaml не называет SHALL — "
|
||||
"требование без этого литерала валидатор отвергает, а правило "
|
||||
"проекта об этом молчит"
|
||||
)
|
||||
|
||||
# Ключ под rules: — имя артефакта схемы. Опечатка или устаревшее имя не
|
||||
# ломает ничего видимого: правила просто не применяются, а конфиг выглядит
|
||||
# написанным.
|
||||
for name in rules_keys(live):
|
||||
if name not in OPENSPEC_ARTIFACTS:
|
||||
rep.error(
|
||||
f"rules.{name} в openspec/config.yaml — такого артефакта у схемы "
|
||||
f"{OPENSPEC_SCHEMA} нет ({', '.join(OPENSPEC_ARTIFACTS)}): правила "
|
||||
f"под ним не применяются и молчат об этом"
|
||||
)
|
||||
|
||||
|
||||
def check_fresh(rep: Report) -> None:
|
||||
"""Не устарел ли слепок формы.
|
||||
|
||||
Стоит один запуск `openspec --version` — десятые доли секунды. Перечень
|
||||
артефактов и имя схемы отсюда не спрашиваются намеренно: они стоят втрое
|
||||
дороже, а меняются только вместе с версией, и потому за ними ходит команда
|
||||
`form`, а эта проверка говорит, когда её звать.
|
||||
"""
|
||||
got = openspec_cli(["--version"])
|
||||
if got is None:
|
||||
rep.skip(
|
||||
"openspec не отвечает (нет на PATH?) — актуальность формы "
|
||||
"config.yaml не проверялась"
|
||||
)
|
||||
return
|
||||
installed = ".".join(got.split(".")[:2])
|
||||
if installed != OPENSPEC_CHECKED:
|
||||
rep.note(
|
||||
f"форма openspec/config.yaml сверена с OpenSpec {OPENSPEC_CHECKED}, "
|
||||
f"установлен {got}: перепроверить — `openspec.py form`. Пока не "
|
||||
f"перепроверено, проверки формы судят по прежней схеме"
|
||||
)
|
||||
|
||||
|
||||
def report(rep: Report) -> int:
|
||||
for msg in rep.errors:
|
||||
print(f"ДРЕЙФ {msg}")
|
||||
for msg in rep.notes:
|
||||
print(f"ЗАМЕЧАНИЕ {msg}")
|
||||
if rep.skipped:
|
||||
print("\nНЕ ПРОВЕРЯЛОСЬ:")
|
||||
for msg in rep.skipped:
|
||||
print(f" {msg}")
|
||||
|
||||
print(
|
||||
"\nМашина проверила форму: имя файла, схему, незаменённый пример, адреса\n"
|
||||
"документов проекта и ключи rules против артефактов схемы. Чего она не\n"
|
||||
"видит — **пересказ вместо ссылки**: утверждение, которое можно\n"
|
||||
"опровергнуть, открыв другой файл проекта, от строки «открой такой-то\n"
|
||||
"файл» она не отличает. Это суждение агента `doc-consistency` из плагина\n"
|
||||
"канона документов; нет плагина — нет и этой проверки, и так и скажи."
|
||||
)
|
||||
if rep.errors:
|
||||
print(f"\nИтог: дрейф, {len(rep.errors)} пунктов.")
|
||||
return DRIFT
|
||||
print("\nИтог: форма сошлась в механизируемой части.")
|
||||
return OK
|
||||
|
||||
|
||||
def cmd_check(args: argparse.Namespace) -> int:
|
||||
root = Path(args.dir).resolve()
|
||||
if not root.is_dir():
|
||||
fail(ENV, f"нет каталога {root}")
|
||||
rep = Report()
|
||||
check_form(root, rep)
|
||||
check_fresh(rep)
|
||||
return report(rep)
|
||||
|
||||
|
||||
def cmd_form(args: argparse.Namespace) -> int:
|
||||
"""Перепроверить слепок формы по живому OpenSpec.
|
||||
|
||||
Ничего не правит и не трогает проект: спрашивает инструмент и печатает, что
|
||||
разошлось с константами скрипта. Чинит человек — правкой констант, образца в
|
||||
references/config-skeleton.md и записью в журнал версий канона, если форма
|
||||
действительно поменялась.
|
||||
"""
|
||||
version = openspec_cli(["--version"])
|
||||
if version is None:
|
||||
fail(
|
||||
ENV,
|
||||
"openspec не отвечает: поставь его или проверь PATH — "
|
||||
"перепроверять форму нечем",
|
||||
)
|
||||
raw = openspec_cli(["templates", "--json"])
|
||||
if raw is None:
|
||||
fail(ENV, "`openspec templates --json` не отработал — схему не спросить")
|
||||
try:
|
||||
artifacts = tuple(json.loads(raw))
|
||||
except json.JSONDecodeError as exc:
|
||||
fail(ENV, f"`openspec templates --json` отдал неразбираемое: {exc}")
|
||||
|
||||
print(f"OpenSpec установлен: {version}")
|
||||
print(f"форма сверена с: {OPENSPEC_CHECKED}")
|
||||
print(f"артефакты схемы: {', '.join(artifacts)}")
|
||||
print(f"записано в скрипте: {', '.join(OPENSPEC_ARTIFACTS)}")
|
||||
|
||||
diffs: list[str] = []
|
||||
if ".".join(version.split(".")[:2]) != OPENSPEC_CHECKED:
|
||||
diffs.append(
|
||||
f"версия: поднять OPENSPEC_CHECKED до "
|
||||
f"{'.'.join(version.split('.')[:2])} — но только после того, как "
|
||||
f"остальные строки этого отчёта сойдутся"
|
||||
)
|
||||
for name in artifacts:
|
||||
if name not in OPENSPEC_ARTIFACTS:
|
||||
diffs.append(
|
||||
f"новый артефакт {name}: решить, нужны ли ему правила в rules, "
|
||||
f"и добавить имя в OPENSPEC_ARTIFACTS"
|
||||
)
|
||||
for name in OPENSPEC_ARTIFACTS:
|
||||
if name not in artifacts:
|
||||
diffs.append(
|
||||
f"артефакта {name} у схемы больше нет: правила под ним в конфигах "
|
||||
f"проектов молчат — убрать из OPENSPEC_ARTIFACTS, из образца и "
|
||||
f"записать в журнал версий канона"
|
||||
)
|
||||
|
||||
print()
|
||||
if not diffs:
|
||||
print("Слепок сходится. Осталось глазами: не изменились ли придирки")
|
||||
print("валидатора — их скрипт проверить не может, они проявляются только")
|
||||
print("отказом `openspec validate --strict` на живой спеке.")
|
||||
return OK
|
||||
print("Разошлось:")
|
||||
for line in diffs:
|
||||
print(f" - {line}")
|
||||
print()
|
||||
print("Правится в трёх местах сразу: константы этого скрипта, образец")
|
||||
print("`references/config-skeleton.md` и запись в журнал версий канона —")
|
||||
print("иначе проекты останутся на прежней форме молча.")
|
||||
return DRIFT
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="openspec.py",
|
||||
description="форма openspec/config.yaml: проверка проекта и сверка слепка",
|
||||
)
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
|
||||
p_check = sub.add_parser("check", help="форма config.yaml в проекте")
|
||||
p_check.add_argument("--dir", default=".", help="корень проекта")
|
||||
p_check.set_defaults(func=cmd_check)
|
||||
|
||||
p_form = sub.add_parser(
|
||||
"form", help="перепроверить слепок формы по живому OpenSpec"
|
||||
)
|
||||
p_form.set_defaults(func=cmd_form)
|
||||
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
return args.func(args)
|
||||
except SystemExit:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001 — последний рубеж, код 4 по словарю
|
||||
print(f"ВНУТРЕННИЙ СБОЙ: {exc}", file=sys.stderr)
|
||||
return INTERNAL
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,358 @@
|
||||
---
|
||||
name: code-resolve
|
||||
description: "Взять одну задачу и довести её до закрытия. Одна точка входа, три сценария, и выбирает сценарий сам скилл, прочитав постановку. Способ известен и меняется поведение — сценарий решения: цикл Spec Driven Development (opsx propose → разметка → ревью дизайна → чекпоинт с объяснением человеческим языком → opsx apply → ревью кода → archive → синк документации → коммит → закрытие). Способ известен, а спека не меняется (тип chore: тулчейн, зависимости, сборка, гит-хуки, перенос, чистка) — сценарий обслуживания: правка → гейт со сверкой состава проверок → ревью фиксированным планом без change (autotests, operations, плюс conventions, если тронут код) → синк документации → коммит → закрытие; планового стопа нет, change не заводится. Нашлась дельта-спека — задача оказалась шире своего типа: стоп с объяснением простым языком и двумя решениями человека, переформулировать запись в fix или feature и решать её процессом того типа следующим прогоном либо прекратить работу. Способа нет, постановка мутная, тип research — сценарий разведки: вопрос и рамки → чтение документов, кода и внешних источников (можно opsx:explore) → чекпоинт вариантов: 2–4 способа решить, цена каждого, что становится невозможным, рекомендация → ответ уезжает в документы канона, исход — в задачи → вычитка написанного → коммит → закрытие. Разведка кода не пишет и change не заводит, а выбранный способ реализуется следующим прогоном. На входе путь к файлу задачи, её слаг или просто текст. Использовать, когда просят взять, сделать или решить задачу, обновить зависимости или сборку, разобраться, изучить, сравнить подходы, проработать сырую идею, ответить на вопрос из беклога."
|
||||
---
|
||||
|
||||
# Работа над одной задачей
|
||||
|
||||
Проводит **одну** задачу от постановки до закрытия. Вокруг планового стопа — без
|
||||
согласований: механику не обсуждаем, делаем.
|
||||
|
||||
**Сценария три, а точка входа одна.** Какой из них идёт, решает **скилл**,
|
||||
прочитав постановку, а не человек до вызова: «есть ли у задачи очевидный способ
|
||||
решения» и «меняется ли то, что записано в спеке» видно после чтения записи, и
|
||||
требовать этих суждений от вызывающего значит требовать их раньше, чем они
|
||||
возможны.
|
||||
|
||||
| Сценарий | Когда | Чем кончается |
|
||||
| --- | --- | --- |
|
||||
| **решение** | способ известен, меняется поведение | код, ревью, архив, коммит, закрытие |
|
||||
| **обслуживание** | способ известен, спека не меняется: тип `chore` | правка, ревью, синк, коммит, закрытие |
|
||||
| **разведка** | способа нет: тип `research`, сырая идея, мутная постановка | ответ в документах, задачи, коммит, закрытие |
|
||||
|
||||
Ход каждого сценария живёт своим справочником: **решение** —
|
||||
[references/solve.md](references/solve.md), **обслуживание** —
|
||||
[references/maintain.md](references/maintain.md), **разведка** —
|
||||
[references/research.md](references/research.md). Здесь только общее: вход,
|
||||
развилка, правила, которые не зависят от сценария. Сценарии лежат порознь и
|
||||
одинаково, потому что привилегированного среди них нет: тот, что жил бы прямо
|
||||
здесь, читался бы как основной, а прочие — как оговорка.
|
||||
|
||||
## Предпосылки
|
||||
|
||||
- **OpenSpec и скиллы `opsx:*` — жёсткая предпосылка сценария решения**, а не
|
||||
опция. На них стоят его шаги 2, 6 и 8, проход `review-specs` и ревью дизайна
|
||||
(они завязаны на `openspec/changes/<id>/specs/*/spec.md` и на
|
||||
`openspec validate --strict`). **Проект без OpenSpec этим скиллом не ведётся** —
|
||||
подключай OpenSpec, а не вырождай цикл сценария; почему ветка деградации здесь
|
||||
не
|
||||
пишется, сказано в `av-dev:code-review`, раздел «Предпосылки», и дом у этого
|
||||
довода там. Заводить руками не надо: каталог и настройку в `config.yaml`
|
||||
делает скилл `av-dev:code-openspec`. **Сценариям разведки и обслуживания
|
||||
OpenSpec не нужен** — они не заводят change; `opsx:explore` берётся разведкой,
|
||||
если плагин есть.
|
||||
- **Проектные копии этих скиллов и агентов удаляются при установке плагина**
|
||||
(`.claude/skills/` — голые имена `resolve`, `review`, а у проектов прошлого
|
||||
поколения ещё `task-pipeline`, `review-pipeline`, `task-batch`, и с префиксом
|
||||
проекта: `<проект>-task-pipeline`, `<проект>-review-pipeline`;
|
||||
`.claude/agents/<проект>-review-*.md`). Две копии одного скилла расходятся, и
|
||||
побеждает та, что короче названа.
|
||||
|
||||
### Обращение к соседним плагинам
|
||||
|
||||
**Копия.** Дом — `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` — конвейер.
|
||||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||||
|
||||
<!-- /копия: граница-плагинов -->
|
||||
|
||||
Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и
|
||||
`av-dev:task-track`. Чем оборачивается отсутствие каждого — на самих шагах и в
|
||||
разделе «Границы».
|
||||
|
||||
Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё
|
||||
не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта,
|
||||
объёмы, модель угроз, прецеденты, — живут в **документах канона** `av-dev-docs`;
|
||||
карта «что где» — `references/project-facts.md` конвейера ревью.
|
||||
|
||||
**Документов канона нет — проект к нему не приведён.** Скажи это строкой и
|
||||
предложи скилл `av-dev:doc-canon`: одна операция на проект против поразрядной
|
||||
деградации на каждой задаче. Работу при этом не останавливай.
|
||||
|
||||
## Вход
|
||||
|
||||
Задача задаётся **путём к файлу, именем файла, слагом или просто текстом**.
|
||||
Ничего из этого не задано — попроси у вызывающего и остановись; сам в беклог не
|
||||
лезь и приоритеты не интерпретируй: что делать дальше, решает не этот скилл.
|
||||
|
||||
**Запись из каталога сперва проверяется на готовность, и проверяет её машина.**
|
||||
Вызови Skill `av-dev:task-track` и попроси прогнать `ready <слаг>`: он смотрит
|
||||
тип, цель у `feature`, пустой ли раздел вопросов и собраны ли разделы схемы
|
||||
типа. Судить это глазами нельзя — ровно тот случай, где машина дешевле и точнее,
|
||||
а цена ошибки отложенная: недостающие критерии приёмки обнаружатся на приёмке,
|
||||
когда сверять уже не с чем.
|
||||
|
||||
**`ready` отказал — это исход, а не препятствие для тебя.** Скажи, чего не
|
||||
хватает, и остановись: дописывать чужую запись за автора не твоя работа. Исход —
|
||||
«не доведена», с названной причиной.
|
||||
|
||||
**Отказ `ready` сценарий не выбирает.** Запись `research` без раздела «Вопрос»
|
||||
(сырьё) — отказ и здесь: у неё нет вопроса, и разведывать нечего.
|
||||
|
||||
Плагина `av-dev-tasks` в проекте нет или задача пришла текстом — прогонять
|
||||
нечего. Тогда прочитай постановку сам и скажи строкой, что готовность машиной не
|
||||
проверялась; работу при этом не останавливай.
|
||||
|
||||
## Развилка: какой сценарий
|
||||
|
||||
Она в два вопроса, и оба стоят до всякой работы.
|
||||
|
||||
**Первый: есть ли у задачи один очевидный способ решения?**
|
||||
|
||||
- **нет** — тип `research`, сырая идея, новое и незнакомое, мутная постановка,
|
||||
два подхода с разной ценой. **Сценарий разведки** —
|
||||
[references/research.md](references/research.md);
|
||||
- **есть** — что делать, понятно; спорно только как. Тогда второй вопрос.
|
||||
|
||||
**Второй: меняется ли то, что записано в `openspec/specs/`?**
|
||||
|
||||
- **меняется** — появляется или правится поведение. **Сценарий решения** —
|
||||
[references/solve.md](references/solve.md);
|
||||
- **не меняется** — тулчейн и сборка, зависимости, гит-хуки и шаги гейта,
|
||||
перенос, чистка. **Сценарий обслуживания** —
|
||||
[references/maintain.md](references/maintain.md).
|
||||
|
||||
**Второй вопрос решается связкой из двух признаков, и оба обязательны:** тип
|
||||
записи предлагает (`chore`, реже `fix`, возвращающий поведение к уже
|
||||
записанному), а отсутствие дельт подтверждает. Тип объявляет автор и может
|
||||
ошибиться; отсутствие дельт — твоё суждение и принимается только вместе с типом.
|
||||
Признаки разошлись — это стоп, а не выбор: скажи, что тип и предмет работы не
|
||||
сходятся, и остановись. Подробно — [maintain.md](references/maintain.md), раздел
|
||||
«Признак — связка, а не одно условие».
|
||||
|
||||
**Признак не в объёме работы, и это относится к обоим вопросам.** Крупная задача
|
||||
с очевидным способом идёт в решение; маленькая, но незнакомая — в разведку;
|
||||
однострочная правка, меняющая поведение, идёт полным циклом решения, а не
|
||||
обслуживанием. Путь, выбираемый по самооценке размера, — самый дешёвый способ
|
||||
«ускориться» и самый дорогой по последствиям. Тип `research` в разведку идёт
|
||||
всегда: её исход знание, а не изменение системы.
|
||||
|
||||
**Назови выбранный сценарий вслух первой репликой** — одной строкой, с причиной.
|
||||
Молча выбранный сценарий человек обнаруживает по тому, что работа пошла не туда,
|
||||
и обнаруживает поздно.
|
||||
|
||||
### Сценарий выбирается один раз
|
||||
|
||||
**Смена сценария по ходу — событие, а не тихий поворот**, и каждая смена
|
||||
устроена по-своему:
|
||||
|
||||
- **решение → разведка**: обнаружилось, что очевидного способа нет. Это **стоп**
|
||||
с исходом «нужна разведка»: назови, что именно неясно, и не продолжай.
|
||||
Кода к этому моменту не написано, и писать его «пока разбираемся» нельзя;
|
||||
- **обслуживание → решение**: нашлась дельта-спека, то есть поведение всё-таки
|
||||
меняется. Задача не сломалась — она **оказалась шире своего типа**, и стоп
|
||||
здесь несёт человеку выбор: назови тип, которым она оказалась (`fix` —
|
||||
расходится с заявленным, `feature` — снаружи появляется то, чего не было),
|
||||
объясни простым языком, что нашлось, и дай два решения — **переформулировать
|
||||
запись и решать процессом того типа следующим прогоном** либо **прекратить
|
||||
работу**. Третьего — «доделать как обслуживание» — нет. Исход в обоих случаях
|
||||
«меняется спека»; сделанное остаётся в рабочем дереве незакоммиченным, тип
|
||||
меняет `av-dev:task-track` и только после ответа. Подробно —
|
||||
[maintain.md](references/maintain.md), раздел «Дельта нашлась по ходу»;
|
||||
- **обслуживание → разведка**: форма правки неизвестна (мажорное обновление,
|
||||
смена сборщика). **Стоп** с исходом «нужна разведка», по тому же основанию,
|
||||
что и у решения;
|
||||
- **разведка → решение или обслуживание**: способ выбран на чекпоинте вариантов.
|
||||
Разведка **всё равно доводится до конца** — ответ записан, задачи уточнены,
|
||||
коммит сделан, — и работа идёт **следующим прогоном**, который запускает
|
||||
человек.
|
||||
|
||||
Обратной смены «решение → обслуживание» нет: задача, заведшая change, доводится
|
||||
циклом решения. Дельта-спеки, оказавшиеся пустыми, — находка ревью дизайна о
|
||||
самой постановке, а не повод свернуть на короткий путь из середины длинного.
|
||||
|
||||
**Соблазн «разведаю по ходу» живёт именно здесь**, и он дорог тем, что выглядит
|
||||
экономией одного прогона. Разведка внутри решения не имеет своего чекпоинта:
|
||||
выбор делается тем, кто уже начал писать, и человек видит его только в
|
||||
объяснении, где обсуждать выбор поздно. Ровно за это сценарии и разведены — не за
|
||||
то, что это разные работы, а за то, что у них разные моменты для человека.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
in["вход: файл, слаг или текст"]
|
||||
ready["ready: готовность записи<br/>av-dev:task-track"]
|
||||
fork{"есть очевидный<br/>способ решения?"}
|
||||
fork2{"меняется ли<br/>спека?"}
|
||||
solve["сценарий решения<br/>references/solve.md<br/>код, ревью, архив, коммит"]
|
||||
main["сценарий обслуживания<br/>references/maintain.md<br/>правка, ревью, синк, коммит"]
|
||||
res["сценарий разведки<br/>references/research.md<br/>ответ в документы и задачи"]
|
||||
|
||||
in --> ready --> fork
|
||||
fork -->|"да"| fork2
|
||||
fork -->|"нет"| res
|
||||
fork2 -->|"да"| solve
|
||||
fork2 -->|"нет: тип chore"| main
|
||||
solve -.->|"способа всё же нет:<br/>стоп, кода не написано"| res
|
||||
main -.->|"нашлась дельта: стоп,<br/>тип на fix или feature,<br/>следующим прогоном"| solve
|
||||
main -.->|"форма неизвестна:<br/>стоп"| res
|
||||
res -.->|"способ выбран:<br/>следующим прогоном,<br/>зовёт человек"| solve
|
||||
```
|
||||
|
||||
Схема — **сводка**: содержание сценариев в их справочниках, и при расхождении
|
||||
прав справочник.
|
||||
|
||||
## Автономность и плановый стоп
|
||||
|
||||
**У двух сценариев ровно один плановый стоп**, и стоят они в разных местах:
|
||||
у решения — объяснение после ревью дизайна, у разведки — варианты до первого
|
||||
написанного требования. Правило вокруг них общее.
|
||||
|
||||
**У обслуживания планового стопа нет вовсе, и это следствие, а не поблажка.**
|
||||
Один стоп с ожиданием ответа у него всё же есть — по найденной дельта-спеке, — но
|
||||
плановым он не является: через него проходят только те прогоны, где задача
|
||||
оказалась не тем, чем объявлена.
|
||||
Чекпоинт объясняет человеку **выбор**, а у обслуживания выбора нет по
|
||||
построению: что делать, сказано в записи, и объяснение свелось бы к пересказу
|
||||
задачи её же автору. Стоп, на котором нечего решать, вырождается в обряд
|
||||
одобрения и обесценивает те стопы, где решать есть что. Правило необратимого
|
||||
(ниже) действует там полностью и срабатывает чаще, чем в двух других сценариях:
|
||||
выкладка, токены, хуки и чужие данные — обычное содержимое задач обслуживания.
|
||||
|
||||
**Вокруг чекпоинта умолчание прежнее — делать, а не спрашивать.** Чекпоинт не
|
||||
отменяет автономность, он даёт развилкам плановое место, куда копиться.
|
||||
|
||||
Разрез простой:
|
||||
|
||||
- развилка найдена **до** чекпоинта — она его и ждёт. Не спрашивай отдельно:
|
||||
чекпоинт рядом и стоит дёшево, а три вопроса подряд стоят дороже одного
|
||||
разговора;
|
||||
- развилка найдена **после** чекпоинта — старое правило: **запиши вопрос и доведи
|
||||
остаток**, не останавливаясь.
|
||||
|
||||
Запись вопроса устроена так:
|
||||
|
||||
1. **Запиши там, где проект держит вопросы** (секция беклога, файл задачи,
|
||||
трекер — это знает проект). Проект не сказал, куда, — отдельной секцией
|
||||
`Вопросы` в своём докладе, и это тоже исход. Тело отвечает на три вещи: **что
|
||||
именно решить**, **какие есть варианты и цена каждого**, **что стоит, пока
|
||||
решения нет**. Плюс твоя рекомендация — человек чаще соглашается, чем выбирает
|
||||
заново, и готовое суждение экономит ему весь контекст.
|
||||
2. **Переформулируй задачу на остаток** — то, что делается без этого решения.
|
||||
Назови границу: докуда доводим сейчас.
|
||||
3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана
|
||||
в объявленных границах. В разведке остаток — это ответ в объявленных рамках:
|
||||
что успели узнать, где остановились и почему.
|
||||
|
||||
**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими
|
||||
оговорками — в плагине `av-dev-tasks`, скилл `av-dev:task-groom`, раздел
|
||||
`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания».
|
||||
Правило принадлежит управлению задачами, потому что решает **сделана задача или
|
||||
вышла**, — это исход планирования, а не исполнения. **Ссылайся, не
|
||||
пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и
|
||||
потеряла из перечня самое необратимое — запись **наружу**.
|
||||
|
||||
Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами —
|
||||
**материализация нерешённого** (запись состояния, зависящего от неотвеченного
|
||||
вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке).
|
||||
Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход
|
||||
«не доведена».
|
||||
|
||||
Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится
|
||||
осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было —
|
||||
в хранилище, в журнал, в витрину или наружу, — спрашивай человека.
|
||||
|
||||
Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос
|
||||
записан, ничего не коммитится наполовину.
|
||||
|
||||
### Когда спрашивать вне чекпоинта
|
||||
|
||||
По другому основанию — не «сложное решение», а **необратимое действие**:
|
||||
|
||||
- деплой, выкладка наружу, смена публичного адреса или токенов;
|
||||
- удаление или перезапись рабочих данных, включая подрезку архивов;
|
||||
- всё, что уходит за пределы машины.
|
||||
|
||||
Здесь ошибка не откатывается коммитом, поэтому спрашиваем даже когда решение
|
||||
кажется очевидным.
|
||||
|
||||
## Границы: чем этот скилл не владеет
|
||||
|
||||
- **Беклогом, целями и приоритетами.** Задача приходит извне. Скилл её не
|
||||
выбирает, не приоритизирует, не заводит и не переоценивает.
|
||||
- **Форматом задач и документов.** Индексы и документы канона руками не правятся,
|
||||
путь к чужому скрипту не выдумывается: этим владеют `av-dev:task-track` и
|
||||
`av-dev:doc-sync`. Закрытие — работа этого скилла, и это осознанное решение с
|
||||
названной ценой: **приёмщик и исполнитель совпали**. Закрытие поэтому **не окончательно** — человек на
|
||||
груминге (`av-dev:task-groom`) возвращает задачу `reopen` с причиной, а доклад
|
||||
по критериям приёмки становится единственным, по чему приёмка вообще возможна.
|
||||
- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос этого
|
||||
скилла ни на одном шаге и ни в одном сценарии. Чекпоинт решения спрашивает «так
|
||||
ли решаем», чекпоинт разведки — «каким из способов», но не «надо ли».
|
||||
|
||||
Что не принадлежит **отдельному сценарию**, названо у него же: урожай ревью и
|
||||
выбор способа — в [solve.md](references/solve.md), изменение поведения и нарезка
|
||||
пачки — в [maintain.md](references/maintain.md), код и приоритет — в
|
||||
[research.md](references/research.md).
|
||||
|
||||
## Наблюдаемые исходы
|
||||
|
||||
**У каждого сценария их четыре**, и живут они у сценария:
|
||||
[решение](references/solve.md) — сделана, не доведена, оказалась крупнее задачи,
|
||||
нужна разведка; [обслуживание](references/maintain.md) — сделана, не доведена,
|
||||
меняется спека, нужна разведка; [разведка](references/research.md) — способ
|
||||
выбран, знание записано, отказ, не доведена.
|
||||
|
||||
Общего исхода нет намеренно. «Сделана» у решения и «знание записано» у разведки —
|
||||
разные вещи с разной приёмкой, и слово, накрывающее оба, скрывало бы именно то,
|
||||
чем прогон кончился. «Сделана» у решения и у обслуживания совпадает словом, но не
|
||||
определением: у первого в него входит пройденный чекпоинт и заархивированный
|
||||
change, у второго — сверенный состав гейта и синк.
|
||||
|
||||
## Доклад
|
||||
|
||||
Ядро общее, и в нём обязательно:
|
||||
|
||||
- **какой сценарий шёл** — решение, обслуживание или разведка, — и почему выбран
|
||||
он;
|
||||
- **исход** одним из четырёх слов своего сценария и, если он не благополучный,
|
||||
чем ограничен результат;
|
||||
- что сделано, какие вопросы записаны и куда;
|
||||
- чего проверить или узнать **не удалось**.
|
||||
|
||||
Сверх ядра каждый сценарий добавляет своё: [solve.md](references/solve.md) —
|
||||
чекпоинт, change, критерии приёмки, урожай и границы покрытия;
|
||||
[maintain.md](references/maintain.md) — чем подтверждён признак, состав гейта до
|
||||
и после, критерии приёмки, урожай и границы покрытия;
|
||||
[research.md](references/research.md) — вопрос и ответ, адреса записи, заведённые
|
||||
задачи, рамки.
|
||||
|
||||
## Тонкости
|
||||
|
||||
- **Не завязывайся на основную ветку и корень репозитория.** Скилл работает в
|
||||
текущем worktree и на текущей ветке: не делай `git checkout`/`switch`, не
|
||||
создавай веток, не пушь.
|
||||
- Прогон проходит **не больше одного** чекпоинта, и это норма, а не упрощение.
|
||||
Два стопа за одну задачу — цена незнания способа, и платится она двумя
|
||||
прогонами, а не одним длинным. У обслуживания чекпоинта нет ни одного, и это
|
||||
тоже норма: там нечего решать.
|
||||
- Держи вызывающего в цикле короткими репликами на переходах фаз, но не проси
|
||||
подтверждать механику: чекпоинт — единственное место, где ждут ответа, а в
|
||||
обслуживании такого места нет вовсе.
|
||||
- **Сценарий назван вслух — значит, его можно оспорить.** Человек, увидевший в
|
||||
первой реплике «иду разведкой, потому что способа не видно», поправит выбор
|
||||
одной фразой; молча выбранный сценарий он поправит через полчаса работы.
|
||||
@@ -0,0 +1,410 @@
|
||||
# Сценарий «обслуживание»
|
||||
|
||||
Способ решения известен, а **того, что нормирует спека, задача не трогает**:
|
||||
тулчейн и сборка, зависимости, гит-хуки и шаги гейта, перенос и чистка. Сценарий
|
||||
**пишет код**, но не заводит change и не пишет требований. Исход — работающая
|
||||
оснастка и синхронная ей документация.
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для всех трёх сценариев — вход, обращение к соседним плагинам, правило
|
||||
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
|
||||
пересказывается.
|
||||
|
||||
## Почему цикл SDD здесь не урезан, а остался без входа
|
||||
|
||||
Это не поблажка по цене, и называть сценарий «коротким путём для мелких задач»
|
||||
нельзя: путь, выбираемый по самооценке размера, и есть тот самый дешёвый способ
|
||||
«ускориться», против которого написана вся защита сценария решения.
|
||||
|
||||
**У обслуживания нет дельта-спек по построению.** Тип `chore` определён через
|
||||
«наблюдаемое поведение не меняется», а на дельтах стоит весь цикл: `propose`
|
||||
их порождает, разметка выведена **из них**, `review-specs` сверяет **с ними**,
|
||||
объяснение чекпоинта собирается из `proposal.md` и `design.md`, `archive` вливает
|
||||
их в актуальные спеки. Change без дельт — пустой артефакт, который потом надо
|
||||
архивировать, и разметчик по нему назовёт не те темы.
|
||||
|
||||
Шаги цикла здесь не пропущены — **им нечего обрабатывать**. Отсюда и состав
|
||||
сценария: выпали ровно те шаги, у которых нет предмета, и не выпал ни один из
|
||||
тех, у которых он есть.
|
||||
|
||||
## Признак — связка, а не одно условие
|
||||
|
||||
Сценарий выбирается двумя проверками сразу, и обе обязательны:
|
||||
|
||||
1. **тип записи предлагает** — `chore`, реже `fix`, чьё исправление возвращает
|
||||
поведение к уже записанному в спеке;
|
||||
2. **отсутствие дельт подтверждает** — прочитав постановку, ты не находишь
|
||||
требования, которое пришлось бы добавить, изменить или снять.
|
||||
|
||||
Один признак без второго не выбирает сценарий. Тип объявляет автор записи, и он
|
||||
может ошибиться в обе стороны; отсутствие дельт — суждение исполнителя, и оно
|
||||
принимается только тогда, когда согласуется с объявленным типом. Расхождение
|
||||
двух признаков — это не развилка, а стоп: скажи, что тип и предмет работы
|
||||
разошлись, и остановись.
|
||||
|
||||
**Имя сценария не равно имени типа, и это намеренно.** `fix` без дельта-спеки
|
||||
идёт сюда законно — поведение разошлось с **заявленным**, значит заявленное уже
|
||||
записано, и менять спеку не нужно. Сценарий, названный именем типа, такую задачу
|
||||
либо отправил бы в полный цикл ради пустого change, либо принял бы как
|
||||
исключение, а исключения не исполняются.
|
||||
|
||||
## Дельта нашлась по ходу — стоп, и у него свой порядок
|
||||
|
||||
Признак тот же, что на шаге 7 сценария решения: **меняется ли то, что записано в
|
||||
`openspec/specs/`**. Обнаружилось, что меняется, — работа перестала быть
|
||||
обслуживанием в ту же секунду, и продолжать её нельзя: коммит обслуживания
|
||||
заявляет «поведение не менялось», а оно меняется.
|
||||
|
||||
**Задача при этом не сломалась — она оказалась шире своего типа.** Поэтому стоп
|
||||
здесь не «бросить и доложить», а три шага по порядку.
|
||||
|
||||
**1. Назови тип, которым задача оказалась.** Разрез тот же, по которому типы и
|
||||
разведены:
|
||||
|
||||
- **`fix`** — поведение расходится с **заявленным**: спека уже описывает верное,
|
||||
и правка возвращает систему к записанному;
|
||||
- **`feature`** — снаружи появляется то, чего не было: спеке нужно новое
|
||||
требование.
|
||||
|
||||
Тип называется прямо и с причиной. «Нужно менять спеки» без имени типа
|
||||
перекладывает классификацию на человека в тот момент, когда весь материал для неё
|
||||
у тебя.
|
||||
|
||||
**2. Объясни человеку простым языком.** Экран текста, не больше:
|
||||
|
||||
- **что просили сделать** — одной фразой из записи;
|
||||
- **что нашлось** — какое поведение меняется, словами домена, а не именами
|
||||
файлов и функций;
|
||||
- **почему это перестало быть обслуживанием** — одной фразой: у обслуживания
|
||||
поведение не меняется по определению;
|
||||
- **чем задача становится** — `fix` или `feature`, с причиной из разреза выше;
|
||||
- **что уже сделано** и что из этого лежит в рабочем дереве.
|
||||
|
||||
Проверка на простой язык та же, что у чекпоинтов двух других сценариев: **в
|
||||
тексте нет `SHALL`, нет имён файлов и функций там, где вещь называется
|
||||
по-русски, и нет слов, которых нет в паспорте проекта.**
|
||||
|
||||
**3. Дай два решения и жди ответа.** Их ровно два, и оба законны:
|
||||
|
||||
- **переформулировать запись** — тип меняется на названный, и дальше задача идёт
|
||||
**процессом своего типа**: сценарием решения, следующим прогоном. Формат записи
|
||||
правит `av-dev:task-track`, а не ты: у нового типа своя схема разделов, и
|
||||
готовность её проверит `ready` — той же машиной, что и на входе. Прогон
|
||||
обслуживания на этом кончается, исход — «меняется спека»;
|
||||
- **прекратить работу** — человек не готов расширять задачу сейчас. Исход тот
|
||||
же, запись остаётся как была, вопрос записывается там, где проект держит
|
||||
вопросы.
|
||||
|
||||
**Третьего решения — «доделать как обслуживание» — нет.** Оно и есть то самое
|
||||
молчаливое изменение поведения, против которого стоит весь разрез: под коммитом,
|
||||
заявляющим «поменяли оснастку», уехала бы правка, не прошедшая ни ревью дизайна,
|
||||
ни чекпоинта, и не оставившая следа в спеках.
|
||||
|
||||
**Сделанное не выбрасывается ни при каком из двух решений.** Оно остаётся в
|
||||
рабочем дереве незакоммиченным: при переформулировке уезжает в change следующим
|
||||
прогоном, при отказе — человек решает сам, откатить или оставить. Коммитить его
|
||||
сообщением про обслуживание нельзя.
|
||||
|
||||
**Прогон, дошедший до этого стопа, стоит дороже обычного** — и это довод за
|
||||
проверку признака на шаге 1, а не после написанного кода.
|
||||
|
||||
## OpenSpec здесь не предпосылка
|
||||
|
||||
Как и разведке, обслуживанию OpenSpec не нужен: оно не заводит change, не пишет
|
||||
дельта-спек и не архивирует. Ни один из проходов его плана ревью на дельта-спеки
|
||||
не завязан — это сказано и в `av-dev:code-review`, раздел «Прогон без change».
|
||||
Каталога в проекте нет — обслуживание идёт целиком, и деградацией это не
|
||||
является.
|
||||
|
||||
## Планового стопа у этого сценария нет
|
||||
|
||||
**И это следствие, а не упрощение.** Чекпоинт решения объясняет человеку
|
||||
**выбор**: в чём проблема, как решаем, чем рискуем. У обслуживания выбора нет по
|
||||
построению — что делать, сказано в записи, а критерии приёмки у него самые
|
||||
дешёвые из всех типов: команда, которая раньше падала или требовала трёх шагов.
|
||||
Объяснение свелось бы к пересказу задачи её же автору. Стоп, на котором нечего
|
||||
решать, вырождается в обряд одобрения и обесценивает те стопы, где решать есть
|
||||
что.
|
||||
|
||||
**Место, где ответа всё же ждут, одно, и плановым оно не является** — стоп по
|
||||
найденной дельте (раздел «Дельта нашлась по ходу»). Через него проходят не все
|
||||
прогоны, а только те, где задача оказалась не тем, чем объявлена.
|
||||
|
||||
**Правило необратимого при этом действует полностью** (SKILL.md, «Когда
|
||||
спрашивать вне чекпоинта»), и здесь оно опаснее, чем кажется. Единственный
|
||||
сценарий без планового стопа — ровно тот, чья работа чаще прочих лезет в
|
||||
выкладку, в токены, в хуки и в чужие данные. Правка оснастки выглядит безобидной
|
||||
до момента, когда её уже не откатить.
|
||||
|
||||
## Ход работы
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
in["сценарий выбран: обслуживание"]
|
||||
s1["1. прочитать задачу<br/>критерии приёмки и границы"]
|
||||
s2["2. сделать правку<br/>гейт тронут — сверить состав, не цвет"]
|
||||
s3["3. гейт проекта до зелёного"]
|
||||
s4["4. ревью фиксированным планом<br/>av-dev:code-review, без change"]
|
||||
s5["5. синк документации — av-dev:doc-sync"]
|
||||
s6["6. коммит работы — av-dev-git:commit"]
|
||||
s7["7. закрыть задачу — av-dev:task-track,<br/>вторым коммитом учёта"]
|
||||
out["исход назван"]
|
||||
|
||||
in --> s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> out
|
||||
s1 -.->|"форма правки неизвестна"| stop1["стоп: нужна разведка"]
|
||||
s2 -.->|"нашлась дельта-спека"| stop2["стоп: назвать тип,<br/>объяснить, дать два решения"]
|
||||
```
|
||||
|
||||
Схема — **сводка**: содержание каждого шага в его разделе ниже, и при расхождении
|
||||
прав текст.
|
||||
|
||||
## Наблюдаемые исходы сценария
|
||||
|
||||
Четыре, и каждый обязан быть назван в докладе прямо:
|
||||
|
||||
- **сделана** — определение сделанного выполнено целиком;
|
||||
- **не доведена** — с причиной и с записанным вопросом; названо, что именно
|
||||
сделано и до какой границы;
|
||||
- **меняется спека** — работа оказалась шире своего типа. Стоп с объяснением и
|
||||
двумя решениями человека: переформулировать запись в `fix` или `feature` и
|
||||
решать её процессом того типа следующим прогоном — либо прекратить. Сделанное
|
||||
остаётся в рабочем дереве незакоммиченным. Доклад называет **оба**: какой тип
|
||||
предложен и что человек выбрал;
|
||||
- **нужна разведка** — форма правки неизвестна (мажорное обновление, смена
|
||||
сборщика, переезд гейта на другой инструмент) **или сработал триггер ADR**:
|
||||
дорогой откат, намеренный отказ от очевидного подхода, пересмотр прежнего
|
||||
решения. Стоп с названной причиной, разведка идёт следующим прогоном.
|
||||
|
||||
**Последний исход — не редкость, и его стоит ждать.** Незнакомое обслуживание —
|
||||
это выбор подхода с ценой и с тем, что становится невозможным, — предмет чекпоинта
|
||||
вариантов, а не работы без стопа. И там же решение получает законный источник для
|
||||
ADR: список источников канон закрыл двумя — архивный `design.md` и записка
|
||||
разведки, — а обслуживание не производит ни того ни другого.
|
||||
|
||||
## Определение сделанного
|
||||
|
||||
Задача сделана, когда верно всё:
|
||||
|
||||
1. гейт проекта зелёный, и **если правка трогала сам гейт — сверен его состав**,
|
||||
а не только цвет;
|
||||
2. ревью проведено фиксированным планом сценария, исход назван по каждой теме
|
||||
плана, а темы, которых в плане нет, названы в границах покрытия;
|
||||
3. **документация синхронизирована с принуждённым отрицанием** — каждый документ
|
||||
канона получил строку;
|
||||
4. коммит сделан в текущую ветку;
|
||||
5. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван
|
||||
оракул и наблюдаемый исход.** Это доклад приёмщику, а не отметка «принято»:
|
||||
исполнитель и приёмщик здесь совпали, и правило то же, что в решении.
|
||||
|
||||
## Шаги
|
||||
|
||||
### 1. Прочитать задачу
|
||||
|
||||
Прочитай запись. У `chore` обязательны два раздела, и оба нужны тебе прямо
|
||||
сейчас: **«Затрагивает»** — границы, которые у обслуживания часто не в коде
|
||||
(конфиг и его образцы, версия зависимости, команда сборки, файл CI), и
|
||||
**«Критерии приёмки»** — с оракулами.
|
||||
|
||||
Здесь же обе проверки признака: тип предлагает, отсутствие дельт подтверждает
|
||||
(раздел «Признак — связка»). И здесь же — проверка на незнакомое: если форма
|
||||
правки не известна до начала, а нащупывается по ходу, объявляй исход **нужна
|
||||
разведка** и не начинай.
|
||||
|
||||
**Проверка на «заодно».** Обслуживание любит склеиваться в пачку — обновить
|
||||
зависимости, переписать сборку и убрать мёртвый код одной задачей. Не мерджится
|
||||
порознь — это несколько задач: объявляй исход **не доведена** с причиной «задача
|
||||
не одна» и останавливайся. Нарезкой владеет `av-dev:task-track`, а не ты, и
|
||||
делать её по ходу нельзя — получится один коммит, в котором обновление
|
||||
зависимости не отделить от чистки.
|
||||
|
||||
### 2. Сделать правку
|
||||
|
||||
Код и конфиги — по конвенциям проекта. Правка по размеру задачи: чинится названное в записи, соседнее не улучшается
|
||||
заодно.
|
||||
|
||||
**Гейт правится — сверь состав, а не цвет.** Красный, ставший зелёным, виден
|
||||
сразу; убыли проверок гейт не покажет — он зелёный и до, и после. Это самая
|
||||
дорогая из возможных правок оснастки: молча выключено то, чем проверяется всё
|
||||
остальное. Состав проверок и способ его снять — **дело проекта**: он объявляет
|
||||
их семантикой гейта в `CLAUDE.md`. Снимай исходное состояние **до** правки, по
|
||||
тому, как проект это описал.
|
||||
|
||||
**Проект состав не описал — скажи строкой доклада, что сверен только цвет.**
|
||||
Обходного пути не выдумывай: угаданный состав хуже отсутствующего, потому что
|
||||
читается как сверенный. Это же строка и повод — предложить проекту дописать слот
|
||||
в `CLAUDE.md`.
|
||||
|
||||
### 3. Гейт до зелёного
|
||||
|
||||
Прогони гейт и добейся зелёного — он же условие следующего шага: пока гейт
|
||||
красный, проходы с мнением не запускаются.
|
||||
|
||||
**Поведенческая верификация здесь другая, чем в решении.** Проверяется не новое
|
||||
поведение, а то, что прежнее не поехало: команда из `CLAUDE.md` поднимается, шаг
|
||||
сборки отрабатывает, хук ставится на чистом клоне. Правка, которую нельзя
|
||||
проверить ничем, кроме «у меня локально работает», называется в докладе строкой.
|
||||
|
||||
### 4. Ревью — план фиксирован сценарием
|
||||
|
||||
Вызови Skill **`av-dev:code-review`**, дав базу диффа, режим и **план сценария**.
|
||||
Change ты не передаёшь — его нет.
|
||||
|
||||
**Разметчик здесь не зовётся, и это правило, а не пропуск.** Обе оси, по которым
|
||||
он судит, у обслуживания не определены: размер он меряет по `proposal.md`,
|
||||
`design.md`, `tasks.md` и дельта-спекам, а незнакомость — по форме решения,
|
||||
которой здесь нет (незнакомое ушло в разведку шагом 1). Разметчик без своего
|
||||
корпуса вернул бы метку, выведенную из ничего.
|
||||
|
||||
Поэтому план у сценария **свой и постоянный**, и глубину он называет сам —
|
||||
проходы берут её из метки, а метки здесь нет:
|
||||
|
||||
| Тема | Дом | Кто закрывает | Глубина и вход | Когда |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `autotests` | `CLAUDE.md`, семантика гейта | `review-autotests` | как обычно: гейт запускается целиком | всегда |
|
||||
| `operations` | `architecture.*`, раздел эксплуатации | `review-basics` | **сверка**: дом темы против диффа, потолок 2 | всегда |
|
||||
| `conventions` + технический разбор | `conventions.*` | `review-code` | вход `small`: только индекс конвенций; потолки 3 технических и 2 конвенционных; **третья половина включена** — сверка с инвариантами `CLAUDE.md`, потолок 1 | дифф трогает код, а не только оснастку |
|
||||
|
||||
**Глубина названа в плане потому, что иначе её неоткуда взять.** Вход и потолки
|
||||
`review-code` заданы меткой, у `review-basics` меткой задана и сама возможность
|
||||
запуска; на прогоне без метки оба взяли бы их наугад — то есть по-разному от
|
||||
прогона к прогону, и молча.
|
||||
|
||||
**Третья половина `review-code` включена намеренно.** В конвейере она живёт при
|
||||
метке `small`, где приёмник тем не запускается, и сверяет дифф с записанными
|
||||
инвариантами `CLAUDE.md` по темам `security`, `operations` и `architecture`.
|
||||
Здесь у неё та же работа: без неё `security` не смотрит вообще никто.
|
||||
|
||||
Триаж обязателен, как и на всяком прогоне: он единственный сток и единственный,
|
||||
кто сверяет план с исходом. На его вход подаётся этот план — вместо плана
|
||||
разметки, которого нет.
|
||||
|
||||
**Условие третьей строки проверяемое, и смотрится оно по диффу**, а не по
|
||||
намерению: обновление зависимости или правка файла CI кода не трогают, чистка и
|
||||
перенос — трогают. `review-code` — единственный проход, который вообще говорит
|
||||
«здесь ошибка в логике», и чистка, прошедшая без него, проверена только на то,
|
||||
что она собирается.
|
||||
|
||||
**Сигнал о заниженной метке на этом прогоне не работает** — метки нет, и
|
||||
поднимать нечего. Его место занимает признак сценария: показалось, что глубины
|
||||
мало, потому что задача крупнее заявленного, — ищи дельту, а не метку.
|
||||
|
||||
**Границы покрытия называются полностью:**
|
||||
|
||||
- `requirements` — предмета нет, дельта-спек не существует;
|
||||
- `security` — своего прохода нет; сверена против записанных инвариантов внутри
|
||||
`review-code`, а он шёл не всегда. Не шёл — тему не смотрел никто, и это
|
||||
говорится прямо;
|
||||
- `architecture` — то же: только против инвариантов, и только если шёл `code`.
|
||||
|
||||
Отчёт, из которого исчезло «что не смотрел никто», сообщает «проверено», не
|
||||
сообщая, что именно.
|
||||
|
||||
Отработка — как в решении: помеченное `инлайн` чини сам и не логируй, `развилка`
|
||||
— вопросом в запись. После правок снова гейт. Отложенные находки собери в секцию
|
||||
доклада `Урожай`; задачи из него заводит `av-dev:task-track`, не ты.
|
||||
|
||||
### 5. Синк документации — главный шаг этого сценария
|
||||
|
||||
**Вызови Skill `av-dev:doc-sync`.** Правило то же и такое же жёсткое:
|
||||
**принуждённое отрицание** — каждый документ канона либо назван обновлённым, либо
|
||||
получает «не требуется, потому что…». Нетронутые группируются одной строкой.
|
||||
|
||||
**Здесь этот шаг весит больше, чем в решении, и вот почему.** Обслуживание не
|
||||
меняет поведения — значит, почти всё, что оно меняет, это документация: команды,
|
||||
шаги гейта, зависимости поимённо, пути, имя основной ветки, настройки с числовым
|
||||
значением, место механизации правила. Ровно эти факты `doc-code-drift` и сверяет
|
||||
с кодом (перечень закрыт, живёт в каноне) — то есть сценарий, чаще всех прочих
|
||||
двигающий сверяемые факты, обязан отчитаться по ним раньше всех прочих.
|
||||
|
||||
Отдельно один документ, которого нет в перечне тем, а синку он нужен:
|
||||
**`conventions.*`, раздел «Механизировано»** — если правило переехало в линтер, и
|
||||
тогда его проза из конвенций **удаляется**, а не остаётся вторым домом.
|
||||
|
||||
**`adr/` этот сценарий не пополняет, и это не пропуск.** У ADR закрытый список
|
||||
источников — архивный `design.md` либо записка разведки, — и ни того ни другого
|
||||
обслуживание не производит. Поэтому триггеры ADR здесь работают **стоп-признаком,
|
||||
а не поводом завести запись**: сработал дорогой откат, намеренный отказ от
|
||||
очевидного подхода или пересмотр прежнего решения — сценарий выбран неверно,
|
||||
объявляй исход **нужна разведка** и останавливайся. Решение с ценой обязано
|
||||
пройти чекпоинт вариантов, а не появиться в коммите обслуживания, чей смысл —
|
||||
«ничего не решали, поменяли оснастку».
|
||||
|
||||
Список документов и их триггеров здесь не дублируется — он в чек-листе скилла
|
||||
`av-dev:doc-sync`; копия уже однажды разошлась с оригиналом. Плагина в проекте
|
||||
нет — иди за перечнем в свой reference,
|
||||
[references/project-facts.md](../../review/references/project-facts.md) конвейера
|
||||
ревью, добавь `adr/` руками и скажи строкой, что синк сделан по перечню
|
||||
документов, без списка триггеров.
|
||||
|
||||
### 6. Коммит
|
||||
|
||||
Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не
|
||||
создавай и не переключай, ничего не пушь.
|
||||
|
||||
Сообщение — по-русски, **скиллом `av-dev-git:commit`**. Вызов не разрешился —
|
||||
напиши сам и скажи строкой, что форму коммита не сверял никто. Одна задача — один
|
||||
осмысленный коммит.
|
||||
|
||||
### 7. Закрыть задачу — после коммита, не раньше
|
||||
|
||||
**Вызови Skill `av-dev:task-track`** и попроси закрыть задачу как реализованную.
|
||||
Порядок обязателен: закрытие удаляет файл задачи, и сделанное до коммита оно
|
||||
оставило бы задачу закрытой без следа работы, если шаг 6 упадёт.
|
||||
|
||||
**Закрытие тоже коммитится — вторым коммитом, тут же**, сообщением про учёт:
|
||||
`закрыта задача <slug>`. Плагина нет — ничего не выдумывай: скажи, что учёт
|
||||
остаётся за владельцем, и назови исход.
|
||||
|
||||
## Границы: чего обслуживание не делает
|
||||
|
||||
- **Не меняет поведения.** Обнаружилось, что меняет, — стоп с исходом «меняется
|
||||
спека»: назвать тип, объяснить, дать два решения. Это единственная граница
|
||||
сценария, у которой есть проверяемый признак, и она же единственная, которую
|
||||
выгодно нарушить молча.
|
||||
- **Не переписывает запись задачи сам.** Тип ты **предлагаешь** с причиной,
|
||||
меняет его `av-dev:task-track` и только после ответа человека: исполнитель,
|
||||
переклеивший тип на ходу, назначает себе другой процесс и другую глубину
|
||||
проверки.
|
||||
- **Не решает, нужна ли работа.** Как и оба соседних сценария: «надо ли» —
|
||||
вопрос человека.
|
||||
- **Не нарезает пачку на задачи.** «Обновить зависимости и переписать сборку» —
|
||||
это `av-dev:task-track` и его правила нарезки.
|
||||
- **Не выбирает форму правки, когда она незнакома, и не принимает решений с
|
||||
ценой.** Мажорное обновление, смена инструмента, намеренный отказ идут
|
||||
разведкой: там есть чекпоинт вариантов и законный источник для ADR, здесь нет
|
||||
ни того ни другого.
|
||||
- **Не заводит задачи из урожая ревью.** Урожай передаётся списком.
|
||||
|
||||
## Доклад обслуживания
|
||||
|
||||
Общее ядро доклада — в SKILL.md; сверх него сценарий обязан назвать:
|
||||
|
||||
- **что подтвердило признак** — тип записи и то, что дельта-спек не нашлось;
|
||||
дельта нашлась — **какой тип предложен, с причиной, и что человек выбрал**:
|
||||
переформулировать или прекратить;
|
||||
- **что стало иначе для разработчика** — одной фразой, адресуясь ему, а не
|
||||
выдуманному пользователю;
|
||||
- **состав гейта до и после**, если правка его трогала; не сверялся — почему;
|
||||
- по каждому критерию приёмки: **оракул и наблюдаемый исход**;
|
||||
- **`Урожай`** — отложенные находки списком;
|
||||
- **строка границ покрытия**: план сценария фиксирован, разметчик не запускался,
|
||||
`requirements` не смотрел никто, а `security` и `architecture` — только против
|
||||
записанных инвариантов, и то если шёл проход `code`.
|
||||
|
||||
## Тонкости сценария
|
||||
|
||||
- **Самый частый способ соврать этим сценарием — назвать `chore` то, что меняет
|
||||
поведение.** Тип, оставшийся от первой формулировки, врёт ровно там, где по
|
||||
нему выбирают путь; проверка признака стоит одного чтения записи и делается на
|
||||
шаге 1, а не после написанного кода.
|
||||
- **Отсутствие чекпоинта не делает сценарий автономнее прочих.** Правило
|
||||
необратимого здесь то же, и срабатывает оно чаще: выкладка, токены, хуки,
|
||||
чужие данные — обычное содержимое задач обслуживания.
|
||||
- **Зелёный гейт после правки гейта ничего не доказывает.** Это единственное
|
||||
место конвейера, где инструмент проверяет сам себя, и потому состав сверяется
|
||||
отдельно от цвета.
|
||||
- **Правка оснастки, сделанная «заодно» внутри чужой задачи, этим сценарием не
|
||||
проходит вовсе** — она едет в чужом коммите и не получает ни своего ревью, ни
|
||||
своей строки синка. Заметил нужную правку по ходу решения — вопрос в запись,
|
||||
а не правка мимоходом.
|
||||
@@ -0,0 +1,397 @@
|
||||
# Сценарий «разведка»
|
||||
|
||||
Отвечает на вопрос задачи и записывает ответ туда, где он переживёт переписку.
|
||||
Исход — **знание**: уточнённые документы и уточнённые задачи. **Кода этот
|
||||
сценарий не пишет и change не заводит.**
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило
|
||||
необратимого, доклад — живёт в SKILL.md и тут не пересказывается.
|
||||
|
||||
**Разведка кончается своим исходом, а не переходом к коду.** Выбранный способ
|
||||
реализует сценарий решения, и запускает его **человек**, следующим прогоном по
|
||||
уточнённой записи. Причина не в церемонии: разведка только что переписала
|
||||
постановку, и брать её в работу тем же заходом значит решать за человека, стоит
|
||||
ли делать это сейчас, — а это приоритет, и он не наш.
|
||||
|
||||
## OpenSpec здесь не предпосылка
|
||||
|
||||
**OpenSpec этому сценарию не нужен**, и это единственное место скилла, где он не
|
||||
предпосылка. Разведка не заводит change и не пишет дельта-спеки: её артефакты —
|
||||
документы канона и записи каталога задач. Скилл `opsx:explore` полезен и зовётся,
|
||||
когда плагин в проекте есть; не разрешился — разведка идёт чтением документов,
|
||||
кода и внешних источников, и это говорится строкой доклада, а не отменяет
|
||||
работу.
|
||||
|
||||
## Кого зовёт этот сценарий
|
||||
|
||||
`av-dev:doc-sync` (ответ уезжает в документы канона), `av-dev:task-track`
|
||||
(задачи заводятся и уточняются), `av-dev-git:commit`. Правило обращения к соседям
|
||||
и ветка «вызов не разрешился» — общие, они в [SKILL.md](../SKILL.md).
|
||||
|
||||
**Отсутствие канона бьёт по разведке сильнее, чем по решению**, и сказать об этом
|
||||
строкой мало: без документов у ответа нет дома, и знание осядет в переписке.
|
||||
Назови исход и предложи `av-dev:doc-canon`; работу не останавливай, но адрес
|
||||
ответа тогда выбираешь сам и говоришь об этом вслух.
|
||||
|
||||
## Что этот сценарий требует от входа
|
||||
|
||||
Вход общий у обоих сценариев (SKILL.md, раздел «Вход»); своего здесь три условия.
|
||||
|
||||
**Паспорт читается раньше кода.** Граница домена и «чем проект **не** является»
|
||||
отсекают половину вариантов до того, как их начнут сравнивать, — а сравнение
|
||||
вариантов и есть работа этого сценария.
|
||||
|
||||
**Сырьё — `research` без раздела «Вопрос» — не берётся.** Исход «не доведена» с
|
||||
причиной «запись это сырьё»: у неё нет вопроса, а разведка без вопроса
|
||||
превращается в чтение всего подряд с отчётом «интересно, но неприменимо».
|
||||
Дописывать вопрос за автора не твоя работа — этим занят штурм сырья в
|
||||
`av-dev:task-track`. Назови, чего не хватает, и остановись.
|
||||
|
||||
**Разведка пришла текстом — сформулируй вопрос сам одной фразой и покажи
|
||||
формулировку в первой же реплике.** Разведка, чей вопрос не назван вслух,
|
||||
признаётся удавшейся любым результатом.
|
||||
|
||||
## Ход работы
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
in["вход: файл, слаг или текст"]
|
||||
s1["1. вопрос и рамки<br/>сырьё без «Вопроса» — отказ"]
|
||||
s2["2. разведка: документы, код,<br/>внешние источники, opsx:explore"]
|
||||
s3(["3. ЧЕКПОИНТ: варианты<br/>2–4 способа, цена каждого,<br/>что становится невозможным"])
|
||||
s4["4. ответ в документы канона<br/>av-dev:doc-sync"]
|
||||
s5["5. задачи: завести и уточнить<br/>av-dev:task-track"]
|
||||
s6["6. вычитка написанного:<br/>документы и записи задач"]
|
||||
s7["7. гейт проекта, затем коммит<br/>av-dev-git:commit"]
|
||||
s8["8. закрыть разведку — av-dev:task-track,<br/>вторым коммитом учёта"]
|
||||
out["исход назван: знание, задачи,<br/>отказ или «не доведена»"]
|
||||
|
||||
in --> s1 --> s2 --> s3
|
||||
s3 -->|"выбран способ,<br/>отказ или знание"| s4
|
||||
s3 -.->|"вопрос не тот"| s1
|
||||
s4 --> s5 --> s6 --> s7 --> s8 --> out
|
||||
```
|
||||
|
||||
Схема — **сводка**: содержание каждого шага в его разделе ниже, и при расхождении
|
||||
прав текст.
|
||||
|
||||
## Плановый стоп сценария
|
||||
|
||||
**До чекпоинта умолчание прежнее — делать, а не спрашивать.** Развилка, найденная
|
||||
по ходу разведки, не задаётся отдельным вопросом: она копится в чекпоинт, который
|
||||
рядом и стоит дёшево.
|
||||
|
||||
Стоп здесь один, и стоит он **перед записью**. Причина в цене: пока варианты
|
||||
живут в контексте, смена решения стоит абзаца; записанный в документы и разложенный
|
||||
на задачи выбор стоит правки документов и разбора беклога. Второго стопа — «покажи,
|
||||
что именно уедет в документы» — нет намеренно: всё, что пишет разведка, лежит в
|
||||
git и читается диффом, а второй стоп на каждой разведке вырождается в ритуал
|
||||
одобрения.
|
||||
|
||||
**Правило необратимого действует и здесь** (SKILL.md, «Когда спрашивать вне
|
||||
чекпоинта»), и разведка обманчива: она кажется безобидной, а замер лезет туда, где
|
||||
живут данные — прогон на боевой базе, запрос к внешнему платному источнику. Здесь
|
||||
ошибка не откатывается правкой текста.
|
||||
|
||||
## Границы: чего разведка не делает
|
||||
|
||||
- **Кодом.** Ни строки, включая «маленький черновик, чтобы проверить». Замер,
|
||||
требующий кода, — это отдельная задача, и её нужно назвать, а не написать по
|
||||
ходу. Исключение ровно одно и оно не про изменение системы: одноразовый
|
||||
**читающий** прогон (запрос, замер, скрипт в песочнице), чей результат уезжает
|
||||
в ответ с провенансом и который ничего не оставляет в репозитории.
|
||||
- **Приоритетом.** Заведённая задача встаёт в конец своей секции; где ей стоять
|
||||
в очереди, решает человек на груминге (`av-dev:task-groom`). Разведка, сама
|
||||
ставящая свой исход первым в беклоге, назначает приоритет тому, что только что
|
||||
придумала.
|
||||
- **Форматом задач и документов.** Индексы и документы руками не правятся: их
|
||||
ведут `av-dev:task-track` и `av-dev:doc-sync`. Твоё — содержание ответа, их —
|
||||
форма и дом.
|
||||
- **Определением ценности.** «Нужно ли это делать вообще» — вопрос человека.
|
||||
Разведка отвечает «как это можно сделать и чего каждый способ стоит».
|
||||
- **Решением задачи.** Выбранный способ реализует сценарий решения, и запускает
|
||||
его человек следующим прогоном. Перейти в него по ходу нельзя — это тот самый
|
||||
переход, ради невозможности которого сценарии и разведены.
|
||||
|
||||
## Наблюдаемые исходы сценария
|
||||
|
||||
Четыре, и каждый обязан быть назван в докладе прямо. Первые три — это те самые
|
||||
«заведены задачи, записано знание, отказ», которыми кончается разведка по
|
||||
определению типа `research`:
|
||||
|
||||
- **способ выбран** — ответ записан, задачи заведены или уточнены, они готовы к
|
||||
взятию. Дальше сценарий решения, следующим прогоном, и запускает его человек;
|
||||
- **знание записано** — вопрос закрыт, задач он не породил: ответ ценен сам по
|
||||
себе (замер, устройство внешнего формата, «так работает и менять не нужно»);
|
||||
- **отказ** — проверили, проблемы нет либо подход отвергнут. **Полноправный
|
||||
исход, а не пустая работа**: «не делаем и вот почему» экономит всю работу,
|
||||
которая иначе была бы сделана. Причина записывается — без неё через квартал
|
||||
разведку закажут заново;
|
||||
- **не доведена** — вопроса нет (сырьё), рамки исчерпаны без ответа, или человек
|
||||
на чекпоинте не одобрил ни одного варианта. Названо, что успели узнать и до
|
||||
какой границы.
|
||||
|
||||
## Определение сделанного для разведки
|
||||
|
||||
У сценария решения оно своё (SKILL.md); здесь — короткое и другое. Разведка
|
||||
сделана, когда верно всё:
|
||||
|
||||
1. **ответ записан по адресу, который назвала задача** — раздел «Куда ляжет
|
||||
ответ». Адреса не было, а вопрос был — ты назначил адрес сам и сказал об этом
|
||||
строкой;
|
||||
2. **у каждого числа провенанс** — команда или условия, которыми оно получено.
|
||||
Число без источника проход ревью обязан читать как условие, а не как замер, и
|
||||
разведка, оставившая голые числа, вредна: по ним будут решать;
|
||||
3. **отвергнутые варианты названы с причиной**. Отвергнутое без причины
|
||||
возвращается на следующей разведке как новая идея;
|
||||
4. задачи, которые исход породил, заведены — или явно сказано, что не породил;
|
||||
5. **написанное вычитано** — документы агентом `doc-wording`, записи задач
|
||||
проходами `task-form` и `task-wording`, каждый по своей пачке;
|
||||
6. написанное закоммичено, разведка закрыта.
|
||||
|
||||
## Шаги
|
||||
|
||||
### 1. Вопрос и рамки
|
||||
|
||||
Прочитай запись. У типа `research` два обязательных раздела, и оба нужны тебе
|
||||
прямо сейчас: **«Вопрос»** — на что отвечаем, **«Куда ляжет ответ»** — по какому
|
||||
адресу он ляжет. Адрес назван заранее не из аккуратности: ответ, не имеющий дома,
|
||||
остаётся в переписке, и через квартал разведку заказывают заново.
|
||||
|
||||
**Адрес назначает автор записи, а не ты.** Запись из каталога без него до тебя
|
||||
не доходит: `ready` требует непустыми оба раздела и откажет — это стоп со
|
||||
строкой, чего не хватает, а не повод дописать за автора. Иначе исполнитель сам
|
||||
назначает себе приёмку, а приёмка разведки — это и есть записанный по названному
|
||||
адресу ответ.
|
||||
|
||||
**Адрес назначаешь ты ровно в одном случае** — когда записи нет вовсе: разведка
|
||||
пришла текстом или в проекте нет учёта задач. Тогда скажи об этом строкой, а
|
||||
выбирай по канону, а не по удобству:
|
||||
|
||||
| Что узнали | Дом ответа |
|
||||
| --- | --- |
|
||||
| наблюдение о внешнем мире, замер с провенансом | `docs/research/` |
|
||||
| решение с ценой: намеренный отказ, дорогой откат | `docs/adr/` |
|
||||
| факт об устройстве системы | тема `architecture` (или своя тема проекта) |
|
||||
| граница домена, «чем проект **не** является» | `passport` |
|
||||
| ответ нужен только этой работе | тело самой записи |
|
||||
|
||||
Раздел **«Рамки»**, если он есть, — это граница разведки: сколько копаем, какие
|
||||
источники, что заведомо вне. Рамок нет, а вопрос широкий — **назначь их сам и
|
||||
покажи в первой реплике**. Разведка без рамок утекает: она всегда может узнать
|
||||
ещё немного, и признак «достаточно» изнутри не виден.
|
||||
|
||||
Здесь же проверка на «не тот вопрос»: если из записи видно, что отвечать надо на
|
||||
другое, скажи это сразу, а не после разведки.
|
||||
|
||||
### 2. Разведка
|
||||
|
||||
Порядок чтения — от дешёвого к дорогому, и он не произволен:
|
||||
|
||||
1. **документы канона проекта** — половина вопросов уже отвечена там, и разведка,
|
||||
начатая с кода, переоткрывает написанное;
|
||||
2. **код и его история** — `git log` по узлу отвечает на «почему так» чаще, чем
|
||||
кажется;
|
||||
3. **внешние источники** — документация формата, чужой опыт, спецификации;
|
||||
4. **замер** — если вопрос про числа. Числа снимаются с провенансом, иначе они
|
||||
бесполезны на следующем шаге.
|
||||
|
||||
**Скилл `opsx:explore`** — законный инструмент этого шага, если плагин в проекте
|
||||
есть: он держит форму размышления и не даёт ему растечься. **В explore не пишем
|
||||
код.** Вызов не разрешился — работай чтением, скажи это строкой.
|
||||
|
||||
Развилку разведки **не записывай вопросом** — она и есть предмет следующего шага.
|
||||
|
||||
### 3. Чекпоинт: варианты
|
||||
|
||||
**Остановись и покажи человеку способы решить.** Это плановый стоп сценария и
|
||||
единственное место, где разведка ждёт ответа.
|
||||
|
||||
Форма — короткая, экран текста:
|
||||
|
||||
- **вопрос**, на который отвечаем, одной фразой (он уже есть в записи);
|
||||
- **2–4 варианта**, не больше. Больше четырёх — это не выбор, а список: человек
|
||||
не сравнит, а признает свою неспособность сравнить и попросит рекомендацию.
|
||||
У каждого варианта: в чём суть простыми словами, **что даёт**, **чего стоит**,
|
||||
**что становится невозможным** (это ловится хуже всего и стоит дороже всего);
|
||||
- **рекомендация с причиной**. Человек чаще соглашается, чем выбирает заново;
|
||||
- что известно **недостоверно** и как это проверить, если проверять дёшево;
|
||||
- **что уедет в документы и в задачи**, если возражений нет, — одной строкой.
|
||||
Это не второй стоп, а предупреждение: человек видит объём последствий там же,
|
||||
где принимает решение.
|
||||
|
||||
Что нельзя: приносить варианты, различающиеся только реализацией; прятать
|
||||
отвергнутое (отвергнутый вариант с названной причиной — половина будущего ADR);
|
||||
приносить один вариант и называть это выбором.
|
||||
|
||||
Проверка на простой язык та же, что у чекпоинта решения: **в тексте нет `SHALL`,
|
||||
нет имён файлов и функций там, где вещь называется по-русски, и нет слов, которых
|
||||
нет в паспорте проекта.**
|
||||
|
||||
Исходы чекпоинта:
|
||||
|
||||
- **выбран способ** — идёшь на шаг 4, исход разведки будет «способ выбран». Кода
|
||||
ты по нему не пишешь: сценарий кончается записью и коммитом;
|
||||
- **ответ и есть результат** — идёшь на шаг 4, исход «знание записано» или
|
||||
«отказ»;
|
||||
- **вопрос не тот** — возвращаешься на шаг 1: переформулируй вопрос и скажи, что
|
||||
из разведанного остаётся в силе;
|
||||
- **ни один вариант не одобрен** — исход «не доведена» с причиной. Записывается
|
||||
всё равно то, что узнано (шаг 4): выброшенная разведка будет заказана заново.
|
||||
|
||||
### 4. Ответ в документы канона
|
||||
|
||||
**Вызови Skill `av-dev:doc-sync`**: он владеет содержимым документов канона.
|
||||
Передай ему ответ, адрес из шага 1 и провенанс каждого числа — писать содержание
|
||||
за тебя он не будет, но дом и форму держит он. Вычитка языка — тоже его агент, но
|
||||
момент её назван отдельно, шагом 6: пачка собирается из шагов 4 и 5 и до конца
|
||||
пятого не полна.
|
||||
|
||||
**Что именно уезжает:**
|
||||
|
||||
- **ответ на вопрос** — по адресу из шага 1;
|
||||
- **отвергнутые варианты с причинами.** Это половина будущего ADR и единственная
|
||||
защита от повторной разведки того же самого;
|
||||
- **решение с ценой — в ADR**, если оно проходит триггер канона (дорогой откат,
|
||||
намеренный отказ, пересмотр прежнего решения). У разведки, кончившейся без
|
||||
кода, `design.md` не будет никогда, поэтому здесь ADR цитирует **записку
|
||||
разведки**, а не архивный change; канон это допускает прямо, и в записи
|
||||
источник называется.
|
||||
|
||||
**Правило принуждённого отрицания здесь не действует.** Это не синк: разведка
|
||||
трогает те документы, которых коснулся её ответ, и перебирать весь канон ей
|
||||
незачем. Но **названо должно быть каждое место, куда ты писал**, — доклад без
|
||||
перечня адресов неотличим от доклада о ненаписанном.
|
||||
|
||||
**Плагина `av-dev-docs` нет** — путь в его дерево не разрешится ниоткуда, поэтому
|
||||
за перечнем документов иди в **свой** reference:
|
||||
[references/project-facts.md](../../review/references/project-facts.md) конвейера
|
||||
ревью. `docs/adr/` и `docs/research/` в нём отсутствуют намеренно (проход ревью их
|
||||
не открывает), а разведке нужны как раз они — добавь их руками. Пиши сам, скажи
|
||||
строкой: «ответ записан без скилла документации — форму и вычитку не сверял
|
||||
никто».
|
||||
|
||||
### 5. Задачи: завести и уточнить
|
||||
|
||||
**Вызови Skill `av-dev:task-track`.** Он владеет форматом, дедупом и индексами;
|
||||
путь к его скрипту не выясняй и индексы руками не правь.
|
||||
|
||||
Что просишь сделать:
|
||||
|
||||
- **уточнить саму разведку** — если её вопрос по ходу изменился;
|
||||
- **уточнить существующие задачи** — разведка часто отвечает не «что делать», а
|
||||
«что в поставленном неверно»: постановка, границы в разделе «Затрагивает»,
|
||||
критерии приёмки;
|
||||
- **завести новые задачи**, если исход их породил. Формулировки приноси готовыми:
|
||||
заголовок, «зачем», тип, границы. Нарезку на независимо полезные части и
|
||||
проверку на дубли делает он — у него на это свои правила и свой сценарий.
|
||||
|
||||
**Пачку задач показывай списком, прежде чем заводить.** Разведка — самый лёгкий
|
||||
способ надуть беклог: она порождает идеи быстрее, чем кто-либо успевает их
|
||||
оценивать, а заведённая задача живёт, пока её кто-то не выкинет руками.
|
||||
|
||||
Плагина нет — задачи остаются **списком формулировок в докладе**, и это говорится
|
||||
строкой: учёт работ остаётся за владельцем.
|
||||
|
||||
### 6. Вычитка написанного — до гейта, не после
|
||||
|
||||
Разведка правит **две вещи сразу**: документы канона (шаг 4) и записи каталога
|
||||
задач (шаг 5). Обе — текст, и портится он в момент письма, а машина этого не
|
||||
видит: `docs.py check` и `tasks.py check` смотрят форму раскладки, а не залог,
|
||||
оценку без факта, жаргон и термин, которого нет в паспорте проекта.
|
||||
|
||||
Пачка **собирается только сейчас**, и поэтому шаг стоит здесь: раньше пятого шага
|
||||
она не полна, а после коммита вычитка уже правит закоммиченное.
|
||||
|
||||
- **Документы** — агент `doc-wording`, владеет им `av-dev:doc-sync` (раздел
|
||||
«Вычитка»). Пачка — адреса, названные на шаге 4, включая `docs/adr/` и
|
||||
`docs/research/`.
|
||||
- **Записи задач** — два прохода, сперва `task-form`, затем `task-wording`;
|
||||
владеет ими `av-dev:task-track` (раздел «Вычитка: два прохода»). Пачка —
|
||||
заведённые и уточнённые на шаге 5 записи. Заголовок и «зачем» правятся **не
|
||||
молча**: покажи предложенное вместе с тем, что было.
|
||||
|
||||
**Что не правилось, то не вычитывается.** Разведка, кончившаяся одним документом
|
||||
и ни одной задачей, зовёт один проход, и это не пропуск — это названная строкой
|
||||
пачка. Скилл-владелец уже прогнал свою пачку по ходу шага — назови это и второй
|
||||
раз тот же файл не гоняй.
|
||||
|
||||
**Судей канона — `doc-consistency` и `doc-code-drift` — здесь не зови.** Они
|
||||
идут на весь канон разом, стоят дорого, и владеет ими `av-dev:doc-healthcheck`,
|
||||
момент вызова которого выбирает человек. Нужно суждение о согласованности — скажи
|
||||
строкой и предложи `healthcheck`, а не зови агентов сам.
|
||||
|
||||
Ни один проход ничего не правит: они возвращают готовые формулировки,
|
||||
подставляешь их ты — и уже с подставленными идёшь на гейт.
|
||||
|
||||
Плагина нет — вызов не разрешится: скажи строкой, что написанное не вычитывал
|
||||
никто, и обходного пути не выдумывай.
|
||||
|
||||
### 7. Гейт и коммит
|
||||
|
||||
**Сперва гейт проекта** — тот же, что гоняет сценарий решения, и по той же
|
||||
причине: разведка только что правила документы канона и индексы задач, а это
|
||||
ровно то, что машина умеет проверить (`docs.py check`, `tasks.py check --dir`,
|
||||
битые ссылки). Красный гейт чинится здесь, а не оставляется следующему прогону:
|
||||
он придёт за код и получит чужую поломку в наследство.
|
||||
|
||||
Гейта в проекте нет — скажи строкой, что записанное не проверял никто.
|
||||
|
||||
Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не
|
||||
создавай и не переключай, ничего не пушь.
|
||||
|
||||
Сообщение — по-русски, **скиллом `av-dev-git:commit`**: форму сообщения держит
|
||||
он, и здесь она не пересказывается. Вызов не разрешился — напиши сообщение сам и
|
||||
скажи строкой, что форму коммита не сверял никто.
|
||||
|
||||
Одна разведка — один осмысленный коммит: записанный ответ и заведённые задачи
|
||||
уезжают вместе, потому что порознь они полуправда.
|
||||
|
||||
### 8. Закрыть разведку — после коммита, не раньше
|
||||
|
||||
**Вызови Skill `av-dev:task-track`** и попроси закрыть запись: ответ записан —
|
||||
`close --implemented`, ушла без ответа — `close --reason`, и строка уезжает в
|
||||
кладбище.
|
||||
|
||||
**Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно
|
||||
оставило бы разведку закрытой без единого следа работы, если шаг 7 упадёт. У
|
||||
разведки это опаснее, чем у решения: следом работы там служит код, а здесь —
|
||||
только записанный ответ. Закрытая разведка без него не оставляет следа вообще —
|
||||
файл задачи удалён, ответ был в переписке.
|
||||
|
||||
**Закрытие тоже коммитится — вторым коммитом, тут же.** Сообщение короткое, про
|
||||
учёт, а не про работу: `закрыта задача <slug>`. Правило «одна разведка — один
|
||||
коммит» про работу, а учёт — не работа.
|
||||
|
||||
Плагина в проекте нет — **ничего не выдумывай**: скажи в докладе, что учёт задач
|
||||
остаётся за владельцем, и назови исход.
|
||||
|
||||
## Доклад разведки
|
||||
|
||||
Общая форма доклада — в SKILL.md; у разведки он свой, потому что докладывать
|
||||
нечего из того, о чём спрашивают решение (ни метки ревью, ни критериев приёмки,
|
||||
ни архивного change). Коротко, и в нём обязательно:
|
||||
|
||||
- **исход** одним из четырёх слов;
|
||||
- **вопрос и ответ** — по фразе на каждое. Ответ, который не сворачивается во
|
||||
фразу, — признак того, что разведка отвечала не на один вопрос;
|
||||
- **куда записано** — перечнем адресов, а не «документация обновлена»;
|
||||
- **какие задачи заведены и уточнены** — слагами;
|
||||
- **что вычитано и чем** — пачка документов и пачка записей, каждая со своими
|
||||
проходами; не вычитанное называется прямо, вместе с причиной;
|
||||
- **что осталось неизвестным** и чего это стоит: разведка без этой строки
|
||||
сообщает «выяснено», не сообщая, что именно осталось не выяснено;
|
||||
- **рамки**, если они ограничили работу: докуда копали и почему остановились.
|
||||
|
||||
## Тонкости
|
||||
|
||||
- **Ответ «зависит от» — не ответ.** Если разведка кончилась развилкой, её исход
|
||||
— варианты с ценой, а не пересказ обеих сторон без рекомендации.
|
||||
- **Отрицательный результат записывается так же тщательно, как положительный.**
|
||||
Соблазн не писать его велик: кажется, что писать нечего. Через квартал именно
|
||||
этой записи и не хватит.
|
||||
- **Чужую разведку не переоткрывай молча.** Нашёл в `docs/research/` или в
|
||||
`docs/adr/` ответ на свой вопрос — исход «знание записано» со ссылкой, и это
|
||||
лучшая из возможных разведок: она стоила одного чтения.
|
||||
@@ -0,0 +1,412 @@
|
||||
# Сценарий «решение»
|
||||
|
||||
Способ решения известен, спорно только как. Проводит задачу от постановки до
|
||||
закрытия и **пишет код**: цикл Spec Driven Development с одним плановым стопом —
|
||||
объяснением после ревью дизайна.
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило
|
||||
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
|
||||
пересказывается.
|
||||
|
||||
**OpenSpec — жёсткая предпосылка именно этого сценария** (SKILL.md,
|
||||
«Предпосылки»): на нём стоят шаги 2, 6 и 8, проход `review-specs` и ревью
|
||||
дизайна.
|
||||
|
||||
Тонкая обёртка над каноническими скиллами `opsx:propose` / `opsx:apply` /
|
||||
`opsx:archive` — зови их через Skill, не переизобретай их шаги. Ревью — скилл
|
||||
`av-dev:code-review`; он же держит правило выбора метки, а называет её агент
|
||||
`review-scope` — один раз на задачу, для обеих стадий ревью.
|
||||
|
||||
## Ход работы
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
in["сценарий выбран: решение"]
|
||||
s1["1. прочитать задачу<br/>критерии приёмки выписать сразу"]
|
||||
s2["2. opsx:propose — change, дельта-спеки, tasks.md"]
|
||||
s3["3. разметка — review-scope:<br/>размер, сложность, метка, план тем"]
|
||||
s4["4. ревью дизайна, состав по метке<br/>+ отработка замечаний"]
|
||||
s5(["5. ЧЕКПОИНТ: объяснение<br/>в чём проблема, как решаем,<br/>чем рискуем"])
|
||||
s6["6. opsx:apply — код, гейт,<br/>поведенческая верификация"]
|
||||
s7["7. ревью кода, та же метка<br/>+ отработка замечаний"]
|
||||
s8["8. opsx:archive"]
|
||||
s9["9. синк документации — av-dev:doc-sync"]
|
||||
s10["10. коммит работы — av-dev-git:commit"]
|
||||
s11["11. закрыть задачу — av-dev:task-track,<br/>вторым коммитом учёта"]
|
||||
|
||||
in --> s1
|
||||
s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 --> s11
|
||||
s3 -.->|"план задачи: та же метка"| s7
|
||||
s5 -.->|"скорректировать:<br/>меняются дельта-спеки"| s3
|
||||
s7 -.->|"находка отменяет дизайн:<br/>меняются дельта-спеки"| s3
|
||||
```
|
||||
|
||||
Схема — **сводка**: содержание каждого шага в его разделе ниже, и при
|
||||
расхождении прав текст.
|
||||
|
||||
## Наблюдаемые исходы сценария
|
||||
|
||||
Четыре, и каждый обязан быть назван в докладе прямо:
|
||||
|
||||
- **сделана** — определение сделанного выполнено целиком;
|
||||
- **не доведена** — с причиной и с записанным вопросом; что именно сделано и до
|
||||
какой границы, названо явно. Сюда же попадает чекпоинт, на котором человек
|
||||
решение не одобрил;
|
||||
- **оказалась крупнее задачи** — распознаётся **до заведения change**, иначе его
|
||||
придётся выбрасывать. Дальше — декомпозиция, и это не работа этого скилла;
|
||||
- **нужна разведка** — очевидного способа решения нет, и это выяснилось уже в
|
||||
работе. Стоп с названной причиной; кода не написано ни строки **намеренно**.
|
||||
Разведка идёт следующим прогоном.
|
||||
|
||||
## Определение сделанного
|
||||
|
||||
Задача сделана, когда верно всё:
|
||||
|
||||
1. гейт проекта зелёный;
|
||||
2. ревью проведено, **план прогона сверен с исходом по каждой теме**, темы без
|
||||
отчёта и без дома названы в границах покрытия;
|
||||
3. решение прошло чекпоинт и не разошлось с одобренным — либо разошлось, и
|
||||
чекпоинт был пройден заново;
|
||||
4. change заархивирован, дельты влиты в актуальные спеки;
|
||||
5. коммит сделан в текущую ветку;
|
||||
6. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван
|
||||
оракул и наблюдаемый исход** — «прогнал вот это, увидел вот то». Это **доклад,
|
||||
а не сертификация: приёмка — не работа этого скилла.** Исполнитель, ставящий
|
||||
себе галочку «принято», проверяет свою работу своим же взглядом — по границе
|
||||
это может делать только приёмщик, разведённый с исполнителем. Критерии приходят
|
||||
снаружи; скилл их не сочиняет и не занижает. Расхождение «по каждому критерию
|
||||
исход есть, а суть задачи не достигнута» — дефект критериев, и о нём
|
||||
сообщается, а не молча дорабатывается.
|
||||
|
||||
## Шаги
|
||||
|
||||
### 1. Прочитать задачу
|
||||
|
||||
Прочитай запись и связанные спеки и черновики.
|
||||
|
||||
Проект даёт задаче **критерии приёмки** — выпиши их сразу: на шаге 2 они уезжают
|
||||
в `tasks.md` change. Файл задачи может быть удалён до коммита, а критерии обязаны
|
||||
его пережить.
|
||||
|
||||
Здесь же проверка на «крупнее задачи»: видно, что одним заходом это не
|
||||
мерджится, — объявляй исход **до** заведения change.
|
||||
|
||||
### 2. Завести change — `opsx:propose`
|
||||
|
||||
Вызови Skill `opsx:propose`. Получаем `proposal.md`, дизайн, дельта-спеки
|
||||
(`ADDED`/`MODIFIED`/`REMOVED Requirements`), `tasks.md`. Каждое `### Requirement`
|
||||
содержит `SHALL`/`MUST`; структурные заголовки английские, сценарии
|
||||
`GIVEN/WHEN/THEN`. Прогони `openspec validate --strict <id>`.
|
||||
|
||||
Критерии приёмки задачи, если они были, копируются в `tasks.md` отдельным блоком.
|
||||
Задаче предшествовала разведка — её записка и отвергнутые варианты **уже
|
||||
записаны** в документах канона (`docs/research/`, `docs/adr/`): сошлись на них из
|
||||
`design.md`, а не переписывай второй раз. Варианты, разобранные без разведки
|
||||
(способ был очевиден, но у него оказались оттенки), — в `design.md`, с причиной
|
||||
отказа по каждому отвергнутому.
|
||||
|
||||
**`proposal.md` пишется так, чтобы его понял человек, не читавший спек.** Это не
|
||||
стилистическое пожелание: из него собирается чекпоинт шага 5, и переписывать его
|
||||
там заново значит завести второй дом для одного объяснения. Требование стоит в
|
||||
`openspec/config.yaml`, `rules.proposal` — то есть применяется в момент
|
||||
порождения артефакта, а не вспоминается после.
|
||||
|
||||
### 3. Разметка задачи — агент `review-scope`
|
||||
|
||||
**Один запуск на всю задачу, и он обслуживает обе стадии ревью.** Запусти
|
||||
агента `review-scope`, дав ему корень проекта, идентификатор change, базу диффа и
|
||||
запись задачи. Кода на этот момент нет, и это условие его работы, а не помеха.
|
||||
|
||||
Он возвращает **план задачи**:
|
||||
|
||||
- **размер** (малое / среднее / крупное) и **сложность** (знакомое /
|
||||
незнакомое), каждое с обоснованием по факту;
|
||||
- **метку** как максимум по двум осям: `small`, `medium` или `large`;
|
||||
- **состав ревью дизайна** — что звать на шаге 4;
|
||||
- **таблицу тем** «тема → дом → глубина → кто закрывает» — для шага 7;
|
||||
- разнесение документов проекта по трём категориям и строку про директивы.
|
||||
|
||||
**Метку выбираешь не ты.** Раньше состав ревью дизайна называл сам оркестратор —
|
||||
то есть тот, кто только что довёл предложение до `propose`. Разведённости с
|
||||
автором в этой точке не было вовсе; теперь есть.
|
||||
|
||||
**План держи в контексте до конца задачи.** На диск он не пишется: файл-план стал
|
||||
бы четвёртым артефактом рядом с `proposal.md`, `tasks.md` и `design.md`, пережил
|
||||
бы задачу и разошёлся бы с ней молча. Прервался прогон — повтори шаг 3, это самый
|
||||
дешёвый его проход.
|
||||
|
||||
**Разметка повторяется ровно в одном случае** — если правки изменили сами
|
||||
**дельта-спеки**: план выведен из них, и план по отменённым требованиям назовёт
|
||||
не те темы. Во всех прочих случаях, включая переделку формы кода на шаге 7,
|
||||
метка остаётся прежней.
|
||||
|
||||
### 4. Ревью дизайна — ДО кода, состав по метке
|
||||
|
||||
Вызови Skill **`av-dev:code-review`**, дав ссылку на change `<id>`,
|
||||
**план разметки с шага 3** и указание, что это ревью дизайна.
|
||||
|
||||
Состав приходит планом, а не решается здесь:
|
||||
|
||||
| Метка | Проходы на предложении |
|
||||
|---|---|
|
||||
| `small` | `specs` |
|
||||
| `medium` | `specs`, `rubric` |
|
||||
| `large` | `specs`, `rubric`, `architecture` + вопрос автору о трёх формах решения |
|
||||
|
||||
`review-specs` в режиме «дизайн ДО кода» идёт **на каждой задаче**: это самый
|
||||
дешёвый проход конвейера, и он ловит то, что на готовом коде уже не чинят.
|
||||
Остальные включаются меткой, потому что стадия стоит на каждой задаче и каждый
|
||||
лишний проход здесь умножается на число задач.
|
||||
|
||||
Смысл стадии: архитектурная находка на готовом коде стоит переписывания и потому
|
||||
игнорируется — та же находка здесь стоит абзаца обсуждения. Если `review-rubric`
|
||||
запускался, перенеси его рубрику в `tasks.md` как приёмочные критерии; там же уже
|
||||
лежат критерии от постановки, если они были.
|
||||
|
||||
**Отработка замечаний, и она идёт до чекпоинта, а не после:**
|
||||
|
||||
- мелочь и явные улучшения — правь сам в спеках и дизайне;
|
||||
- развилки (компромисс, scope, инвариант) — **не в запись, а в чекпоинт**: он
|
||||
следующим шагом, и это ровно то, ради чего он поставлен здесь;
|
||||
- после правок перепрогони `openspec validate --strict <id>`.
|
||||
|
||||
### 5. Чекпоинт: объяснение
|
||||
|
||||
**Остановись и объясни человеку, что происходит.** Единственный плановый стоп
|
||||
этого сценария, и он обязателен для всякой задачи.
|
||||
|
||||
Он стоит **после** ревью дизайна намеренно. Человек читает объяснение, уже
|
||||
просеянное машиной: то, что поймал бы `review-specs`, до него не доходит, а
|
||||
внимание — самый дорогой ресурс процесса, и тратить его на выловимое машиной
|
||||
нельзя.
|
||||
|
||||
**Объяснение не сочиняется заново — оно собирается из артефактов**, `proposal.md`
|
||||
и `design.md`. Третий пересказ был бы третьим домом одного и того же и разошёлся
|
||||
бы с обоими. Что показываешь:
|
||||
|
||||
- **в чём проблема** — словами домена из паспорта, без имён модулей и функций;
|
||||
- **как решаем** — суть одним абзацем. Не пересказ дельта-спек: спека нормирует,
|
||||
а здесь объясняют;
|
||||
- **что человек увидит иначе**, когда это будет сделано;
|
||||
- **чего мы намеренно не делаем** и почему — граница scope ловится хуже всего;
|
||||
- **чем рискуем и что осталось нерешённым** — сюда съезжаются развилки,
|
||||
накопленные до этого места, и находки ревью с пометкой `развилка`;
|
||||
- **что дальше**, если возражений нет.
|
||||
|
||||
Проверка на «простой язык» одна и механическая: **в тексте нет `SHALL`, нет имён
|
||||
файлов и функций там, где вещь называется по-русски, и нет слов, которых нет в
|
||||
паспорте проекта.** Не проходит — переписывай, а не объясняй, почему иначе
|
||||
нельзя.
|
||||
|
||||
Длина — экран. Длинное объяснение не читают, а пролистывают, и чекпоинт
|
||||
превращается в ритуал одобрения.
|
||||
|
||||
Три исхода:
|
||||
|
||||
- **согласен** — идёшь на шаг 6;
|
||||
- **скорректировать** — правишь спеки и дизайн по сказанному. Изменились
|
||||
**дельта-спеки** — повтори шаг 3 (разметка выведена из них) и ту часть ревью
|
||||
дизайна, которой касается правка; затем чекпоинт **заново**. Правка внутри
|
||||
дизайна без спек — повтори только чекпоинт;
|
||||
- **не одобрено** — исход «не доведена» с причиной. Change остаётся
|
||||
незаархивированным, задача не закрывается, ничего не коммитится наполовину.
|
||||
|
||||
### 6. Написать код — `opsx:apply`
|
||||
|
||||
Вызови Skill `opsx:apply` для реализации `tasks.md`. Код — по конвенциям проекта
|
||||
(каталог `docs/conventions/`). Меняешь схему — обнови её описание в документации
|
||||
тем же change, если проект этого требует: гейт обычно это проверяет.
|
||||
|
||||
Прогони гейт и добейся зелёного — он же гейт следующего шага.
|
||||
|
||||
**Поведенческая верификация.** Если задача меняет реальное поведение (новый
|
||||
эндпоинт, разбор входа, схема, форма ответа) — зелёных юнит-тестов мало. Подними
|
||||
изменение вживую командой из раздела команд `CLAUDE.md` и прогони сценарий.
|
||||
Пропусти только для чисто внутренних правок без наблюдаемого рантайма.
|
||||
|
||||
**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца
|
||||
шага.
|
||||
|
||||
### 7. Ревью кода — та же метка
|
||||
|
||||
Вызови Skill **`av-dev:code-review`**, дав ссылку на change `<id>`,
|
||||
базу диффа, **план разметки с шага 3** и режим запуска.
|
||||
|
||||
**Метку ты не выбираешь, и это правило, а не упрощение.** Её назвал
|
||||
`review-scope` ещё на шаге 3 — по размеру и сложности, с обоснованием по каждой
|
||||
оси. Причина в разведённости: ты только что написал этот код, и решать, насколько
|
||||
глубоко его проверять, тебе нельзя — под давлением «я почти закончил» решение
|
||||
известно заранее. Правило выбора живёт в скилле конвейера —
|
||||
`av-dev:code-review`, `references/review-levels.md`; проектные
|
||||
триггеры — в `docs/review.*`, подраздел «Триггеры метки».
|
||||
|
||||
**Метка не пересматривается по факту диффа.** Дифф может выйти крупнее, чем
|
||||
ожидалось при разметке, — это не повод её поднимать: пересмотр означал бы второй
|
||||
запуск разметчика, ровно то, ради устранения чего он и переехал на шаг 3.
|
||||
|
||||
**Считаешь метку заниженной — скажи это в докладе строкой, а не переспорь.**
|
||||
Разметчик вправе и поднять, и понизить; твоё несогласие это факт для человека, а
|
||||
не команда конвейеру. Место, где такое несогласие превращается в изменение
|
||||
правил, — журнал дефектов `docs/review.md`, и только постфактум.
|
||||
|
||||
**Плана нет — ревью кода не запускается.** Триаж требует план обязательным
|
||||
входом: без него он не может сверить, все ли размеченные темы вернули отчёт, а
|
||||
эта сверка — единственная защита от молчащего пропуска. Потерял план (прервалась
|
||||
сессия, ушёл контекст) — повтори шаг 3, а не гони прогон без него.
|
||||
|
||||
**Режим по умолчанию — `по графу`, и обосновывать его не надо.** Конвейер сам
|
||||
знает свои рёбра: гейт открывает проходы с мнением, проходы с пометкой «держит
|
||||
машину» идут цепочкой (иначе замеры портят друг друга и находка выглядит
|
||||
доказанной), триаж — сток. Просить **`линейно`** нужно только по причине, и она
|
||||
называется строкой: так сказал оператор; машина занята чем-то ещё; идёт разбор
|
||||
самого конвейера.
|
||||
|
||||
Скилл сам гоняет гейт, нужные проходы и обязательный триаж. Возвращает отчёт с
|
||||
потолком 7 пунктов, разметкой `Действие: инлайн | развилка` и секцией границ
|
||||
покрытия.
|
||||
|
||||
**Сверь план прогона с исходом, прежде чем коммитить.** Отчёт начинается планом
|
||||
разметчика — таблицей «тема → дом → глубина → кто закрывает», — и против каждой
|
||||
темы обязан стоять исход. Тема без отчёта и тема без дома — разные вещи, и обе
|
||||
должны быть названы. Реестр короткий (шесть тем ядра плюс свои) — сверка стоит
|
||||
одного взгляда.
|
||||
|
||||
#### Отработка, и здесь появляется одно новое правило
|
||||
|
||||
Помеченное `инлайн` чини сам и не логируй. `развилка` — вопросом в запись (он уже
|
||||
сформулирован триажем, его остаётся перенести). После правок — снова гейт.
|
||||
|
||||
**Находка, отменяющая одобренный дизайн, отменяет и одобрение.** Признак
|
||||
проверяемый: **меняются ли дельта-спеки**.
|
||||
|
||||
- не меняются — находка внутри дизайна, дожимай сам, это обычная отработка;
|
||||
- меняются — решение стало другим, а одобрено было прежнее. Повтори шаг 3
|
||||
(разметка выведена из дельта-спек) и **вернись на чекпоинт шага 5** с тем, что
|
||||
изменилось и почему.
|
||||
|
||||
**Это правило старше правила о развилке.** Находка класса `развилка`, чьё
|
||||
основание — «надо менять спеку», подпадает под оба; побеждает возврат на
|
||||
чекпоинт, а вопрос в запись при нём остаётся, но возврата не заменяет. Иначе
|
||||
одобренный дизайн переделывался бы записанным вопросом, то есть молча.
|
||||
|
||||
Тихо переделать утверждённое нельзя. Чекпоинт, который можно обойти находкой
|
||||
ревью, не значит ничего, а человек при этом уверен, что одобрил именно то, что
|
||||
уехало в коммит.
|
||||
|
||||
**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для
|
||||
этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада
|
||||
`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не этот
|
||||
скилл** — их заводит `av-dev:task-track` своим сценарием «задачи из ревью и
|
||||
аудита»: своя нарезка, свой формат, свои правила дублей. Твоя обязанность — не
|
||||
потерять и передать.
|
||||
|
||||
**Границы покрытия из отчёта не выбрасывай** — они уезжают в финальный доклад
|
||||
сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно»,
|
||||
превращается в ложное ощущение проверенности.
|
||||
|
||||
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`; шаг 8
|
||||
унесёт его в архив вместе с change) — это обязательно, а не «если удобно».** По
|
||||
нему потом видно, что было найдено и что из этого осталось в урожае. И это
|
||||
единственный **независимый** артефакт о составе прогона: своей прозе здесь верить
|
||||
нельзя — она написана тем же, кто мог проход и пропустить.
|
||||
|
||||
### 8. Архивировать — `opsx:archive`
|
||||
|
||||
Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в
|
||||
актуальные спеки. Не пропускай `openspec validate --strict` перед этим.
|
||||
|
||||
### 9. Синк документации
|
||||
|
||||
**Вызови Skill `av-dev:doc-sync`**: он владеет содержимым документов канона и
|
||||
ведёт чек-лист синка.
|
||||
|
||||
**Правило одно и оно жёсткое: принуждённое отрицание.** Доклад обязан назвать
|
||||
**каждый** документ канона — либо чем он обновлён, либо «не требуется, потому
|
||||
что…». Нетронутые группируются одной строкой с общей причиной. Список триггеров
|
||||
прозой уже проверен на живом проекте и дал 6 записей ADR на 43 изменения;
|
||||
работает только обязательное отрицание.
|
||||
|
||||
**Список документов и их триггеров здесь не дублируется** — он в чек-листе скилла
|
||||
`av-dev:doc-sync`, и копия уже однажды разошлась с оригиналом, потеряв два
|
||||
триггера.
|
||||
|
||||
**Плагина `av-dev-docs` в проекте нет** — путь в его дерево не разрешится ниоткуда,
|
||||
поэтому за списком иди в **свой** reference:
|
||||
[references/project-facts.md](../../review/references/project-facts.md)
|
||||
конвейера ревью перечисляет все документы канона с их предметом. Пройди по этому
|
||||
перечню — каждый документ получает строку, отрицание остаётся обязательным.
|
||||
|
||||
**Двух домов в том перечне нет намеренно, а синку они нужны: `docs/adr/` и
|
||||
`docs/research/`.** Проход ревью их не открывает — процессные, — но ADR как раз
|
||||
**главный выход синка**: решение, принятое по ходу задачи, без этой строки
|
||||
теряется систематически. Добавь их к перечню руками: `adr/` — решение с ценой,
|
||||
принятое в этой задаче; `research/` — если по ходу узналось новое о внешнем мире
|
||||
(записку разведки, предшествовавшей задаче, пишет не этот сценарий).
|
||||
Триггеры при этом ты знаешь хуже, и это называется в докладе строкой: «синк
|
||||
сделан по перечню документов, без списка триггеров — плагина `av-dev-docs` нет».
|
||||
Канона в проекте тоже нет — назови это исходом и предложи `av-dev:doc-canon`.
|
||||
|
||||
### 10. Коммит
|
||||
|
||||
Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не
|
||||
создавай и не переключай, ничего не пушь.
|
||||
|
||||
Сообщение — по-русски, **скиллом `av-dev-git:commit`**: форму сообщения держит
|
||||
он, и здесь она не пересказывается. Вызов не разрешился — плагина в проекте нет:
|
||||
напиши сообщение сам и скажи строкой доклада, что форму коммита не сверял никто.
|
||||
Одна задача — один осмысленный коммит.
|
||||
|
||||
### 11. Закрыть задачу — **после коммита, не раньше**
|
||||
|
||||
**Вызови Skill `av-dev:task-track`** и попроси закрыть задачу как реализованную —
|
||||
он владеет форматом и двигает строку индекса сам. Путь к его скрипту не выясняй и
|
||||
индексы руками не правь: мост между плагинами — вызов скилла, а не путь.
|
||||
|
||||
**Порядок обязателен.** Закрытие удаляет файл задачи; сделанное до коммита оно
|
||||
оставило бы задачу закрытой без единого следа работы, если шаг 10 упадёт.
|
||||
|
||||
**Закрытие тоже коммитится — вторым коммитом, тут же.** Удаление файла задачи и
|
||||
правка индексов (их имена знает `av-dev-tasks`, не ты) — это правки в рабочем
|
||||
дереве, и оставить их незакоммиченными нельзя: закрытие, не доехавшее до основной
|
||||
ветки, оставит задачу открытой молча, а опора «индексы под git показывают, что и
|
||||
когда закрыто» без коммита — пустые слова. Сообщение короткое, про учёт, а не про
|
||||
работу: `закрыта задача <slug>`. Это второй коммит осознанно: правило «одна задача
|
||||
— один осмысленный коммит» про работу, а учёт — не работа.
|
||||
|
||||
Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: скажи
|
||||
в докладе, что учёт задач остаётся за владельцем, и назови исход.
|
||||
|
||||
## Доклад решения
|
||||
|
||||
Общее ядро доклада — в SKILL.md; сверх него сценарий решения обязан назвать:
|
||||
|
||||
- **что было одобрено на чекпоинте и совпало ли с тем, что уехало в коммит** —
|
||||
расхождение здесь называется прямо, даже если оно мелкое;
|
||||
- ссылка на архивный change и хеш коммита;
|
||||
- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход** —
|
||||
это доклад приёмщику, а не отметка «принято»;
|
||||
- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс);
|
||||
- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы не
|
||||
запускались и что проверить было невозможно. Доклад без неё сообщает
|
||||
«проверено», не сообщая, что именно.
|
||||
|
||||
## Тонкости сценария
|
||||
|
||||
- Гейт блокирует: пока он красный, проходы с мнением не запускаются. Чинить и
|
||||
перезапускать, а не «посмотреть заодно».
|
||||
- Стиль правок — заточка под проект и конвенции, по размеру задачи, без
|
||||
улучшений заодно.
|
||||
- **Занизить метку ревью, пропустить тему или проскочить чекпоинт — самый дешёвый
|
||||
способ «ускориться», и он же самый дорогой по последствиям.** Защита устроена
|
||||
так, что регулятора у тебя нет: метку выбирает разметчик **до того**, как ты
|
||||
написал код, план сверяется по темам, непокрытое называется строкой, а
|
||||
расхождение с одобренным — отдельным пунктом доклада.
|
||||
- **Заведение задач из урожая ревью — не твоя работа.** Отложенные находки
|
||||
отдаются **списком**; превращает их в задачи `av-dev:task-track`, у него на
|
||||
этот вход отдельный сценарий «задачи из ревью и аудита». Плагина нет — урожай
|
||||
остаётся списком в докладе, и это говорится строкой.
|
||||
- **Способ решения ты не выбираешь.** Он приходит известным: из постановки, из
|
||||
разведки, от человека. Выбор между двумя подходами с разной ценой делается в
|
||||
разведке, у своего чекпоинта, — не по ходу этого сценария.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,108 @@
|
||||
# Калибровка проходов
|
||||
|
||||
Без измерения набор проходов растёт монотонно и вырождается в театр: каждый
|
||||
кажется полезным, потому что иногда что-то говорит. Калибровка отвечает на
|
||||
единственный вопрос — **ловит ли проход дефект своего класса**.
|
||||
|
||||
## Процедура (инъекция дефекта)
|
||||
|
||||
1. Взять **реальный коммит** из истории (`git log --oneline`), лучше
|
||||
архивированный change с непустым диффом.
|
||||
2. Внести в него **один** дефект того класса, который проход обязан ловить по
|
||||
своему charter'у. Дефект должен быть правдоподобным — таким, какой реально
|
||||
пишет модель, а не карикатурой (`panic("TODO")` не считается).
|
||||
3. Прогнать **только этот проход** на подготовленном диффе — **три раза**,
|
||||
каждый в чистом контексте.
|
||||
4. Зафиксировать: нашёл `n/3`, число находок всего, число ложных.
|
||||
5. Вердикт:
|
||||
|
||||
| Результат | Вердикт | Что делаем |
|
||||
|---|---|---|
|
||||
| нашёл 3/3 или 2/3, ложных немного | `keep` | ничего |
|
||||
| нашёл 1/3 или 0/3 | `retune` | правим charter — сужаем вход, убираем чек-лист, добавляем оракул |
|
||||
| `retune` уже был дважды подряд | `drop` | удаляем проход |
|
||||
| находит, но ложных больше трети от всех находок | `retune` | триаж съедает больше, чем экономит проход |
|
||||
|
||||
Вердикты образуют храповик со счётчиком — его-то таблица и не показывает:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state "проход в составе метки" as live
|
||||
state "retune №1 — правка charter'а" as r1
|
||||
state "retune №2 — последняя попытка" as r2
|
||||
state "проход удалён" as dead
|
||||
|
||||
[*] --> live: заведён и откалиброван ДО включения
|
||||
live --> r1: 1/3, 0/3 или ложных больше трети
|
||||
r1 --> live: замер keep — счётчик сброшен
|
||||
r1 --> r2: снова не ловит
|
||||
r2 --> live: замер keep — счётчик сброшен
|
||||
r2 --> dead: снова не ловит — это театр
|
||||
```
|
||||
|
||||
Схема — **сводка** к таблице вердиктов выше: она добавляет только счётчик, и при
|
||||
расхождении прав таблица.
|
||||
|
||||
**`retune` не более двух раз подряд.** Проход, не находящий дефект своего класса
|
||||
в 2 из 3 прогонов после двух правок промпта, — это театр. Удалять, а не
|
||||
бесконечно править формулировки: каждая итерация правки промпта стоит дороже,
|
||||
чем отсутствие прохода.
|
||||
|
||||
**Существующий проход не удаляется без замера.** Сначала калибровка, потом
|
||||
решение — иначе удаляется то, что работало, а остаётся то, что громче. Обратный
|
||||
пример уже был: проход про идиоматичность стоял в списке на удаление как
|
||||
«вкусовщина», а замер показал, что он зарабатывает **экспериментами против
|
||||
поведения библиотеки и драйвера**, — и находка, воспроизведённая числом, отменила
|
||||
решение, принятое по ощущению.
|
||||
|
||||
## Состав проходов принадлежит плагину, а не проекту
|
||||
|
||||
Проходы общие. Проект не может удалить проход — он может **не звать** его, и
|
||||
тогда это идёт строкой «не запускался» в границы покрытия, как любой другой
|
||||
пропуск. Молча сузить состав нельзя: пропуск прохода не отличим от прохода без
|
||||
находок.
|
||||
|
||||
Отсюда два следствия:
|
||||
|
||||
- **правка charter'а — правка для всех проектов.** Прежде чем сужать
|
||||
формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки
|
||||
живёт там, метод — в charter'е;
|
||||
- **удаление прохода из плагина требует замера на двух проектах**, а не на одном:
|
||||
класс, не всплывший здесь, мог быть единственным работающим там.
|
||||
|
||||
## Пробы дефектов по проходам
|
||||
|
||||
Проба — заготовка инъекции. Список пополняется из журнала проскочивших дефектов
|
||||
(см. [review-journal.md](review-journal.md)): реальный проскочивший дефект —
|
||||
лучшая проба, какая вообще возможна, потому что синтетические смещены в сторону
|
||||
тех, которые уже умеешь придумывать.
|
||||
|
||||
| Проход | Класс дефекта для инъекции | Заготовка пробы |
|
||||
|---|---|---|
|
||||
| `review-scope` | пропущенная тема | положить в `docs/` новый документ и проверить, попал ли он в план темой |
|
||||
| `review-autotests` | отсутствующая верификация | убрать тест на изменённую ветку, оставить код рабочим |
|
||||
| `review-specs` | поведение вне спеки | добавить незаказанный фолбэк-дефолт на пустом входе |
|
||||
| `review-code` | нарушение прозаической конвенции | увести штатный отказ мимо единой точки трансляции ошибки |
|
||||
| `review-code` | технический дефект | не проверить возвращённую ошибку в ветке раннего возврата |
|
||||
| `review-rubric` | нарушенное свойство узла | у клиента внешнего сервиса убрать таймаут и протяжку `context` |
|
||||
| `review-basics` | отказ, видимый чтением | убрать обработку ошибки записи так, чтобы отказ считался успехом |
|
||||
| `review-basics` | своя тема проекта | нарушить правило из документа, у которого нет именного прохода |
|
||||
| `review-architecture` | второй способ | завести вторую точку генерации id мимо единой |
|
||||
| `review-adversary` | построенный путь | принять внешний идентификатор без разбора до запроса в хранилище |
|
||||
| `review-ops` | деградация окружения | убрать обработку недоступности внешней зависимости в фоновом цикле |
|
||||
| `review-triage` | шум | подать 20 находок, из них 15 вкусовщина и 3 дубля — проверить потолок и дедуп |
|
||||
|
||||
Метрик сверх этого не заводим. Precision, корреляция между проходами, стоимость
|
||||
прогона в токенах — всё это красиво звучит и никем не считается вручную; набор
|
||||
показателей, который не собирают, создаёт впечатление измеряемости и тем вреден.
|
||||
Работает ровно один механизм: инъекция дефекта и вердикт. Если корреляция двух
|
||||
проходов действительно бросается в глаза — это видно по полю `Найдено проходом`
|
||||
в триажированных отчётах и без отдельной метрики.
|
||||
|
||||
## Когда калибровать
|
||||
|
||||
- при заведении нового прохода — **до** включения в состав метки по умолчанию;
|
||||
- при правке charter'а существующего — иначе непонятно, правка помогла или нет;
|
||||
- при появлении записи в журнале проскочивших дефектов — калибруем тот проход,
|
||||
который должен был поймать;
|
||||
- планово — нет. Календарная калибровка ради галочки сама превращается в театр.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Контракт находок
|
||||
|
||||
Единый формат для всех проходов конвейера ревью. Проход, нарушивший контракт,
|
||||
считается сломанным — триаж вправе выбросить его вывод целиком.
|
||||
|
||||
## Форма находки
|
||||
|
||||
```
|
||||
### <краткая формулировка ПОСЛЕДСТВИЯ, не симптома>
|
||||
- Файл: internal/<пакет>/<файл>.go:120-134
|
||||
- Severity: critical | major | minor | nit
|
||||
- Confidence: high | medium | low
|
||||
- Оракул: <падающий тест / команда с выводом / положение руководства / нет>
|
||||
- Последствие: <что произойдёт и при каких условиях>
|
||||
- Предложение: <конкретное изменение>
|
||||
- Найдено проходом: <имя агента; у проходов с раздельными потолками — имя и половина, например `code/техника`>
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
- **Заголовок через последствие.** Не «нет проверки токена», а «читатель без
|
||||
токена выгрузит всю историю». Не «слияние перезаписывает запись», а «повторная
|
||||
доставка сотрёт поля у уже сохранённой записи, и восстановить их нечем».
|
||||
Симптом в заголовке — это заявка на то, что читатель сам достроит последствие;
|
||||
он не достроит, он просто починит симптом.
|
||||
- **`critical` без оракула или построенного пути не существует.** Оракул — это
|
||||
падающий тест, вывод выполненной команды или поимённое положение руководства. Не
|
||||
«вероятно, здесь гонка», а прогон детектора гонок с его выводом.
|
||||
- **`confidence: low` — это «так обычно пишут».** Такие находки допустимы, но не
|
||||
поднимаются выше `minor`. Частотность конструкции в публичном коде — не
|
||||
аргумент.
|
||||
- **Находка без поля «Последствие» не выводится вовсе.** Пустое «Последствие:
|
||||
ухудшает читаемость» равносильно отсутствию поля.
|
||||
- **`nit` допустим только при нарушении записанной конвенции** — со ссылкой на
|
||||
файл и раздел конвенций проекта (`docs/conventions/`) либо на
|
||||
правило линтера. Если правило механизируемо, но не механизировано — это не
|
||||
находка ревью, это `Promote candidate` (см. [promote.md](promote.md)).
|
||||
- **`critical` по основанию «нарушен инвариант проекта» требует инвариантов.**
|
||||
Ссылка идёт на пункт раздела инвариантов `CLAUDE.md` дословно. Без них основание
|
||||
недоступно — см. [project-facts.md](project-facts.md), поразрядная деградация.
|
||||
- **Расхождение — не дефект, пока не названо последствие.** Особенно для
|
||||
архитектурного прохода: «я бы сделал иначе» без последствия не выводится.
|
||||
|
||||
## Шкала severity
|
||||
|
||||
| Severity | Что это | Пример |
|
||||
|---|---|---|
|
||||
| `critical` | нарушение инварианта проекта, потеря или порча данных, утечка секрета, построенный путь к отказу | запись потеряна при слиянии; тело пользовательской выгрузки в поле лога |
|
||||
| `major` | сломанное требование дельта-спеки, необрабатываемый отказ штатного сценария, флаки-тест, поведение вне спеки, меняющее исход | приём отвечает 200, не записав тело: доставка считается принятой, а данных нет |
|
||||
| `minor` | отступление от конвенции с реальной ценой, отсутствующая наблюдаемость, дублирование, которое разойдётся | ни одного чекпоинта на пути разбора: молчащая автоматизация неотличима от пустого потока |
|
||||
| `nit` | нарушение записанной конвенции без последствий за пределами чтения | `msg` с интерполяцией вместо константы |
|
||||
|
||||
Шкала привязана к обратимости, а не к громкости: класс «необратимо и молча»
|
||||
всегда весит больше класса «шумно и лечится повтором». Что здесь необратимо,
|
||||
говорит `CLAUDE.md` — что в этом проекте необратимо.
|
||||
|
||||
## Блок границ покрытия
|
||||
|
||||
Каждый проход завершает вывод этим блоком. Он не сокращается и не заменяется
|
||||
фразой «всё проверено».
|
||||
|
||||
```
|
||||
## Coverage of this pass
|
||||
- проверено: <что реально прочитано/запущено, с путями и командами>
|
||||
- не проверялось и почему: <бюджет, недоступный инструмент, вне входа>
|
||||
- принципиально недоступно этому проходу: <из charter'а агента>
|
||||
```
|
||||
|
||||
## Финальный отчёт триажа
|
||||
|
||||
Секции строго в этом порядке, потолок — 7 пунктов в первых двух:
|
||||
|
||||
1. `Блокирует мердж` (≤3, каждая с оракулом);
|
||||
2. `Стоит исправить сейчас` (≤4);
|
||||
3. `Гипотезы без доказательства` — что понижено и почему;
|
||||
4. `Promote candidates` — кандидаты в конвенцию или правило линтера;
|
||||
5. `Границы покрытия` — сводная, обязательная.
|
||||
|
||||
Перед секциями — сводка для человека: размер, сложность, метка и режим
|
||||
прогона, состояние гейта, **план разметки задачи с исходом по каждой теме**,
|
||||
сколько находок пришло на вход и сколько осталось.
|
||||
|
||||
**Реестр сводки — темы, а не проходы, и это не оформление.** Перечень запущенных
|
||||
проходов отвечает «все, кто должен был, отработали» и молчит о том, что именно
|
||||
осталось непроверенным: уехавший в старшую метку проход уносит тему с собой
|
||||
беззвучно. План же называет тему, её дом, глубину и исполнителя — и тема,
|
||||
оставшаяся без отчёта, видна сразу. Перечень проходов из сводки не исчезает, но
|
||||
идёт **внутри** плана, колонкой «кто закрывает».
|
||||
|
||||
Каждая находка в секциях 1–2 несёт дополнительное поле:
|
||||
|
||||
```
|
||||
- Действие: инлайн | развилка
|
||||
```
|
||||
|
||||
`инлайн` — оркестратор чинит сам, не спрашивая и не логируя. `развилка` — цена
|
||||
исправления сопоставима с переработкой, либо выбор меняет scope, либо решение
|
||||
трогает инвариант: уезжает вопросом с вариантами и ценой каждого туда, где
|
||||
проект держит вопросы, а работа продолжается на остатке.
|
||||
|
||||
Потребитель отчёта — оркестратор, который **реализует прочитанное**. Поэтому
|
||||
потолок в 7 пунктов — не забота о внимании читателя, а защита кодовой базы от
|
||||
правок, которых никто не заказывал.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Откуда проход берёт проектную конкретику
|
||||
|
||||
Конвейер общий, находки — проектные. Проход, не знающий, что в этом проекте
|
||||
нельзя нарушать, чем краснеет гейт и сколько данных реально идёт через узел,
|
||||
выдаёт правдоподобные общие места: их дорого опровергать и нечем подтверждать.
|
||||
|
||||
Отдельного файла-брифа **нет**. Проектная конкретика живёт в документах канона
|
||||
`av-dev-docs`, и проход читает их напрямую: пути жёсткие, посредник не нужен, а
|
||||
второй дом для тех же фактов разошёлся бы и выглядел актуальным.
|
||||
|
||||
Определение канона держит скилл `av-dev:doc-canon`. Здесь только карта «тема →
|
||||
её дом → что оттуда берётся».
|
||||
|
||||
## Карта тем
|
||||
|
||||
**Дом бывает файлом или каталогом** — `docs/security.md` и `docs/security/`
|
||||
называют одну и ту же тему. Форму дома называет план разметки задачи; проход её не
|
||||
угадывает.
|
||||
|
||||
| Тема | Дом | Что оттуда берётся |
|
||||
| --- | --- | --- |
|
||||
| `requirements` | `openspec/specs/`, `openspec/changes/<id>/specs/` | нормативное поведение и дельты изменения |
|
||||
| `autotests` | `CLAUDE.md`, семантика гейта | команда гейта, чем краснеет безусловно, чего в нём нет, кто гоняет дорогое |
|
||||
| `conventions` | `docs/conventions.*` | конвенции прозой и **что уже механизировано** правилом |
|
||||
| `architecture` | `docs/architecture.*` | компоненты и capability, единые точки проекта |
|
||||
| | источник `docs/passport.*` | что система делает и **чего не делает**, граница домена |
|
||||
| `security` | `docs/security.*` | периметр, недоверенный вход, из чего строятся пути и ключи, что вне модели |
|
||||
| `operations` | `docs/architecture.*`, раздел эксплуатации | окружение, внешние зависимости поимённо, наблюдатель, характер потока |
|
||||
| | источник `docs/database.*` | чем физически лежит запись, что при чтении и записи, настройки с числовым значением |
|
||||
| *тема проекта* | её **свой** документ в `docs/` | то, что проект счёл нужным записать |
|
||||
|
||||
**`docs/adr.*` и `docs/research.*` в этой карте нет намеренно.** Они процессные
|
||||
документы: прогон ревью их не открывает. Раньше первый питал тему `architecture`,
|
||||
второй — `operations` и `requirements`; обе строки убраны, и цена этого названа в
|
||||
`SKILL.md`, раздел «Честный предел».
|
||||
|
||||
**Дом темы зависит ещё и от метки.** На `small` темы `security`, `operations` и
|
||||
`architecture` смотрятся не против домов из этой таблицы, а против **инвариантов
|
||||
`CLAUDE.md`**, и закрывает их `code`. Таблица описывает полный дом темы; сколько
|
||||
из него открыто на этом прогоне, говорит план разметки задачи.
|
||||
|
||||
Сквозное, не привязанное к теме:
|
||||
|
||||
| Что нужно проходу | Где лежит |
|
||||
| --- | --- |
|
||||
| инварианты **с severity рядом с формулировкой** | `CLAUDE.md` (и `AGENTS.md`, если он рядом), раздел инвариантов |
|
||||
| что запускать запрещено, с путями; `testdata`; куда писать временное; имя основной ветки | `CLAUDE.md` |
|
||||
| типовые узлы, типовые ложноположительные, **вопросы по темам**, триггеры метки, недоступно проверке | `docs/review.*`, раздел настройки |
|
||||
| прецеденты: воспроизведённые дефекты с оракулом | `docs/review.*`, журнал |
|
||||
|
||||
**Вопросы проекта привязаны к теме, а не к имени прохода.** Раньше блок в
|
||||
`docs/review.md` адресовался поимённо (`ops: <вопрос>`), и когда проход уехал в
|
||||
старшую метку, вопрос перестал задаваться молча. Тема переезд прохода
|
||||
переживает.
|
||||
|
||||
## Сшивать обязаны проходы
|
||||
|
||||
Раньше эти факты лежали рядом в одном файле, и соседство работало само. Теперь
|
||||
они разложены по домам, и **проход обязан собрать их сам** — иначе снимет верное
|
||||
число и честно понизит находку до гипотезы, потому что сравнить будет не с чем.
|
||||
|
||||
Два обязательных стыка:
|
||||
|
||||
- **замер + настройка.** «Пик 768 МиБ» — аномалия только рядом со строкой
|
||||
«запись лежит сжатой и распаковывается целиком»; «блокировка удерживалась
|
||||
5.019 с» — гарантированный отказ соседа только рядом с известным таймаутом
|
||||
занятости. **Число проход снимает сам, на этом прогоне**, настройки берёт из
|
||||
`docs/database.md`, и сшивают их `ops` и `adversary`. Раньше числа брались из
|
||||
`docs/research/`; теперь этот документ процессный, и замер неизвестной свежести
|
||||
больше не выдаёт себя за оракул.
|
||||
- **инвариант + обратимость.** severity берётся из `CLAUDE.md`; если её там
|
||||
нет — она **выводится по обратимости последствия** и помечается «выведена по
|
||||
обратимости», а не выдаётся за решение проекта.
|
||||
|
||||
**У `basics` стыков нет, и это не упущение.** Он не меряет, поэтому сшивать число
|
||||
с настройкой ему нечего; единственное его основание для `critical` — инвариант из
|
||||
`CLAUDE.md`, всё остальное он формулирует условиями и оставляет гипотезой. Его
|
||||
вход намеренно узкий: дома тем из плана плюс инварианты и журнал. Широкий вход —
|
||||
это метка `large`, и там он есть у `architecture`. Греп по базе ему разрешён
|
||||
точечный — «есть ли второй вызывающий», — но обход всей базы и инвентарь
|
||||
концепций не его работа.
|
||||
|
||||
**У `scope` стыков нет по другой причине: он не читает содержимого.** Его дело —
|
||||
найти дома и раздать темы, а не пересказать написанное. Пересказ сделал бы его
|
||||
посредником между документом и проходом, а посредник расходится с источником и при
|
||||
этом выглядит актуальным.
|
||||
|
||||
## Деградация — поразрядная
|
||||
|
||||
Документа нет — деградирует то, что из него читалось, и **только оно**. Каждый
|
||||
проход пишет **свою** строку в границы покрытия; триаж собирает их в один
|
||||
список и **не сливает в одну строку**: разные пробелы чинятся разным — периметр
|
||||
пишется руками за десять минут, а числа требуют замера.
|
||||
|
||||
**Кто какой документ читает — из документа не выводится, а назначается планом.**
|
||||
Документ питает тему (это записано на стороне канона, таблица «Роли документов и
|
||||
темы ревью»), а тему на этом прогоне закрывает тот, кого назвала разметка задачи; вся
|
||||
раскладка «тема → проход → глубина» — в `SKILL.md` этого скилла и больше нигде.
|
||||
**Списка читателей не ведёт никто, и это не пробел.** Он жил бы на стороне
|
||||
канона, а документ живёт дольше, чем раскладка проходов: список разошёлся бы с
|
||||
конвейером молча и при этом выглядел актуальным. Однажды уже разошёлся.
|
||||
|
||||
Ниже — только **последствие** отсутствия дома, и оно называет самое дорогое, а не
|
||||
всех пострадавших.
|
||||
|
||||
| Нет дома | Что деградирует |
|
||||
| --- | --- |
|
||||
| `CLAUDE.md` без инвариантов | `critical` по основанию «нарушен инвариант проекта» не присваивается никем |
|
||||
| `docs/security.*` | тема `security` остаётся без дома: вопросы задаются по коду, `critical` не ставится, периметр неизвестен |
|
||||
| `docs/database.*` | замер не с чем сравнить: находка темы `operations` не поднимается выше гипотезы |
|
||||
| `docs/passport.*` | тема `architecture` теряет границу домена и вырождается в общее мнение |
|
||||
| `docs/review.*` | `triage` отсеивает вслепую: типовых ложноположительных нет; вопросы проекта по темам не задаются |
|
||||
| `docs/conventions.*` | вторая половина `code` идёт вхолостую: записанных конвенций нет |
|
||||
| `docs/architecture.*` | «не появился ли второй способ» не проверяется — единых точек не знает никто; тема `operations` теряет перечень внешних зависимостей |
|
||||
|
||||
Строка в границах покрытия обязана называть **причину**: «`docs/security.md` в
|
||||
проекте нет» читается иначе, чем «есть, но периметр не назван». Без причины
|
||||
строка неотличима от «мы просто не стали» и перестаёт читаться на третьей задаче.
|
||||
|
||||
**Документов канона нет вовсе** — проект не приведён к канону. Это не повод
|
||||
работать вслепую: скажи об этом строкой и предложи `av-dev:doc-canon`. Одна
|
||||
операция на проект против деградации на каждой задаче.
|
||||
|
||||
## Правило чтения
|
||||
|
||||
- **Читай в источнике, не по памяти.** Документы правятся по ходу работы, в том
|
||||
числе этой же задачей.
|
||||
- **Число без провенанса — условие, а не утверждение.** Число, чей источник по
|
||||
ссылке не подтвердился, читается как условие и **называется расходящимся**, а
|
||||
не подменяется догадкой.
|
||||
- **Пустое, названное пустым, — это факт.** «Внешних зависимостей нет — смотри
|
||||
на диск и на СУБД» экономит обязательный вопрос. Отсутствие строки — не факт,
|
||||
а пробел, и его надо назвать в границах покрытия.
|
||||
- **Свойство, ставшее правилом линтера, из конвенций удалено** и лежит в
|
||||
перечне механизированного — в `docs/conventions/README.md`, если конвенции
|
||||
каталогом, и отдельным разделом `docs/conventions.md`, если файлом. Проверять
|
||||
его проходом — тратить внимание на уже проверенное.
|
||||
@@ -0,0 +1,121 @@
|
||||
# Промоут: находка → конвенция → правило → удаление
|
||||
|
||||
Механизм храповика. Без него конвейер выдаёт одни и те же находки бесконечно, а
|
||||
конвенции не растут — то есть внимание тратится повторно на уже решённое.
|
||||
|
||||
Роли уровней:
|
||||
|
||||
- **generative-проходы** — механизм *открытия* неявного (дорого, шумно, но
|
||||
только они достают то, чего нет в списках);
|
||||
- **конвенции** — дешёвая *регрессионная сетка* на уже открытое;
|
||||
- **правила линтера** — то же с детерминированным оракулом и нулевой ценой
|
||||
внимания.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
f["находка ревью"]
|
||||
cond{"принята и не специфична<br/>для одного места?"}
|
||||
no["промоуту не подлежит:<br/>место одно — комментарий в коде;<br/>вкусовщина — вон на триаже;<br/>нужен рантайм — в журнал ревью"]
|
||||
conv["конвенция:<br/>проверяемое свойство + какой проход нашёл"]
|
||||
rule["правило линтера, запретитель,<br/>тест-сканер или анализатор"]
|
||||
clean["шаг 3: формулировка удалена из конвенций,<br/>строка — в перечень механизированного"]
|
||||
|
||||
f --> cond
|
||||
cond -->|нет| no
|
||||
cond -->|да| conv
|
||||
conv --> rule
|
||||
rule --> clean
|
||||
rule -->|"ложных чаще, чем ловит (~треть)"| conv
|
||||
```
|
||||
|
||||
Ребро назад — обратное движение (внизу): правило, дающее ложные срабатывания
|
||||
чаще, чем ловит, снимается в прозу. Ребро `rule → clean` **обязательное**: без
|
||||
него первые два шага не окупаются, а именно его и пропускают.
|
||||
|
||||
Схема — **сводка**: условия каждого шага в его разделе, и при расхождении прав
|
||||
текст.
|
||||
|
||||
## Шаг 1. Находка → конвенция
|
||||
|
||||
Условия: находка **принята** при ревью (не отвергнута, не понижена в гипотезу) и
|
||||
**не специфична для одного места**.
|
||||
|
||||
- Формулируется как **проверяемое свойство**, а не как совет: «уровень доменного
|
||||
отказа выбирает единственный логирующий чекпоинт», а не «внимательнее с
|
||||
уровнями логов».
|
||||
- Записывается источник — какой проход нашёл. Это единственные данные для
|
||||
калибровки: проход, чьи находки регулярно доезжают до конвенции, оправдан;
|
||||
проход, чьи находки не доезжают никогда, — кандидат на `drop` (см.
|
||||
[calibration.md](calibration.md)).
|
||||
- Место записи — конвенции проекта, файл или нужный файл каталога (путь — в
|
||||
каталог `docs/conventions/`). Если
|
||||
тема относится к поведению системы, а не к тому, как мы пишем код, — это не
|
||||
конвенция, а требование: заводится дельта-спека обычным путём.
|
||||
|
||||
Промоут идёт **тем же путём, что change → spec**: правка попадает в тот же
|
||||
коммит, что и исправление кода, с пометкой в сообщении — история промоутов
|
||||
остаётся видна в `git log` по файлу конвенций.
|
||||
|
||||
## Шаг 2. Конвенция → правило
|
||||
|
||||
Как только свойство выражается детерминированно, оно переезжает в инструмент.
|
||||
Порядок предпочтения — от дешёвого к дорогому:
|
||||
|
||||
1. **готовое правило существующего линтера** — включить в конфиг;
|
||||
2. **запрет идентификатора или импорта** правилом-«запретителем» с собственным
|
||||
паттерном;
|
||||
3. **правило с настройкой формы** — когда важно не имя, а конструкция;
|
||||
4. **тест-сканер исходников** — когда правило про структуру проекта или про
|
||||
схему: направление зависимостей, форма миграций, матчинг ошибки по тексту,
|
||||
бизнес-логика в транспорте;
|
||||
5. **собственный анализатор** — последний рубеж, заводим только если 1–4 не
|
||||
выражают правило.
|
||||
|
||||
Правило обязано быть **зелёным на текущем коде в момент включения**: иначе
|
||||
хук блокирует любой коммит, и правило снимут первым же раздражённым движением.
|
||||
Приводить код в соответствие — часть шага 2, отдельным коммитом.
|
||||
|
||||
## Шаг 3. Удаление из конвенций и из промптов
|
||||
|
||||
**Шаг, который пропускают чаще всего, и единственный, ради которого затевались
|
||||
первые два.**
|
||||
|
||||
Как только правило работает:
|
||||
|
||||
- из файла конвенций убирается формулировка правила; остаётся, если нужно, одна
|
||||
строка «проверяется линтером `<имя>`» — но только там, где без неё раздел
|
||||
теряет связность;
|
||||
- правило переезжает в **перечень механизированного в доме конвенций**
|
||||
(`docs/conventions/README.md` у каталога, отдельный раздел
|
||||
`docs/conventions.md` у файла) — со ссылкой на место механизации: конфиг
|
||||
линтера, собственный анализатор, тест-сканер исходников. Не названное место
|
||||
означает, что проход будет добросовестно проверять уже проверенное;
|
||||
- из контекста инструмента спек убирается дубль, если он там был.
|
||||
|
||||
Charter'ы проходов при этом **не правятся**: они общие и живут в плагине, а
|
||||
предмет проверки приходит из документов проекта. Именно поэтому шаг 3 дешевле,
|
||||
чем был:
|
||||
вычеркнуть строку в одном файле проекта, а не в девяти промптах.
|
||||
|
||||
Практический критерий: **в прозаических конвенциях остаётся только то, что
|
||||
принципиально не выражается правилом.** Файл конвенций на несколько сотен строк
|
||||
размазывает внимание модели по тривиальному — она добросовестно проверит
|
||||
именование полей лога и не дойдёт до формы решения. Каждая строка конвенций,
|
||||
которую можно было бы проверить машиной, оплачивается дефектом, который не
|
||||
поймали где-то ещё.
|
||||
|
||||
## Обратное движение
|
||||
|
||||
Правило, которое даёт ложные срабатывания чаще, чем ловит (порядка трети от
|
||||
общего числа), снимается и возвращается в прозу — или удаляется совсем, если
|
||||
свойство перестало быть важным. Снятие фиксируется там же, где включалось, с
|
||||
одной строкой «почему».
|
||||
|
||||
## Что промоуту не подлежит
|
||||
|
||||
- Находка, специфичная для одного места (её лечит комментарий в коде).
|
||||
- Вкусовщина: не меняет поведения, не влияет на стоимость следующего изменения,
|
||||
не нарушает записанного. Такое выбрасывается на триаже и не хранится.
|
||||
- Свойство, требующее знания рантайма (профиль нагрузки, история инцидентов) —
|
||||
его нельзя проверить ни промптом, ни линтером; место такому — в журнале ревью
|
||||
как «признано неавтоматизируемым» (см. [review-journal.md](review-journal.md)).
|
||||
@@ -0,0 +1,105 @@
|
||||
# Журнал дефектов
|
||||
|
||||
Артефакт проекта, а не плагина: файл живёт в репозитории — **`docs/review.md`**,
|
||||
слот канона `av-dev-docs`. Здесь описано, зачем он и какой формы, потому что без
|
||||
него конвейер не учится: находки закрываются, а почему их не поймали — забывается,
|
||||
и один и тот же класс проскакивает второй раз.
|
||||
|
||||
Тот же файл держит **настройку конвейера под проект** — типовые узлы, типовые
|
||||
ложноположительные, вопросы по темам, недоступно проверке. Это не соседство по
|
||||
случаю: все четыре раздела — производные калибровки, а журнал им источник.
|
||||
|
||||
## Что туда попадает
|
||||
|
||||
**Воспроизведённый дефект — с пометкой `проскочил` или `пойман ревью`.**
|
||||
Записывается **сразу**, а не ретроспективно: со временем теряется не сам факт, а то,
|
||||
почему дефект не поймали, — единственное, ради чего журнал существует.
|
||||
|
||||
Пометка делит журнал на две выборки с разным назначением:
|
||||
|
||||
- **проскочил** — проверочный набор для калибровки конвейера. Реальный промах сильнее
|
||||
синтетической пробы: синтетические смещены в сторону тех, которые уже умеешь
|
||||
придумывать;
|
||||
- **пойман ревью** — прецеденты с оракулом. Самая сильная опора, какая у прохода
|
||||
бывает: проектная, воспроизводимая и однажды уже оказавшаяся правдой. Без
|
||||
журнала они остаются только в отчётах триажа в архиве change, где их никто не
|
||||
ищет.
|
||||
|
||||
Реализованные задачи и принятые решения сюда не пишутся: у них есть коммит, спека
|
||||
и `docs/adr/`.
|
||||
|
||||
Отдельно сюда попадают **решения о составе прогонов**: перестали звать проход,
|
||||
понизили метку правилом, сузили класс проверяемого. Не потому, что это промах,
|
||||
а потому, что здесь лежит цена: если что-то теперь проскочит, первый вопрос —
|
||||
«не тот ли это класс, который мы перестали проверять».
|
||||
|
||||
Каждое такое решение обязано получить строку в подразделе **«Перестали проверять
|
||||
сознательно»** раздела «Недоступно проверке» того же файла. Журнал хранит «почему
|
||||
тогда так решили», раздел настройки — то, во что смотрит каждый прогон. Решение,
|
||||
оставшееся только в журнале, в границы покрытия не доедет.
|
||||
|
||||
## Форма записи
|
||||
|
||||
**Это дом формы, и у него есть копия.** Скелет `docs/review.md`, который кладёт
|
||||
в проект `av-dev:doc-canon`, повторяет её дословно — он уезжает в репозиторий и обязан там что-то говорить. Правка формы
|
||||
здесь **обязана** тянуть правку скелета и запись в журнал версий канона; иначе
|
||||
проекты продолжат писать по старой форме, а конвейер — ждать поля, которого нет.
|
||||
Дословность сверяет `scripts/copies.py` маркетплейса по маркерам ниже — но
|
||||
запись в журнал версий он не проверит, это остаётся на человеке.
|
||||
|
||||
<!-- дом: журнал-дефектов-форма -->
|
||||
```
|
||||
## ГГГГ-ММ-ДД — <краткое последствие> [проскочил|пойман]
|
||||
|
||||
- **Где:** путь:строка либо «конвейер, а не код»
|
||||
- **Симптом:** как обнаружилось, кем и когда
|
||||
- **Причина:** что на самом деле было не так
|
||||
- **Чем воспроизведён:** тест, команда, замер — с числами
|
||||
- **Почему не поймали:** только для проскочивших — какой проход обязан был найти
|
||||
и что ему помешало
|
||||
- **Что меняем:** правило прохода, шаг гейта, конвенция, факт в документе
|
||||
проекта — либо «ничего, цена поимки выше цены дефекта»
|
||||
```
|
||||
<!-- /дом: журнал-дефектов-форма -->
|
||||
|
||||
Пункт «чем воспроизведён» отличает запись от байки: без него на неё нельзя
|
||||
сослаться как на оракул. Регрессионный тест, написанный вместе с починкой,
|
||||
годится наравне с независимым экспериментом — он исполняемый и падает на старом
|
||||
коде. Слабее он ровно в одном: сформулирован уже зная ответ, и это отмечается
|
||||
словом.
|
||||
|
||||
Последний пункт важнее остальных. Вывод «ничего не меняем» — законный исход: не
|
||||
всякий дефект стоит того, чтобы усложнять ради него ревью каждой задачи.
|
||||
|
||||
## Куда ведёт запись
|
||||
|
||||
Три адреса, и выбор между ними — половина ценности журнала:
|
||||
|
||||
- **в документ проекта** — если проход не мог знать факта. Адрес зависит от рода
|
||||
факта, и карта их всех — [project-facts.md](project-facts.md):
|
||||
настройка хранилища → `docs/database.md`;
|
||||
что необратимо и какой шаг гейта красит безусловно → `CLAUDE.md`; периметр и
|
||||
недоверенный вход → `docs/security.*`. **Вопрос по теме**, если промах лечится
|
||||
не фактом, а заданным вопросом, → раздел «Вопросы по темам» того же
|
||||
`docs/review.*`; адресуй теме, а не имени прохода — проход уедет между
|
||||
метками, тема останется. Самый частый адрес и самый дешёвый. Прежде чем
|
||||
править charter, проверь, не хватит ли факта или вопроса: charter общий для
|
||||
всех проектов, документ — про этот.
|
||||
- **в конвенции или в правило линтера** — если свойство выражается
|
||||
детерминированно (процедура — [promote.md](promote.md)).
|
||||
- **в charter прохода** — если сломан **метод**, а не знание. Правка charter'а
|
||||
меняет поведение во всех проектах, поэтому она требует калибровки
|
||||
([calibration.md](calibration.md)) и обоснования, почему это не лечится фактом
|
||||
в документе проекта.
|
||||
|
||||
## Что журнал даёт конвейеру
|
||||
|
||||
- **пробы для калибровки** — выборка по пометке `проскочил`;
|
||||
- **готовые оракулы** — выборка по пометке `пойман ревью`: находка того же
|
||||
класса подтверждается ссылкой на запись, а не рассуждением;
|
||||
- **основание для правил конвейера** — требование называть запущенные проходы
|
||||
поимённо, отказ от чисел, производных от размера корпуса, и правило очереди для
|
||||
меряющих проходов выведены из конкретных записей, а не из общих соображений;
|
||||
- **счётчик обратимости решений** — сузили состав проходов и через месяц поймали
|
||||
дефект ровно того класса, который перестали проверять: решение пересматривается
|
||||
фактом, а не спором.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Метки задачи — выбор, цена, доли
|
||||
|
||||
**Дом правила выбора метки.** Состав проходов по каждой метке, схема процесса и
|
||||
раздача тем живут в [SKILL.md](../SKILL.md) — там диспетчер, и на готовой задаче
|
||||
его достаточно. Здесь то, что читают, когда метку **выбирают, оспаривают или
|
||||
калибруют**.
|
||||
|
||||
Применяет правило `review-scope` при разметке задачи — не автор изменения. Его
|
||||
рабочая выжимка лежит в уставе агента; расходиться она с этим файлом не вправе, а
|
||||
при расхождении прав этот.
|
||||
|
||||
## Правило выбора — две оси, а не один вопрос
|
||||
|
||||
**Оси две, они измеряют разное, и метка есть максимум по ним.**
|
||||
|
||||
| | **знакомое** — форму решения можно назвать до начала | **незнакомое** — форму предстоит нащупать по ходу |
|
||||
|---|---|---|
|
||||
| **малое** — один узел | `small` | `large` |
|
||||
| **среднее** — несколько узлов одного слоя | `medium` | `large` |
|
||||
| **крупное** — несколько слоёв, перенос ответственности, большой рефакторинг | `large` | `large` |
|
||||
|
||||
**Метка — не синоним размера.** Совпадают они только в левом верхнем углу: малое
|
||||
**незнакомое** изменение получает `large`, трогая один узел. Поэтому в плане
|
||||
стоят три строки, а не одна: размер, сложность и метка — каждая со своим
|
||||
обоснованием. Проход, выведший объём диффа из метки, ошибётся ровно на этом
|
||||
случае — а он и есть самый опасный: незнакомая форма в одном узле течёт там, где
|
||||
её никто не ждёт.
|
||||
|
||||
**Размер** — про объём: сколько мест трогается. **Сложность** — про
|
||||
неизвестность: знаем ли мы форму решения заранее. Признак незнакомого простой и
|
||||
проверяемый: **перед работой нельзя назвать, какие узлы будут тронуты**.
|
||||
|
||||
Раньше обе оси были склеены в один вопрос «крупное **или** незнакомое?». Ответ
|
||||
получался тот же, но две вещи под одним именем не измеришь по отдельности, и
|
||||
потому разметка не могла сказать «изменение среднее, но совершенно знакомое» —
|
||||
а именно эта пара и есть рабочее умолчание. Теперь обе оси называются в плане
|
||||
поимённо, и обе — с обоснованием.
|
||||
|
||||
**Оси называются и на стадии дизайна, и на стадии кода — но считаются один
|
||||
раз.** Это и есть причина, по которой разметка переехала к `propose`: состав
|
||||
ревью дизайна выводится из той же пары, что и состав ревью кода, а считать её
|
||||
дважды значит один раз посчитать без разведённости с автором.
|
||||
|
||||
**Обратимость — не третья ось, а отрицательный тест.** Она не уточняет размер и
|
||||
не уточняет сложность: она запрещает нижнюю метку независимо от обеих.
|
||||
|
||||
**Отрицательный тест `small`, и он важнее положительного:** изменение, которое
|
||||
после мерджа **не откатывается обратной правкой**, — не `small`, каким бы
|
||||
маленьким ни был дифф. Сюда попадают миграция схемы и данных, формат на диске,
|
||||
публичный контракт, имя, которое разойдётся по кодовой базе. Три строки миграции
|
||||
— это `medium`, а не `small`: размер диффа и цена ошибки здесь расходятся.
|
||||
|
||||
Что здесь считается крупным, что — незнакомым и что — мелким, проект уточняет в
|
||||
`docs/review.md`, подразделе «Триггеры метки»: **тремя списками** — по одному на
|
||||
каждую ось вверх и один вниз, поимённо, узлами или capability. Это **уточнение**,
|
||||
а не отмена: не записано — работает таблица выше.
|
||||
|
||||
## Спорный случай решается вниз, и у этого есть цена
|
||||
|
||||
Правило асимметрично, потому что асимметрична цена ошибки.
|
||||
|
||||
- **Спорно между `medium` и `large` → бери `medium`.** Ошибка в эту сторону
|
||||
стоит находки, которая всплывёт на следующей задаче или в журнале дефектов.
|
||||
Ошибка в обратную стоит трёх тяжёлых проходов, двое из которых держат машину и
|
||||
идут цепочкой, — и платится она **на каждой** задаче, выбранной неверно.
|
||||
- **Спорно между `small` и `medium` → бери `medium`.** Раньше эта строка
|
||||
обосновывалась тем, что состав одинаков и ошибка почти бесплатна. Теперь состав
|
||||
разный, и обоснование стало прямо противоположным: на `small` три темы ядра
|
||||
смотрятся **только против записанных инвариантов**, а спорный случай — ровно тот,
|
||||
где неизвестно, покрыт ли он инвариантом. Сомнение здесь стоит дороже, чем
|
||||
раньше, и потому решается вниз тем более твёрдо.
|
||||
|
||||
**Выбор сделан в пользу пропускной способности, и это записано, а не подразумевается.**
|
||||
Конвейер настроен на поток задач, а не на максимум находок с каждой: поправить в
|
||||
следующей задаче дешевле, чем держать одну два часа. Отсюда три обязанности,
|
||||
без которых сделка превращается в незаметную потерю качества:
|
||||
|
||||
- **границы покрытия называют темы и их глубину**, а не только запущенные
|
||||
проходы — иначе `small` выглядит так же, как `large` без находок;
|
||||
- **журнал дефектов в `docs/review.md` перестаёт быть хорошей практикой и
|
||||
становится единственной обратной связью**: проскочивший дефект — единственный
|
||||
сигнал, что метка выбрана слишком низко;
|
||||
- **возврат в код — повод пересмотреть метку.** Задача, которая приходит в тот
|
||||
же узел третий раз, уже не мелкая, чем бы ни выглядел её дифф.
|
||||
|
||||
## Метка — максимум по поверхности
|
||||
|
||||
**Обе оси меряются по всему диффу разом, и максимум по каждой отвечает за весь
|
||||
дифф.** Метка изменения — не средневзвешенное: одна строка в перечне границ
|
||||
задачи поднимает метку всему остальному, включая ту часть, которая сама по себе
|
||||
была бы `small`.
|
||||
|
||||
Обратное тоже верно и тоже не бесплатно: у каждой задачи есть **несокращаемый
|
||||
костяк — гейт, спеки, код, триаж**. Разрезать задачу, обе половины которой
|
||||
остаются в одной метке, значит заплатить костяк дважды за ту же проверку.
|
||||
Резать стоит там, где разрез **снимает доказательство с большей части диффа**.
|
||||
Шов и правило нарезки живут у того, кто ведёт задачи, — скилл
|
||||
`av-dev:task-track`, его раздел о нарезке. Пути туда конвейер не выносит: за
|
||||
пределы своего плагина он ходит вызовом скилла, а не файлом.
|
||||
|
||||
Разметка в костяк не входит — она платится один раз на задачу, а не один раз на
|
||||
прогон, и потому **разрез задачи её не удваивает**. Это единственное, что стало
|
||||
дешевле от переезда разметки к `propose`, и это же снимает прежний довод против
|
||||
нарезки.
|
||||
|
||||
**Размер, сложность, метка и глубина объявляются в отчёте, и все четыре с
|
||||
обоснованием.** Метка выбирает `review-scope`; он вправе и поднять, и понизить
|
||||
её — но не молча: строка «метка X, потому что размер Y и сложность Z»
|
||||
обязательна на каждом прогоне, а не только когда метка отличается от ожидаемой.
|
||||
|
||||
## Чем `small` дешевле `medium` и что это стоит
|
||||
|
||||
Экономят три рычага — непуск, вход, потолок, — и они общие для всех проходов и
|
||||
всех меток; их дом и точные числа в [SKILL.md](../SKILL.md), раздел «Модель по
|
||||
проходу». Здесь только то, что рычаги делают **с этой меткой**:
|
||||
|
||||
1. **Составом.** `basics` на `small` не запускается — кроме случая, когда у
|
||||
проекта есть свои темы; тогда он идёт **только с ними**, ровно как в `large`.
|
||||
Три темы ядра, которые он держал бы, переходят к `code` сверкой по
|
||||
инвариантам.
|
||||
2. **Входом.** На `small` `specs` читает только дельта-спеку, а `code` — только
|
||||
**индекс** конвенций (перечень родов и что механизировано), не весь их дом. На
|
||||
`medium` оба читают дома целиком.
|
||||
3. **Потолком.** На `small` потолки самые жёсткие из трёх меток, и каждый
|
||||
напечатан в границах покрытия своего прохода.
|
||||
|
||||
**Что `small` за это не проверяет, названо поимённо и обязано идти строкой в
|
||||
границы покрытия:** темы `security`, `operations` и `architecture` смотрятся
|
||||
только против **записанных инвариантов** `CLAUDE.md`. Свойство, которого в
|
||||
инвариантах нет, с этой меткой не спросит никто — ни сценарием, ни чтением
|
||||
дома темы. Это и есть цена метки, и она заметно больше прежней: раньше `small`
|
||||
отличался от `medium` одним проходом на один вопрос, то есть не экономил
|
||||
ничего и назывался отдельной меткой зря.
|
||||
|
||||
**`large` назван по тому, что он добавляет: вход шире диффа.** Он единственный, где
|
||||
живут тяжёлые проходы, и единственный, где что-то **запускается**. `basics` в нём
|
||||
берёт только проектные темы; своих тем у проекта нет — он не запускается вовсе, и
|
||||
план говорит об этом строкой. **На `small` действует то же правило и по той же
|
||||
причине** — приёмник запускается только тогда, когда ему есть что принимать.
|
||||
Совпадение неслучайное: `basics` держит темы ядра ровно при одной метке из трёх,
|
||||
а приёмником проектных тем работает на всех.
|
||||
|
||||
## Доли — не пожелание, а проверка правила, и проверок две
|
||||
|
||||
**Сверху: `large` — 5–10%.** Если туда уходит каждая третья задача, метку
|
||||
выбирают по ощущению важности. Обратный перекос виден по журналу проскочивших
|
||||
дефектов: класс, который ловят только меряющие проходы, начинает всплывать после
|
||||
мерджа.
|
||||
|
||||
**Снизу: `small` не должен обгонять `medium`.** Ориентир — до трети задач, но
|
||||
сравнение важнее числа: **перевес `small` над `medium` значит, что рабочее
|
||||
умолчание сместилось, а решения об этом никто не принимал.** Проверка нужна
|
||||
именно теперь: пока две нижние метки совпадали составом, дрейф между ними не
|
||||
стоил ничего, и проверки не было. Сейчас он стоит трёх тем ядра, которые на
|
||||
`small` смотрятся только против инвариантов, — то есть ровно того, чем `small` и
|
||||
дёшев.
|
||||
|
||||
Считается это по журналу дефектов и по отчётам, а не по ощущению: метка
|
||||
напечатана в каждом отчёте, и посчитать её за месяц — работа на минуту.
|
||||
|
||||
**У дрейфа вниз есть свой стимул, и его стоит назвать.** `small` дешевле по
|
||||
времени и по деньгам, а выбирает метку хоть и не автор, но проход, читающий
|
||||
описание, написанное автором. Занижённое описание даёт занижённую метку без
|
||||
чьего-либо злого умысла — потому корректор и вынесен в `code`, который смотрит
|
||||
уже на код, а не на описание.
|
||||
@@ -0,0 +1,319 @@
|
||||
---
|
||||
name: doc-canon
|
||||
description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл init.
|
||||
---
|
||||
|
||||
# Приведение проекта к канону
|
||||
|
||||
Три операции, одна машина сравнения с разными исходами:
|
||||
|
||||
| Операция | Когда | Исход |
|
||||
| --- | --- | --- |
|
||||
| `check` | начало сессии, шаг синка, гейт | что разошлось |
|
||||
| `adopt` | проект в чужой раскладке | перенос в канон |
|
||||
| `upgrade` | канон вырос, проект отстал | по журналу версий |
|
||||
|
||||
**Определение канона — [references/canon.md](references/canon.md).** Здесь оно не
|
||||
пересказывается: два описания одной раскладки разъедутся, и работать будет то,
|
||||
которое прочитали последним. Прочитай его **до** первой правки.
|
||||
|
||||
- [references/skeletons.md](references/skeletons.md) — **что именно класть** в
|
||||
каждый незаполненный слот. Не выдумывай заглушку своей формы: `docs.py`
|
||||
узнаёт только плейсхолдер `<!-- заполнить: … -->` из шаблонов.
|
||||
- [references/language.md](references/language.md) — **как это написано словами**:
|
||||
информационный стиль, применённый к проектным текстам, таблицы англицизмов и
|
||||
жаргона. Раскладка отвечает, где текст лежит, — этот файл отвечает, каким он
|
||||
должен быть. Правила общие для документов канона, задач, решений ADR и
|
||||
записок разведки, и дом у них общий — `shared/language.md` в репозитории
|
||||
плагинов, а этот файл его копия. Вычитывают их два прохода по охвату:
|
||||
документы — `doc-wording`, записи каталога задач — `task-wording`.
|
||||
- [references/changelog.md](references/changelog.md) — журнал версий канона.
|
||||
|
||||
## Три правила, из которых всё следует
|
||||
|
||||
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
|
||||
разложилось и **что не разложилось**, — и только после подтверждения
|
||||
переносится хоть один файл. Массовый перенос без подтверждения разгребать
|
||||
дороже, чем согласовать.
|
||||
2. **Ничего не терять.** Содержимое переезжает целиком; ссылки чинятся тем же
|
||||
проходом, что и перенос. Старый файл удаляется **только** после того, как
|
||||
всё его содержимое нашло дом, и это названо поимённо.
|
||||
3. **Что не классифицировалось — назвать.** Проглоченный абзац выглядит как
|
||||
«всё перенеслось». Список «не разложилось» идёт в доклад целиком, с причиной
|
||||
по каждому пункту.
|
||||
|
||||
## Инструмент
|
||||
|
||||
```
|
||||
ds="$CLAUDE_PLUGIN_ROOT/skills/canon/scripts/docs.py"
|
||||
|
||||
python3 $ds check --dir <корень> [--base <rev>] # раскладка, ссылки, версия, сверки
|
||||
python3 $ds version --dir <корень> # версия канона скрипта и проекта
|
||||
```
|
||||
|
||||
**Формы `openspec/config.yaml` здесь больше нет.** Каталог принадлежит конвейеру,
|
||||
и форму смотрит его скрипт — скилл `av-dev:code-openspec`, команда
|
||||
`openspec.py check`. Проект работает по OpenSpec, а плагина конвейера нет — форму
|
||||
не проверяет никто, и это надо сказать строкой доклада, а не считать, что она
|
||||
верна.
|
||||
|
||||
**Коды выхода — тот же словарь, что у `tasks.py`:** 0 сошлось, 1 дрейф, 2 ошибка
|
||||
употребления, 3 окружение, 4 внутренний сбой. Ветвись на коде, а не на тексте.
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф раскладки» — рабочая ситуация, «это не
|
||||
корень проекта» — нерабочая.
|
||||
|
||||
### Граница механизируемого — объявляется вслух
|
||||
|
||||
Скрипт печатает её сам последним абзацем, и **эту строку из доклада выбрасывать
|
||||
нельзя**. `check`, отчитавшийся «канон соблюдён» на проекте, где из шести файлов
|
||||
три лишние, хуже отсутствующего.
|
||||
|
||||
Машина **дрейфом** считает: отсутствующий путь канона, файл вне канона, битую
|
||||
ссылку, отставшую версию, capability без упоминания в обзоре, миграцию без правки
|
||||
`database.md`. **Замечанием** — незаполненный плейсхолдер и слабое упоминание
|
||||
capability: незаполненный канон это переходное состояние, а не отказ. Маркеры
|
||||
долга просто считает числом.
|
||||
|
||||
Того, чего она не умеет, **ты не судишь сам** — для этого есть два агента, и
|
||||
разведены они по глубине:
|
||||
|
||||
| Агент | Что смотрит | Читает |
|
||||
| --- | --- | --- |
|
||||
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` |
|
||||
| `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий |
|
||||
|
||||
Судит **не тот, кто писал**: самопроверка документа слабее всего ровно там, где
|
||||
формулировка казалась удачной при написании. Ни один из них ничего не правит —
|
||||
оба возвращают готовые формулировки, подставляешь ты.
|
||||
|
||||
## Обращение к соседним плагинам
|
||||
|
||||
`adopt` зовёт двоих: `av-dev:code-openspec` (шаг 4, пункт 3) и
|
||||
`av-dev:task-track` (шаг 4, пункт 5). Каталоги `openspec/` и `tasks/` каноном не
|
||||
ведутся, и трогать их этому скиллу нечем, кроме вызова.
|
||||
|
||||
**Копия.** Дом правила — `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` — конвейер.
|
||||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||||
|
||||
<!-- /копия: граница-плагинов -->
|
||||
|
||||
Чем оборачивается отсутствие каждого — на самих пунктах шага 4. `adopt` из-за
|
||||
этого не останавливается ни в одном из двух случаев.
|
||||
|
||||
## `check`
|
||||
|
||||
1. `docs.py check`, при наличии базы диффа — с `--base`.
|
||||
2. **Судей документов на каждом `check` не зови.** Ими владеет отдельный скилл —
|
||||
`av-dev:doc-healthcheck`, — и там же записано, когда его звать: он дорог, и
|
||||
прогон по каждому `check` не окупается. `check` отвечает на «сходится ли
|
||||
форма», `healthcheck` — на «не разошлись ли утверждения».
|
||||
3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и
|
||||
чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи
|
||||
`healthcheck`, а не зови агентов сам.
|
||||
|
||||
Дрейф раскладки чинится переносом; смысловые находки — это либо правка
|
||||
документа, либо задача, если работы больше чем на абзац.
|
||||
|
||||
## `adopt` — проект в чужой раскладке
|
||||
|
||||
### 1. Осмотрись
|
||||
|
||||
`docs.py check` — он уже назовёт упразднённые слоты с адресом, куда каждый
|
||||
уезжает. **Но смотрит он только верхний уровень `docs/`:** упразднённое в корне
|
||||
репозитория (`BRIEF.md`) и во вложенных каталогах он не назовёт никогда, поэтому
|
||||
корневые `*.md` читай глазами. Плюс: `CLAUDE.md`, `openspec/specs/` (список
|
||||
capability), `openspec/config.yaml`.
|
||||
|
||||
### 2. Составь карту
|
||||
|
||||
Каждый найденный файл получает строку: **куда едет, целиком или разбирается, что
|
||||
делать с оригиналом**. Разбор `docs/specs/` — самое дорогое место, и он делается
|
||||
поимённо по capability:
|
||||
|
||||
| Что в файле | Куда |
|
||||
| --- | --- |
|
||||
| требования, сценарии, поведение | `openspec/specs/<capability>/spec.md` — **или уже там**, тогда файл дубль |
|
||||
| компоненты, транспорты, раскладка, деплой | `docs/architecture.md` |
|
||||
| конвенции чужой системы, формат чужих данных | `docs/research/` |
|
||||
| обоснование принятого решения | `docs/adr/` |
|
||||
|
||||
**Дубль удаляется только после поимённой сверки**: открыть спеку capability,
|
||||
открыть файл, убедиться, что в файле нет ничего сверх спеки. Нашлось сверх —
|
||||
сперва переезжает в спеку дельтой, потом файл удаляется.
|
||||
|
||||
### 3. Покажи карту человеку
|
||||
|
||||
`AskUserQuestion`, **не больше трёх вопросов за итерацию**, рекомендация первым
|
||||
вариантом. Показывается: сколько файлов, куда каждый, спорные отнесения, список
|
||||
«не разложилось». Механику (порядок строк, имена файлов внутри `research/`) не
|
||||
выноси — это не развилка.
|
||||
|
||||
### 4. Перенеси
|
||||
|
||||
Порядок важен — он минимизирует окно, в котором ссылки битые:
|
||||
|
||||
1. `docs/.docs.json` с `{"canon": <текущая версия>}` и путём миграций, если БД есть;
|
||||
2. каталоги канона и скелет **по [references/skeletons.md](references/skeletons.md)**:
|
||||
незаполненное — одной честной информативной строкой, а не «TBD»;
|
||||
3. **OpenSpec, если его нет или `config.yaml` остался примером** — **вызови
|
||||
Skill `av-dev:code-openspec`**. Каталог принадлежит конвейеру, и команда
|
||||
заведения с формой файла живут там. Пересказ инвариантов, конвенций и правил
|
||||
ревью из `context` вычисти ссылкой на дом — на переводимом проекте он там
|
||||
почти наверняка есть. Вызов не разрешился — `docs.py` о каталоге тогда тоже
|
||||
молчит, и форму `config.yaml` не проверяет никто; скажи это строкой;
|
||||
4. переносы содержимого;
|
||||
5. каталог задач — **вызови скилл `av-dev:task-track`**, сценарий адаптации: он
|
||||
владеет форматом задач. Он же переименует транслитные слаги в английские и
|
||||
тем же проходом починит перекрёстные ссылки;
|
||||
6. починка ссылок на перенесённое во всём репозитории — `docs/`, `openspec/`,
|
||||
`CLAUDE.md`, `README.md`;
|
||||
7. удаление оригиналов — **только тех, чьё содержимое найдено в новом доме**;
|
||||
8. **шаг `docs.py check` в гейт проекта.** Путь к скрипту — переменной с
|
||||
умолчанием на канонический путь маркетплейса, чтобы переустановка плагина не
|
||||
меняла `Taskfile`; шаг обязан **краснеть внятно**, если скрипт не найден, а не
|
||||
пропускаться. Передай ему базу диффа (`--base`) той же переменной, что и
|
||||
остальным шагам гейта: без неё сверка миграций со схемой не гоняется вовсе.
|
||||
Пример строки покажи человеку — гейт принадлежит проекту, и правит его он.
|
||||
|
||||
**Шагов в гейте три, и они независимы.** `docs.py check` не тянет за собой
|
||||
ни задачи, ни конвейер: без своих строк дрейф каталога задач и формы
|
||||
`openspec/config.yaml` перестаёт ловиться совсем. Ставь соседские шаги по
|
||||
следу присутствия — `<каталог задач>/.tasks.json` есть, значит ставится
|
||||
`tasks.py check --dir <каталог задач>`; `openspec/config.yaml` есть, значит
|
||||
ставится `openspec.py check`. Следа нет — плагина в проекте нет, шаг не
|
||||
ставится, и это **строка доклада**, а не поломка: назови, чего теперь не
|
||||
проверяет никто. У каждого шага своя переменная пути с тем же умолчанием на
|
||||
канонический путь маркетплейса; `$CLAUDE_PLUGIN_ROOT` в гейт не подставляй —
|
||||
он ведёт только в свой плагин;
|
||||
9. `docs.py check` — до **отсутствия дрейфа раскладки**. Замечания
|
||||
(незаполненные плейсхолдеры, слабое упоминание capability) остаются:
|
||||
незаполненный канон это объявленное переходное состояние из шага 5, а не
|
||||
отказ. Пересчитай эти пункты в докладе переходного состояния — не выдавай
|
||||
их за поломку и не молчи о них.
|
||||
|
||||
**Задачи `docs.py` не проверяет** — их ведёт другой плагин, и согласованность
|
||||
каталога показывает только `tasks.py check`. Позвал на шаге 5 скилл задач —
|
||||
его отчёт идёт в доклад отдельной строкой, и пункт «задачи без цели» в нём
|
||||
зелёным не станет: цели не сочиняются адаптацией (запрет записан у того, кто
|
||||
ведёт задачи), их проставляет человек порциями переоценки на первом груминге —
|
||||
скилл `av-dev:task-groom`.
|
||||
|
||||
### 5. Объяви переходное состояние
|
||||
|
||||
Сразу после переноса канон **заполнен не весь**, и это нормально, но обязано
|
||||
быть названо, иначе следующий агент примет скелет за поломку.
|
||||
|
||||
Печатается по факту: сколько документов стоят честной строкой вместо
|
||||
содержания, сколько маркеров долга в `architecture.md`, сколько задач без
|
||||
критериев приёмки. Закрывается порциями по ходу работы, а не одним заходом.
|
||||
|
||||
### 6. Позови обоих судей
|
||||
|
||||
`docs.py` увидел раскладку, а не смысл: перенос растащил один факт по двум домам,
|
||||
оставил в `architecture.md` поведение, которому место в спеке, и оторвал ADR от
|
||||
его `design.md`. Ничего из этого скрипт не видит, и первый прогон на живом
|
||||
проекте обычно самый урожайный — правило единственного дома до адаптации никто не
|
||||
проверял.
|
||||
|
||||
Вызови Skill **`av-dev:doc-healthcheck`** — он зовёт обоих судей на весь канон
|
||||
разом и держит разбор урожая порциями.
|
||||
|
||||
**Передай им объявленное переходное состояние из шага 5** — иначе честная строка
|
||||
в незаполненном слоте вернётся находкой, а это не поломка, а объявленный долг.
|
||||
|
||||
### 7. Вычитай написанное — агент `doc-wording`
|
||||
|
||||
Судьи смотрят утверждения, а `adopt` только что **писал текст**: честные строки
|
||||
в пустые слоты, переписанные при переносе абзацы, шапки перенесённых документов.
|
||||
Язык этого текста не проверяет никто другой, а зовущий здесь по определению тот,
|
||||
кто его и написал.
|
||||
|
||||
Позови агента **по названной пачке** — документы, которые ты завёл или правил,
|
||||
плюс перенесённые целиком. Весь канон ему не нужен: он работает по списку, и
|
||||
список же служит ему словарём терминов. Находки — готовые формулировки,
|
||||
подставляешь их ты.
|
||||
|
||||
## `upgrade` — канон вырос
|
||||
|
||||
1. `docs.py version` — версия проекта и версия скрипта.
|
||||
2. Проект новее скрипта — **обнови маркетплейс**, а не проект: это отстал
|
||||
плагин.
|
||||
3. Иначе иди по [changelog.md](references/changelog.md) снизу вверх от версии
|
||||
проекта до текущей и делай названное в каждой записи. Записи независимы и
|
||||
применяются по порядку.
|
||||
4. Подними `canon` в `docs/.docs.json` до текущей.
|
||||
5. `docs.py check`.
|
||||
6. **Позови судей** — Skill `av-dev:doc-healthcheck`.
|
||||
7. **Позови вычитку** — агент `doc-wording`, но **только по тем документам,
|
||||
которых записи журнала коснулись**, и только если правка была текстовой, а не
|
||||
переименованием файла. Записи журнала пишутся руками в проектной прозе, и
|
||||
дописанный по журналу раздел — такой же свежий текст, как на синке.
|
||||
|
||||
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
|
||||
это дефект журнала, и о нём надо сказать, а не догадываться.
|
||||
|
||||
**Каталог задач повышается своим журналом, а не этим.** У него своя версия
|
||||
формата — ключ `tasks` в `<каталог задач>/.tasks.json`, — и двигает её плагин
|
||||
`av-dev-tasks`. Запись канона вправе сказать «позови соседа», но не вправе
|
||||
двигать чужое число: две версии, которые ходят по одному журналу, разъезжаются
|
||||
на первом же проекте, поставившем один плагин без другого. Отстал каталог
|
||||
задач — это скажет `tasks.py check` своей строкой гейта, а повысит скилл
|
||||
`av-dev:task-track`.
|
||||
|
||||
**Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.docs.json` с
|
||||
версией скрипта — и только его. Применена ли запись журнала **по существу**, он
|
||||
не знает: проект несёт `"canon": 6` и может не иметь того, чего требовала любая
|
||||
из пройденных версий. Записи применяются руками (переименовать секцию, проставить
|
||||
типы, дописать раздел каждому `fix`), а ручной проход по нескольким записям
|
||||
подряд — ровно то место, где половина шага делается и забывается. Судьи и есть
|
||||
проверка, которой у `upgrade` иначе нет: `doc-consistency` увидит, что документы
|
||||
разошлись после переименований, `doc-code-drift` — что переехавший факт
|
||||
разошёлся с кодом.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не сочиняет содержание.** Пустой слот получает честную строку о том, что его
|
||||
наполнить пока нечем, а не выдуманный абзац. Придуманный периметр модели угроз
|
||||
хуже отсутствующего: по нему будут строиться находки.
|
||||
- **Не удаляет то, чьё содержимое не нашло дом.** Оригинал живёт, пока не
|
||||
названо поимённо, куда переехал каждый его кусок.
|
||||
- **Не ведёт содержимое канона** — это скилл `docs`. Здесь только раскладка.
|
||||
- **Не заводит проект с нуля** — это скилл `init`.
|
||||
- **Не правит историю.** В старых коммитах старые пути остаются, и это нормально.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Что нашёл `docs.py`: код выхода и число пунктов дрейфа.
|
||||
- Что перенесено: файл → дом, числом и поимённо для спорного.
|
||||
- **Удалённые дубли** — с указанием, против какой спеки сверялся каждый.
|
||||
- **Не разложилось** — поимённо, с причиной.
|
||||
- Переходное состояние числами: честных строк, маркеров долга, задач без
|
||||
критериев.
|
||||
- **Граница покрытия**: что проверила машина, что судил ты, чего не смотрел
|
||||
никто.
|
||||
@@ -0,0 +1,600 @@
|
||||
# Канон документов проекта
|
||||
|
||||
**Номер версии здесь не стоит намеренно.** Этот файл описывает канон таким, какой
|
||||
он сейчас, а число живёт в двух домах, которые не расходятся: константа в
|
||||
`docs.py` (её печатает `docs.py version`) и верхняя запись
|
||||
[журнала](changelog.md). Литерал в шапке был третьим и отстал на первом же
|
||||
повышении — версию 13 он пережил, объявляя канон двенадцатым.
|
||||
|
||||
Это **единственный дом определения канона**. Скиллы `init`, `canon` и `docs`
|
||||
читают его, а не пересказывают: три описания одной раскладки разъедутся, и
|
||||
работать будет то, которое прочитали последним. Меняется канон — меняется этот
|
||||
файл и появляется запись в [changelog.md](changelog.md).
|
||||
|
||||
## Зачем канон жёсткий
|
||||
|
||||
Пути фиксированы, и проект под них подгоняется, а не наоборот. Причина не
|
||||
техническая: проектов много, все малого и среднего размера, и ориентироваться в
|
||||
слегка похожих, но разных раскладках дороже, чем один раз привести их к общей.
|
||||
Рядом лежит OpenSpec, у которого структура тоже строгая.
|
||||
|
||||
Цена принята сознательно: плагин не переносится на чужой репозиторий как есть —
|
||||
чужой репозиторий **приводится** к канону скиллом `canon`.
|
||||
|
||||
Раскладка отвечает, **где** текст лежит и на какой вопрос отвечает. Каким он
|
||||
должен быть **словами** — общий для всех документов канона файл
|
||||
[language.md](language.md): информационный стиль, англицизмы, жаргон. Он
|
||||
относится и к задачам, и к решениям ADR, и к запискам разведки.
|
||||
|
||||
## Сопровождение и эксплуатация — целое и часть
|
||||
|
||||
**Копия.** Дом — `shared/operations.md` в репозитории плагинов: словарь
|
||||
делят роадмап, архитектура и тема ревью `operations`, то есть три плагина,
|
||||
и ни один из трёх им не владеет. Правится дом, а не этот файл.
|
||||
|
||||
<!-- копия: сопровождение-словарь из av-dev/shared/operations.md -->
|
||||
|
||||
Одна тема живёт в трёх местах, и путать их слова нельзя.
|
||||
|
||||
**Сопровождение** — всё, чем держат проект: инструмент и сборка, процесс,
|
||||
выкладка, метрики и логи, инфраструктура, дежурство. **Эксплуатация** — его
|
||||
часть: работа системы на проде. Целое и часть, и никогда наоборот.
|
||||
|
||||
| Место | Уровень | Что там |
|
||||
| --- | --- | --- |
|
||||
| `ROADMAP.md`, секция `Сопровождение` | план | **работы**, которые собираемся делать: цели и их задачи |
|
||||
| `architecture.md`, раздел «Эксплуатация» | состояние | **как устроено сейчас**: где работает, что рядом, кто перезапускает |
|
||||
| тема ревью `operations` | оптика | **чем проверяем**: «это упало через неделю на проде» |
|
||||
|
||||
Слово **«поддержка» не употребляется вовсе** — в нём слышится помощь
|
||||
пользователю, а это другая работа.
|
||||
|
||||
**Граница с возможностями проходит по тому, кто наблюдает.** «Приложение
|
||||
сообщает о своём состоянии» — возможность приложения, её место среди прочих
|
||||
целей: наблюдает пользователь сервиса. «Дежурный видит состояние на одном
|
||||
экране» — сопровождение: наблюдаем мы. Одни и те же метрики попадают в разные
|
||||
секции роадмапа, и это верно — секции отвечают на разные вопросы.
|
||||
|
||||
<!-- /копия: сопровождение-словарь -->
|
||||
|
||||
## Раскладка
|
||||
|
||||
**Документ канона живёт файлом или каталогом.** `docs/security.md` и
|
||||
`docs/security/` — одно и то же; форму выбирает проект по объёму написанного, и
|
||||
переход между формами не меняет ни канон, ни версию. Обе формы сразу — ошибка:
|
||||
два дома для одного факта расходятся молча.
|
||||
|
||||
```
|
||||
CLAUDE.md памятка агенту: что это, стек, инварианты с
|
||||
severity, команды, семантика гейта, запреты
|
||||
AGENTS.md необязателен, лежит рядом; читается теми же
|
||||
docs/
|
||||
.docs.json версия канона и пути, нужные проверкам
|
||||
passport.md | passport/ зачем и для кого; чем НЕ является; сценарии
|
||||
architecture.md | architecture/ как сложено — обзор; окружение и эксплуатация
|
||||
database.md | database/ схема хранилища; представление данных и настройки
|
||||
security.md | security/ периметр; недоверенный вход; что вне модели
|
||||
conventions.md | conventions/ как пишем код; что механизировано
|
||||
research.md | research/ наблюдения и числа с провенансом
|
||||
adr.md | adr/ почему решено так; статусы, правило замены
|
||||
review.md | review/ настройка конвейера под проект + журнал дефектов
|
||||
<своя тема>.md | <своя тема>/ всё, что проект счёл нужным проверять
|
||||
tasks/ каталог задач — плагин av-dev-tasks, не канон;
|
||||
лежит в корне, вне docs/, и канон его не требует
|
||||
openspec/
|
||||
config.yaml только нужды генерации артефактов + ссылки
|
||||
specs/<capability>/spec.md что система делает — нормативно
|
||||
changes/archive/ архив изменений с design.md — сырьё для ADR
|
||||
```
|
||||
|
||||
**У документа-каталога обязателен `README.md`** — вход, по которому его читают агенты.
|
||||
`adr/` в форме каталога держит ещё и `template.md`, а записи именуются
|
||||
`ADR-ГГГГ-ММ-ДД-slug.md`.
|
||||
|
||||
## Три категории документов
|
||||
|
||||
Раньше здесь стояло плоское правило «каждый документ `docs/` — тема ревью». Оно
|
||||
неверно ровно наполовину: паспорт и схема хранилища ревью нужны, но темами не
|
||||
являются, а журнал решений и журнал наблюдений ревью изменения не нужны вовсе.
|
||||
Плоское правило заставляло разметчика либо плодить фантомные темы, либо терять
|
||||
документы молча — а молчащая потеря и есть то, против чего канон написан.
|
||||
|
||||
**Разрез один и проверяемый: можно ли по документу сказать «в этом изменении
|
||||
сделано не так»?**
|
||||
|
||||
| Категория | Ответ на разрез | Что с ней делает ревью |
|
||||
| --- | --- | --- |
|
||||
| **тема** | да, прямо | заводит направление проверки и требует исполнителя |
|
||||
| **источник темы** | нет, но он задаёт границу, по которой судит чужая тема | читается как материал, своей темы не порождает |
|
||||
| **процессный документ** | нет: он про то, как мы работаем, а не про изменение | не судит по нему изменение |
|
||||
|
||||
| Документ | Категория | Куда питает |
|
||||
| --- | --- | --- |
|
||||
| `conventions.*` | тема | `conventions` |
|
||||
| `security.*` | тема | `security` |
|
||||
| `architecture.*` | тема | `architecture`; раздел эксплуатации — `operations` |
|
||||
| *свой документ проекта* | тема | своя тема, именем документа |
|
||||
| `passport.*` | источник | `architecture` — граница домена, «чем **не** является» |
|
||||
| `database.*` | источник | `operations` — схема и настройки с числами |
|
||||
| `CLAUDE.md`, `AGENTS.md` | источник | `autotests` (семантика гейта); инварианты — сквозные |
|
||||
| `openspec/specs/` | источник | `requirements` |
|
||||
| `openspec/config.yaml` | процессный | — (настройка порождения артефактов, слой **до** тем; заводит конвейер) |
|
||||
| `tasks/` | процессный | — (чужое владение: плагин `av-dev-tasks`) |
|
||||
| `review.*` | процессный | — (настройка самого конвейера, слой **над** темами) |
|
||||
| `adr.*` | процессный | — |
|
||||
| `research.*` | процессный | — |
|
||||
| `.docs.json` | процессный | — (служебный файл, не документ) |
|
||||
|
||||
**Список тем открытый, и это не послабление, а механизм.** Категории
|
||||
`источник` и `процессный` **закрыты** — они перечислены здесь поимённо и
|
||||
проектом не пополняются. Всё остальное, что проект кладёт в `docs/`, — тема: у
|
||||
конвейера есть приёмник для темы, к которой нет именной оптики, и заведён он
|
||||
ровно за этим. Завёл `docs/accessibility.md` — появилась тема `accessibility`, и
|
||||
она попадает в план каждого прогона.
|
||||
|
||||
Отсюда следствие, ради которого правило и заведено: **`docs/` — это конфигурация
|
||||
ревью.** Проект настраивает проверку тем, что пишет о себе, а не отдельным файлом
|
||||
настроек, который разошёлся бы с документами.
|
||||
|
||||
**«Не судит по нему» и «не открывает» — не одно и то же, и разница существенна.**
|
||||
`docs/review.*` проходы читают на каждом прогоне: там лежат вопросы по темам,
|
||||
журнал дефектов, типовые узлы и типовые ложноположительные. Это чтение конвейером
|
||||
**собственной настройки**, а не суждение об изменении, и потому оно законно.
|
||||
`adr/`, `research/` и `tasks/` не открывает никто: по ним изменение не судят, и
|
||||
настройкой конвейера они не являются.
|
||||
|
||||
**Процессный документ — не документ второго сорта.** `adr/` и `research/`
|
||||
проверяются наравне с остальными, но **сверкой документации**, а не прогоном
|
||||
ревью: ADR без ссылки на источник, замена без парного статуса, число
|
||||
без провенанса — это работа агентов `doc-consistency` и `doc-code-drift`, и она
|
||||
осталась там же, где была. Изменилось одно: прогон ревью не открывает их как
|
||||
критерий и не судит по ним изменение.
|
||||
|
||||
Цена этого решения записана, а не подразумевается: **расхождение изменения с
|
||||
записанным решением прогоном больше не ловится.** Раньше архитектурный проход
|
||||
читал `adr/` и мог сказать «здесь отменено решение ADR-2026-03-11, а парного
|
||||
статуса нет»; теперь это скажет только `doc-consistency`, а зовёт его скилл
|
||||
`healthcheck`. Сделка сознательная — ADR объясняет прошлое, а не предъявляет
|
||||
требование к изменению, и чтение всего каталога решений на каждой задаче
|
||||
оплачивалось на каждой, а срабатывало на единицах.
|
||||
|
||||
### Имена файлов английские, текст русский
|
||||
|
||||
**Текст документов русский; имена файлов, capability и задач — английские,
|
||||
kebab-case.** Причина не эстетическая: имя файла стоит в ссылках из других
|
||||
документов, в коммитах и в путях, которые набирают руками, — а кириллица в пути
|
||||
ломается по-разному в разных местах и не набирается на английской раскладке.
|
||||
|
||||
**Транслита не заводим.** Слаг именуется английским словом **по сути**, а не
|
||||
записью русского латиницей: `queue-as-table`, а не `ochered-tablicej`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается.
|
||||
|
||||
У ADR имя вдобавок несёт форму — `ADR-ГГГГ-ММ-ДД-slug.md`: по ней записи
|
||||
сортируются, и по ней же ищется дата решения.
|
||||
|
||||
`docs.py check` проверяет кириллицу и kebab-case **жёстко**, форму имени ADR —
|
||||
тоже, а транслит **эвристикой**, то есть замечанием: английское слово от
|
||||
транслита машина не отличает. Слаги каталога задач ведёт `tasks.py` — там та же
|
||||
проверка и тот же разрез.
|
||||
|
||||
**Переименование — не правка, а перенос ссылок**: делается одним проходом по
|
||||
всем местам, где имя упомянуто, иначе останутся битые ссылки. Для задач это
|
||||
умеет `tasks.py adopt`; для документов канона правит человек, а `docs.py` потом
|
||||
показывает, что ссылки целы.
|
||||
|
||||
## Роли документов и темы ревью
|
||||
|
||||
Одна строка на каждый — на какой вопрос он отвечает, в какой он категории и
|
||||
какую тему питает. **Кто именно закрывает тему, здесь не указано намеренно**: это
|
||||
зависит от метки прогона и меняется вместе с конвейером, а документ живёт
|
||||
дольше. Раскладку «тема → проход → глубина» держит скилл
|
||||
`av-dev:code-review`.
|
||||
|
||||
**Общего словаря у канона с конвейером ровно три вида имён: имена категорий,
|
||||
имена тем и имена меток.** Категорий три — `тема`, `источник`, `процессный`;
|
||||
**меток тоже три, и они закрыты: `small`, `medium`, `large`.** Метка это итог
|
||||
классификации задачи, и по ней конвейер выбирает исполнителей на обеих стадиях
|
||||
ревью; проект её не выдумывает, а только уточняет триггеры. Ими проект и
|
||||
настраивает ревью — вопросами по темам и триггерами метки. **Имён проходов канон не называет нигде**, включая вывод `docs.py`:
|
||||
проход переименовывается и переезжает между метками, и канон, назвавший его, в
|
||||
этот день соврёт молча. Обратное направление законно — конвейер называет
|
||||
документы канона поимённо, потому что он их читатель.
|
||||
|
||||
| Документ | Вопрос | Категория и тема |
|
||||
| --- | --- | --- |
|
||||
| `CLAUDE.md`, `AGENTS.md` | что нельзя нарушать, чем краснеет гейт | источник: `autotests`; инварианты — сквозные, во все темы |
|
||||
| `passport.*` | зачем и для кого, чем это **не** является | источник: `architecture` |
|
||||
| `architecture.*` | как сложено и где что работает | тема `architecture`; раздел эксплуатации — `operations` |
|
||||
| `database.*` | что лежит в хранилище и какими настройками | источник: `operations` |
|
||||
| `security.*` | против кого защищаемся и что вне модели | тема `security` |
|
||||
| `conventions.*` | как мы пишем код | тема `conventions` |
|
||||
| `openspec/specs/` | что система делает — нормативно | источник: `requirements` |
|
||||
| `research.*` | что показала реальность, а не документация | процессный |
|
||||
| `adr.*` | почему решено именно так | процессный |
|
||||
| `review.*` | как настроен конвейер и что уже проскакивало | процессный: слой **над** темами |
|
||||
| `tasks/` | что делаем и в каком порядке | процессный |
|
||||
| *свой документ проекта* | что проект счёл нужным проверять | **своя тема**, именем документа |
|
||||
|
||||
### `passport.md`
|
||||
|
||||
Цель; закрытый список потребителей и что каждому нужно; **чем целью не
|
||||
является** — это граница домена, по которой архитектурный проход судит о
|
||||
переносе понятия; типовые сценарии; мера, по которой проект считается удавшимся;
|
||||
референсы, у кого подсматривать.
|
||||
|
||||
### `architecture.md` — **обзор, не поведение**
|
||||
|
||||
Принципы; компоненты **со ссылками на capability**, а не с пересказом их
|
||||
требований; **единые точки проекта** — где генерируются идентификаторы и время,
|
||||
где единственный парсер входного формата, где маппинг доменной ошибки в код
|
||||
ответа, где общий путь приёма (это материал для вопроса «не появился ли второй
|
||||
способ»); внешние границы и форматы чужих систем; окружение — где работает, что
|
||||
рядом, кто перезапускает; **внешние зависимости поимённо** и чем каждая
|
||||
отказывает (не только «падает», но и «отвечает медленно», «молчит», «отдаёт
|
||||
мусор»); кто заметит отказ и когда; характер потока — непрерывный, по запросу,
|
||||
по расписанию; деплой; открытые вопросы.
|
||||
|
||||
**Обратимости здесь нет** — её единственный дом `CLAUDE.md`: туда ходят пять
|
||||
проходов, и раздвоение адреса означало бы, что проект написал ответ, а ревью его
|
||||
не прочитало.
|
||||
|
||||
**Поведение системы сюда не пишется.** Его нормативный дом — `openspec/specs/`,
|
||||
куда `opsx:archive` вливает дельты; второй дом синхронизировать руками
|
||||
невозможно, и он разойдётся.
|
||||
|
||||
Раздел, ещё не разнесённый при переезде, помечается маркером долга:
|
||||
|
||||
```
|
||||
<!-- канон: поведение → openspec/specs/<capability> -->
|
||||
```
|
||||
|
||||
`docs.py` считает маркеры и печатает остаток числом. Гейт от них **не краснеет**:
|
||||
это долг, а не отказ, иначе постепенный переезд стал бы невозможен.
|
||||
|
||||
### `database.md`
|
||||
|
||||
Схема: таблицы, ключи, связи, правило времени и идентификаторов. Плюс то, чего
|
||||
нет в схеме, но без чего замер не превращается в находку: **чем физически лежит
|
||||
запись** (сжатый BLOB, JSON-строка, колонки), что происходит при чтении и записи
|
||||
(распаковка целиком, read-modify-write), и **настройки с числовым значением** —
|
||||
таймаут занятости, режим журналирования, лимит тела, размер пула, ретеншен.
|
||||
|
||||
Конвенции идентификаторов и именования — не схема, они в `conventions/`.
|
||||
|
||||
### `security.md`
|
||||
|
||||
**Периметр первой строкой.** «Сервис открыт наружу» и «контур доверенный,
|
||||
публичного интернета здесь нет, не выдумывай его» — противоположные постановки
|
||||
под одним заголовком, и разбор темы `security` между ними сам не выберет. Контур ещё
|
||||
не развёрнут — назови **оба** периметра, целевой и сегодняшний, и скажи прямо,
|
||||
против какого строятся находки.
|
||||
|
||||
Дальше: что недоверенное и каким каналом приходит; **из чего строятся пути и
|
||||
ключи** (раскладка файлов, состав координатного ключа, имя каталога) — отсюда
|
||||
строится выход за пределы песочницы; что разграничивает доступ; что
|
||||
чувствительнее чего; **что вне модели** — перечислить явно.
|
||||
|
||||
### `conventions/`
|
||||
|
||||
Прозой остаётся **только то, что не выражается правилом**. `README.md` держит
|
||||
индекс, правило промоута и **перечень уже механизированного** со ссылкой на
|
||||
место механизации — конфиг линтера, собственный анализатор, тест-сканер
|
||||
исходников. Не названное место механизации означает, что проход добросовестно
|
||||
проверит уже проверенное.
|
||||
|
||||
### `research/`
|
||||
|
||||
Наблюдения за внешним миром: что реально шлёт источник, чем документация формата
|
||||
расходится с практикой, какие числа сняты с живого потока. **Числа — с
|
||||
провенансом**, то есть с командой или условиями, которыми получены.
|
||||
`README.md` — как снималось и индекс тем.
|
||||
|
||||
Число без источника проход обязан читать как условие, а не как замер. Число, чей
|
||||
источник по ссылке не подтвердился, не выбрасывается и не переписывается по
|
||||
догадке — остаётся с пометкой «расходится с источником: там <что нашли>».
|
||||
|
||||
### `adr/`
|
||||
|
||||
**ADR продвигает уже написанное решение, а не сочиняет его заново.** Запись
|
||||
цитирует решение и ссылается на источник. Источников два, и оба законны:
|
||||
|
||||
- **архивный `design.md`** — решение принято по ходу изменения:
|
||||
`openspec/changes/archive/<id>/design.md`. Обычный случай;
|
||||
- **записка разведки** — решение принято разведкой, и change по нему не будет
|
||||
никогда: намеренный отказ, выбор подхода, «проверили и не делаем». У такой
|
||||
работы нет `design.md` по построению, и без второго источника её решение либо
|
||||
не попадало в `adr/` вовсе, либо попадало сочинённым заново.
|
||||
|
||||
Источник называется в записи всегда — по нему видно, чем решение подтверждено.
|
||||
|
||||
Заводится, когда верно одно из трёх:
|
||||
|
||||
<!-- дом: adr-когда-заводить -->
|
||||
- **дорогой откат** — переделка стоит дороже переписывания одного файла;
|
||||
- **намеренный отказ** от очевидного подхода;
|
||||
- **пересмотр прежнего решения** — тогда у старой записи обязателен статус
|
||||
«заменено на».
|
||||
<!-- /дом: adr-когда-заводить -->
|
||||
|
||||
Не заводится для рутины и для того, что видно из кода и `git log`.
|
||||
|
||||
Записи неизменяемы: передумали — заводится новая, старая получает статус.
|
||||
Активная запись статуса не имеет.
|
||||
|
||||
**Статус живёт полем меты записи**, там же, где дата и источник:
|
||||
`- **Статус:** заменено на ADR-…` либо `- **Статус:** устарело`. Места ему в
|
||||
шаблоне не отводилось, и каждая запись изобретала своё — то абзацем, то
|
||||
заголовком; в таблице `adr/README.md` статус при этом обязан быть, а брать его
|
||||
оттуда, где он у каждого свой, нельзя.
|
||||
|
||||
### `review.md`
|
||||
|
||||
Два раздела с разными сроками жизни.
|
||||
|
||||
**Настройка конвейера под проект**, пять подразделов с точными именами — по ним
|
||||
проходы находят свой кусок:
|
||||
|
||||
- **Типовые узлы** — рода узлов проекта и 3–5 проверяемых свойств к каждому;
|
||||
- **Типовые ложноположительные** — находки, которые здесь выглядят убедительно и
|
||||
всегда неверны, каждая со строкой «почему здесь это не дефект»;
|
||||
- **Вопросы по темам** — в форме `<тема>: <вопрос> (<провенанс>)`. **Не по именам
|
||||
проходов**: проход уезжает между метками, а тема остаётся, и вопрос,
|
||||
адресованный проходу, перестал бы задаваться молча в тот день, когда тот уехал
|
||||
в старшую метку. Задаёт вопрос тот, кто закрывает тему на этом прогоне.
|
||||
Адресовать можно только теме: `passport`, `database`, `adr`, `research` и
|
||||
`review` — не темы, и вопрос, адресованный им, не задаст никто;
|
||||
- **Триггеры метки** — проектная конкретизация правила выбора метки ревью,
|
||||
**тремя списками**. Два поднимают, по одному на ось: что в этом проекте считается
|
||||
**крупным** (объём: сколько узлов и слоёв трогает) и что считается
|
||||
**незнакомым** (форма решения: известна до начала или нащупывается по ходу).
|
||||
Любая из двух осей поднимает прогон до `large`, старшей метки, — а она
|
||||
рассчитана на 5–10% задач. Третий список — что считается **мелким** (опускает
|
||||
до `small`); он один, потому что вниз метку опускает только совпадение обеих
|
||||
осей сразу. Перечнем мест, узлами или capability, а не вторым определением
|
||||
класса. Уточняет умолчания, а не отменяет их. Рабочее умолчание — `medium`:
|
||||
миграция схемы и публичный контракт метку **не** поднимают, их проверяют
|
||||
проходы, которые в `medium` и так есть;
|
||||
- **Недоступно проверке** — два подраздела, оба **по темам**: «не проверит ни
|
||||
один проход» (принципиальная граница, по факту промаха не пересматривается) и
|
||||
«перестали проверять сознательно» (пересматривается первым). Тема, у которой в
|
||||
проекте нет дома, сюда не пишется: её и так называет план каждого прогона.
|
||||
|
||||
**Журнал дефектов:** запись на каждый воспроизведённый дефект с пометкой
|
||||
**проскочил / пойман ревью**. Проскочившие — проверочный набор для калибровки конвейера,
|
||||
выборка по пометке. Пойманные с оракулом — лучшая опора для прохода: проектные,
|
||||
воспроизводимые, однажды оказавшиеся правдой.
|
||||
|
||||
### `tasks/`
|
||||
|
||||
**Каталог задач канону не принадлежит.** Его ведёт отдельный плагин
|
||||
`av-dev-tasks` — своим скриптом, своим конфигом `<каталог>/.tasks.json`, своей
|
||||
версией формата в нём же и своим журналом версий. Канон о том числе не
|
||||
высказывается и его не двигает: повышает каталог задач тот, кто его ведёт.
|
||||
Канон **резервирует место** в `docs/` и внутрь не смотрит:
|
||||
`docs.py` каталог не открывает, его отсутствия не считает дрейфом и согласованность
|
||||
задач не проверяет. Проект, поставивший только канон документов, задач не ведёт
|
||||
вовсе, и отказом это быть не может.
|
||||
|
||||
Раскладку, форму записи и команды держит скилл `av-dev:task-track`. Ниже — то,
|
||||
от чего зависит, читается ли проект как продукт: канон высказывается об этом
|
||||
потому, что роадмап отвечает на вопрос о **системе**, а не о работах.
|
||||
|
||||
**`ROADMAP.md` отвечает на «что приложение уже умеет и чего ещё не умеет».** Это
|
||||
не очередь работ: цель — **возможность приложения**, задача — шаг к ней.
|
||||
Достигнутая цель из роадмапа **не исчезает** — строка с датой переезжает в
|
||||
секцию достигнутого, потому что «что умеет» и есть половина вопроса, ради
|
||||
которого документ открывают. Вторым домом поведения роадмап при этом не
|
||||
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
|
||||
**когда и в каком порядке** оно появилось.
|
||||
|
||||
**У каждой записи есть тип, и тип решает, что с ней можно делать.** Дом типа —
|
||||
поле меты `Тип` первой строкой; эмодзи в заголовке от него производна. Словарь
|
||||
закрыт:
|
||||
|
||||
| Тип | Что это |
|
||||
| --- | --- |
|
||||
| 🎯 `goal` | возможность приложения |
|
||||
| ✨ `feature` | снаружи появляется то, чего не было |
|
||||
| 🐞 `fix` | поведение расходится с заявленным |
|
||||
| 🧹 `chore` | обслуживание, поведение не меняется |
|
||||
| 🔬 `research` | исход — знание, а не изменение |
|
||||
|
||||
**Схемы записи здесь нет намеренно.** Какие разделы тип требует, нужна ли ему
|
||||
цель и берётся ли он в работу — скилл `av-dev:task-track`, раздел «Тип
|
||||
записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Ссылки в
|
||||
дерево того плагина здесь нет намеренно: он ставится отдельно, и путь наружу
|
||||
разрешился бы не всегда. Канон фиксирует **словарь**, потому что
|
||||
от него зависит, читается ли проект как продукт; схема — механика ведения задач,
|
||||
и второй её экземпляр разошёлся бы с первым (он и разошёлся: канон успел
|
||||
объявить цель у `fix` запрещённой, хотя она там необязательна).
|
||||
|
||||
Схема требуется **к взятию в работу**, а не к заведению: беклог пополняется чаще,
|
||||
чем разбирается, и требование на входе выгоняло бы в заметки то, что должно
|
||||
лежать задачей. Запись, не собравшая разделы своего типа, — законное состояние
|
||||
беклога; невзятой её делает `tasks.py ready`.
|
||||
|
||||
Отдельного типа для незаполненной записи нет: «ещё не описано» — состояние, а не
|
||||
род работы, и называется оно **`research` без раздела «Вопрос»**. Такая запись в
|
||||
работу не берётся и лежит в конце своей категории.
|
||||
|
||||
Раскладку, форму записи и алгоритм работы над каждым типом держит скилл
|
||||
`av-dev:task-track`.
|
||||
|
||||
### `CLAUDE.md`
|
||||
|
||||
Что это и стек; **инварианты с severity рядом с формулировкой** — по ним проходы
|
||||
присваивают `critical`, поэтому severity стоит здесь, а не выводится каждым
|
||||
проходом заново; команды; **семантика гейта** — чем краснеет безусловно и почему,
|
||||
где логи, что означает исход, чего в гейте намеренно нет, **кто и когда обязан
|
||||
гонять дорогое вне гейта**.
|
||||
|
||||
Плюс то, что нужно git-операциям и проходам и не выводится ниоткуда:
|
||||
|
||||
- **имя основной ветки** — от неё считается база диффа
|
||||
(`git merge-base HEAD <ветка>`), в неё коммитит работу конвейер.
|
||||
Угадывание между `master` и `main` ломает интеграцию целиком;
|
||||
- **что запускать запрещено, с путями** — рабочая БД, боевой каталог данных,
|
||||
внешние сервисы. Запретом с путями, а не «будь осторожен»;
|
||||
- **где `testdata`** и что в них лежит; **куда писать временное**;
|
||||
- **что считается необратимым** — единственный дом: от обратимости зависит вся
|
||||
шкала ранжирования триажа и право проходов на `critical`;
|
||||
- **что считается сломанным** — красная проверка, обгоняющая развитие;
|
||||
**ориентир по размеру порции**, если он замерялся. Оба слота читает скилл
|
||||
`av-dev:task-groom`, и имена их — его; названы они здесь потому, что дом
|
||||
содержимого `CLAUDE.md` один и он тут.
|
||||
|
||||
### `openspec/config.yaml`
|
||||
|
||||
**Файл канону не принадлежит, и проверяет его тоже не канон.** Каталог
|
||||
`openspec/` — предпосылка конвейера: без него не работают ни `opsx:propose`, ни
|
||||
ревью дизайна, ни сверка требований. Заводит его, настраивает и **проверяет
|
||||
форму** скилл `av-dev:code-openspec`: там образец файла, там же скрипт
|
||||
`openspec.py check`. `docs.py` о файле не говорит ничего.
|
||||
|
||||
Канон называет его здесь по одной причине: `openspec/specs/` — **дом темы
|
||||
`requirements`**, и без этой строки карта тем неполна. На форму самого
|
||||
`config.yaml` канон не высказывается.
|
||||
|
||||
**Одно за каноном всё же остаётся, и это не форма, а единственный дом.** Блок
|
||||
`context` — самое частое место для второго дома: он читается при порождении
|
||||
каждого артефакта, туда удобно дописать «чтобы агент знал», и так заводятся копии
|
||||
инвариантов, конвенций, состава гейта и правил ревью. Расходятся они молча.
|
||||
Разрез: **утверждение, которое можно опровергнуть, открыв другой файл проекта, —
|
||||
пересказ; строка, которая говорит, какой файл открыть, — ссылка.** Машина этого
|
||||
не различает; судит агент `doc-consistency`, и `config.yaml` у него во входе.
|
||||
|
||||
## Правило единственного дома
|
||||
|
||||
Факт живёт ровно в одном файле; остальные ссылаются. Карта на случай спора:
|
||||
|
||||
<!-- дом: карта-домов -->
|
||||
| Факт | Дом |
|
||||
| --- | --- |
|
||||
| поведение системы | `openspec/specs/<capability>/spec.md` |
|
||||
| почему решено так | `adr/`, источник — архивный `design.md` либо записка разведки |
|
||||
| граница домена, «чем не является» | `passport.md` |
|
||||
| инвариант и его severity | `CLAUDE.md` |
|
||||
| что приложение умеет и чего не умеет; порядок работ | `tasks/ROADMAP.md` |
|
||||
| измеренное число | `research/` |
|
||||
| настройка с числовым значением | `database.md` |
|
||||
| периметр и модель угроз | `security.md` |
|
||||
| что необратимо | `CLAUDE.md` — **не** `architecture.md` |
|
||||
| единые точки проекта | `architecture.md` |
|
||||
| имя основной ветки, `testdata`, временный каталог | `CLAUDE.md` |
|
||||
| что уже механизировано правилом | `conventions.*`, раздел «Механизировано» |
|
||||
<!-- /дом: карта-домов -->
|
||||
|
||||
## Пустое называется пустым
|
||||
|
||||
Скелет канона заводится **целиком** с первого дня. Незаполненный документ держит
|
||||
**одну честную информативную строку**, а не заглушку:
|
||||
|
||||
- «внешних зависимостей нет — смотри на диск и на СУБД»;
|
||||
- «наблюдений на живых данных нет: внешний источник один, формат документирован»;
|
||||
- «прецедентов не накоплено»;
|
||||
- «сознательно ничего не отключали»;
|
||||
- «архитектуры пока нет: кода нет, заводится первой задачей».
|
||||
|
||||
Проход читает такую строку **как факт** и не тратит на неё обязательный вопрос.
|
||||
Отсутствие файла он не может прочитать никак, а «TBD» читает как пробел —
|
||||
поэтому `docs.py check` отличает честную строку от нетронутого плейсхолдера
|
||||
шаблона и напоминает о втором.
|
||||
|
||||
## Слотов нет
|
||||
|
||||
Файлы и каталоги, которых в каноне **нет**, и куда уезжает их содержимое:
|
||||
|
||||
| Было | Куда |
|
||||
| --- | --- |
|
||||
| `docs/review-brief.md` | документы канона и есть бриф; остаток — в `review.md` |
|
||||
| `docs/specs/` | `openspec/specs/` (поведение) и `architecture.md` (обзор) |
|
||||
| `docs/drafts/` | идея → запись `research`; отказ → ADR; порядок → `ROADMAP.md`; размышление → `opsx:explore` |
|
||||
| `docs/plan.md` | `tasks/ROADMAP.md` |
|
||||
| `BRIEF.md` | `passport.md` |
|
||||
| `docs/backlog/` | `tasks/` в корне репозитория |
|
||||
| `docs/review-journal.md`, `docs/review/journal.md` | `docs/review.md` |
|
||||
|
||||
## Что проверяет машина, а что человек
|
||||
|
||||
Граница объявляется вслух в каждом отчёте: `check`, отчитавшийся «канон
|
||||
соблюдён» на проекте, где из шести файлов три лишние, хуже отсутствующего.
|
||||
|
||||
| Проверяет `docs.py` | Судит агент | Какой |
|
||||
| --- | --- | --- |
|
||||
| отсутствующие пути канона | смысловой дубль документа и capability | `doc-consistency` |
|
||||
| файлы в `docs/` вне канона | поведение, оставшееся в `architecture.md` | `doc-consistency` |
|
||||
| имя файла не kebab-case латиницей; форма имени ADR | транслит в имени — сверх эвристики | `doc-wording` |
|
||||
| битые относительные ссылки | прямое противоречие между документами | `doc-consistency` |
|
||||
| версия канона и её отставание | достаточность честной строки в пустом слоте | `doc-consistency` |
|
||||
| нетронутый плейсхолдер шаблона | ADR без ссылки на источник, замена без парного статуса | `doc-consistency` |
|
||||
| маркеры долга — числом | **протухший факт, разошедшийся с кодом** | `doc-code-drift` |
|
||||
| миграция изменена, а `database.md` нет | зависимость в манифесте, не названная в обзоре | `doc-code-drift` |
|
||||
| capability без упоминания в `architecture.md` | второй способ там, где обзор обещал единственный | `doc-code-drift` |
|
||||
| | **пересказ документа канона в `context` вместо ссылки** | `doc-consistency` |
|
||||
| | придирки валидатора: сменились ли они | никакой — проявляются отказом `openspec validate --strict` |
|
||||
| | связность и читаемость | `doc-wording` |
|
||||
|
||||
**Форма `openspec/config.yaml` в левой колонке отсутствует не по забывчивости.**
|
||||
С канона 10 `docs.py` о файле не говорит ничего: имя, `schema`, незаменённый
|
||||
пример, адреса паспорта и `CLAUDE.md`, ключи `rules` и сторож версии OpenSpec —
|
||||
всё это смотрит `openspec.py check` скилла `av-dev:code-openspec`. Плагина
|
||||
конвейера в проекте может не быть; тогда форму не проверяет никто, и это строка
|
||||
доклада.
|
||||
|
||||
**Агентов двое, и разведены они по глубине, а не по охвату.** `doc-consistency`
|
||||
читает только `docs/` и `openspec/`, `doc-code-drift` — весь репозиторий и гоняет
|
||||
читающие команды. Слитый агент делал бы одну половину поверхностной; тот же
|
||||
разрез, что между `task-form` и `task-wording`.
|
||||
|
||||
**Зовутся оба одинаково и одним скиллом — `av-dev:doc-healthcheck`, на весь
|
||||
канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке
|
||||
документации: `doc-consistency` на
|
||||
`opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по
|
||||
определению требует двух, и на большинстве задач синк правит один. Пачка,
|
||||
отбираемая работой, вдобавок не видит того, чего работа не касалась, — а именно
|
||||
там расхождение и живёт: правка отменяет решение в одном документе, парный статус
|
||||
нужен в другом.
|
||||
|
||||
**Перечень фактов, которые `doc-code-drift` сверяет с кодом, закрыт** — имя
|
||||
основной ветки, команды, пути, зависимости поимённо, настройки с числовым
|
||||
значением, единые точки проекта, capability, проверяемые инварианты. «Сверить
|
||||
архитектуру с кодом» задача без дна, и агент, которому её поставили, выдаёт
|
||||
правдоподобную труху вместо находок.
|
||||
|
||||
## `docs/.docs.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"canon": <текущая версия>,
|
||||
"migrations": "internal/store/migrations"
|
||||
}
|
||||
```
|
||||
|
||||
`canon` — версия канона, под которую проект приведён, целым числом: обратной
|
||||
совместимости у канона нет, есть «приведён» и «не приведён». Число подставляет
|
||||
`init`, `adopt` или `upgrade`, и берётся оно из `docs.py version`, а не из
|
||||
образца: литерал в образце протухает на первом же повышении канона.
|
||||
`migrations` — путь каталога миграций, если БД есть; по нему `docs.py` делает
|
||||
сверку с `database.md`.
|
||||
|
||||
**Имя файла — имя плагина, который его завёл.** Канон документов ведёт
|
||||
`av-dev-docs`, поэтому `.docs.json`; у каталога задач по тому же правилу
|
||||
`.tasks.json`, у конвейера — `openspec/config.yaml`. До версии 13 файл звался
|
||||
`.pm.json` — по плагину `av-dev-pm`, который распался на четыре и которого
|
||||
больше нет; имя пережило владельца и указывало в пустоту. Прежнее имя `docs.py`
|
||||
не читает: два дома для одной версии канона расходятся молча, а переименование
|
||||
стоит одну команду (версия 13 журнала, и `check` называет её сам, когда видит
|
||||
старый файл).
|
||||
|
||||
**Ключа `tasks` здесь больше нет.** Настройки каталога задач вернулись в свой
|
||||
файл `<каталог задач>/.tasks.json`, потому что ведёт их другой плагин: конфиг,
|
||||
лежащий в `docs/`, был бы домом, которого нет у проекта, поставившего учёт работ
|
||||
без канона документов. Состав ключей описывает тот плагин, а не канон. Там же —
|
||||
**версия формата задач**, и она своя: у проекта без `docs/` версии канона нет
|
||||
вовсе, сверять её было бы не с чем. Прежний ключ читается, пока живы
|
||||
непереехавшие проекты, и `tasks.py` говорит о нём замечанием на каждом
|
||||
прогоне — версия 8 журнала просит его убрать.
|
||||
|
||||
Ключей будет больше по мере роста проверок; неизвестный ключ `docs.py`
|
||||
игнорирует, отсутствующий — считает «проверка неприменима» и говорит об этом
|
||||
строкой, а не молчит.
|
||||
@@ -0,0 +1,790 @@
|
||||
# Журнал версий канона
|
||||
|
||||
Одна запись на версию. Проект знает свою версию из `docs/.docs.json`; `canon
|
||||
upgrade` идёт по записям снизу вверх от версии проекта до текущей и делает то,
|
||||
что в них названо. Записи ниже версии 13 зовут этот файл прежним именем,
|
||||
`docs/.pm.json`, — так и было на день записи, и переписывать историю мы не
|
||||
станем; переименование делает запись 13.
|
||||
|
||||
**Каталог задач этим журналом не повышается.** У него своя версия формата и свой
|
||||
журнал — `references/changelog.md` скилла `av-dev-tasks:tasks`. Записи 8, 11 и 12
|
||||
трогали его в те времена, когда своего числа у него не было; впредь запись канона
|
||||
вправе позвать соседа, но не двигать его версию.
|
||||
|
||||
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
||||
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
||||
`upgrade`.
|
||||
|
||||
Версия — целое число. Обратной совместимости у канона нет: есть «приведён» и «не
|
||||
приведён».
|
||||
|
||||
---
|
||||
|
||||
## Версия 14 — 2026-08-11
|
||||
|
||||
У ADR стало два законных источника. Прежде запись цитировала только архивный
|
||||
`design.md`, то есть решение, принятое по ходу изменения. Решение, принятое
|
||||
**разведкой** — намеренный отказ, выбор подхода, «проверили и не делаем», — не
|
||||
имеет `design.md` по построению: change по нему не заводится никогда. Триггер
|
||||
канона такое решение ловит («намеренный отказ от очевидного подхода»), а дома у
|
||||
него не было, и оно оседало в записке разведки или в переписке.
|
||||
|
||||
**Что изменилось.** `adr/` принимает второй источник — записку разведки. Правило
|
||||
«промоут, а не второе сочинение» не тронуто: запись по-прежнему цитирует уже
|
||||
написанное и **называет источник**, изменилось только то, что источников два.
|
||||
Следом сказали то же самое: карта домов, разрез проверки `doc-consistency`, вход
|
||||
и устав самого агента, скелеты `docs/adr/README.md` и `docs/adr/template.md`.
|
||||
|
||||
**Почему это версия, а не правка текста.** Два следствия уезжают в репозиторий
|
||||
проекта. По карте домов судит агент согласованности — прежняя редакция читала ADR
|
||||
со ссылкой на записку разведки как нарушение; а скелеты `adr/` лежат в проекте
|
||||
файлами и говорят там от имени канона.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. Ничего с существующими записями: прежние ADR ссылаются на `design.md`, и это
|
||||
по-прежнему верно.
|
||||
2. **Поднять шапку `docs/adr/README.md`**: «промоут поверх архивного `design.md`»
|
||||
→ «промоут поверх уже написанного», с обоими источниками. Точный текст — в
|
||||
[skeletons.md](skeletons.md), раздел `docs/adr/README.md`.
|
||||
3. **Поднять `docs/adr/template.md`**: строка `- **Источник:**` называет два
|
||||
возможных источника.
|
||||
4. `docs/.docs.json`: `"canon": 14`.
|
||||
|
||||
**Чего делать не надо.** Заводить ADR задним числом по старым разведкам. Запись
|
||||
заводится, когда решение принимается, а не когда о нём вспомнили: сочинённое
|
||||
через полгода обоснование — ровно то «второе сочинение», против которого правило
|
||||
и написано.
|
||||
|
||||
---
|
||||
|
||||
## Версия 13 — 2026-08-11
|
||||
|
||||
Служебный файл канона переименован: `docs/.pm.json` → `docs/.docs.json`. Имя
|
||||
досталось от плагина `av-dev-pm`, который распался на четыре и которого больше
|
||||
нет: файл пережил владельца и указывал в пустоту. Правило простое и теперь
|
||||
соблюдается всеми тремя: **имя служебного файла — имя плагина, который его
|
||||
завёл**, `.docs.json` — канон, `.tasks.json` — задачи, `openspec/config.yaml` —
|
||||
конвейер.
|
||||
|
||||
**Что изменилось.** `docs.py` читает только новое имя. Прежнее он не читает
|
||||
намеренно: два дома для одной версии канона расходятся молча, а тут расхождение
|
||||
стоило бы дорого — по этому числу `upgrade` решает, какие записи применять.
|
||||
Файл под старым именем `check` узнаёт и называет отдельной строкой с готовой
|
||||
командой, а не жалуется на пропажу.
|
||||
|
||||
**Что появилось у соседа.** У каталога задач теперь есть **своя версия
|
||||
формата** — ключ `tasks` в `<каталог задач>/.tasks.json`, — и свой журнал версий
|
||||
в скилле `av-dev-tasks:tasks`. До сих пор её не было вовсе: формат задач менялся
|
||||
записями этого журнала (8, 11, 12), хотя каталог принадлежит другому плагину и
|
||||
ставится без канона документов. Канон это число не двигает.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. `git mv docs/.pm.json docs/.docs.json` — одним коммитом с шагом 2. Содержимое
|
||||
не меняется: ключи те же.
|
||||
2. **Поправить упоминания прежнего имени** в своих файлах — `CLAUDE.md`, гейт,
|
||||
`README.md`, `docs/**`. Битой ссылкой это чаще всего не выглядит (файл
|
||||
служебный, на него ссылаются прозой), поэтому `docs.py check` таких упоминаний
|
||||
не ловит: ищи `grep -rn '\.pm\.json'` по репозиторию.
|
||||
3. **Объявить версию формата задач**, если каталог задач в проекте есть:
|
||||
`<каталог задач>/.tasks.json` с ключом `"tasks": <версия>`. Файла нет вовсе —
|
||||
заведи, он теперь обязателен: версия не настройка, от которой можно
|
||||
отказаться. Какое число ставить и что сделать перед этим, говорит журнал
|
||||
владельца — **позови скилл `av-dev-tasks:tasks`**, здесь этих шагов нет
|
||||
намеренно: второй перечень чужих шагов разошёлся бы с первым.
|
||||
4. Гейт не меняется: шаги те же, версию задач сторожит `tasks.py check`, который
|
||||
в нём уже стоит.
|
||||
5. `docs/.docs.json`: `"canon": 13`.
|
||||
|
||||
**Чего делать не надо.** Ключи в файле не трогаются, документы не переезжают,
|
||||
записи задач не меняются: версия 13 — про имена служебных файлов и про то, кто
|
||||
чью версию двигает.
|
||||
|
||||
---
|
||||
|
||||
## Версия 12 — 2026-08-09
|
||||
|
||||
Спринты отменены. Работа идёт задача за задачей, и замороженный набор перестал
|
||||
что-либо удерживать: он отвечал на вопрос «что делать дальше», а между наборами
|
||||
на этот вопрос не отвечал никто.
|
||||
|
||||
**Что изменилось.** Индексов задач два вместо трёх: `SPRINT.md` упразднён.
|
||||
Приоритет стал тем, чем он и является, — **порядком строк в `BACKLOG.md`**:
|
||||
первая строка секции это то, что делают следующим. Назначает порядок человек,
|
||||
машина его не выводит; двигают его `move --after` и `move --first` с причиной.
|
||||
|
||||
Гейт готовности записи стоял на взятии задачи в спринт — единственном месте, где
|
||||
её судили целиком. Момент нужен и без спринта: теперь это команда
|
||||
`tasks.py ready <слаг>`, и зовёт её тот, кто берёт задачу в работу.
|
||||
|
||||
Ритуал между спринтами (`av-dev-tasks:session`) стал скиллом груминга
|
||||
(`av-dev-tasks:groom`): два вопроса — что сейчас самое важное и что перестало
|
||||
быть важным.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. **Вернуть задачи из набора в беклог и снести `SPRINT.md`.** Порядок такой:
|
||||
`git rm tasks/SPRINT.md`, затем `tasks.py check --dir tasks --fix`. Строки
|
||||
набора после удаления файла становятся бездомными, и `--fix` возвращает их в
|
||||
беклог **в конец своей секции** — с пометкой, что позицию назначает человек.
|
||||
Наоборот делать нельзя: `check` без удалённого файла увидит третий индекс и
|
||||
станет ругаться на него, а не чинить.
|
||||
2. **Снять теги `sprint:<слаг>`** с записей — `tasks.py edit <слаг> --rm-tag
|
||||
sprint:<слаг>`. Тег больше никем не читается, а `check` о нём молчит: он
|
||||
законный свободный тег. Пропущенный вреда не сделает, но и пользы не несёт.
|
||||
3. **Расставить порядок** — первый груминг: `av-dev-tasks:groom`. После шага 1
|
||||
очередь состоит из того, что машина поставила в конец, то есть очереди нет
|
||||
вовсе. Пока порядок не назначен, «что делать дальше» по-прежнему без ответа.
|
||||
4. Поправить упоминания спринта в `CLAUDE.md` проекта, если они были: слот
|
||||
«общий станок» переехал в груминг под именем «что считается сломанным»,
|
||||
ориентир «5–8 задач в спринте» стал ориентиром размера порции разбора.
|
||||
5. `docs/.pm.json`: `"canon": 12`.
|
||||
|
||||
**Чего делать не надо.** `REJECTED.md`, `ROADMAP.md` и файлы `items/` не
|
||||
меняются: спринт жил только в собственном индексе и в тегах.
|
||||
|
||||
---
|
||||
|
||||
## Версия 11 — 2026-08-09
|
||||
|
||||
Каталог задач уехал из `docs/` в корень репозитория. Версия 8 отпустила его из
|
||||
канона — перестала требовать, перестала проверять, — но место он занимал всё то
|
||||
же, `docs/tasks/`. Полдела: каталог, принадлежащий одному плагину, лежал внутри
|
||||
дерева, которым владеет другой. Проекту, поставившему учёт работ без канона
|
||||
документов, приходилось заводить `docs/` ради одной вложенной папки.
|
||||
|
||||
**Что изменилось.** Дом задач — `tasks/` в корне репозитория. `tasks.py` ищет его
|
||||
там первым; `docs/tasks/` и `doc/tasks/` остаются в списке поиска для
|
||||
непереехавших проектов, а `init` заводит только в корне. Настройки — там же,
|
||||
`tasks/.tasks.json`.
|
||||
|
||||
**Что осталось терпимым.** `docs.py` по-прежнему не считает `docs/tasks/` файлом
|
||||
вне канона: непереехавший проект не должен получать выдуманную ошибку вдобавок к
|
||||
этой записи, которая и так велит ему переехать.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. `git mv docs/tasks tasks` — одним коммитом вместе с шагом 2, чтобы ссылки не
|
||||
жили битыми между коммитами.
|
||||
2. **Починить относительные ссылки внутри записей.** Файл `tasks/items/x.md`
|
||||
стал на уровень ближе к корню: `../../passport.md` в теле записи теперь
|
||||
`../docs/passport.md`. Тот же сдвиг у ссылок из индексов. Это самая тихая
|
||||
часть переезда: битая относительная ссылка не мешает `tasks.py check`, её
|
||||
ловит только `docs.py check` и только у документов канона.
|
||||
3. Проверить ссылки **на** задачи снаружи: `CLAUDE.md`, `README.md`, гейт,
|
||||
`docs/review.md`. Путь `docs/tasks/...` в них теперь ведёт в никуда.
|
||||
4. Поправить путь в гейте: `tasks.py check --dir tasks`.
|
||||
5. `docs/.pm.json`: `"canon": 11`.
|
||||
|
||||
## Версия 10 — 2026-08-09
|
||||
|
||||
Проверка формы `config.yaml` ушла к тому, кто файл заводит. Версия 9 перенесла в
|
||||
конвейер настройку OpenSpec и честно назвала остаток: форма и сторож версии
|
||||
остались в `docs.py`, то есть у файла было два плагина — один заводит, другой
|
||||
проверяет. Остаток закрыт.
|
||||
|
||||
**Что появилось.** Скрипт `openspec.py` в скилле `av-dev-code:openspec`, две
|
||||
команды: `check --dir <корень>` — форма в проекте, `form` — сверка слепка с живым
|
||||
OpenSpec. Коды выхода те же, что у `docs.py` и `tasks.py`.
|
||||
|
||||
**Что удалено из `docs.py`.** Константы `OPENSPEC_*`, проверка формы, сторож
|
||||
версии и подкоманда `openspec-form` — 252 строки. Скрипт канона про
|
||||
`openspec/config.yaml` не говорит теперь ничего; `openspec/specs/` он по-прежнему
|
||||
знает, потому что это дом темы `requirements` и часть карты тем.
|
||||
|
||||
**Что стало лучше по дороге.** Адреса `docs/passport.md` и `CLAUDE.md` требуются
|
||||
теперь **только к тем документам, которые в проекте есть**. Прежняя проверка
|
||||
требовала их безусловно, то есть на проекте без канона документов требовала
|
||||
битую ссылку. Теперь отсутствие документа — строка «не проверялось» с указанием,
|
||||
что без канона конвейер работает вслепую.
|
||||
|
||||
**Что осталось за каноном.** Один вопрос, и это не форма: не пересказан ли в
|
||||
`context` документ, у которого есть свой дом. Разрез — утверждение, опровергаемое
|
||||
открытием другого файла, против строки «открой такой-то файл»; машине он не
|
||||
виден, судит агент `doc-consistency`, и `config.yaml` у него во входе.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. Заменить в гейте и в скриптах `docs.py openspec-form` на `openspec.py form`.
|
||||
Подкоманды больше нет: прежний вызов упадёт ошибкой употребления (код 2), а не
|
||||
промолчит.
|
||||
2. **Добавить в гейт шаг `openspec.py check`, если проект работает по OpenSpec.**
|
||||
Форму раньше проверял `docs.py check` заодно; теперь он о ней молчит, и без
|
||||
отдельного шага незаменённый пример в `config.yaml` перестанет ловиться. Это
|
||||
главная потеря этого повышения, и она тихая.
|
||||
3. Проект по OpenSpec без установленного `av-dev-code` — форму не проверяет
|
||||
никто. Либо поставить плагин, либо назвать это принятым риском вслух.
|
||||
4. `docs/.pm.json`: `"canon": 10`.
|
||||
|
||||
## Версия 9 — 2026-08-09
|
||||
|
||||
OpenSpec уехал в конвейер. Каталог `openspec/` версией 7 был объявлен слотом
|
||||
канона: `init` его заводил, `adopt` тоже, образец `config.yaml` лежал в скелетах,
|
||||
а отсутствие каталога `docs.py` считал отказом. Разрез был проведён не там. По
|
||||
OpenSpec работает конвейер — без каталога не запускаются ни `opsx:propose`, ни
|
||||
ревью дизайна, ни сверка требований, — а канон документов о нём только
|
||||
высказывался. Проект, которому конвейер не нужен, получал отказ за отсутствие
|
||||
того, чем не пользуется.
|
||||
|
||||
**Что появилось.** Скилл `av-dev-code:openspec`: заводит каталог, заменяет
|
||||
закомментированный пример в `config.yaml` настройкой, объясняет разрез между
|
||||
ссылкой и пересказом. Образец файла переехал туда же — в
|
||||
`references/config-skeleton.md` того скилла.
|
||||
|
||||
**Что изменилось.** `init` и `canon adopt` OpenSpec больше не заводят, а **зовут
|
||||
скилл конвейера**; вызов не разрешился — плагина конвейера нет, и это строка
|
||||
доклада, а не поломка. Отсутствие `openspec/` для `docs.py check` стало
|
||||
неприменимостью вместо отказа: остальные четыре проверки формы идут только при
|
||||
живом каталоге.
|
||||
|
||||
**Что осталось на месте и почему.** Проверка формы `config.yaml` и сторож версии
|
||||
(`docs.py openspec-form`) пока живут в скрипте канона — переносить их значит
|
||||
заводить в конвейере свой скрипт, а этого у него нет ни одного. Разрез названного
|
||||
это не отменяет, но и не завершает: **у файла сейчас два плагина — один заводит,
|
||||
другой проверяет**, и это временное состояние, а не задуманное.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. Ничего не переносить: файлы проекта эта версия не двигает. Меняется только то,
|
||||
кто их заводит.
|
||||
2. Проверить, что плагин `av-dev-code` установлен, если проект работает по
|
||||
OpenSpec. Без него `docs.py check` про каталог промолчит — и молчание это
|
||||
законное, так что отсутствие настройки перестанет ловиться само.
|
||||
3. Проект **не** работает по OpenSpec: убедиться, что `openspec/` нет, и
|
||||
перестать держать его пустым ради проверки. Она больше не требует каталога.
|
||||
4. `docs/.pm.json`: `"canon": 9`.
|
||||
|
||||
## Версия 8 — 2026-08-09
|
||||
|
||||
Канон отпустил каталог задач. Плагин `av-dev-pm` расколот на `av-dev-docs`
|
||||
(документы) и `av-dev-tasks` (учёт работ), и каждый теперь ставится сам по себе.
|
||||
Пока владелец был один, `docs/tasks/` числился слотом канона: `docs.py` требовал
|
||||
каталог, звал внутрь чужой скрипт и выдавал его дрейф за свой, а настройки задач
|
||||
жили ключом `tasks` в `docs/.pm.json`. Для проекта, поставившего только документы,
|
||||
всё это — отказ на ровном месте: задач он не ведёт, и требовать их не за что.
|
||||
|
||||
**Что изменилось.** Каталог задач канону не принадлежит; канон резервирует ему
|
||||
место в `docs/` и внутрь не смотрит. `docs.py` больше не проверяет согласованность
|
||||
задач вовсе — это делает `tasks.py` сам, командой своего плагина. Дом настроек
|
||||
каталога задач — `<каталог задач>/.tasks.json`; ключ `tasks` в `docs/.pm.json`
|
||||
читается, только пока своего файла нет, и об этом говорится замечанием.
|
||||
|
||||
**Что удалено.** Проверка `check_tasks` из `docs.py` и ключ `"tasks"` из скелета
|
||||
`docs/.pm.json`.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. Перенести настройки задач: содержимое ключа `"tasks"` из `docs/.pm.json` — в
|
||||
`docs/tasks/.tasks.json` тем же объектом. Ключа в проекте нет (имена файлов
|
||||
и заголовков умолчательные) — переносить нечего, шаг пропускается.
|
||||
2. Удалить ключ `"tasks"` из `docs/.pm.json` после переноса. Оставленный он не
|
||||
читается, и `tasks.py` скажет об этом замечанием на каждом прогоне.
|
||||
3. Проверить, что согласованность задач по-прежнему кто-то гоняет: раньше её
|
||||
тянул за собой `docs.py check`, теперь — только `tasks.py check`. **Если в
|
||||
гейте проекта стоял один `docs.py`, добавить туда второй шаг** — иначе дрейф
|
||||
индексов перестанет ловиться молча, и это самая вероятная потеря на этом
|
||||
повышении.
|
||||
4. Установить оба плагина, если нужны оба: `av-dev-docs` и `av-dev-tasks`
|
||||
вместо прежнего `av-dev-pm`. Прежний из `enabledPlugins` убрать.
|
||||
5. `docs/.pm.json`: `"canon": 8`.
|
||||
|
||||
## Версия 7 — 2026-08-07
|
||||
|
||||
`openspec/` был предпосылкой, о которой канон говорил, но за которой не следил.
|
||||
Каталог назван в раскладке, `openspec/specs/` объявлен домом темы `requirements`,
|
||||
`config.yaml` описан абзацем — а заводил всё это человек руками, и проверялось
|
||||
из перечисленного ничего. Заведение нового проекта проходило мимо: `init`
|
||||
собирал документы канона и оставлял проект без каталога, без которого не работают
|
||||
ни `opsx:propose`, ни ревью дизайна, ни сверка требований.
|
||||
|
||||
Хуже отсутствия оказался файл из коробки. `openspec init` кладёт `config.yaml`,
|
||||
где `context` и `rules` — закомментированный пример на английском. Такой файл
|
||||
читается как настроенный: он есть, он валиден, имя правильное. Работает он как
|
||||
пустой, и узнаётся это по предложению, написанному на другом языке, с
|
||||
capability по имени пакета и без единого `SHALL`.
|
||||
|
||||
**Что изменилось:**
|
||||
|
||||
1. **`init` заводит OpenSpec сам** — `openspec init --tools claude`, до первого
|
||||
документа канона. Команда названа в каноне поимённо, потому что её печатает
|
||||
отказ `docs.py`.
|
||||
2. **У `openspec/config.yaml` появилась каноническая форма** и скелет в
|
||||
`skeletons.md`. Содержание — только то, что нужно **в момент порождения
|
||||
артефакта**: язык, правила именования capability, придирки валидатора и
|
||||
**адреса** документов канона. Пересказ паспорта, инвариантов, конвенций и
|
||||
правил ревью в него не переносится.
|
||||
3. **`docs.py check` проверяет пять вещей:** каталог `openspec/` есть; файл
|
||||
называется `config.yaml` (`config.yml` OpenSpec читать не станет и об этом не
|
||||
сообщит); `context` и `rules.specs` не остались примером, а правила для
|
||||
`specs` называют `SHALL`; `context` называет `passport` и `CLAUDE.md`; ключи
|
||||
под `rules:` — имена артефактов схемы, а не опечатки.
|
||||
4. **За свежестью формы следит машина, а не память.** Схема и перечень
|
||||
артефактов — слепок чужого инструмента; `check` сравнивает `major.minor`
|
||||
установленного OpenSpec с версией, на которой форма сверялась, и при
|
||||
расхождении даёт замечание. Перепроверяет `docs.py openspec-form`, и чинится
|
||||
расхождение **в плагине, а не в проекте**.
|
||||
5. **Шестое проверяет агент.** Отличить ссылку на документ от пересказа документа
|
||||
машина не умеет — это работа `doc-consistency`, и в таблице «Что проверяет
|
||||
машина, а что человек» она стоит строкой.
|
||||
|
||||
**Что переехало:** ничего в раскладке `docs/`. Ни один файл не переименовывается
|
||||
и не перемещается.
|
||||
|
||||
**Что сделать проекту:**
|
||||
|
||||
1. Нет `openspec/` — завести: `openspec init --tools claude`. Команда кладёт ещё
|
||||
и `.claude/skills/openspec-*` с `.claude/commands/opsx/*`; это её нормальная
|
||||
работа, удалять их не надо.
|
||||
2. Открыть `openspec/config.yaml` и привести к скелету из
|
||||
[skeletons.md](skeletons.md): блок `context` с языком, правилами именования
|
||||
capability, требованием `SHALL` и **адресами** `docs/passport.md` и
|
||||
`CLAUDE.md`; блок `rules` с четырьмя правилами для `specs`.
|
||||
3. **Вычистить из `context` пересказ.** Инварианты, перечень конвенций, состав
|
||||
шагов гейта, правило выбора метки и состав проходов ревью — заменить ссылкой
|
||||
на дом. Признак пересказа простой: строку можно опровергнуть, открыв другой
|
||||
файл проекта.
|
||||
4. Проверить имя файла: `config.yml` переименовать в `config.yaml`. Если жили оба
|
||||
— содержимое `.yml` до сих пор не читалось никем, и переносить из него нужно
|
||||
именно то, чего нет в `.yaml`.
|
||||
5. `docs/.pm.json`: `"canon": 7`.
|
||||
|
||||
---
|
||||
|
||||
## Версия 6 — 2026-08-07
|
||||
|
||||
Версия 5 объявила: **каждый документ `docs/` — тема ревью**. Правило оказалось
|
||||
верным ровно наполовину и потому вредным целиком. Паспорт и схему хранилища
|
||||
ревью читает, но темами они не являются — они задают границу, по которой судит
|
||||
чужая тема. Журнал решений и журнал наблюдений ревью изменения не нужны вовсе:
|
||||
ADR объясняет прошлое решение, а не предъявляет требование к изменению.
|
||||
|
||||
Разметчик, применявший плоское правило буквально, обязан был либо завести
|
||||
фантомные темы `passport`, `adr`, `database`, `research` и продублировать ими
|
||||
работу тем `architecture` и `operations`, либо потерять четыре документа молча —
|
||||
а молчащая потеря и есть то, против чего канон написан.
|
||||
|
||||
**Что изменилось:**
|
||||
|
||||
1. **Три категории документов вместо одной.** Разрез проверяемый: можно ли по
|
||||
документу сказать «в этом изменении сделано не так»? **Тема** — да, прямо
|
||||
(`conventions`, `security`, `architecture`, свои документы проекта).
|
||||
**Источник темы** — нет, но он задаёт границу для чужой темы (`passport.*` →
|
||||
`architecture`, `database.*` → `operations`, `CLAUDE.md` → `autotests`,
|
||||
`openspec/specs/` → `requirements`). **Процессный документ** — нет, он про то,
|
||||
как мы работаем (`tasks/`, `review.*`, `adr.*`, `research.*`, `.pm.json`).
|
||||
2. **Категории `источник` и `процессный` закрыты, категория `тема` открыта.**
|
||||
Прежде открытым был весь список, и «не темы ровно две» противоречило
|
||||
собственной раскладке канона. Теперь пополняется только одно множество, и
|
||||
документ, которого нет в раскладке, — однозначно своя тема проекта.
|
||||
3. **`adr/` и `research/` уходят из входа ревью изменения.** Прогон их больше не
|
||||
открывает. Проверяться они не перестали: ADR без ссылки на архивный
|
||||
`design.md`, замена без парного статуса, число без провенанса — это по-прежнему
|
||||
работа `doc-consistency` и `doc-code-drift`, на сессии между спринтами.
|
||||
4. **`docs.py` печатает категорию в отказе.** «Нет источника passport» читается
|
||||
иначе, чем «нет темы security». Обязательность при этом не изменилась:
|
||||
заводятся все документы одинаково и с первого дня.
|
||||
5. **У задачи появилась метка — `small`, `medium` или `large`.** Это итог
|
||||
классификации и **единственный вход, по которому конвейер выбирает
|
||||
исполнителей** на обеих стадиях ревью. Прежние имена `quick`, `standard` и
|
||||
`wide` описывали глубину прогона, то есть свойство ревью; метка описывает
|
||||
**задачу** — а выбирают по ней одно и то же. Слово «ступень» уходит:
|
||||
у одной вещи одно имя.
|
||||
6. **Метка выводится из двух осей и не равна ни одной из них.** Размер (малое,
|
||||
среднее, крупное) и сложность (знакомое, незнакомое); метка — максимум по
|
||||
ним. Малое **незнакомое** изменение получает `large`, трогая один узел, —
|
||||
поэтому размер и метка пишутся отдельными строками, и выводить одно из
|
||||
другого нельзя.
|
||||
|
||||
**Цена, записанная явно:** расхождение изменения с записанным решением прогоном
|
||||
больше не ловится. Раньше архитектурный проход мог сказать «здесь отменено
|
||||
решение ADR-2026-03-11, парного статуса нет»; теперь это скажет только сверка
|
||||
документации. Сделка сознательная: чтение всего каталога решений оплачивалось на
|
||||
каждой задаче, а срабатывало на единицах.
|
||||
|
||||
**Что переехало:** ничего в раскладке. Ни один файл не переименовывается и не
|
||||
перемещается.
|
||||
|
||||
**Что сделать проекту:**
|
||||
|
||||
1. `docs/review.*`, подраздел «Вопросы по темам»: убрать вопросы, адресованные
|
||||
`passport`, `database`, `adr`, `research` и `review` — **ни одно из этих имён
|
||||
больше не тема**. Под каноном 5 темой был каждый документ `docs/`, поэтому
|
||||
такие вопросы там законны и почти наверняка есть. Переадресовать:
|
||||
про границу домена и про решение → `architecture`; про хранилище, настройку и
|
||||
измеренное число → `operations`. Вопрос, который никуда не переадресовывается,
|
||||
удалить, а не оставить висеть: адресованный несуществующей теме, он не
|
||||
задаётся никем и молча.
|
||||
2. Там же, «Недоступно проверке»: те же пять имён убрать из разнесения по темам,
|
||||
переразнеся содержимое по оставшимся.
|
||||
3. Там же: подраздел **«Триггеры профиля» → «Триггеры метки»**, и разнести его
|
||||
на **три** списка вместо двух — «крупное здесь» (про объём), «незнакомое
|
||||
здесь» (про форму решения) и «мелкое здесь» (опускает до `small`). Раньше
|
||||
первые две оси были склеены в один список, и потому объём в правило по факту
|
||||
не входил.
|
||||
4. **Переименовать метки прогона везде, где проект их называет** — в «Триггерах
|
||||
метки», в «Недоступно проверке», в журнале дефектов: `quick` → **`small`**,
|
||||
`standard` → **`medium`**, `wide` → **`large`**. Метка это итог классификации
|
||||
задачи, и три её значения — часть общего словаря канона и конвейера. Слово
|
||||
«ступень» из документов уходит: у одной вещи одно имя.
|
||||
5. Проверить, что свои темы проекта не совпадают именем с закрытыми категориями:
|
||||
`docs/passport/`, `docs/adr/`, `docs/research/`, `docs/database/`,
|
||||
`docs/review/` — это слоты канона, а не свои темы, и своим смыслом их
|
||||
наполнять нельзя.
|
||||
6. Ничего не заводить и не удалять: раскладка канона 6 совпадает с раскладкой
|
||||
канона 5 файл в файл.
|
||||
7. `docs/.pm.json`: `"canon": 6`.
|
||||
|
||||
---
|
||||
|
||||
## Версия 5 — 2026-08-06
|
||||
|
||||
Канон перестал быть списком файлов и стал **списком тем ревью**. Раскладка та же,
|
||||
но читается иначе: документ в `docs/` — это направление проверки, а не просто
|
||||
текст. Отсюда три правки, и все три развязывают то, что раньше было жёстко
|
||||
сцеплено.
|
||||
|
||||
**Что изменилось:**
|
||||
|
||||
1. **Тема живёт файлом или каталогом, на выбор проекта.** `docs/security.md` и
|
||||
`docs/security/` — одно и то же; тема разрослась, стала каталогом с
|
||||
`README.md` — канон не сменился и версия не двинулась. Прежде форма была
|
||||
задана поимённо: `conventions`, `research` и `adr` обязаны были быть
|
||||
каталогами, остальные — файлами, и обосновать это было нечем. Обе формы сразу
|
||||
— ошибка: два дома для одного факта расходятся молча.
|
||||
2. **Список тем открытый.** Всё, что проект кладёт в `docs/`, становится темой
|
||||
ревью и попадает в план каждого прогона; именной оптики у такой темы нет, её
|
||||
разбирает общий проход конвейера, заведённый ровно за этим.
|
||||
Прежде `docs.py` называл незнакомый файл «вне канона» — теперь называет своей
|
||||
темой проекта и перечисляет их в отчёте. Не темы ровно две: `docs/tasks/` и
|
||||
`docs/review.*`.
|
||||
3. **`AGENTS.md` рядом с `CLAUDE.md` — законно.** Он почти стандарт; обязателен
|
||||
по-прежнему только `CLAUDE.md`, но если лежат оба, читаются оба, и проверки
|
||||
канона смотрят на второй так же, как на первый.
|
||||
|
||||
**Что переехало:**
|
||||
|
||||
- в `docs/review.*`: **«Вопросы к проходам» → «Вопросы по темам»**, форма
|
||||
`<тема>: <вопрос> (<провенанс>)`. Причина не косметическая: вопрос,
|
||||
адресованный проходу, перестал задаваться молча в тот день, когда тот уехал в
|
||||
верхнюю ступень ревью. Тема переезд прохода переживает, имя прохода — нет;
|
||||
- там же **«Недоступно проверке» — по темам**, оба подраздела.
|
||||
|
||||
**Что сделать проекту:**
|
||||
|
||||
1. Ничего не переименовывать, если всё уже разложено по канону 4: обе формы
|
||||
дома законны, и текущая — одна из них.
|
||||
2. `docs/review.*`, подраздел «Вопросы к проходам»: переименовать в «Вопросы по
|
||||
темам» и переадресовать каждый вопрос теме вместо имени прохода. Темы ядра —
|
||||
`requirements`, `autotests`, `conventions`, `architecture`, `security`,
|
||||
`operations`.
|
||||
3. Там же «Недоступно проверке»: разнести обе половины по темам.
|
||||
4. Проверить, не лежит ли в `docs/` документ, который раньше считался лишним и
|
||||
потому не заводился. Теперь он законен и станет темой ревью — это и есть
|
||||
способ добавить проверку, которой в конвейере нет.
|
||||
5. `docs/.pm.json`: `"canon": 5`.
|
||||
6. Позвать судей `doc-consistency` и `doc-code-drift` — шагом 6 `upgrade`.
|
||||
|
||||
## Версия 4 — 2026-08-05
|
||||
|
||||
Две правки, обе про то, как читается каталог задач. Первая — секция роадмапа
|
||||
переименована, и вместе с именем расширен её смысл; достигнутое переехало вниз.
|
||||
Вторая — **у каждой записи появился тип, и тип определяет, что с записью можно
|
||||
делать**. Раскладка не меняется, файлов канона не прибавляется.
|
||||
|
||||
**Что переехало:**
|
||||
|
||||
- секция роадмапа `Разработка` → **`Сопровождение`** (англ. `Tooling` →
|
||||
**`Operations`**). Прежнее имя называло слишком много: роадмап **весь** про
|
||||
разработку, и секция с таким именем не отличалась от остальных ничем;
|
||||
- **тип записи** — из префикса заголовка (`[goal]`/`[idea]`) и тега
|
||||
`kind:<род>` в **поле меты `Тип`** первой строкой. Эмодзи в заголовке от него
|
||||
производна;
|
||||
- **поле места** у задачи: `Секция` → **`Категория`**. У цели остаётся `Секция`:
|
||||
у задачи поле называет полку домена, в которую она вернётся из спринта, у цели
|
||||
— часть роадмапа, то есть состояние очереди. Одно имя на два смысла их и
|
||||
смешивало.
|
||||
|
||||
**Что добавилось:**
|
||||
|
||||
1. **Смысл секции расширен.** Было «инструмент и процесс», стало «чем держат
|
||||
проект: инструмент, процесс, эксплуатация». Метрики, логи, инфраструктура,
|
||||
выкладка и дежурство — сюда же. Расширение не косметическое: английское
|
||||
`Operations` при узком смысле обещало бы эксплуатацию, а внутри лежал бы
|
||||
линтер.
|
||||
2. **Общий словарь трёх мест** — [canon.md](canon.md), раздел «Сопровождение и
|
||||
эксплуатация». Сопровождение — всё, чем держат проект; эксплуатация — его
|
||||
часть, работа системы на проде. `ROADMAP.md`, секция `Сопровождение` — план
|
||||
работ; `architecture.md`, раздел «Эксплуатация» — как устроено сейчас;
|
||||
эксплуатационный проход ревью — оптика проверки. Слить их в одно слово
|
||||
нельзя: они отвечают на разные вопросы. Слово **«поддержка» не употребляется
|
||||
вовсе** — в нём слышится помощь пользователю.
|
||||
3. **Граница с возможностями проходит по тому, кто наблюдает.** «Приложение
|
||||
сообщает о своём состоянии» — возможность приложения, её место среди прочих
|
||||
целей. «Дежурный видит состояние на одном экране» — сопровождение. Одни и те
|
||||
же метрики попадают в разные секции роадмапа, и это верно.
|
||||
4. **Порядок секций стал каноническим**, и `Готово` переехало **вниз**:
|
||||
`Запланировано` | `Направления` | `Сопровождение` | `Готово`. Достигнутое
|
||||
копится — через год этой секции больше, чем всех остальных вместе, — и стоя
|
||||
первой она отодвигает за экран то, ради чего роадмап открывают чаще всего.
|
||||
Порядок проверяет `tasks.py check`, переставляет `check --fix`.
|
||||
5. **Заголовок секции отбивается пустой строкой с обеих сторон.** Прежде
|
||||
проверялась только строка после заголовка; перестановка секций двигает целые
|
||||
блоки, и два заголовка оказываются вплотную. Правит `check --fix`.
|
||||
6. **Тип — единственная ось записи, закрытый словарь из пяти значений:**
|
||||
`goal` | `feature` | `fix` | `chore` | `research`. Осей было две — тип записи
|
||||
(`goal`/`idea`/`task`) и род работы (`kind:` тегом), — но из двенадцати
|
||||
клеток произведения законны были шесть, а алгоритм работы крепится к роду, а
|
||||
не к типу. Оси схлопнуты.
|
||||
7. **Тип задаёт схему тела:** какие разделы обязательны, какие допустимы, нужна
|
||||
ли цель, берётся ли запись в спринт. Проверяет `sprint take`, замечания даёт
|
||||
`check`. Два раздела новые: **`Воспроизведение`** у `fix` (не
|
||||
воспроизводится — это `research`, а не `fix`; правило было записано и не
|
||||
проверялось) и **`Вопрос` + `Куда ляжет ответ`** у `research` вместо
|
||||
критериев приёмки (приёмка разведки — записанный ответ, и критерии в форме
|
||||
«оракул: тест» ей натянуты).
|
||||
8. **Тип `idea` упразднён.** Он значил не род работы, а состояние
|
||||
незаполненности, а состояние типом быть не может. Теперь оно называется
|
||||
честно: `research` без раздела «Вопрос» — **сырьё**. В спринт не берётся, как
|
||||
и прежняя идея, лежит **в конце своей категории** (проверяет `check`,
|
||||
переставляет `--fix`) и отбирается `list --raw`. Порядка «по важности» в
|
||||
беклоге по-прежнему нет: этот порядок производен от типа, а не назначен
|
||||
человеком.
|
||||
9. **Алгоритм работы над каждым типом** — отдельным файлом,
|
||||
`skills/tasks/references/task-<тип>.md`: схема, что проверяет машина, что
|
||||
человек, и порядок шагов.
|
||||
10. **Имена файлов проверяются.** Правило «текст русский, имена английские»
|
||||
стояло в каноне и не было подкреплено ничем: `docs.py` имён не смотрел вовсе.
|
||||
Теперь смотрит — кириллица и не-kebab-case **жёстко**, форма имени
|
||||
`ADR-ГГГГ-ММ-ДД-slug.md` жёстко, транслит **эвристикой**, то есть
|
||||
замечанием. Заодно из раскладки канона убраны плейсхолдеры `<тема>.md`,
|
||||
приглашавшие называть файлы по-русски.
|
||||
11. **Два агента вместо обещания.** В каноне была таблица «Что проверяет машина,
|
||||
а что человек», и её правая колонка три версии описывала судью, которого не
|
||||
существовало. Судьи заведены и разведены по глубине: **`doc-consistency`**
|
||||
(документ ↔ документ ↔ openspec: факт в двух домах, прямое противоречие,
|
||||
поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса,
|
||||
число без провенанса, заглушка вместо честной строки); **`doc-code-drift`**
|
||||
(документ ↔ код по закрытому перечню фактов). Оба зовутся раз в спринт на
|
||||
сессии, а также после adopt и после upgrade, на весь канон разом.
|
||||
|
||||
**Что сделать проекту:**
|
||||
|
||||
1. Переименовать заголовок секции в `docs/tasks/ROADMAP.md`: `## Разработка` →
|
||||
`## Сопровождение` (или `## Tooling` → `## Operations`, если индекс
|
||||
английский). **`check --fix` этого не сделает**: регистр канонической секции
|
||||
он правит сам, а чужую секцию только называет ошибкой — смысл за человеком.
|
||||
2. Поправить поле `- **Секция:**` в файлах целей, которые в ней лежат. Порядок
|
||||
именно такой: сперва заголовок, потом `python3 tasks.py check --dir
|
||||
docs/tasks` покажет расхождение поимённо.
|
||||
3. Перечитать состав секции: цели про выкладку, метрики, логи и инфраструктуру,
|
||||
если они лежали в `Направлениях` за неимением места, переезжают сюда.
|
||||
4. Прогнать `python3 tasks.py check --dir docs/tasks --fix`. За один проход он
|
||||
переставит секции роадмапа в канонический порядок (`Готово` уедет вниз вместе
|
||||
со всем содержимым), поправит отбивку заголовков и **переведёт записи на
|
||||
типы**: перенесёт значение из тега `kind:` и префикса `[goal]`/`[idea]` в поле
|
||||
`Тип`, снимет тег, поставит эмодзи в заголовок, переименует `Секция` →
|
||||
`Категория` у задач и снесёт сырьё в конец категорий.
|
||||
5. Разобрать то, что `--fix` вернул пометкой `НЕОДНОЗНАЧНО`. Главный случай —
|
||||
**записи без типа**: заведённые до появления рода работы, они не несут ни
|
||||
тега, ни префикса, и машина их не угадывает (`feature` от `chore` не
|
||||
отличает). Проставить руками: `edit <слаг> --type …`.
|
||||
6. Дописать новые обязательные разделы у задач, которые собираются в спринт:
|
||||
`Воспроизведение` у каждого `fix`, `Вопрос` и `Куда ляжет ответ` у каждого
|
||||
`research`. Не «заодно по всему беклогу», а порциями переоценки: `check`
|
||||
ошибкой это не считает, отказывает только `sprint take`. Сколько задач готово
|
||||
к взятию, печатает блок здоровья `check`.
|
||||
7. Прогнать `python3 docs.py check`: он назовёт имена файлов не по правилу.
|
||||
Кириллицу и не-kebab-case править обязательно, транслит — по решению
|
||||
человека. **Переименование ADR это перенос ссылок**: слаг стоит в
|
||||
`adr/README.md`, в `architecture.md` и в чужих документах, и делается одним
|
||||
проходом, иначе останутся битые ссылки (их `docs.py` потом и покажет).
|
||||
8. `docs/review.md`, подраздел «Триггеры профиля» — переписать целиком, он
|
||||
отстал дважды. Снести перечень мест для `deep`: профиль упразднён вместе с
|
||||
проходом независимой реализации, и перечень стал указателем в пустоту.
|
||||
Оставшийся перечень перевести на новое правило: `wide` теперь означает не
|
||||
«новое понятие», а **крупное или незнакомое** изменение и рассчитан на 5–10%
|
||||
задач; отдельным списком назвать, что здесь считается **мелким** (это `quick`).
|
||||
Форма подраздела — в [skeletons.md](skeletons.md). Там же проверить журнал
|
||||
дефектов и «Недоступно проверке» на упоминания независимой реализации: класс
|
||||
«форма решения, где спека выбора не сделала» переезжает в подраздел «перестали
|
||||
проверять сознательно», а рядом с ним встаёт вторая честная строка — на
|
||||
`quick` и `standard` не проверяется ничего, что требует запуска.
|
||||
9. `docs/.pm.json`: `"canon": 4`.
|
||||
10. Позвать **обоих судей** — `doc-consistency` и `doc-code-drift`, шагом 6
|
||||
`upgrade`. Пунктов выше десять, половина из них ручная, и именно здесь видно,
|
||||
какие сделаны только наполовину: переименования секций и полей разводят
|
||||
документы, а `check` сверяет число версии, а не существо. Первый прогон на
|
||||
живом проекте вдобавок самый урожайный — правило единственного дома до сих пор
|
||||
никто не проверял. Разбирать порциями, а не одним заходом.
|
||||
|
||||
## Версия 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. **Форма заголовка записи** — по типу: задача отвечает на «что нужно сделать»
|
||||
и пишется глаголом в неопределённой форме («Не отбрасывать молча лишние
|
||||
символы»), цель — на «что приложение будет уметь», идея просто называет, о
|
||||
чём она. `check` считает заголовки не в форме действия и печатает число в
|
||||
блоке здоровья. Годность формулировки — не машине: её смотрит новый агент
|
||||
`task-form` (форма записи, только чтение), а язык текста — `doc-wording`.
|
||||
5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
|
||||
индексах. Написание канонических секций и отбивку правит `check --fix`; он
|
||||
же сводит написание секции в мете файла с заголовком индекса.
|
||||
6. **Язык проектных текстов** — [language.md](language.md), общий дом для
|
||||
документов канона, задач, решений ADR и записок разведки: информационный
|
||||
стиль (глагол вместо отглагольного существительного, активный залог, факт
|
||||
вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и
|
||||
то, что из стиля отброшено намеренно. Проектных файлов не добавляет и
|
||||
раскладку не меняет — это правила письма, а не новый слот.
|
||||
7. **Умолчание профиля ревью сменилось** — это не раскладка, но проектный текст
|
||||
под него уже написан. `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. Переименовать секции роадмапа: `порядок` → `Запланировано`, `темы` →
|
||||
`Направления`; завести `Готово` **первой** и `Разработка` последней
|
||||
(порядок секций поменялся в версии 4 — если едешь сразу на неё, заводи
|
||||
`Готово` последней и не переставляй дважды).
|
||||
Прозаические разделы вроде «Что уже пройдено», которые велись руками,
|
||||
разложить: звенья — строками в `Готово` (дата, слаг, что стало возможно),
|
||||
обоснование очереди оставить прозой в `Запланировано`. Любой `##` в индексе
|
||||
проверка считает секцией, и теперь `check` называет чужую секцию ошибкой.
|
||||
8. Переформулировать цели ответом на **«что приложение будет уметь»**: не
|
||||
«Работа со слиянием», а «Исход слияния не зависит от порядка доставки».
|
||||
Свойство поведения — законная цель. Цель, которая не про приложение
|
||||
(процесс, инструмент), переезжает в `Разработка`.
|
||||
9. `[epic]`, если он в проекте заводился: это либо цель, либо набор задач под
|
||||
общей целью. `check` назовёт его неизвестным типом.
|
||||
10. Прогнать `python3 tasks.py check --dir docs/tasks --fix`: он поднимет
|
||||
написание канонических секций, поставит отбивку после заголовков и сведёт
|
||||
секцию в мете файлов с заголовками индексов. Секции беклога проект
|
||||
переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе.
|
||||
11. Переписать заголовки задач в форму действия — по мере того, как задача
|
||||
попадает в работу, а не «заодно»: `check` печатает их число, а `task-form`
|
||||
предложит формулировки на замену пачкой.
|
||||
12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
|
||||
числом**. Правила языка применяются к тому, что пишется и правится сейчас;
|
||||
сплошная вычитка старых документов стоит дороже, чем даёт.
|
||||
13. `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-code/skills/review/references/review-journal.md` |
|
||||
| правило заведения ADR в `docs/adr/README.md` | [canon.md](canon.md), раздел `adr/` |
|
||||
@@ -0,0 +1,213 @@
|
||||
# Язык проектных текстов
|
||||
|
||||
**Копия.** Дом — `shared/language.md` в репозитории плагинов; язык общий для
|
||||
документов канона и для задач, и потому не принадлежит ни одному плагину.
|
||||
Правится дом, а не этот файл: расхождение ловит `copies.py` на гейте коммита.
|
||||
|
||||
<!-- копия: язык-доктрина из av-dev/shared/language.md -->
|
||||
|
||||
Правила — для всего, что пишется словами: задачи и цели, документы канона,
|
||||
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
||||
сообщений программы пользователю — там свои конвенции проекта.
|
||||
|
||||
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
||||
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком.
|
||||
|
||||
## Зачем он здесь
|
||||
|
||||
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
|
||||
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
|
||||
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
|
||||
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
|
||||
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
||||
а это и есть цена, которой мы избегаем.
|
||||
|
||||
## Что взято сверх правил вычитки
|
||||
|
||||
Эти три требования судит человек, а не проход вычитки: находка по ним требует
|
||||
увидеть текст целиком, а не фразу.
|
||||
|
||||
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
||||
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
||||
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
|
||||
собственный вопрос («что это за система», «как сложено», «почему так решили»).
|
||||
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
||||
исход правки.
|
||||
|
||||
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
||||
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
||||
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
||||
ищет её.
|
||||
|
||||
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
|
||||
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
|
||||
столько, чтобы длинный текст можно было просматривать, а не только читать
|
||||
подряд.
|
||||
|
||||
## Что отброшено намеренно
|
||||
|
||||
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
|
||||
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
|
||||
|
||||
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
|
||||
ломает причинную связь, а в решении и в задаче ценность именно в ней:
|
||||
«поэтому», «иначе», «раз так» несут смысл и остаются.
|
||||
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
|
||||
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
|
||||
вводные, которые не меняют смысл предложения.
|
||||
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
|
||||
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
|
||||
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
|
||||
«дописать позже», и такой текст лучше не публиковать.
|
||||
|
||||
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
|
||||
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
<!-- /копия: язык-доктрина -->
|
||||
|
||||
## Правила
|
||||
|
||||
<!-- копия: язык-правила из av-dev/shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
| чекпоинт | плановый стоп работы, на котором ждут ответа человека. «Остановка» называет любой перерыв, «согласование» — обряд одобрения, а здесь место в процессе, назначенное заранее |
|
||||
| синк | сверка каждого документа канона с только что сделанной работой, с обязательным отрицанием по нетронутым. «Обновление документации» называет исход, а не работу, и молчит о принуждённом отрицании |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство), **опиниативный** (проход с мнением). Каждое
|
||||
было латинизмом или калькой при живом русском слове, и каждое к моменту снятия
|
||||
жило в трёх-шести файлах разом — то есть выглядело словарём, не будучи им.
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- копия: порог-правки из av-dev/shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
@@ -0,0 +1,463 @@
|
||||
# Скелеты документов канона
|
||||
|
||||
Что кладут `init` и `canon adopt` в незаполненный слот. Правило одно:
|
||||
**честная информативная строка вместо заглушки**. Проход читает строку как факт;
|
||||
`<!-- заполнить: … -->` он читает как пробел, и `docs.py check` о таком
|
||||
плейсхолдере напоминает.
|
||||
|
||||
Плейсхолдер ставится только там, где ответ **обязан** быть и его не спросили.
|
||||
Всё, чего в проекте пока просто нет, описывается словами, а не плейсхолдером.
|
||||
|
||||
**Шаблоны — единственное место, где правило канона копируется намеренно.**
|
||||
`adr/README.md` и `review.md` уезжают в репозиторий проекта и обязаны там что-то
|
||||
говорить; определение при этом остаётся в [canon.md](canon.md). Отсюда
|
||||
обязанность: **правка такого правила в каноне тянет запись в
|
||||
[changelog.md](changelog.md)** — и запись называет, какой файл проекта поднимает
|
||||
`upgrade`. Без этого копия в проекте останется на старой версии молча.
|
||||
|
||||
**Каждая такая копия помечена и сверяется машиной.** Дом обрамляется
|
||||
`<!-- дом: <id> -->` … `<!-- /дом: <id> -->`, копия —
|
||||
`<!-- копия: <id> из <путь> -->` … `<!-- /копия: <id> -->`;
|
||||
`scripts/copies.py` маркетплейса требует дословного
|
||||
совпадения. Правишь текст внутри маркеров — правь дом, а не копию.
|
||||
|
||||
**Сама пара маркеров в проект не переносится.** Это машинерия маркетплейса:
|
||||
путь в ней ведёт в дерево плагина, и в репозитории проекта он не разрешится ни
|
||||
во что. Кладя скелет, копируй содержимое между маркерами, а строки
|
||||
`<!-- копия: … -->` и `<!-- /копия: … -->` оставляй здесь.
|
||||
|
||||
## `docs/passport.md`
|
||||
|
||||
```markdown
|
||||
# Паспорт проекта
|
||||
|
||||
Зачем это и для кого. [architecture.md](architecture.md) отвечает «как
|
||||
устроено», [tasks/ROADMAP.md](../tasks/ROADMAP.md) — «в каком порядке», паспорт —
|
||||
«зачем и для кого».
|
||||
|
||||
## Цель
|
||||
|
||||
<!-- заполнить: одна фраза без технических деталей -->
|
||||
|
||||
**Потребители** — список закрытый: он определяет, что считать нужным, а что
|
||||
интересным.
|
||||
|
||||
| Кто | Что ему нужно от нас |
|
||||
| --- | --- |
|
||||
|
||||
Цель достигнута, когда:
|
||||
|
||||
## Что целью не является
|
||||
|
||||
Граница домена. По ней в теме `architecture` судят, не перенесено ли понятие
|
||||
через границу.
|
||||
|
||||
## Типовые сценарии
|
||||
|
||||
## Референсы
|
||||
|
||||
Где смотреть prior art, когда упёрлись.
|
||||
```
|
||||
|
||||
## `docs/architecture.md`
|
||||
|
||||
```markdown
|
||||
# Архитектура
|
||||
|
||||
Обзор: как сложено и где что работает. **Поведение системы здесь не
|
||||
описывается** — его нормативный дом `openspec/specs/`.
|
||||
|
||||
## Принципы
|
||||
|
||||
## Компоненты
|
||||
|
||||
Каждый — строкой со ссылкой на capability, а не пересказом её требований.
|
||||
|
||||
## Внешние границы и форматы
|
||||
|
||||
## Эксплуатация
|
||||
|
||||
- Где работает, что рядом, кто перезапускает:
|
||||
- Внешние зависимости поимённо и чем каждая отказывает (падает, отвечает
|
||||
медленно, молчит, отдаёт мусор):
|
||||
- Кто заметит отказ и когда:
|
||||
- Характер потока (непрерывный, по запросу, по расписанию):
|
||||
|
||||
## Единые точки проекта
|
||||
|
||||
Где генерируются идентификаторы и время; где единственный парсер входного
|
||||
формата; где маппинг доменной ошибки в код ответа; где общий путь приёма.
|
||||
Материал для вопроса «не появился ли второй способ делать то, что уже делается».
|
||||
|
||||
## Деплой
|
||||
|
||||
## Открытые вопросы
|
||||
```
|
||||
|
||||
Пустой проект: «Архитектуры пока нет: кода нет. Наполняется первой задачей.»
|
||||
Нет внешних зависимостей: «Внешних зависимостей нет — смотри на диск и на СУБД.»
|
||||
|
||||
## `docs/database.md`
|
||||
|
||||
```markdown
|
||||
# Схема хранилища
|
||||
|
||||
СУБД, миграции, правило времени и идентификаторов.
|
||||
|
||||
## Таблицы
|
||||
|
||||
## Представление данных
|
||||
|
||||
Чем физически лежит запись и что происходит при чтении и записи.
|
||||
|
||||
## Настройки с числовым значением
|
||||
|
||||
Таймаут занятости, режим журналирования, лимит тела, размер пула, ретеншен.
|
||||
Без них замер не превращается в находку: пик памяти — аномалия только рядом
|
||||
со строкой «запись лежит сжатой и распаковывается целиком».
|
||||
```
|
||||
|
||||
Нет БД — файла нет, и в `docs/.docs.json` нет ключа `migrations`.
|
||||
|
||||
## `docs/security.md`
|
||||
|
||||
```markdown
|
||||
# Модель угроз
|
||||
|
||||
## Периметр
|
||||
|
||||
<!-- заполнить: первой строкой, против кого защищаемся -->
|
||||
|
||||
Контур не развёрнут — назови оба периметра, целевой и сегодняшний, и скажи
|
||||
прямо, против какого строятся находки.
|
||||
|
||||
## Недоверенный вход
|
||||
|
||||
Что приходит извне и каким каналом: тело запроса, файл, аргумент команды,
|
||||
ответ внешней системы, содержимое архива.
|
||||
|
||||
## Из чего строятся пути и ключи
|
||||
|
||||
Раскладка файлов на диске, состав координатного ключа записи, имя каталога.
|
||||
Отсюда строится выход за пределы песочницы.
|
||||
|
||||
## Что разграничивает доступ
|
||||
|
||||
## Что чувствительнее чего
|
||||
|
||||
## Что вне модели
|
||||
|
||||
Перечислить явно. Пустой пункт означает, что в теме `security` угрозу выдумают
|
||||
за тебя, и находка никогда не будет исправлена.
|
||||
```
|
||||
|
||||
## `docs/conventions/README.md`
|
||||
|
||||
```markdown
|
||||
# Конвенции кода
|
||||
|
||||
Как мы пишем код — в отличие от `openspec/specs/`, который описывает, что
|
||||
система делает.
|
||||
|
||||
**Прозой остаётся только то, что не выражается правилом.** Свойство, ставшее
|
||||
правилом линтера, отсюда удаляется и переезжает в перечень ниже.
|
||||
|
||||
## Записи
|
||||
|
||||
## Механизировано
|
||||
|
||||
| Правило | Где механизировано |
|
||||
| --- | --- |
|
||||
|
||||
Не названное здесь место механизации означает, что проход по конвенциям будет
|
||||
добросовестно проверять уже проверенное.
|
||||
```
|
||||
|
||||
Пустой проект: «Конвенций пока нет: код не написан. Наполняется по мере
|
||||
реального трения, а не вперёд.»
|
||||
|
||||
## `docs/research/README.md`
|
||||
|
||||
```markdown
|
||||
# Разведка
|
||||
|
||||
Наблюдения за внешним миром: что реально шлёт источник, чем документация
|
||||
формата расходится с практикой. Источник истины — этот каталог, а не чужая
|
||||
документация.
|
||||
|
||||
**Каждый вывод — с числами и командой, которой получен**, чтобы его можно было
|
||||
перепроверить.
|
||||
|
||||
## Как снималось
|
||||
|
||||
## Записи
|
||||
```
|
||||
|
||||
Нет внешних источников: «Внешних источников данных нет — разведка неприменима.»
|
||||
|
||||
## `docs/adr/README.md`
|
||||
|
||||
```markdown
|
||||
# Журнал решений
|
||||
|
||||
Одна запись — одно решение. **ADR продвигает уже написанное решение, а не
|
||||
сочиняет его заново**: запись цитирует решение и ссылается на источник —
|
||||
`openspec/changes/archive/<id>/design.md`, а у решения, принятого разведкой без
|
||||
изменения, на её записку.
|
||||
|
||||
## Когда заводить
|
||||
|
||||
Верно одно из трёх:
|
||||
|
||||
<!-- копия: adr-когда-заводить из av-dev/skills/doc-canon/references/canon.md -->
|
||||
- **дорогой откат** — переделка стоит дороже переписывания одного файла;
|
||||
- **намеренный отказ** от очевидного подхода;
|
||||
- **пересмотр прежнего решения** — тогда у старой записи обязателен статус
|
||||
«заменено на».
|
||||
<!-- /копия: adr-когда-заводить -->
|
||||
|
||||
Не заводить для рутины и для того, что видно из кода и `git log`.
|
||||
|
||||
## Соглашения
|
||||
|
||||
- Имя файла — `ADR-ГГГГ-ММ-ДД-slug.md`, дата — когда решение реально принято.
|
||||
Слаг **английский по сути, а не транслитом**: `queue-as-table`, не
|
||||
`ochered-tablicej`. Форму имени и слаг проверяет `docs.py check`.
|
||||
- Записи неизменяемы: передумали — новая запись, старой ставится статус.
|
||||
- Активная запись статуса не имеет. Значений два: `заменено на ADR-…` и
|
||||
`устарело`; ставятся полем меты записи — `- **Статус:** …` рядом с датой и
|
||||
источником, а не абзацем в теле.
|
||||
|
||||
## Записи
|
||||
|
||||
Новые сверху.
|
||||
|
||||
| Дата | Запись | Статус |
|
||||
| --- | --- | --- |
|
||||
```
|
||||
|
||||
## `docs/adr/template.md`
|
||||
|
||||
```markdown
|
||||
# Краткий заголовок решения
|
||||
|
||||
- **Дата:** ГГГГ-ММ-ДД
|
||||
- **Источник:** openspec/changes/archive/<id>/design.md — либо записка разведки,
|
||||
если решение принято без изменения
|
||||
|
||||
Статус ставится тем же полем и только при пересмотре:
|
||||
`- **Статус:** заменено на ADR-…` либо `- **Статус:** устарело`.
|
||||
У активной записи поля нет.
|
||||
|
||||
## Решение
|
||||
|
||||
Что именно решено — одной фразой.
|
||||
|
||||
## Почему
|
||||
|
||||
Намерение и причина. Цитата из источника, а не пересказ. Пиши так, чтобы через
|
||||
год было понятно без чтения переписки.
|
||||
|
||||
## Последствия
|
||||
|
||||
- `+` что стало лучше.
|
||||
- `−` чем платим: ограничения, риски, нагрузка на поддержку.
|
||||
```
|
||||
|
||||
## `docs/review.md`
|
||||
|
||||
```markdown
|
||||
# Ревью: настройка и журнал
|
||||
|
||||
## Как настроен конвейер
|
||||
|
||||
### Типовые узлы
|
||||
|
||||
Рода узлов проекта и 3–5 проверяемых свойств к каждому. Рода, а не инвентарь
|
||||
пакетов: род, который проект задумал, но ещё не написал, включать полезно.
|
||||
|
||||
### Типовые ложноположительные
|
||||
|
||||
Находки, которые здесь выглядят убедительно и всегда неверны. Каждая — с одной
|
||||
строкой «почему здесь это не дефект».
|
||||
|
||||
### Вопросы по темам
|
||||
|
||||
Форма: `<тема>: <вопрос> (<провенанс>)`. Главный источник — журнал ниже. Вопрос
|
||||
задаёт тот проход, который закрывает эту тему на текущем прогоне, дополнительно
|
||||
к обязательным.
|
||||
|
||||
**Адресуй теме, а не имени прохода.** Проходы переезжают между метками и
|
||||
упраздняются; вопрос, адресованный проходу, перестанет задаваться в тот день,
|
||||
когда тот уедет в старшую метку, — и заметить это будет нечем. Тема переезд
|
||||
переживает.
|
||||
|
||||
Темы ядра: `requirements`, `autotests`, `conventions`, `architecture`,
|
||||
`security`, `operations`. Плюс любая своя — та, под которую проект завёл в
|
||||
`docs/` **свой** документ. Документы категорий `источник` и `процессный` тем не
|
||||
порождают, и адресовать вопрос `passport`, `database`, `adr`, `research` или
|
||||
`review` нельзя — таких тем нет. Вопрос про границу домена адресуй
|
||||
`architecture`, вопрос про хранилище и числа — `operations`.
|
||||
|
||||
### Триггеры метки
|
||||
|
||||
Проектная конкретизация правила выбора метки. **Списка три: по одному на
|
||||
каждую ось вверх и один вниз** — поимённо, узлами или capability.
|
||||
|
||||
**Крупное здесь** — про объём: что трогает несколько узлов или слоёв, переносит
|
||||
ответственность между ними, перекладывает существующий код в новую форму.
|
||||
|
||||
**Незнакомое здесь** — про форму решения: то, чего в проекте ещё не было и чью
|
||||
форму предстоит нащупать по ходу. Признак простой: перед работой нельзя назвать,
|
||||
какие узлы будут тронуты.
|
||||
|
||||
Любая из двух осей поднимает прогон до `large`, старшей метки: там `security`,
|
||||
`operations` и `architecture` проверяют запуском, и там же единственные замеры.
|
||||
Метка рассчитана на **5–10% задач**; если сюда попадает каждая третья, списки
|
||||
написаны слишком широко.
|
||||
|
||||
**Мелкое здесь** — опускает до `small`. Ориентир по доле — до трети задач, и в
|
||||
любом случае меньше, чем `medium`: перевес `small` значит, что рабочее умолчание
|
||||
сместилось само. Помни отрицательный тест конвейера: что
|
||||
после мерджа не откатывается обратной правкой (миграция, формат на диске,
|
||||
публичный контракт, имя), — не `small`, каким бы маленьким ни был дифф.
|
||||
|
||||
Уточняет умолчания конвейера, не отменяет их; рабочее умолчание — `medium`.
|
||||
|
||||
### Недоступно проверке
|
||||
|
||||
Оба подраздела — **по темам**: «в теме `operations` не проверяется X» читается,
|
||||
а «не проверяется X» через месяц не найдёт ни один проход.
|
||||
|
||||
**Не проверит ни один проход** — принципиальная граница; по факту промаха не
|
||||
пересматривается.
|
||||
|
||||
**Перестали проверять сознательно** — что, когда и почему, со ссылкой на запись
|
||||
журнала. Пересматривается **первым**, как только что-то проскочило.
|
||||
|
||||
Тему, у которой в проекте нет дома, сюда писать не надо: её называет план
|
||||
каждого прогона, и это честнее разовой записи.
|
||||
|
||||
## Журнал дефектов
|
||||
|
||||
Запись на каждый воспроизведённый дефект, сразу, а не ретроспективно: со
|
||||
временем теряется не факт, а то, почему дефект не поймали.
|
||||
|
||||
Форма:
|
||||
|
||||
<!-- копия: журнал-дефектов-форма из av-dev/skills/code-review/references/review-journal.md -->
|
||||
## ГГГГ-ММ-ДД — <краткое последствие> [проскочил|пойман]
|
||||
|
||||
- **Где:** путь:строка либо «конвейер, а не код»
|
||||
- **Симптом:** как обнаружилось, кем и когда
|
||||
- **Причина:** что на самом деле было не так
|
||||
- **Чем воспроизведён:** тест, команда, замер — с числами
|
||||
- **Почему не поймали:** только для проскочивших — какой проход обязан был найти
|
||||
и что ему помешало
|
||||
- **Что меняем:** правило прохода, шаг гейта, конвенция, факт в документе
|
||||
проекта — либо «ничего, цена поимки выше цены дефекта»
|
||||
<!-- /копия: журнал-дефектов-форма -->
|
||||
```
|
||||
|
||||
Пара маркеров `копия:` внутри — машинерия маркетплейса; в `docs/review.md`
|
||||
проекта уезжает только содержимое между ними (см. выше).
|
||||
|
||||
Новый проект: «Дефектов пока не было. Настройка конвейера появится с первым
|
||||
ревью.»
|
||||
|
||||
## `CLAUDE.md`
|
||||
|
||||
Лежит в корне, не в `docs/`. Единственный файл канона, который агент читает
|
||||
**всегда**, поэтому в нём то, без чего нельзя сделать ни шага.
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
Памятка для работы над <проект>. Перед задачей прочитай также
|
||||
[docs/passport.md](docs/passport.md), [docs/architecture.md](docs/architecture.md)
|
||||
и [docs/conventions/](docs/conventions/README.md).
|
||||
|
||||
## Что это
|
||||
|
||||
Абзац: что делает и чего **не** делает.
|
||||
|
||||
## Стек
|
||||
|
||||
## Инварианты
|
||||
|
||||
Что нарушать нельзя. Каждый пункт — три вещи: формулировка **как проверяемое
|
||||
свойство**, а не лозунг; последствие нарушения и его обратимость; **severity**
|
||||
рядом. По этим формулировкам проходы ревью присваивают `critical`, поэтому
|
||||
severity стоит здесь, а не выводится каждым проходом заново.
|
||||
|
||||
## Команды
|
||||
|
||||
## Гейт
|
||||
|
||||
- Команда целиком и как определяется база диффа:
|
||||
- Где логи шагов:
|
||||
- Что означает каждый исход:
|
||||
- **Что красит безусловно и почему:**
|
||||
- Чего в гейте намеренно нет и **кто тогда обязан это гонять:**
|
||||
|
||||
## Запреты
|
||||
|
||||
Что запускать нельзя, **с путями**: рабочая БД, боевой каталог данных, внешние
|
||||
сервисы. Плюс где `testdata` и куда писать временное.
|
||||
|
||||
## Работа
|
||||
|
||||
- **Основная ветка:** <имя>
|
||||
- **Необратимое** (спрашивается у человека всегда):
|
||||
- **Что считается сломанным** — какая красная проверка обгоняет развитие,
|
||||
то есть останавливает текущую работу:
|
||||
- **Ориентир по размеру порции:** своё число, если замерялось
|
||||
- **Что такое «сделана»:** конвейер проекта пройден + критерии приёмки проверены
|
||||
поимённо
|
||||
|
||||
## Язык
|
||||
|
||||
- Документация, комментарии, сообщения коммитов — русский.
|
||||
- Код и идентификаторы — английский.
|
||||
```
|
||||
|
||||
Имя основной ветки, запреты с путями и «что необратимо» — не украшение: без
|
||||
первого падают git-операции батча и расчёт базы диффа, без второго проход может
|
||||
тронуть рабочие данные, без третьего вся шкала ранжирования триажа держится на
|
||||
догадке.
|
||||
|
||||
## `openspec/config.yaml`
|
||||
|
||||
**Образец переехал.** Файл заводит и заполняет плагин конвейера — скилл
|
||||
`av-dev:code-openspec`, — потому что по OpenSpec работает он, а не канон
|
||||
документов. Проект без конвейера каталога `openspec/` не имеет вовсе, и образец
|
||||
файла, которого у него нет, в скелетах канона лежал бы мёртвым грузом.
|
||||
|
||||
**Форму не проверяет и `docs.py`** — с канона 10 он о файле молчит вовсе.
|
||||
Проверяет её тот же владелец: скилл `av-dev:code-openspec`, команда
|
||||
`openspec.py check`. Плагина конвейера в проекте может не быть — тогда форму не
|
||||
смотрит никто, и это строка доклада, а не поломка. Что канон о файле всё же
|
||||
говорит (единственный дом, а не форма) — [canon.md](canon.md), раздел
|
||||
`openspec/config.yaml`.
|
||||
|
||||
## `docs/.docs.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"canon": <текущая версия>
|
||||
}
|
||||
```
|
||||
|
||||
`<текущая версия>` подставляет `init` или `adopt`, целым числом; берётся она из
|
||||
`docs.py version` (строка «канон скрипта»), а не из памяти. Литерал здесь
|
||||
протухает при каждом повышении канона, поэтому его тут и нет: незамещённый
|
||||
плейсхолдер ломает разбор JSON громко, а отставшее число дало бы дрейф молча.
|
||||
|
||||
Плюс `"migrations": "<путь>"`, если есть БД. Ключа `"tasks"` здесь **нет**:
|
||||
настройки каталога задач и версия их формата переехали в свой файл `<каталог
|
||||
задач>/.tasks.json`, потому что ведёт их другой плагин. Состав ключей —
|
||||
[canon.md](canon.md).
|
||||
|
||||
Имя файла — по плагину-владельцу, `av-dev-docs`. До версии 13 он звался
|
||||
`.pm.json`, по распавшемуся `av-dev-pm`; проект с прежним именем `docs.py check`
|
||||
называет отдельной строкой и зовёт переименовать.
|
||||
@@ -0,0 +1,666 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Проверка раскладки документов проекта против канона av-dev.
|
||||
|
||||
Определение канона — references/canon.md рядом со скриптом. Здесь только
|
||||
механизируемая часть: пути, лишние файлы, битые ссылки, версия, плейсхолдеры,
|
||||
маркеры долга и две сверки с кодом. Смысловые дубли и оставшееся в архитектуре
|
||||
поведение судит агент — скрипт об этом говорит вслух в конце отчёта.
|
||||
|
||||
Коды выхода — тот же словарь, что у tasks.py:
|
||||
0 сошлось
|
||||
1 дрейф раскладки (рабочая ситуация, чинится)
|
||||
2 ошибка употребления
|
||||
3 окружение: не тот каталог, битый конфиг
|
||||
4 внутренний сбой
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import NoReturn
|
||||
|
||||
CANON_VERSION = 14
|
||||
|
||||
OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4
|
||||
|
||||
# Дом версии канона и путей, нужных проверкам. Имя — от плагина, который файл
|
||||
# завёл: настройки канона документов ведёт `av-dev-docs`, и файл называется по
|
||||
# нему. Прежнее имя досталось от `av-dev-pm` — плагина, который распался на
|
||||
# четыре и которого больше нет; читать его скрипт не умеет намеренно, потому что
|
||||
# два дома для версии канона расходятся молча, а переименование стоит одну
|
||||
# команду и названо записью 13 журнала.
|
||||
CONFIG = "docs/.docs.json"
|
||||
LEGACY_CONFIG = "docs/.pm.json"
|
||||
|
||||
# --- Раскладка канона -------------------------------------------------------
|
||||
|
||||
# Документ канона: имя → (категория, на какой вопрос отвечает).
|
||||
#
|
||||
# Категории — из canon.md, раздел «Три категории документов». Разрез один: можно
|
||||
# ли по документу сказать «в этом изменении сделано не так»?
|
||||
# тема — да, прямо: документ заводит направление проверки изменения;
|
||||
# источник — нет, но он задаёт границу, по которой судит чужая тема;
|
||||
# процессный — нет: он про то, как мы работаем, а не про изменение.
|
||||
#
|
||||
# **Категория не меняет обязательности документа** — заводятся все три
|
||||
# одинаково и с первого дня. Она меняет только то, что с документом делает
|
||||
# конвейер ревью, и потому печатается в отказе: «нет источника passport»
|
||||
# читается иначе, чем «нет темы security», и чинится теми же руками, но с
|
||||
# другим приоритетом.
|
||||
#
|
||||
# **Документ живёт файлом `docs/<имя>.md` либо каталогом `docs/<имя>/` с
|
||||
# README.md внутри.** Форму выбирает проект: документ разросся — стал каталогом,
|
||||
# и это не смена канона и не повод править скрипт. Обе формы сразу — ошибка: это
|
||||
# два дома для одного факта, ровно то, от чего канон и защищает.
|
||||
DOCS = {
|
||||
"passport": ("источник", "зачем и для кого, чем НЕ является"),
|
||||
"architecture": ("тема", "как сложено — обзор, окружение, эксплуатация"),
|
||||
"security": ("тема", "периметр, недоверенный вход, что вне модели"),
|
||||
"conventions": ("тема", "как мы пишем код; индекс, промоут, что механизировано"),
|
||||
"research": ("процессный", "что показала реальность: наблюдения и числа"),
|
||||
"adr": ("процессный", "почему решено так; индекс, статусы, правило замены"),
|
||||
"review": ("процессный", "настройка конвейера + журнал дефектов"),
|
||||
}
|
||||
|
||||
# Документ, обязательный только при условии: имя → (ключ .docs.json, категория,
|
||||
# пояснение).
|
||||
CONDITIONAL_DOCS = {
|
||||
"database": ("migrations", "источник", "схема хранилища и настройки"),
|
||||
}
|
||||
|
||||
# Обязательные файлы вне раскладки docs/.
|
||||
REQUIRED = {
|
||||
"CLAUDE.md": "памятка агенту: инварианты с severity, команды, семантика гейта",
|
||||
CONFIG: "версия канона и пути, нужные проверкам",
|
||||
}
|
||||
|
||||
# Файлы, которые документ-каталог обязан держать сверх README.md.
|
||||
DOC_EXTRA = {
|
||||
"adr": {"template.md": "шаблон записи ADR"},
|
||||
}
|
||||
|
||||
# Служебное в docs/ и каталог задач, оставшийся там от прежней раскладки. Формы
|
||||
# у них скрипт не проверяет, и по разным причинам: `.docs.json` не markdown, а
|
||||
# задачи **принадлежат другому плагину** — `av-dev-tasks`, со своим скриптом,
|
||||
# своим конфигом и своей версией формата (её сторожит `tasks.py check`).
|
||||
#
|
||||
# Дом задач с версии 11 — `tasks/` в корне репозитория, то есть вне `docs/`
|
||||
# вовсе. `docs/tasks/` здесь терпится потому, что непереехавший проект не должен
|
||||
# получать «файл вне канона» вдобавок к записи журнала, которая и так велит ему
|
||||
# переехать. Внутрь скрипт не смотрит ни в том, ни в другом случае.
|
||||
#
|
||||
# Прежнее имя конфига терпится ровно за тем же: про переименование проект
|
||||
# слышит одну строку — от `check_required`, — а не две, из которых вторая ещё и
|
||||
# зовёт файл лишним.
|
||||
NOT_DOCS = {".docs.json", ".pm.json", "tasks"}
|
||||
|
||||
# Слоты, которых в каноне нет, — с адресом, куда уезжает содержимое. Имена,
|
||||
# совпадающие с темой, отсюда убраны намеренно: `docs/conventions.md` и
|
||||
# `docs/review/` теперь законные формы своих тем.
|
||||
RETIRED = {
|
||||
"review-brief.md": "документы канона и есть бриф; остаток — в review",
|
||||
"review-journal.md": "→ документ review",
|
||||
"plan.md": "→ tasks/ROADMAP.md (плагин av-dev-tasks)",
|
||||
"local-research.md": "→ документ research",
|
||||
"specs": "поведение → openspec/specs/, обзор → тема architecture",
|
||||
"drafts": "идея → запись research, отказ → ADR, порядок → ROADMAP.md",
|
||||
"backlog": "→ tasks/ в корне репозитория (плагин av-dev-tasks)",
|
||||
}
|
||||
|
||||
# --- Слаги в именах файлов --------------------------------------------------
|
||||
|
||||
# Текст документов русский, а **имена файлов английские, kebab-case**. Причина
|
||||
# не в эстетике: имя файла стоит в ссылках из других документов, в коммитах и в
|
||||
# путях, которые люди набирают руками, — а кириллица в пути ломается по-разному
|
||||
# в разных местах и не набирается на английской раскладке.
|
||||
SLUG = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
|
||||
ADR_NAME = re.compile(r"ADR-(\d{4})-(\d{2})-(\d{2})-(.+)")
|
||||
CYRILLIC = re.compile(r"[а-яёА-ЯЁ]")
|
||||
|
||||
# Признаки транслита — и только они. Отличить английское слово от транслита
|
||||
# машина не умеет, поэтому находка идёт **замечанием**: кластеры, которых в
|
||||
# английском практически не бывает, плюс окончания русских падежей.
|
||||
#
|
||||
# Слабые маркеры выброшены намеренно, каждый по своему ложному срабатыванию:
|
||||
# `ost` ловит `post` и `cost`, `sch` — `schema`, `ya` — `yaml`, `nost` —
|
||||
# `nostalgia`, хвост `ii` — `radii`. Набор подобран так, чтобы ложных
|
||||
# срабатываний не было вовсе: правило, краснеющее на правде, приучает
|
||||
# пролистывать весь блок. Цена известна и принята — `sostoyanie-partii`
|
||||
# проходит мимо.
|
||||
#
|
||||
# Тот же приём, что `translit_ish` в tasks.py; скрипты независимы намеренно —
|
||||
# каждый уезжает в чужой проект в одиночку.
|
||||
TRANSLIT_CLUSTER = re.compile(r"zh|kh|shch|tsy|iya|ovanie|enie|stvo")
|
||||
TRANSLIT_TAIL = re.compile(r"(?:ej|oj|ij|yj|yy|aya)$")
|
||||
|
||||
|
||||
def translit_ish(slug: str) -> bool:
|
||||
if TRANSLIT_CLUSTER.search(slug):
|
||||
return True
|
||||
return any(TRANSLIT_TAIL.search(part) for part in slug.split("-"))
|
||||
|
||||
|
||||
def check_slugs(root: Path, rep: Report) -> None:
|
||||
"""Имена файлов канона: латиница kebab-case, у ADR — ещё и форма имени.
|
||||
|
||||
Каталог задач не трогаем: его слаги ведёт и проверяет tasks.py, и вторая
|
||||
проверка того же места разошлась бы с первой.
|
||||
"""
|
||||
docs = root / "docs"
|
||||
if not docs.is_dir():
|
||||
return
|
||||
# Имена, выбранные каноном, а не проектом: их форма задана здесь же.
|
||||
fixed = {"README.md", "template.md"} | {f"{name}.md" for name in DOCS}
|
||||
# Все документы-каталоги, включая свои темы проекта: правило имён общее, а
|
||||
# перечислять их поимённо значило бы закрыть открытый список.
|
||||
for folder in sorted(docs.iterdir()):
|
||||
if not folder.is_dir() or folder.name in NOT_DOCS:
|
||||
continue
|
||||
sub = folder.name
|
||||
for path in sorted(folder.rglob("*.md")):
|
||||
name = path.name
|
||||
rel = path.relative_to(root)
|
||||
if name in fixed:
|
||||
continue
|
||||
stem = path.stem
|
||||
if sub == "adr":
|
||||
m = ADR_NAME.fullmatch(stem)
|
||||
if not m:
|
||||
rep.error(
|
||||
f"{rel}: имя не по форме ADR-ГГГГ-ММ-ДД-slug.md — "
|
||||
f"по имени сортируются записи и ищется дата решения"
|
||||
)
|
||||
continue
|
||||
stem = m.group(4)
|
||||
if CYRILLIC.search(stem):
|
||||
rep.error(
|
||||
f"{rel}: кириллица в имени файла — слаги английские, "
|
||||
f"kebab-case (текст документа при этом русский)"
|
||||
)
|
||||
continue
|
||||
if not SLUG.fullmatch(stem):
|
||||
rep.error(
|
||||
f"{rel}: имя не kebab-case латиницей — только строчные "
|
||||
f"буквы, цифры и одиночные дефисы"
|
||||
)
|
||||
continue
|
||||
if translit_ish(stem):
|
||||
rep.note(
|
||||
f"{rel}: имя похоже на транслит («{stem}») — слаг именуется "
|
||||
f"английским словом по сути, а не записью русского латиницей: "
|
||||
f"транслит нечитаем тому, кто ищет по смыслу. Проверено "
|
||||
f"эвристикой: английское слово от транслита машина не отличает"
|
||||
)
|
||||
check_capability_slugs(root, rep)
|
||||
|
||||
|
||||
def check_capability_slugs(root: Path, rep: Report) -> None:
|
||||
specs = root / "openspec" / "specs"
|
||||
if not specs.is_dir():
|
||||
return
|
||||
for folder in sorted(specs.iterdir()):
|
||||
if not folder.is_dir():
|
||||
continue
|
||||
if CYRILLIC.search(folder.name) or not SLUG.fullmatch(folder.name):
|
||||
rep.error(
|
||||
f"openspec/specs/{folder.name}/: имя capability — латиница "
|
||||
f"kebab-case; оно стоит в ссылках из architecture.md и в спеках"
|
||||
)
|
||||
|
||||
|
||||
DEBT_MARKER = re.compile(r"<!--\s*канон:\s*(.+?)\s*-->")
|
||||
PLACEHOLDER = re.compile(r"<!--\s*заполнить:\s*(.+?)\s*-->")
|
||||
MD_LINK = re.compile(r"\[[^\]]*\]\(\s*<?([^)>\s]+)>?(?:\s+[\"'(][^)]*)?\)")
|
||||
FENCE = re.compile(r"^\s*(```|~~~)")
|
||||
|
||||
|
||||
INLINE_CODE = re.compile(r"`[^`\n]*`")
|
||||
|
||||
|
||||
def strip_code(text: str) -> str:
|
||||
"""Выкинуть блоки кода и вставки в обратных кавычках.
|
||||
|
||||
Путь в примере или в шаблоне — не ссылка, и краснеть на нём значит краснеть
|
||||
на каждом образце документа. Инлайн-код тоже: `[docs/backlog](tasks/…)`
|
||||
в тексте про подписи ссылок — иллюстрация, а не ссылка."""
|
||||
out, inside = [], False
|
||||
for line in text.splitlines():
|
||||
if FENCE.match(line):
|
||||
inside = not inside
|
||||
continue
|
||||
out.append("" if inside else INLINE_CODE.sub("", line))
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
@dataclass
|
||||
class Report:
|
||||
errors: list[str] = field(default_factory=list)
|
||||
notes: list[str] = field(default_factory=list)
|
||||
debts: list[str] = field(default_factory=list)
|
||||
skipped: list[str] = field(default_factory=list)
|
||||
|
||||
def error(self, msg: str) -> None:
|
||||
self.errors.append(msg)
|
||||
|
||||
def note(self, msg: str) -> None:
|
||||
self.notes.append(msg)
|
||||
|
||||
def debt(self, msg: str) -> None:
|
||||
self.debts.append(msg)
|
||||
|
||||
def skip(self, msg: str) -> None:
|
||||
self.skipped.append(msg)
|
||||
|
||||
|
||||
def fail(code: int, msg: str) -> NoReturn:
|
||||
print(f"ОТКАЗ: {msg}", file=sys.stderr)
|
||||
sys.exit(code)
|
||||
|
||||
|
||||
def read_config(root: Path, rep: Report) -> dict:
|
||||
path = root / CONFIG
|
||||
if not path.exists():
|
||||
return {}
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
except json.JSONDecodeError as exc:
|
||||
fail(ENV, f"{CONFIG} не разбирается: {exc}")
|
||||
if not isinstance(data, dict):
|
||||
fail(ENV, f"{CONFIG} должен быть объектом")
|
||||
return data
|
||||
|
||||
|
||||
# --- Проверки ---------------------------------------------------------------
|
||||
|
||||
|
||||
def check_version(root: Path, cfg: dict, rep: Report) -> None:
|
||||
if not (root / CONFIG).exists():
|
||||
return # об отсутствии файла скажет check_required, второй раз не нужно
|
||||
if "canon" not in cfg:
|
||||
rep.error(f"в {CONFIG} нет ключа canon — версия канона не объявлена")
|
||||
return
|
||||
got = cfg["canon"]
|
||||
if not isinstance(got, int):
|
||||
rep.error(f"canon в {CONFIG} должен быть целым числом, а не {got!r}")
|
||||
return
|
||||
if got < CANON_VERSION:
|
||||
rep.error(
|
||||
f"проект приведён к канону версии {got}, текущая — {CANON_VERSION}: "
|
||||
f"нужен canon upgrade"
|
||||
)
|
||||
elif got > CANON_VERSION:
|
||||
rep.error(
|
||||
f"проект приведён к канону версии {got}, а скрипт знает {CANON_VERSION}: "
|
||||
f"устарел плагин, обнови маркетплейс"
|
||||
)
|
||||
|
||||
|
||||
def doc_home(root: Path, name: str) -> tuple[Path | None, str | None]:
|
||||
"""Дом документа: файл `docs/<имя>.md` или каталог `docs/<имя>/`.
|
||||
|
||||
Возвращает путь и жалобу. Обе формы сразу — это два дома для одного факта, и
|
||||
расходятся они молча: правят одну, читают другую.
|
||||
"""
|
||||
docs = root / "docs"
|
||||
as_file = docs / f"{name}.md"
|
||||
as_dir = docs / name
|
||||
if as_file.is_file() and as_dir.is_dir():
|
||||
return as_file, (
|
||||
f"{name} живёт сразу двумя домами — docs/{name}.md и docs/{name}/:"
|
||||
f" оставить один, иначе правят один, а читают другой"
|
||||
)
|
||||
if as_file.is_file():
|
||||
return as_file, None
|
||||
if as_dir.is_dir():
|
||||
if not (as_dir / "README.md").is_file():
|
||||
return as_dir, (
|
||||
f"docs/{name}/ без README.md — у документа-каталога вход"
|
||||
f" обязателен: по нему его читают агенты"
|
||||
)
|
||||
return as_dir, None
|
||||
return None, None
|
||||
|
||||
|
||||
def check_required(root: Path, cfg: dict, rep: Report) -> None:
|
||||
for rel, what in REQUIRED.items():
|
||||
if (root / rel).exists():
|
||||
continue
|
||||
# Файл под прежним именем — это не «нет файла», а незаконченный переезд,
|
||||
# и чинится он одной командой. Без этой ветки проект услышал бы «нет
|
||||
# версии канона» и пошёл заводить второй файл рядом с первым.
|
||||
if rel == CONFIG and (root / LEGACY_CONFIG).exists():
|
||||
rep.error(
|
||||
f"нет {rel} — {what}. Настройки лежат под прежним именем"
|
||||
f" {LEGACY_CONFIG} (от плагина av-dev-pm, которого больше нет):"
|
||||
f" `git mv {LEGACY_CONFIG} {rel}` — журнал канона, версия 13."
|
||||
f" Прежнее имя не читается, поэтому в этом прогоне всё"
|
||||
f" остальное проверено так, будто настроек нет вовсе"
|
||||
)
|
||||
continue
|
||||
rep.error(f"нет {rel} — {what}")
|
||||
|
||||
for name, (kind, what) in DOCS.items():
|
||||
home, complaint = doc_home(root, name)
|
||||
if home is None:
|
||||
rep.error(
|
||||
f"нет документа {name} (docs/{name}.md или docs/{name}/),"
|
||||
f" категория «{kind}» — {what}"
|
||||
)
|
||||
continue
|
||||
if complaint:
|
||||
rep.error(complaint)
|
||||
if home.is_dir():
|
||||
for extra, why in DOC_EXTRA.get(name, {}).items():
|
||||
if not (home / extra).is_file():
|
||||
rep.error(f"нет docs/{name}/{extra} — {why}")
|
||||
|
||||
for name, (key, kind, what) in CONDITIONAL_DOCS.items():
|
||||
home, complaint = doc_home(root, name)
|
||||
if complaint:
|
||||
rep.error(complaint)
|
||||
if key in cfg and home is None:
|
||||
rep.error(
|
||||
f"нет документа {name} (docs/{name}.md или docs/{name}/),"
|
||||
f" категория «{kind}» — {what}"
|
||||
f" (обязателен: в .docs.json объявлен {key})"
|
||||
)
|
||||
elif key not in cfg and home is None:
|
||||
rep.skip(f"{name} — в .docs.json нет ключа {key}, проверка неприменима")
|
||||
|
||||
|
||||
def check_stray(root: Path, rep: Report) -> None:
|
||||
"""Лишнего в docs/ больше нет — есть свои темы проекта.
|
||||
|
||||
Категории `источник` и `процессный` **закрыты**: они перечислены в каноне
|
||||
поимённо и проектом не пополняются. Открыта только категория `тема` —
|
||||
поэтому любой документ в docs/, которого нет в раскладке, и есть заявка на
|
||||
свою тему, и запретить её нельзя. Проверяются только слоты, у которых дом в
|
||||
другом месте, — иначе переехавшее содержимое вернулось бы темой и выглядело
|
||||
законным.
|
||||
"""
|
||||
docs = root / "docs"
|
||||
if not docs.is_dir():
|
||||
rep.error("нет каталога docs/")
|
||||
return
|
||||
known = set(DOCS) | set(CONDITIONAL_DOCS)
|
||||
own: list[str] = []
|
||||
for entry in sorted(docs.iterdir()):
|
||||
name = entry.name
|
||||
if name in RETIRED:
|
||||
rep.error(f"docs/{name} — слота нет в каноне: {RETIRED[name]}")
|
||||
continue
|
||||
if name in NOT_DOCS:
|
||||
continue
|
||||
topic = name[:-3] if entry.is_file() and name.endswith(".md") else name
|
||||
if topic in known:
|
||||
continue
|
||||
if entry.is_file() and not name.endswith(".md"):
|
||||
rep.error(f"docs/{name} — не markdown: тема ревью читается как текст")
|
||||
continue
|
||||
if entry.is_dir() and not (entry / "README.md").is_file():
|
||||
rep.error(
|
||||
f"docs/{name}/ без README.md — у темы-каталога вход обязателен:"
|
||||
f" по нему её читают агенты"
|
||||
)
|
||||
continue
|
||||
own.append(topic)
|
||||
if own:
|
||||
rep.note(
|
||||
f"свои темы проекта: {', '.join(own)} — именной оптики у них нет,"
|
||||
f" их разбирает общий проход конвейера"
|
||||
)
|
||||
|
||||
|
||||
def canon_docs(root: Path) -> list[Path]:
|
||||
"""Документы канона. Каталог задач ведёт tasks.py; упразднённые каталоги
|
||||
уже названы отдельной строкой, и их внутренние ссылки не наша забота —
|
||||
они переезжают целиком."""
|
||||
out = []
|
||||
docs = root / "docs"
|
||||
skip = {"tasks"} | {name for name in RETIRED if not name.endswith(".md")}
|
||||
if docs.is_dir():
|
||||
for path in sorted(docs.rglob("*.md")):
|
||||
head = path.relative_to(docs).parts[0]
|
||||
if head in skip or head in RETIRED:
|
||||
continue
|
||||
out.append(path)
|
||||
# AGENTS.md лежит рядом с CLAUDE.md и читается теми же агентами: он почти
|
||||
# стандарт, и проект вправе держать оба. Обязателен по-прежнему только
|
||||
# первый.
|
||||
for name in ("CLAUDE.md", "AGENTS.md"):
|
||||
path = root / name
|
||||
if path.exists():
|
||||
out.append(path)
|
||||
return out
|
||||
|
||||
|
||||
def check_links(root: Path, rep: Report) -> None:
|
||||
for path in canon_docs(root):
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
except OSError as exc:
|
||||
rep.error(f"{path.relative_to(root)} не читается: {exc}")
|
||||
continue
|
||||
for target in MD_LINK.findall(strip_code(text)):
|
||||
target = target.strip()
|
||||
if not target or target.startswith(("http://", "https://", "#", "mailto:")):
|
||||
continue
|
||||
clean = target.split("#", 1)[0]
|
||||
if not clean:
|
||||
continue
|
||||
if (path.parent / clean).exists():
|
||||
continue
|
||||
rep.error(f"{path.relative_to(root)}: битая ссылка на {target}")
|
||||
|
||||
|
||||
def check_placeholders_and_debt(root: Path, rep: Report) -> None:
|
||||
for path in canon_docs(root):
|
||||
text = strip_code(path.read_text(encoding="utf-8", errors="replace"))
|
||||
rel = path.relative_to(root)
|
||||
for what in PLACEHOLDER.findall(text):
|
||||
# Замечание, а не дрейф: незаполненный канон — объявленное переходное
|
||||
# состояние, и краснеть на нём значит требовать выдумать содержание.
|
||||
rep.note(f"{rel}: плейсхолдер шаблона не заполнен — {what}")
|
||||
for what in DEBT_MARKER.findall(text):
|
||||
rep.debt(f"{rel}: {what}")
|
||||
|
||||
|
||||
def doc_text(root: Path, name: str) -> str | None:
|
||||
"""Текст документа целиком: файл или все markdown каталога, склеенные.
|
||||
|
||||
Проверке всё равно, одним файлом написан документ или десятью: она ищет
|
||||
упоминание, а упоминание живёт в любом из них.
|
||||
"""
|
||||
home, _ = doc_home(root, name)
|
||||
if home is None:
|
||||
return None
|
||||
if home.is_file():
|
||||
return home.read_text(encoding="utf-8", errors="replace")
|
||||
return "\n".join(
|
||||
path.read_text(encoding="utf-8", errors="replace")
|
||||
for path in sorted(home.rglob("*.md"))
|
||||
)
|
||||
|
||||
|
||||
def check_capabilities(root: Path, rep: Report) -> None:
|
||||
specs = root / "openspec" / "specs"
|
||||
text = doc_text(root, "architecture")
|
||||
if not specs.is_dir():
|
||||
rep.skip("openspec/specs/ нет — сверка capability с архитектурой неприменима")
|
||||
return
|
||||
if text is None:
|
||||
rep.skip(
|
||||
"темы architecture нет — capability не сверены с обзором "
|
||||
"(об отсутствии сказано отдельной строкой)"
|
||||
)
|
||||
return
|
||||
for d in sorted(specs.iterdir()):
|
||||
if not d.is_dir():
|
||||
continue
|
||||
name = d.name
|
||||
# Засчитываем только явное упоминание: ссылку на спеку или имя в обратных
|
||||
# кавычках. Голая подстрока совпадает с именем пакета или CLI-команды и
|
||||
# даёт ложное «упомянуто» — то есть проверку, проходящую не по той причине.
|
||||
explicit = f"openspec/specs/{name}" in text or f"`{name}`" in text
|
||||
loose = re.search(rf"\b{re.escape(name)}\b", text) is not None
|
||||
if explicit:
|
||||
continue
|
||||
if loose:
|
||||
rep.note(
|
||||
f"capability {name}: в теме architecture есть слово «{name}», но "
|
||||
f"нет ни ссылки на openspec/specs/{name}, ни имени в обратных "
|
||||
f"кавычках — проверь, это про capability или про пакет"
|
||||
)
|
||||
else:
|
||||
rep.error(
|
||||
f"capability {name} есть в openspec/specs/, но не упомянута в "
|
||||
f"теме architecture — обзор отстал от нормативных спек"
|
||||
)
|
||||
|
||||
|
||||
def changed_files(root: Path, base: str, rep: Report) -> list[str] | None:
|
||||
"""Объединение закоммиченного, рабочего дерева и untracked.
|
||||
|
||||
Гейт гоняют ДО коммита, поэтому `base...HEAD` не видит ровно ту правку, ради
|
||||
которой проверка и заводилась: миграция уже лежит в дереве, но ещё не в
|
||||
истории. Пропущенная правка выглядела бы как зелёный шаг."""
|
||||
cmds = [
|
||||
["diff", "--name-only", base],
|
||||
["ls-files", "--others", "--exclude-standard"],
|
||||
]
|
||||
seen: list[str] = []
|
||||
for cmd in cmds:
|
||||
try:
|
||||
out = subprocess.run(
|
||||
["git", "-C", str(root), *cmd],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=True,
|
||||
)
|
||||
except (subprocess.CalledProcessError, FileNotFoundError) as exc:
|
||||
rep.skip(f"сверка миграций пропущена: git не отдал дифф ({exc})")
|
||||
return None
|
||||
seen.extend(line for line in out.stdout.splitlines() if line)
|
||||
return sorted(set(seen))
|
||||
|
||||
|
||||
def check_migrations(root: Path, cfg: dict, base: str | None, rep: Report) -> None:
|
||||
migrations = cfg.get("migrations")
|
||||
if not migrations:
|
||||
rep.skip("в .docs.json нет ключа migrations — сверка со схемой неприменима")
|
||||
return
|
||||
if not base:
|
||||
rep.skip("база диффа не названа (--base) — сверка миграций со схемой не гонялась")
|
||||
return
|
||||
changed = changed_files(root, base, rep)
|
||||
if changed is None:
|
||||
return
|
||||
touched = [f for f in changed if f.startswith(migrations.rstrip("/") + "/")]
|
||||
if not touched:
|
||||
return
|
||||
# Тема database бывает файлом и каталогом — правкой считается любой её файл.
|
||||
if not any(
|
||||
f == "docs/database.md" or f.startswith("docs/database/") for f in changed
|
||||
):
|
||||
rep.error(
|
||||
f"миграции изменены ({len(touched)} файлов), а тема database — нет: "
|
||||
f"схема в документации отстала"
|
||||
)
|
||||
|
||||
|
||||
# --- Отчёт ------------------------------------------------------------------
|
||||
|
||||
|
||||
def report(rep: Report) -> int:
|
||||
for msg in rep.errors:
|
||||
print(f"ДРЕЙФ {msg}")
|
||||
for msg in rep.notes:
|
||||
print(f"ЗАМЕЧАНИЕ {msg}")
|
||||
if rep.debts:
|
||||
print(f"\nДОЛГ ({len(rep.debts)} маркеров, гейт от них не краснеет):")
|
||||
for msg in rep.debts:
|
||||
print(f" {msg}")
|
||||
if rep.skipped:
|
||||
print("\nНЕ ПРОВЕРЯЛОСЬ:")
|
||||
for msg in rep.skipped:
|
||||
print(f" {msg}")
|
||||
|
||||
print(
|
||||
"\nМашина проверила раскладку, имена файлов, ссылки, версию и две\n"
|
||||
"сверки с кодом. Форму openspec/config.yaml она не проверяет: каталог\n"
|
||||
"принадлежит конвейеру, и форму смотрит его скрипт\n"
|
||||
"(`av-dev:code-openspec`, команда `openspec.py check`). Согласованность\n"
|
||||
"документов между собой и с кодом — тоже не её: это суждение агентов\n"
|
||||
"`doc-consistency` (документ ↔ документ ↔ openspec) и `doc-code-drift`\n"
|
||||
"(документ ↔ код)."
|
||||
)
|
||||
if rep.errors:
|
||||
print(f"\nИтог: дрейф, {len(rep.errors)} пунктов.")
|
||||
return DRIFT
|
||||
print("\nИтог: канон соблюдён в механизируемой части.")
|
||||
return OK
|
||||
|
||||
|
||||
def cmd_check(args: argparse.Namespace) -> int:
|
||||
root = Path(args.dir).resolve()
|
||||
if not root.is_dir():
|
||||
fail(ENV, f"каталог {root} не найден")
|
||||
if not (root / "docs").exists() and not (root / "CLAUDE.md").exists():
|
||||
fail(ENV, f"{root} не похож на корень проекта: нет ни docs/, ни CLAUDE.md")
|
||||
|
||||
rep = Report()
|
||||
cfg = read_config(root, rep)
|
||||
check_version(root, cfg, rep)
|
||||
check_required(root, cfg, rep)
|
||||
check_stray(root, rep)
|
||||
check_slugs(root, rep)
|
||||
check_links(root, rep)
|
||||
check_placeholders_and_debt(root, rep)
|
||||
check_capabilities(root, rep)
|
||||
check_migrations(root, cfg, args.base, rep)
|
||||
return report(rep)
|
||||
|
||||
|
||||
def cmd_version(args: argparse.Namespace) -> int:
|
||||
root = Path(args.dir).resolve()
|
||||
cfg = read_config(root, Report())
|
||||
got = cfg.get("canon", "не объявлена")
|
||||
print(f"канон скрипта: {CANON_VERSION}")
|
||||
print(f"канон проекта: {got}")
|
||||
return OK
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="docs.py",
|
||||
description="механическая проверка канона документов проекта",
|
||||
)
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
|
||||
p_check = sub.add_parser("check", help="раскладка, ссылки, версия, сверки с кодом")
|
||||
p_check.add_argument("--dir", default=".", help="корень проекта (по умолчанию текущий)")
|
||||
p_check.add_argument("--base", default=None, help="база диффа для сверки миграций")
|
||||
p_check.set_defaults(func=cmd_check)
|
||||
|
||||
p_ver = sub.add_parser("version", help="версия канона скрипта и проекта")
|
||||
p_ver.add_argument("--dir", default=".", help="корень проекта")
|
||||
p_ver.set_defaults(func=cmd_version)
|
||||
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
return args.func(args)
|
||||
except SystemExit:
|
||||
raise
|
||||
except Exception as exc: # noqa: BLE001 — последний рубеж, код 4 по словарю
|
||||
print(f"ВНУТРЕННИЙ СБОЙ: {exc}", file=sys.stderr)
|
||||
return INTERNAL
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
name: doc-healthcheck
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию канона проверяет скилл canon, язык документов — агент doc-wording."
|
||||
---
|
||||
|
||||
# Здоровье документации
|
||||
|
||||
Проверяет то, **чего машина не видит**: разошлись ли документы между собой и с
|
||||
кодом. Раскладка, версия, битые ссылки, нетронутые плейсхолдеры — это `canon
|
||||
check` и его скрипт; здесь начинается там, где кончается `docs.py`.
|
||||
|
||||
Разрез проверяемый: **машина сверяет форму, этот скилл — утверждения**. «В
|
||||
`architecture.md` есть раздел» проверит скрипт. «В `architecture.md` написано,
|
||||
что зависимость одна, а в манифесте их три» — суждение, и его выносит агент.
|
||||
|
||||
## Когда звать
|
||||
|
||||
**Зовёт человек**, но признак наблюдаемый, а не календарный:
|
||||
|
||||
- **с прошлой сверки сделан десяток задач.** Документы протухают ровно от
|
||||
сделанной работы: переименованная цель сборки, ушедшая зависимость, второй
|
||||
способ делать то, что обзор объявил единственным, факт, дописанный в
|
||||
`architecture.md` и уже живущий в `CLAUDE.md`;
|
||||
- **вернулись к проекту после перерыва** — прежде чем опираться на написанное;
|
||||
- **перед тем как опереться на документ в решении**, если оно дорогое;
|
||||
- шагом `adopt` и шагом `upgrade` — их зовёт скилл `canon` сам.
|
||||
|
||||
**Не на каждой задаче и не на каждом синке документации.** Цена реальная:
|
||||
`doc-consistency` идёт на `opus`, потому что сличение утверждений — суждение;
|
||||
`doc-code-drift` хоть и на `sonnet`, но читает репозиторий целиком. Прогон по
|
||||
каждой сделанной задаче был бы самой дорогой церемонией процесса, а находок дал
|
||||
бы почти те же: документы расходятся не с одной задачи, а с десятка.
|
||||
|
||||
Прежде оба звались шагом сессии между спринтами. Спринтов нет, и **момент
|
||||
пришлось назвать заново** — иначе их не звал бы никто, кроме разовых `adopt` и
|
||||
`upgrade`, то есть на живом проекте никогда.
|
||||
|
||||
## Обращение к соседним плагинам
|
||||
|
||||
**Копия.** Дом — `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` — конвейер.
|
||||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||||
|
||||
<!-- /копия: граница-плагинов -->
|
||||
|
||||
Здесь сосед один: `av-dev:task-track`, когда находка тянет на задачу. Его нет —
|
||||
находки остаются списком в докладе, и это говорится строкой.
|
||||
|
||||
## Пачка — весь канон, и это не расточительство
|
||||
|
||||
Оба агента зовутся **на весь канон разом**, а не на пачку, отобранную работой.
|
||||
|
||||
Когда пачку отбирала работа, без присмотра оставалось ровно то, чего работа не
|
||||
касалась: правка, отменившая решение, живёт в одном документе, а парный статус
|
||||
нужен в другом; факт, продублированный год назад, не попадёт ни в один диапазон
|
||||
диффа. Канон мал — он читается целиком, и цена этого известна заранее.
|
||||
|
||||
## Кого зовёшь и что передаёшь
|
||||
|
||||
| Агент | Что смотрит | Читает | Модель |
|
||||
| --- | --- | --- | --- |
|
||||
| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` | `opus` |
|
||||
| `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий | `sonnet` |
|
||||
|
||||
**`doc-code-drift` обязан получить раздел запретов `CLAUDE.md`.** Он гоняет
|
||||
команды — только читающие, — и без перечня запретов не знает, чего в этом
|
||||
проекте запускать нельзя. Не передал — он либо остановится, либо тронет то, чего
|
||||
трогать не следовало.
|
||||
|
||||
**Судит не тот, кто писал.** Ни один из двоих ничего не правит: оба возвращают
|
||||
готовые формулировки, подставляешь ты. Самопроверка документа слабее всего ровно
|
||||
там, где формулировка казалась удачной при написании.
|
||||
|
||||
Одного из двух можно позвать отдельно — но **скажи в докладе, кого именно
|
||||
позвал**. Доклад, умолчавший об этом, читается как «сверено целиком».
|
||||
|
||||
## Разбор урожая
|
||||
|
||||
Находки — обычный материал правки, и разбирать их надо **порциями**, а не одним
|
||||
заходом: тридцать находок подряд получают «принято» не потому, что верны, а
|
||||
потому, что разбор затянулся.
|
||||
|
||||
По каждой находке ровно три исхода:
|
||||
|
||||
1. **Строка на замену** — правь документ сразу. Формулировка уже готова, спорить
|
||||
не с чем, и откладывание превращает её в задачу дороже самой правки.
|
||||
2. **Работа больше чем на абзац** — задача типа `chore`. Заводит её **не этот
|
||||
скилл**: вызови Skill `av-dev:task-track`, у него свой формат, дедупликация
|
||||
против беклога и кладбища. Плагина нет — отдай списком в докладе и скажи это
|
||||
строкой.
|
||||
3. **Не находка** — агент ошибся, документ прав. Скажи это прямо: неразобранная
|
||||
находка и отклонённая различаются, и вторая экономит время на следующем
|
||||
прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел
|
||||
настройки, — там дом типовых ложноположительных.
|
||||
|
||||
## Доклад
|
||||
|
||||
- **Кого позвал** — обоих или одного, и почему одного.
|
||||
- Находки по каждому агенту: сколько, что поправлено сразу, что стало задачей
|
||||
(со слагами), что отклонено и почему.
|
||||
- **Границы покрытия**: что смотрели и чего не смотрели. У `doc-code-drift` она
|
||||
идёт из его собственного отчёта — перечень фактов у него закрытый, и он
|
||||
называет, какие из них проверить было нечем.
|
||||
- Канона в проекте нет вовсе — это исход, а не пустой прогон: скажи строкой и
|
||||
предложи `av-dev:doc-canon`.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина.
|
||||
- **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это
|
||||
агент `doc-wording`, и зовут его отдельно, по пачке правленных документов.
|
||||
Звонящие у него названные — последний шаг синка в `av-dev:doc-sync`, шаг 9
|
||||
`av-dev:doc-init` и шаг вычитки в обоих режимах `canon`, — просто ни один из
|
||||
них не здесь. У него другой ритм: он нужен там, где текст только что писали, а
|
||||
не там, где он год лежал. Оркестровать его нечем — он один и работает по
|
||||
названному списку.
|
||||
- **Не правит документы за агентов** — они возвращают формулировки, решение
|
||||
подставить принимает человек или ты по его правилу.
|
||||
- **Не заводит задачи** — этим владеет `av-dev:task-track`.
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
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`. Признак: в
|
||||
репозитории уже есть документация или беклог в какой-то раскладке.
|
||||
- **Не решает за человека**, что важно: цель, границы и периметр — его ответы.
|
||||
@@ -0,0 +1,220 @@
|
||||
---
|
||||
name: doc-sync
|
||||
description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл canon.
|
||||
---
|
||||
|
||||
# Ведение содержимого канона
|
||||
|
||||
Скилл владеет **содержимым** документов канона; раскладкой владеет `canon`.
|
||||
Определение канона и роли документов — [канон](../canon/references/canon.md),
|
||||
здесь не пересказывается.
|
||||
|
||||
Главный вызывающий — **шаг синка документации в конвейере задачи**. Конвейер
|
||||
живёт в другом плагине и зовёт этот скилл по имени; проект без конвейера ведёт
|
||||
документацию тем же скиллом вручную.
|
||||
|
||||
## Правило, из которого всё следует
|
||||
|
||||
**Принуждённое отрицание.** Синк обязан назвать **каждый** документ канона: либо
|
||||
чем он обновлён, либо «не требуется, потому что…». Нетронутые группируются одной
|
||||
строкой с общей причиной.
|
||||
|
||||
Причина, по которой правило именно такое, измерена: у ADR был список триггеров
|
||||
прозой — и он дал **6 записей на 43 изменения**. Прозаический триггер, который
|
||||
некому проверить, не срабатывает. Отличить «не написал» от «написал, что не
|
||||
требуется» можно только тогда, когда отрицание обязательно.
|
||||
|
||||
Это тот же приём, что «границы покрытия» в отчёте ревью и «пустое называется
|
||||
пустым» в каноне.
|
||||
|
||||
## Чек-лист синка
|
||||
|
||||
Идёт сверху вниз; каждая строка попадает в доклад.
|
||||
|
||||
| Документ | Обновляется, когда | Проверка |
|
||||
| --- | --- | --- |
|
||||
| `openspec/specs/` | всегда при изменении поведения | вливает `opsx:archive` |
|
||||
| `database.md` | тронуты миграции | `docs.py check --base` |
|
||||
| `architecture.md` | новый компонент, граница, внешняя зависимость, изменилось окружение | `docs.py`: capability без упоминания |
|
||||
| `adr/` | дорогой откат, намеренный отказ, пересмотр прежнего | нет — только этот чек-лист |
|
||||
| `research/` | узнали новое о внешнем формате или данных | нет |
|
||||
| `security.md` | новый недоверенный вход, токен, путь наружу, сдвиг периметра | нет |
|
||||
| `conventions/` | находка принята и не специфична для одного места | промоут |
|
||||
| `review.md` | дефект воспроизведён; сузили или расширили проверку | нет |
|
||||
| `passport.md` | новый потребитель, сдвиг границы «чем не является» | нет |
|
||||
| `CLAUDE.md` | изменился инвариант, гейт, запрет, необратимое | нет |
|
||||
|
||||
Пример доклада:
|
||||
|
||||
```
|
||||
Синк документации:
|
||||
- architecture.md — добавлен воркер свёртки, ссылка на capability reindex
|
||||
- database.md — миграция 00006, таблица bucket
|
||||
- adr/ — заведён ADR-2026-08-03-queue-as-table: отказ от внешней очереди
|
||||
- research/ — новое о формате не узнано
|
||||
- passport, security, conventions, review — не требуется: изменение внутреннее
|
||||
```
|
||||
|
||||
## Сверка — не здесь, а в `av-dev:doc-healthcheck`
|
||||
|
||||
Синк правит документы поодиночке, а расходятся они **между собой**: факт,
|
||||
дописанный в `architecture.md`, уже живёт в `CLAUDE.md`; периметр в
|
||||
`security.md` не знает про новый эндпоинт. Поймать это на своей же правке нельзя,
|
||||
и судит это агент `doc-consistency`.
|
||||
|
||||
**Но синк его не зовёт.** Обоими судьями документов владеет скилл
|
||||
`av-dev:doc-healthcheck`, и зовут их на весь канон разом, а не на пачку,
|
||||
отобранную работой. Причина в цене: `doc-consistency` на `opus` по каждой
|
||||
сделанной задаче — самая дорогая церемония процесса, а `doc-code-drift` хоть и на
|
||||
`sonnet`, но читает репозиторий целиком. К тому же расхождение между двумя
|
||||
документами по определению требует двух документов, а на большинстве задач синк
|
||||
правит один.
|
||||
|
||||
Что теряется: привязка находки к задаче, которая её породила. Что выигрывается,
|
||||
кроме денег: синк перестаёт отбирать пачку, и в неё попадают документы,
|
||||
которых работа не касалась, — расхождение, внесённое правкой в одном месте, там
|
||||
и живёт.
|
||||
|
||||
## Вычитка — наоборот, здесь
|
||||
|
||||
**Язык правленого вычитывается тем же прогоном, который его написал, и зовёшь
|
||||
агента `doc-wording` ты.** Довод обратный доводу про судей: он читает **только
|
||||
названную пачку**, стоит дёшево и ищет ровно то, что портится в момент письма, —
|
||||
залог, оценку без факта, жаргон, термин без ввода. Ждать `healthcheck` здесь
|
||||
нечего: через месяц никто уже не помнит, какую фразу имел в виду автор.
|
||||
|
||||
Позови его **последним шагом правки, до коммита**, отдав список файлов, которых
|
||||
она коснулась, — и назови этот список в промпте: по нему же он судит, известен ли
|
||||
термин. Находки он отдаёт готовыми формулировками, подставляешь их ты.
|
||||
|
||||
**Условие вызова — правка, а не синк.** Синк самый частый вызывающий, но не
|
||||
единственный: разведка (`av-dev:code-resolve`, сценарий разведки) пишет ответ по
|
||||
одному адресу и синком себя не считает намеренно — вычитка ей нужна ровно та же.
|
||||
Признак один и читается буквально: **документы правились — зови, ничего не правил
|
||||
— не зови**.
|
||||
|
||||
## ADR — промоут, а не второе сочинение
|
||||
|
||||
Обоснование уже написано: `opsx:propose` кладёт `design.md` в каждый change, и
|
||||
после архивации он лежит в `openspec/changes/archive/<id>/design.md` с разделами
|
||||
`Context` / `Goals / Non-Goals` / `Decisions` / `Risks / Trade-offs`.
|
||||
|
||||
**ADR цитирует решение оттуда и ссылается на источник.** Не пересказывает и не
|
||||
сочиняет заново.
|
||||
|
||||
**Второй законный источник — записка разведки**, и приходит он от скилла
|
||||
`av-dev:code-resolve`, сценарий разведки: решение, принятое разведкой (намеренный отказ, выбор
|
||||
подхода, «проверили и не делаем»), `design.md` не имеет по построению — change по
|
||||
нему не будет никогда. Промоут при этом тот же: цитата и ссылка, но на записку.
|
||||
Перечень источников закрыт и живёт в [каноне](../canon/references/canon.md),
|
||||
раздел `adr/`.
|
||||
|
||||
**Триггер заведения, форма имени и правило замены — в
|
||||
[каноне](../canon/references/canon.md), раздел `adr/`.** Здесь они не
|
||||
повторяются: копия правила расходится с оригиналом на первой же смене версии
|
||||
канона, а расходится незаметно.
|
||||
|
||||
Твоя часть — **применить триггер к этой задаче и сказать вслух, сработал он или
|
||||
нет**. Строка «adr/ — не требуется: решение рутинное» и есть то, ради чего
|
||||
чек-лист существует; её отсутствие неотличимо от «забыл посмотреть».
|
||||
|
||||
Порядок работы: открой источник — архивный `design.md` change либо записку
|
||||
разведки, — найди в нём решение, проходящее триггер, процитируй его и причину,
|
||||
сошлись на источник, добавь строку в индекс `docs/adr/README.md` сверху.
|
||||
|
||||
## Чистка `architecture.md`
|
||||
|
||||
Обзор не держит поведение — его нормативный дом `openspec/specs/`. **Форма
|
||||
маркера долга и правило «гейт от них не краснеет» — в
|
||||
[каноне](../canon/references/canon.md), раздел `architecture.md`.**
|
||||
|
||||
Разбирается порциями: раздел вычищает та задача, которая его касается.
|
||||
Содержимое не выбрасывается, а переезжает — требования в дельта-спеку change,
|
||||
обоснование в ADR, обзор остаётся строкой со ссылкой на capability.
|
||||
|
||||
## Запись в `research/`
|
||||
|
||||
Наблюдение о внешнем мире: что реально шлёт источник, чем документация формата
|
||||
расходится с практикой. **Требование провенанса и правило про расходящееся
|
||||
число — в [каноне](../canon/references/canon.md), раздел `research/`.**
|
||||
|
||||
Твоя часть — заметить, что по ходу задачи узналось новое о внешних данных, и не
|
||||
дать этому остаться в контексте. Признак: ты правил разбор, опираясь на то, чего
|
||||
нет ни в одном документе.
|
||||
|
||||
## Обращение к соседним плагинам
|
||||
|
||||
Два раздела ниже — запись в `review.md` и промоут в конвенции — берут форму у
|
||||
конвейера ревью: она принадлежит ему, а не канону. Берут **вызовом скилла**, а не
|
||||
чтением файла по пути.
|
||||
|
||||
**Копия.** Дом правила — `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` — конвейер.
|
||||
Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего
|
||||
формата: у канона документов и у каталога задач они свои и двигаются порознь.
|
||||
|
||||
<!-- /копия: граница-плагинов -->
|
||||
|
||||
Чем оборачивается отсутствие конвейера — в каждом из двух разделов отдельно: без
|
||||
него работа не отменяется, отменяется только его процедура.
|
||||
|
||||
## Запись в `review.md`
|
||||
|
||||
Файл держит два раздела с разными сроками жизни — журнал дефектов и настройку
|
||||
конвейера. **Что в каком и в какой форме — в
|
||||
[каноне](../canon/references/canon.md), раздел `review.md`**; подробности формы
|
||||
записи и выбор адреса, куда она ведёт, — у конвейера ревью проекта (при
|
||||
`av-dev-code` — `Skill av-dev:code-review`, его
|
||||
`references/review-journal.md`). **Конвейера в проекте нет** — пиши по форме из
|
||||
скелета `review.md`, которую положил канон, и скажи в докладе, что подробностей
|
||||
формы взять негде.
|
||||
|
||||
Твоя часть на синке: **дефект пишется сразу**, а не «потом, когда починим».
|
||||
Со временем теряется не факт, а то, почему дефект не поймали, — единственное,
|
||||
ради чего журнал есть. И решение сузить проверки (перестали звать проход, понизили
|
||||
метку) обязано попасть в раздел настройки, а не остаться в отчёте ревью.
|
||||
|
||||
## Промоут в конвенции
|
||||
|
||||
Находка → конвенция → правило линтера → **удаление из прозы**. Процедура целиком
|
||||
принадлежит конвейеру ревью проекта (при `av-dev-code` — его
|
||||
`references/promote.md`, читается через `Skill av-dev:code-review`);
|
||||
роль каталога конвенций — в [каноне](../canon/references/canon.md). **Конвейера
|
||||
нет** — три шага всё равно твои, просто без его процедуры: сформулируй правило,
|
||||
поищи, чем оно механизируется, и вычеркни прозу, если механизировалось.
|
||||
|
||||
Твоя часть — **третий шаг, который пропускают чаще всего**: правило заработало,
|
||||
а формулировка осталась в прозе, и проход продолжает проверять уже проверенное.
|
||||
На синке это отдельная строка: «conventions/ — правило X механизировано,
|
||||
формулировка удалена» либо «не требуется».
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не проверяет раскладку** — это `canon`.
|
||||
- **Не заводит недостающие документы** — их скелет кладёт `canon adopt` или
|
||||
`init`.
|
||||
- **Не сочиняет содержание.** Нечего записать — так и пишется, честной строкой.
|
||||
- **Не переоформляет документы «заодно»**: правится то, чего коснулась работа.
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
name: task-groom
|
||||
description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл tasks; выполнение задачи — конвейер проекта."
|
||||
---
|
||||
|
||||
# Груминг: что важно, что перестало
|
||||
|
||||
Скилл отвечает на **два вопроса**, и всё, что не служит им, — не его работа:
|
||||
|
||||
1. **Что сейчас самое важное?**
|
||||
2. **Что перестало быть важным?**
|
||||
|
||||
Ответ на оба **записывается порядком строк в беклоге**: первая строка секции —
|
||||
то, что делают следующим; то, что перестало быть важным, из беклога уходит с
|
||||
причиной. Приоритет — свойство очереди, а не задачи, и живёт он в индексе
|
||||
(правило 4 скилла `tasks`). Груминг — единственное место, где очередь
|
||||
назначается человеком.
|
||||
|
||||
**Скилл интерактивный.** Он не «приводит беклог в порядок» сам: суждение о
|
||||
важности принадлежит человеку, и весь ход — это подготовленные развилки с
|
||||
рекомендацией. Что решается фактом (сделано, отменено, дублируется), решается
|
||||
без вопросов и показывается списком.
|
||||
|
||||
Форматом и содержимым записей владеет скилл `tasks` — груминг зовёт его
|
||||
операции, а не правит файлы руками. Выполнением задачи — конвейер проекта.
|
||||
|
||||
## Три правила, из которых всё следует
|
||||
|
||||
1. **Порядок назначает человек, машина его не выводит.** Ни давность, ни тип, ни
|
||||
число задач под целью приоритетом не являются. Единственное место в очереди,
|
||||
назначенное не человеком, — конец секции у сырья, и оно из очереди изъято
|
||||
(`tasks`, правило 4).
|
||||
2. **Порция важнее охвата.** Тридцать задач за заход — это усталость и
|
||||
штамповка: последние десять получат «оставить» не потому, что живы, а потому,
|
||||
что разбор затянулся. Лучше две честные порции, чем один полный проход.
|
||||
3. **Причина уезжает в запись.** Всё, что решено здесь, оставляет след:
|
||||
`--reason` у закрытия и переноса, ответ в теле задачи, строка в докладе.
|
||||
Решение, оставшееся в переписке, будет принято заново через месяц.
|
||||
|
||||
## Когда груминг созрел
|
||||
|
||||
**Зовёт человек.** Скилл сам себя не назначает, но обязан **напоминать**, и
|
||||
признак наблюдаемый, а не календарный:
|
||||
|
||||
- в беклоге появились записи, которых человек ещё не видел (заведены интейком по
|
||||
ходу работы, урожаем ревью, разбором находок);
|
||||
- на верхних строках очереди есть задача с открытым вопросом — очередь
|
||||
показывает то, что взять нельзя;
|
||||
- `tasks.py check` печатает «готово к взятию: 0 из N» — брать сегодня нечего.
|
||||
|
||||
Порога в неделях нет намеренно: счётчик простоя пришлось бы вести руками, а
|
||||
решает всё равно человек. Признак — **очередь перестала быть твоей**: взялся
|
||||
перечитывать, почему эти задачи стоят в таком порядке, — пора.
|
||||
|
||||
## Вопрос, блокер, необратимое
|
||||
|
||||
| | Что это | Когда спрашиваем | Что останавливает |
|
||||
| --- | --- | --- | --- |
|
||||
| **Вопрос** | решение человека | на груминге, пачкой | взятие задачи в работу |
|
||||
| **Блокер** | работа не может продолжаться ни одной задачей | немедленно | всё |
|
||||
|
||||
Право на **необратимое** — третье и отдельное: что именно необратимо, называет
|
||||
`CLAUDE.md` проекта, и спрашивается оно всегда, независимо от того, когда был
|
||||
последний груминг.
|
||||
|
||||
**Блокер определяется исходом, а не одновременностью.** Встали разом или
|
||||
задачи выпадали по одной — если продолжать нечем, это блокер, и человек
|
||||
спрашивается немедленно, а не ждёт ближайшего груминга.
|
||||
|
||||
**Отличать вопрос от застревания.** Правило про остаток принадлежит управлению
|
||||
задачами: оно решает, **сделана задача или вышла**, а это исход планирования, не
|
||||
исполнения. **Ниже канонический текст; конвейер проекта на него ссылается, а не
|
||||
пересказывает** — два экземпляра одного правила разъезжаются, и разъезжаются
|
||||
незаметно, потому что расхождение видно только на редком входе.
|
||||
|
||||
> Есть остаток, который доводится без ответа, — задача продолжается, вопрос
|
||||
> записывается в файл. Остатка нет — задача возвращается в беклог.
|
||||
|
||||
С двумя оговорками, без которых тест ошибается:
|
||||
|
||||
> **Остаток, который материализует нерешённое** — записывает в хранилище,
|
||||
> журнал, витрину **или наружу** состояние, зависящее от неотвеченного вопроса,
|
||||
> — **не остаток**. Решение поднимается до начала записи: откатить запись
|
||||
> дороже, чем подождать ответ, а иногда невозможно. «Наружу» — часть правила, а
|
||||
> не пример: выкладка, публикация и отправка данных третьей стороне не
|
||||
> откатываются тем более.
|
||||
|
||||
> **Пол для остатка:** остаток, из которого пропала польза, названная в «зачем», —
|
||||
> это не сделанная задача, а вернувшаяся в беклог.
|
||||
|
||||
## Ход груминга
|
||||
|
||||
Четыре шага, и порядок — зависимость, а не список.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
check["tasks.py check (+ --fix)<br/>результат — строкой в доклад"]
|
||||
s1["1. Осмотреться<br/>что накопилось, чего человек ещё не видел"]
|
||||
s2["2. Разобрать вопросы<br/>пачкой, не больше трёх за раз"]
|
||||
s3["3. Что перестало быть важным<br/>порциями по 5–8"]
|
||||
s4["4. Что важно сейчас<br/>расставить порядок строк"]
|
||||
|
||||
check --> s1 --> s2 --> s3 --> s4
|
||||
s2 -->|"неотвеченный вопрос → судим о важности вслепую"| s4
|
||||
s3 -->|"без переоценки очередь строится из протухшего"| s4
|
||||
```
|
||||
|
||||
Схема — **сводка**: процедура каждого шага в
|
||||
[references/portions.md](references/portions.md), и при расхождении прав текст.
|
||||
|
||||
**1. Осмотреться.** `tasks.py check` (при дрейфе — `--fix`), затем показать
|
||||
человеку текущую очередь: верхние строки каждой секции и что появилось с
|
||||
прошлого раза. Это половина ответа на «что важно»: очередь, которую не видели,
|
||||
обсуждать бессмысленно.
|
||||
|
||||
**2. Разобрать вопросы.** Вопрос — решение человека, и разбирается он **пачкой**,
|
||||
а не по одному, как только возник: по одному это дёрганье, пачкой это груминг.
|
||||
Вопрос на верхних строках очереди разбирается **вне очереди порции**: иначе
|
||||
правило «задача с открытым вопросом в работу не берётся» создаёт стимул вопрос
|
||||
не записывать, лишь бы не вычеркнуть задачу из ближайшей работы.
|
||||
|
||||
**3. Что перестало быть важным.** Порциями по 5–8. Сперва то, что решается
|
||||
фактом и не требует ничьего суждения (сделано попутно, отменено решением,
|
||||
дублируется, симптомы одного дефекта), затем то, что решает человек (жива ли,
|
||||
та ли цель, задача ли это ещё).
|
||||
|
||||
**4. Что важно сейчас.** Расстановка порядка — `move --after <слаг>` и
|
||||
`move --first`. Разбирается **не весь беклог, а верх очереди**: первые три-пять
|
||||
строк каждой секции. Ниже пятой строки порядок всё равно перестаёт что-либо
|
||||
значить — до них дойдут после следующего груминга, и очередь к тому времени
|
||||
будет другой.
|
||||
|
||||
## Приоритет: как его расставляют
|
||||
|
||||
**Вопрос ставится сравнением, а не оценкой.** «Насколько важна эта задача» не
|
||||
имеет проверяемого ответа; «что из этих двух делают раньше» — имеет. Поэтому
|
||||
очередь строится попарно и сверху: что первое, что после него.
|
||||
|
||||
Доводы, которые принимаются:
|
||||
|
||||
- **что сломано сейчас** — работоспособность обгоняет развитие, и это не правило
|
||||
вкуса: сломанное дорожает само;
|
||||
- **что разблокирует остальное** — задача, после которой можно взять три другие,
|
||||
стоит раньше любой из трёх;
|
||||
- **что дешевеет от того, что сделано** — работа рядом с только что тронутым
|
||||
кодом стоит меньше, чем та же работа через квартал;
|
||||
- **что дорожает от ожидания** — данные копятся, миграция усложняется, внешний
|
||||
срок приближается;
|
||||
- **цель, которую человек назвал следующей.**
|
||||
|
||||
Довод **записывается причиной** (`move --after <слаг> --reason …`). Порядок без
|
||||
причины — это порядок, который на следующем груминге назначат заново с нуля.
|
||||
|
||||
**Цель и приоритет — независимые оси.** Очередь может идти поперёк целей, и это
|
||||
законно: задачи одной цели не обязаны стоять подряд. Но если под целью годами
|
||||
ничего не поднимается наверх — это разговор про цель, а не про очередь, и он
|
||||
идёт на шаге 3.
|
||||
|
||||
## Документы устаревают тем же ходом работы
|
||||
|
||||
Груминг судит **задачи**, а не документы, и агентов канона не зовёт: они
|
||||
принадлежат плагину `av-dev-docs`, и когда их звать — решает он.
|
||||
|
||||
Но повод назвать это здесь есть: беклог и документы протухают от одного и того
|
||||
же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан
|
||||
десяток задач, — скажи строкой, что документы стоит сверить
|
||||
(`av-dev:doc-healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем,
|
||||
и это тоже строка.
|
||||
|
||||
## Интерактив
|
||||
|
||||
- Вопросы — через `AskUserQuestion`, **не больше трёх за раз**. Порция в 5–8
|
||||
задач обычно даёт больше трёх суждений: веди несколько итераций по ≤3, а не по
|
||||
одному вопросу на задачу и не одним перегруженным запросом.
|
||||
- К каждому варианту — **предварительное суждение, рекомендация первым
|
||||
вариантом**: «предлагаю выкинуть, потому что …». Возразить дешевле, чем судить
|
||||
с нуля.
|
||||
- Всё, что решается фактом, решай сам и показывай списком в докладе.
|
||||
- **Останавливайся на границе порции**, даже если «ещё чуть-чуть осталось».
|
||||
Между порциями — промежуточный доклад.
|
||||
|
||||
Примеры итераций, отбор порции, храповик на залежавшихся —
|
||||
[references/portions.md](references/portions.md).
|
||||
|
||||
## Стимулы, которые процесс создаёт
|
||||
|
||||
Правило, которое можно обойти в свою пользу, будет обойдено.
|
||||
|
||||
**Приёмщик и исполнитель совпадают, и это надо назвать вслух.** Задачу закрывает
|
||||
тот же агент, который её и сделал. Груминг приёмкой не занимается — отдельного
|
||||
ритуала у неё нет, — и настоящих опор остаётся две:
|
||||
|
||||
- **независимый отчёт ревью** — артефакт, написанный не исполнителем; при
|
||||
конвейере `av-dev-code` это отчёт триажа в
|
||||
`openspec/changes/archive/<id>/review/` (до архивации — `changes/<id>/review/`);
|
||||
- **`reopen <слаг> --reason`** — закрытие не окончательно. Заметил на груминге,
|
||||
что закрытая задача сделана не тем, чем обещала, — возвращай, это штатная
|
||||
операция, а не скандал. Индексы под git: `git log -p` по беклогу показывает,
|
||||
что и когда закрыто, потому что закрытие коммитится отдельным коммитом учёта.
|
||||
|
||||
Известные обходы:
|
||||
|
||||
- **Не записать вопрос** на задаче, которую хочется поднять наверх очереди.
|
||||
Защита: вопросы верхних строк разбираются вне очереди порции, шагом 2.
|
||||
- **Оставить всё как есть.** Груминг, на котором ничего не сдвинулось и ничего
|
||||
не закрылось, — это не «беклог в порядке», а не проведённый груминг. Защита:
|
||||
задача из верхних строк, которую и этот заход оставляет без изменений, **либо
|
||||
двигается, либо получает записанную причину**, почему её держат.
|
||||
- **Расставить порядок молча**, без доводов: тогда через месяц он неотличим от
|
||||
случайного. Защита: причина у каждого движения и строка доклада.
|
||||
- **Разобрать много и мелко** вместо немногого и важного: тридцать полей гигиены
|
||||
вместо трёх решений о важности. Защита: гигиена — работа скилла `tasks` и
|
||||
побочный продукт здесь; доклад называет **решения**, а не правки.
|
||||
|
||||
## Слоты проекта
|
||||
|
||||
Груминг не знает ни языка, ни сборки, ни CI. Проект дописывает в `CLAUDE.md`:
|
||||
|
||||
1. **Что считается сломанным** — какая красная проверка обгоняет развитие.
|
||||
Не названо — спрашиваем человека, а не решаем сами.
|
||||
2. **Необратимое** — что спрашивается всегда (тот же слот, что у скилла `tasks`;
|
||||
дом один).
|
||||
3. **Ориентир по размеру порции**, если он замерялся. Умолчание — 5–8 задач, и
|
||||
это **ориентир, а не закон**.
|
||||
|
||||
Числа проекта (сколько задач приходит за месяц, каков прирост беклога) — предмет
|
||||
наблюдения человека, а не константы этого скилла.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Что просмотрено: N из M, сколько порций, по какому признаку отобраны.
|
||||
- Вопросы: разобрано N, из них отвечено без человека N, снято тегов N.
|
||||
- **Что перестало быть важным**: удалено как реализованное (со ссылками), ушло
|
||||
без реализации (с причинами), понижено до сырья, слито, сменило тип или цель.
|
||||
- **Что важно сейчас**: верх очереди по каждой секции — слаги в порядке, и по
|
||||
каждому движению довод одной строкой.
|
||||
- **Границы покрытия**: сколько задач не трогали и какие именно секции, теги или
|
||||
цели остались — иначе доклад читается как «беклог разобран».
|
||||
- `tasks.py check` после правок — результат строкой.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
Не пишет код и не выполняет задачи. Не заводит и не переоформляет записи сам по
|
||||
себе — формат и содержимое ведёт `tasks` (груминг зовёт его операции). Не решает
|
||||
за человека, что важно: он готовит развилки и рекомендует. Не принимает
|
||||
закрытые задачи отдельным ритуалом — `reopen` есть, момента у него нет. Не судит
|
||||
документы проекта — это плагин `av-dev-docs`.
|
||||
@@ -0,0 +1,163 @@
|
||||
# Порции, разбор и расстановка
|
||||
|
||||
Процедура шагов 2–4 груминга. Рамка и правила — [SKILL.md](../SKILL.md).
|
||||
|
||||
Начинается всё с `tasks.py check` (и `check --fix`, если дрейф накопился) —
|
||||
результат идёт строкой в доклад.
|
||||
|
||||
## Шаг 2. Разбор вопросов
|
||||
|
||||
`tasks.py list --questions` — всё, что накопилось. Порядок по каждому вопросу:
|
||||
|
||||
1. **Проверь, не отвечен ли он уже** — решением, документом, соседним
|
||||
изменением, самим ходом сделанной с тех пор работы. Отвеченный вопрос не
|
||||
выносится человеку: это самая частая находка и она не требует ничьего
|
||||
решения.
|
||||
2. **Сформулируй развилку** с вариантами и последствием каждого, рекомендация —
|
||||
первым вариантом.
|
||||
3. **Вынеси пачкой** через `AskUserQuestion`, не больше трёх за раз.
|
||||
4. **Запиши ответ в тело задачи, опустоши раздел «Вопросы»**, сними тег
|
||||
(`edit <slug> --rm-tag question`), **перепиши «зачем»**: «Решено: …» на вопрос
|
||||
«почему это лежит в беклоге» уже не отвечает. Опустошение раздела — не
|
||||
уборка, а условие взятия: правило и причина в скилле `tasks`,
|
||||
[references/task-format.md](../../tasks/references/task-format.md).
|
||||
|
||||
**Вопросы на верхних строках очереди разбираются вне очереди порции** — здесь
|
||||
же, даже если сама задача в порцию переоценки не попала. Иначе правило «задача с
|
||||
открытым вопросом в работу не берётся» создаёт стимул вопрос не записывать, лишь
|
||||
бы не вычеркнуть задачу из ближайшей работы.
|
||||
|
||||
## Шаг 3. Что перестало быть важным
|
||||
|
||||
Цель — выкинуть то, что перестало быть задачей, и вернуть остальному честное
|
||||
состояние. Не «пересмотреть всё», а «пересмотреть порцию до конца».
|
||||
|
||||
### Порция и правило остановки
|
||||
|
||||
- **5–8 задач за порцию.** Размер обоснован усталостью, а не пропускной
|
||||
способностью, и менять его не надо — **надо брать несколько порций**.
|
||||
- **Отбор порций по порядку:**
|
||||
1. **свежее** — заведённое с прошлого груминга: оно ещё не проходило ни одной
|
||||
проверки на нужность. Свежесть меряется git'ом, как и залежалость, — датой
|
||||
появления файла в истории;
|
||||
2. дальше **по залежалости** — `list --stale`;
|
||||
3. по потребности — одна секция целиком, один тег (партия ревью), одна цель
|
||||
(`--goal`), список от человека.
|
||||
- **Останавливайся на границе порции**, даже если «ещё чуть-чуть осталось».
|
||||
Между порциями — промежуточный доклад.
|
||||
|
||||
### Что делать с каждой задачей
|
||||
|
||||
Сперва то, что не требует ничьего решения:
|
||||
|
||||
1. **Проверь, не сделано ли уже.** Задача, реализованная попутно в соседнем
|
||||
изменении, — самая частая находка. Смотри код, документацию, историю коммитов
|
||||
по ключевым словам. Удаление «как реализованной» деструктивно и без следа
|
||||
(в `REJECTED.md` реализованные не пишутся), поэтому порог улики жёсткий:
|
||||
`close <slug> --implemented` только имея **конкретный коммит или строку
|
||||
документа**, закрывающие задачу, и ссылка идёт в доклад. Есть лишь косвенные
|
||||
признаки — не удаляй сам, вынеси в пачку вопросов. Сделана частично → задача
|
||||
сжимается до остатка: тело правишь редактором, заголовок и «зачем» — через
|
||||
`edit`.
|
||||
2. **Проверь, не отменена ли решением.** Документ, ADR или архивное изменение
|
||||
мог закрыть вопрос иначе — тогда `close <slug> --reason "<ссылка на
|
||||
решение>"`. Задача закрывается не только коммитом.
|
||||
3. **Проверь пересечения.** Две задачи об одном — содержимое в одну, вторую
|
||||
`close <slug> --reason "слита с <другой-слаг>"`. Смотри **шире порции**:
|
||||
интейк дедуплицирует новое против существующего, но никогда не пересматривает
|
||||
уже лежащее, и две задачи с одной причиной могут лежать рядом месяцами.
|
||||
4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами
|
||||
одного дефекта, сливаются в одну — это находка, которую интейк дать не мог.
|
||||
5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство
|
||||
репозитория в рамках, предписание процесса в теле, тип, разошедшийся с
|
||||
задачей, границы вместо реализации в разделе «Затрагивает». Список и правила —
|
||||
в скилле `tasks`. **Груминг — то самое место, где беклог добирает тип и
|
||||
разделы его схемы:** требовать их на входе значило бы выгонять в заметки то,
|
||||
что должно лежать задачей, а к взятию в работу они уже обязательны (`ready`).
|
||||
Блок здоровья `check` печатает, сколько записей готово к взятию, — по этому
|
||||
числу и видно, добрал ли груминг.
|
||||
|
||||
Гигиена — **побочный продукт, а не предмет**. Тридцать полей вместо трёх
|
||||
решений о важности означают, что груминг не состоялся.
|
||||
|
||||
Затем — то, что решает человек:
|
||||
|
||||
6. **Жива ли она вообще.** Контекст мог измениться: ушла зависимость, отпал
|
||||
сценарий, обошли иначе. Здесь и звучит вопрос, выкидывать ли.
|
||||
7. **Та ли цель — и нужна ли она вообще.** `feature`, которой не находится цель,
|
||||
— кандидат на выход: новая возможность вне цели это возможность, которой никто
|
||||
не заказывал. Операционной задаче (`fix`, `chore`, `research`) цель не нужна,
|
||||
и выдумывать её здесь не надо.
|
||||
|
||||
**Отменяется и сама цель** — когда замысел оказался неверен, а не когда
|
||||
задача выбрала не ту. Тогда порция расширяется до всех задач этой цели: каждую
|
||||
либо закрыть своей причиной, либо перевесить на другую цель, и только потом
|
||||
закрыть цель. Порядок и почему он такой —
|
||||
[task-goal.md](../../tasks/references/task-goal.md#отменённая-цель--сперва-задачи-потом-цель).
|
||||
8. **Задача ли это по-прежнему.** Не проходит `ready` по существу, а не по
|
||||
недописанным разделам → `edit <slug> --type research` и опустошённый раздел
|
||||
«Вопрос», то есть сырьё; дальше штурм. Разрослась → это несколько задач под
|
||||
той же целью, дальше декомпозиция.
|
||||
9. **Не подешевела ли она.** Сделанная с прошлого раза работа меняет цену
|
||||
**других** задач: рядом с только что тронутым кодом та же работа стоит меньше.
|
||||
Это довод и на шаге 4 — задача, внезапно подешевевшая, поднимается в очереди
|
||||
не потому, что стала важнее, а потому, что окно открыто.
|
||||
|
||||
### Храповик на залежавшихся
|
||||
|
||||
Сильно залежавшаяся задача — сигнал сама по себе: её либо ни разу не собирались
|
||||
делать, либо нечем взять. Измеряй наблюдаемым — датой последней правки из git
|
||||
(`list --stale` ставит такие первыми); счётчик «сколько грумингов пережила»
|
||||
нигде не хранится.
|
||||
|
||||
Задача из верхних строк `--stale`, которую и этот заход оставляет без изменений,
|
||||
**либо двигается (меняет цель, поднимается в очереди, уходит с причиной), либо
|
||||
остаётся с явно записанной причиной**, почему её держим (`move <slug> --reason
|
||||
…` — без `--section` секция берётся текущая). Молчаливое «оставить как есть» на
|
||||
давно неподвижной задаче — это решение не принимать решение; запись причины
|
||||
превращает его в осознанное и не даёт тому же вопросу всплыть на следующем
|
||||
груминге.
|
||||
|
||||
## Шаг 4. Что важно сейчас — расстановка
|
||||
|
||||
Разбирается **верх очереди**, а не весь беклог: первые три-пять строк каждой
|
||||
секции. Ниже пятой строки порядок всё равно перестаёт что-либо значить.
|
||||
|
||||
1. **Покажи текущий верх** — `list --index backlog`, по секциям, в том порядке,
|
||||
в каком строки лежат. Плюс состояние проекта из роадмапа: секция `Готово`
|
||||
отвечает на «где мы», `Запланировано` — на «куда шли».
|
||||
2. **Спрашивай сравнением, а не оценкой.** «Что из этих двух делают раньше»
|
||||
имеет проверяемый ответ, «насколько важна эта задача» — нет. Веди попарно и
|
||||
сверху: что первое, что после него.
|
||||
3. **Двигай командой, с причиной** — `move <slug> --after <другой> --reason …`
|
||||
или `move <slug> --first --reason …`. Довод берётся из перечня в
|
||||
[SKILL.md](../SKILL.md#приоритет-как-его-расставляют): сломано сейчас,
|
||||
разблокирует остальное, дешевеет от сделанного, дорожает от ожидания,
|
||||
названная цель.
|
||||
4. **Проверь верх на готовность** — `tasks.py ready <слаг> …` по первым строкам.
|
||||
Задача, стоящая первой и не проходящая `ready`, — это очередь, которая врёт:
|
||||
взять её нельзя. Либо дописывается здесь же, либо уступает место.
|
||||
|
||||
Пример одной итерации:
|
||||
|
||||
> **Верх секции «Игра», сейчас в таком порядке:**
|
||||
> `board-render-once` · `draw-before-full-board` · `move-parse-strict`
|
||||
>
|
||||
> 1. Что делаем первым?
|
||||
> - `draw-before-full-board` *(рекомендую)* — ничья объявляется на неполном
|
||||
> поле: игра врёт о результате, это сломано сейчас
|
||||
> - `board-render-once` — печать поля дублируется; мешает всякой правке
|
||||
> отрисовки, то есть разблокирует остальное
|
||||
> - оставить как есть
|
||||
> 2. `move-parse-strict` — третьей или выше?
|
||||
> - Оставить третьей *(рекомендую)* — ошибка ввода видна игроку сразу
|
||||
> - Поднять второй: тот же разбор трогает `board-render-once`, окно открыто
|
||||
|
||||
Каждый вариант несёт причину — ту самую, что уедет в `--reason`.
|
||||
|
||||
## Что делать, если разбирать нечего
|
||||
|
||||
Беклог пуст или в нём три задачи и все живые — груминг кончается за минуту, и
|
||||
это законный исход. Скажи строкой: очередь такая-то, сдвигать нечего. Придумывать
|
||||
работу, чтобы груминг «состоялся», — ровно тот ритуал без выгоды, от которого
|
||||
процесс избавлялся.
|
||||
@@ -0,0 +1,763 @@
|
||||
---
|
||||
name: task-track
|
||||
description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Он же повышает каталог до текущей версии формата по своему журналу версий, когда tasks.py check говорит, что каталог отстал. Расстановка приоритетов и разбор накопившегося — скилл groom. Не реализует задачи — этим занимается скилл решения задачи.
|
||||
---
|
||||
|
||||
# Задачи
|
||||
|
||||
Задачи — каталог markdown-файлов. Одна запись = один файл `items/<slug>.md` плюс
|
||||
строка **ровно в одном** индексе. Скилл владеет **форматом и содержимым**:
|
||||
заводит, редактирует, закрывает, разбирает находки ревью, дробит, штурмует сырьё.
|
||||
|
||||
Чем он **не** владеет: **очередью** — что делать следующим и что перестало быть
|
||||
важным, решает скилл `groom`, а этот скилл лишь даёт ему операции; и выполнением
|
||||
задачи — это конвейер проекта.
|
||||
|
||||
## Шесть правил, из которых всё следует
|
||||
|
||||
Ситуация не покрыта инструкцией — решай по ним.
|
||||
|
||||
0. **Цель — возможность приложения, задача — шаг к ней.** Цель отвечает на «что
|
||||
приложение будет уметь», её «Завершение» — наблюдаемый признак того, что уже
|
||||
умеет; задача отвечает на «что для этого нужно сделать». Оценивается проект
|
||||
по **поведению**, а не по внутреннему устройству, поэтому и роадмап отвечает
|
||||
не «сколько работ осталось», а «что уже умеет и чего ещё не умеет».
|
||||
Свойство поведения — тоже возможность: «сообщает о своём состоянии»,
|
||||
«исход слияния не зависит от порядка доставки» — законные цели.
|
||||
1. **Беклог гниёт с той стороны, где его пополняют.** Заведение — самая частая
|
||||
операция и с худшим отказом: из одного разговора рождается пять файлов, а
|
||||
переоценка потом разгребает то, чего не надо было заводить. Дедупликация и
|
||||
фильтр на входе дешевле любой чистки. Заводим только то, что **не делаем
|
||||
сейчас** и о потере чего пожалеем.
|
||||
2. **Файл — источник истины, индексы производны.** Разошлись — неправы индексы.
|
||||
Согласованность механизируема и проверяется командой, а не вниманием: всё,
|
||||
что ловит `tasks.py check`, не должно попадать ни в чек-лист, ни в промпт.
|
||||
Поэтому **«зачем» живёт в мете файла**, а строка индекса его лишь
|
||||
повторяет: пока поле лежало только в индексе, восстановление пропавшей
|
||||
строки теряло его молча и навсегда. Единственное исключение намеренное: **в каком
|
||||
индексе лежит запись, знают индексы** — поля-состояния в файле нет. И
|
||||
**порядок строк в беклоге**: приоритет это свойство очереди, а не задачи, и в
|
||||
файле ему места нет (правило 4).
|
||||
3. **Причина переживает запись.** Выкинутая без причины задача вернётся через
|
||||
квартал тем же текстом. Реализованная оставляет след в коммите — выкинутая не
|
||||
оставляет ничего, поэтому у неё есть `REJECTED.md`.
|
||||
4. **Приоритет — это порядок строк, а цель есть не у всякой задачи.** Очередь
|
||||
внутри секции беклога значима: **первая строка — то, что делают следующим**.
|
||||
Приоритет назначает человек на груминге, машина его не выводит и не угадывает.
|
||||
|
||||
Прежде здесь стояло «порядка нет, есть цель», и обосновано это было тем, что
|
||||
на «что делать дальше» отвечает **набор спринта**. Набора больше нет, а
|
||||
вопрос остался — и без порядка отвечать на него стало нечем.
|
||||
|
||||
**Дом приоритета — индекс, а не файл.** Это то же исключение из правила 2,
|
||||
что и «в каком индексе лежит запись»: приоритет — свойство очереди. Положи он
|
||||
в файл числом, и два соседних файла смогли бы утверждать одно и то же место,
|
||||
а строка индекса — противоречить обоим.
|
||||
|
||||
Цель обязательна там, где она и есть содержание работы, — у **новой
|
||||
возможности** (`feature`). Починка, техдолг и разведка служат
|
||||
работоспособности, а не направлению, и живут без цели законно. Придуманная им
|
||||
цель — то же враньё, от которого спасает тип. **Цель и приоритет —
|
||||
независимые оси:** очередь может идти поперёк целей, и это законно.
|
||||
|
||||
Одно место в очереди назначено **не человеком, а типом**: **сырьё**
|
||||
(`research` без раздела «Вопрос») стоит в конце своей категории. Его не берут,
|
||||
и между берущимся оно каждый раз требует открыть файл, чтобы это понять. Раз
|
||||
это выводится, проверяет и чинит это машина.
|
||||
5. **Тип решает, что с записью можно делать.** Тип — единственная ось и первое
|
||||
поле меты: от него зависит, какие разделы обязательны в теле, нужна ли цель,
|
||||
берётся ли запись в работу и в каком индексе живёт её строка. Словарь закрыт;
|
||||
ни один тип не подошёл — значит, в записи их два, и её надо разделить.
|
||||
|
||||
## Раскладка
|
||||
|
||||
Каталог задач — **`tasks/` в корне репозитория, жёстко.** Он принадлежит этому
|
||||
плагину, а не канону документов: `docs/` ведёт другой плагин (`av-dev-docs`), и
|
||||
проект, поставивший учёт работ без него, каталога `docs/` не имеет вовсе. Внутри
|
||||
`docs/` задачи лежали до версии канона 11; непереехавший проект скрипт
|
||||
по-прежнему находит, но новый заводит только в корне.
|
||||
|
||||
```
|
||||
tasks/
|
||||
items/ задачи и цели файлами, <slug>.md, слаги английские
|
||||
ROADMAP.md состояние проекта: что уже умеет и чего ещё не умеет
|
||||
BACKLOG.md что можно взять — только задачи, целей здесь нет.
|
||||
Порядок строк в секции значим: это очередь
|
||||
REJECTED.md ушедшее БЕЗ реализации, с причиной и датой
|
||||
```
|
||||
|
||||
Правило, снимающее путаницу: **`BACKLOG.md` — то, что берут; `ROADMAP.md` — то,
|
||||
подо что берут.** Цель в работу взять нельзя — берут её задачи, — поэтому в
|
||||
списке берущихся ей не место.
|
||||
|
||||
**Четыре секции роадмапа, и последняя отвечает на половину вопроса:**
|
||||
|
||||
| Секция | Англ. | Что в ней |
|
||||
| --- | --- | --- |
|
||||
| `Запланировано` | `Planned` | очередь значима и обосновывается прозой рядом |
|
||||
| `Направления` | `Directions` | очереди нет, тянутся долго |
|
||||
| `Сопровождение` | `Operations` | чем держат проект: инструмент, процесс, эксплуатация — не возможности приложения, и потому отдельно |
|
||||
| `Готово` | `Done` | достигнутые цели — строкой с датой, **без ссылки на файл**: файл удалён, поведение живёт в спеках |
|
||||
|
||||
**Порядок тоже канонический, и `Готово` стоит последним не из скромности.**
|
||||
Достигнутое **копится**: через год этой секции больше, чем всех остальных
|
||||
вместе. Стоя первой, она отодвигает за экран ровно то, ради чего роадмап
|
||||
открывают чаще всего, — что делается сейчас и что дальше. Порядок проверяет
|
||||
`check`, переставляет `check --fix`.
|
||||
|
||||
**Секции роадмапа канонические, категории беклога — нет**, и разница не в любви к
|
||||
единообразию. У каждой секции роадмапа свой смысл, в достигнутое пишет сам `close`, и
|
||||
роадмап, названный по-своему, читался бы только своим автором. Категории беклога
|
||||
(`Ядро`, `Инфра`) смысла не несут — это полки домена, и остаются делом проекта.
|
||||
Отсюда и разные имена поля меты: у цели **Секция** (часть роадмапа — состояние
|
||||
очереди), у задачи **Категория** (полка домена, на которой она лежит).
|
||||
|
||||
Отсюда четыре правила, которые проверяет `tasks.py check`: **состав закреплён**
|
||||
(чужая секция — ошибка, а не вольность), **все четыре обязаны быть** (нет
|
||||
секции — нет ответа на её часть вопроса), **язык один на весь индекс**, **порядок
|
||||
канонический**. `--roadmap-sections` у `init` нет: выбирать нечего.
|
||||
|
||||
**Заголовок секции отбит пустой строкой с обеих сторон и написан с прописной.**
|
||||
Во всех индексах одинаково, включая категории беклога, которые проект называет сам.
|
||||
Написание канонических секций правит `check --fix` (заодно и ссылку на секцию в
|
||||
мете файлов: имя секции принадлежит заголовку индекса, файл на неё только
|
||||
ссылается); отбивку и порядок он правит везде.
|
||||
|
||||
Оговорка про `Сопровождение`: слово `окружение` сюда не годится — в
|
||||
`architecture.md` оно уже значит боевое окружение приложения, и одно слово в двух
|
||||
смыслах развело бы документы канона. А `Разработка`, стоявшая тут раньше,
|
||||
называла слишком много: роадмап **весь** про разработку, и секция с таким именем
|
||||
не отличалась от остальных ничем.
|
||||
|
||||
**Секции «блокеры» в беклоге нет.** Блокер — это *состояние* (работа не может
|
||||
продолжаться ни одной задачей), а не полка: он живёт ровно до ответа человека, и
|
||||
записи в такой секции не успевают жить. Следы блокера остаются вопросами в
|
||||
файлах задач. Постоянно пустая секция со старой семантикой
|
||||
«разбираются пачками» противоречила бы правилу «блокер эскалируется немедленно»,
|
||||
поэтому `init` её заводить отказывается, а `check` о ней говорит. **Проекту,
|
||||
который переезжает с такой секцией, её надо удалить** — это единственное место,
|
||||
где это сказано.
|
||||
|
||||
**Запись живёт в одном индексе за раз.** Индексов два, и выбирает между ними
|
||||
тип: цель в роадмапе, задача в беклоге. Сменился тип — строка переезжает
|
||||
(`edit --type`). Файл в `items/` при этом **не двигается**: он и есть запись,
|
||||
индексы лишь показывают, где она числится и в каком порядке стоит.
|
||||
|
||||
**Порядок строк в беклоге — приоритет**, и он единственное, чего в файле нет
|
||||
(правило 4). Отсюда следствие для всякой машинной правки индекса:
|
||||
восстановленная или перенесённая строка встаёт **в конец своей секции**, и
|
||||
скрипт об этом говорит. Молчаливая вставка выдала бы машинную позицию за
|
||||
решение человека — а решение это его.
|
||||
|
||||
**У сделанной задачи записи не остаётся** — файл и строка удаляются (`close
|
||||
--implemented`). Ей хватает коммита и документации проекта; вторая запись была
|
||||
бы вторым домом для того же факта. Вопрос «что было сделано и когда» отвечается
|
||||
даром: индексы лежат под git, а закрытие коммитится отдельным коммитом учёта —
|
||||
`git log -p tasks/BACKLOG.md` отдаёт историю без отдельного журнала.
|
||||
|
||||
**У достигнутой цели запись остаётся, и это единственное исключение.** Файл
|
||||
удаляется так же, а строка переезжает в секцию `Готово` с датой. Причина в том,
|
||||
что цель — не работа, а **возможность**: «что приложение умеет» это половина
|
||||
вопроса, ради которого роадмап и открывают, и стирать её вместе с файлом значит
|
||||
оставить инструмент, отвечающий только «что осталось». Вторым домом это не
|
||||
становится: поведение живёт в `openspec/specs/`, а роадмап отвечает **когда и в
|
||||
каком порядке оно появилось** — другой вопрос. Ссылки на файл в строке нет
|
||||
намеренно: файл удалён, а битая ссылка — законная ошибка `check`.
|
||||
|
||||
Куда запись может переехать и какой командой — весь набор переходов:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state "BACKLOG.md — что берут" as B
|
||||
state "ROADMAP.md — подо что берут" as P
|
||||
state "REJECTED.md — ушла без реализации" as R
|
||||
state "записи нет — реализована" as D
|
||||
state "ROADMAP.md, «умеет» — цель достигнута" as A
|
||||
|
||||
[*] --> B: add --type feature|fix|chore|research
|
||||
[*] --> P: add --type goal
|
||||
B --> P: edit --type goal --section
|
||||
P --> B: edit --type feature|fix|chore|research --section
|
||||
B --> D: close --implemented
|
||||
P --> A: close --implemented
|
||||
B --> R: close --reason
|
||||
P --> R: close --reason
|
||||
D --> B: reopen --reason
|
||||
R --> B: reopen --reason
|
||||
A --> P: reopen --reason
|
||||
```
|
||||
|
||||
Состояния здесь — **где числится строка**, а не где лежит файл: файл
|
||||
`items/<slug>.md` не двигается ни на одном переходе. Стрелок «руками» на схеме
|
||||
нет намеренно — каждый переход это команда, и другого способа его совершить не
|
||||
существует.
|
||||
|
||||
Схема — **сводка**: условия и оговорки живут в тексте разделов, и при
|
||||
расхождении прав текст.
|
||||
|
||||
## Цели
|
||||
|
||||
**Цель — возможность приложения.** Такой же файл в `items/`, тип `goal` (🎯),
|
||||
перечисленный в `ROADMAP.md`. Формулируется ответом на вопрос **«что приложение
|
||||
будет уметь»**, а не названием области работ: не «Работа с чтением», а «Чтение
|
||||
данных клиентами»; не «Рефакторинг слияния», а «Исход слияния не зависит от
|
||||
порядка доставки».
|
||||
|
||||
**Свойство поведения — тоже возможность.** «Наблюдаемость» это «приложение
|
||||
сообщает о своём состоянии»; «прочность слияния» это «исход не зависит от
|
||||
порядка». Такие цели законны и переформулировки в функцию не требуют — требуют
|
||||
только, чтобы формулировка отвечала на «что приложение делает», а не на «какую
|
||||
часть кода мы трогаем».
|
||||
|
||||
**Целью не становится работа, которой держат проект.** Состав перечислен
|
||||
[в словаре сопровождения](references/operations.md);
|
||||
на вопрос «что приложение будет уметь» ничто из него не отвечает. Им отведена отдельная секция роадмапа,
|
||||
чтобы они были видны в том же экране и при этом не читались как возможности
|
||||
продукта.
|
||||
|
||||
**Граница проходит по тому, кто наблюдает, а не по теме.** «Приложение сообщает
|
||||
о своём состоянии» — возможность: наблюдает пользователь сервиса, и цели место
|
||||
среди прочих. «Дежурный видит состояние на одном экране» — сопровождение:
|
||||
наблюдаем мы. Одна и та же наблюдаемость попадает в разные секции, и это верно —
|
||||
секции отвечают на разные вопросы.
|
||||
|
||||
**Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема
|
||||
живёт ещё в двух местах: разделе «Эксплуатация» в `architecture.md` и теме ревью
|
||||
`operations`. Словарь у всех трёх общий, дом у него один — `shared/operations.md`
|
||||
в репозитории плагинов, — а здесь лежит дословная копия:
|
||||
[references/operations.md](references/operations.md). Пересказывать его своими
|
||||
словами нельзя: три перечня «чем держат проект» уже разъезжались на «метриках и
|
||||
логах» против «мониторинга».
|
||||
|
||||
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; не про приложение, а про то,
|
||||
чем его держат, — `Сопровождение`; в `Готово` кладёт сам `close`.
|
||||
|
||||
- **Список задач цели выводится, а не хранится.** В теле цели — зачем она и что
|
||||
считается её завершением; перечня задач там нет. Он был бы третьим индексом и
|
||||
поехал бы на первой же закрытой задаче, а `check` про него не знает. Связь
|
||||
однонаправленна: задача несёт тег `goal:<слаг>`, перечень даёт
|
||||
`tasks.py list --goal <слаг>`.
|
||||
- **Статус цели выводится.** Цель достигнута, когда у неё не осталось открытых
|
||||
задач; `[x]`/`[~]` руками не ведутся, а `close` цели с живыми задачами
|
||||
скрипт запретит. Достижение — `close <цель> --implemented`: файл удаляется,
|
||||
строка с датой переезжает в `Готово`. Ошиблись — `reopen` вернёт файл и
|
||||
**снимет строку достигнутого**, чтобы роадмап не утверждал того, чего нет. Единственная оговорка: цель без задач неотличима — «ещё не
|
||||
разобрана» или «всё закрыто». Различает **тег `decomposed`** в мете
|
||||
цели: он ставится, когда цель разложена на задачи. Тег, а не строка в теле —
|
||||
потому что проверяется механически: `check` **напоминает** о нём у пустой цели
|
||||
(замечанием, не ошибкой — неразобранная цель это законное состояние), а `check
|
||||
--fix` сам проставляет его цели, у которой задачи есть.
|
||||
- **Тип `[epic]` упразднён.** Он был зонтиком между целью и задачами — «задача,
|
||||
которая не мерджится целиком». Зонтик теперь цель, а слишком крупный шаг просто
|
||||
дробится на шаги помельче под той же целью, и промежуточному типу места не
|
||||
осталось. Замер подтвердил: ноль употреблений на 97 записей двух живых
|
||||
проектов. Встретился в чужом беклоге — это цель либо набор задач, и `check`
|
||||
назовёт его неизвестным типом.
|
||||
|
||||
## Тип записи
|
||||
|
||||
**Тип — единственная ось, и он решает, что с записью можно делать.** Дом типа —
|
||||
**поле меты `Тип` первой строкой**; эмодзи в заголовке H1 от него производна, её
|
||||
ставит `add` и чинит `check --fix`.
|
||||
|
||||
| Тип | Обязательные разделы | Цель | В работу | Устав |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 🎯 `goal` | `Завершение` | — | нет | [task-goal.md](references/task-goal.md) |
|
||||
| ✨ `feature` | `Затрагивает`, `Критерии приёмки` | **обязательна** | да | [task-feature.md](references/task-feature.md) |
|
||||
| 🐞 `fix` | `Воспроизведение`, `Затрагивает`, `Критерии приёмки` | необязательна | да | [task-fix.md](references/task-fix.md) |
|
||||
| 🧹 `chore` | `Затрагивает`, `Критерии приёмки` | нет | да | [task-chore.md](references/task-chore.md) |
|
||||
| 🔬 `research` | `Вопрос`, `Куда ляжет ответ` | нет | да | [task-research.md](references/task-research.md) |
|
||||
|
||||
Сверх обязательных у любой задачи допустимы `Рамки` и `Вопросы`. Раздел не из
|
||||
схемы своего типа — **замечание, а не ошибка**: свой раздел законная вольность
|
||||
проекта, но `Воспроизведение` у `chore` почти всегда значит, что тип проставлен
|
||||
не тот, и сказать об этом стоит, не запрещая.
|
||||
|
||||
**Осей было две, и ортогональность у них была фальшивой.** Тип записи
|
||||
(`goal`/`idea`/`task`) и род работы (`kind:<род>` тегом) давали двенадцать клеток
|
||||
произведения, из которых законны были шесть: у цели род запрещён, у задачи
|
||||
обязателен, у идеи пуст. Плюс алгоритм работы крепится не к `task`, а к `fix` и
|
||||
`research` — то есть к роду. Оси схлопнуты, тег `kind:` упразднён.
|
||||
|
||||
**Тип `idea` упразднён вместе с ними.** Он значил не род работы, а **состояние
|
||||
незаполненности** — «первый, второй или третий вопрос теста готовности не
|
||||
отвечается», — а состояние типом быть не может: оно меняется по мере того, как
|
||||
запись дописывают, а тип меняют командой. Теперь это состояние называется честно:
|
||||
`research` без раздела «Вопрос» — **сырьё**. В работу не берётся ровно как
|
||||
прежняя идея, лежит в конце своей категории и отбирается `list --raw`.
|
||||
|
||||
Словарь **закрыт**. Открытый разъедется на синонимах — `bug`, `bugfix`, `fix`,
|
||||
`defect`, — и отбор по типу перестанет отвечать на свой единственный вопрос. Ни
|
||||
один тип не подходит — это сигнал, что в задаче их два и её надо разделить.
|
||||
|
||||
**Требуется тип там, где по нему принимают решение:** `ready` без типа
|
||||
откажет, потому что не знает, каких разделов требовать. `check` о пропаже только
|
||||
**напоминает** — беклог, заведённый до появления типа, законен, и переоформлять
|
||||
его «заодно» здесь не просят.
|
||||
|
||||
**Тип не выбирает метку ревью и глубину проверки.** Профиль выбирается по факту
|
||||
изменения, а не по типу задачи: `chore` бывает миграцией схемы, `fix` — правкой
|
||||
публичного контракта. Правило «предписание процесса в теле задачи снимается»
|
||||
типом не отменяется, а подтверждается: он описывает работу, а не то, как её
|
||||
проверять.
|
||||
|
||||
**Одно исполнителю тип всё же говорит — каким сценарием работу вести, и то не
|
||||
один.** В плагине `av-dev-code` скилл `resolve` выбирает сценарий связкой из двух
|
||||
признаков: тип **предлагает** (`chore` — обслуживание, `research` — разведка),
|
||||
а подтверждает его предмет работы — есть ли что менять в спеках. Признаки
|
||||
разошлись — работа останавливается, и тип меняется здесь, командой `edit --type`,
|
||||
а не переклеивается исполнителем по ходу. Метку и глубину это по-прежнему не
|
||||
задаёт: их называет разметка изменения, а на прогоне без change — сам сценарий.
|
||||
|
||||
## Как написана задача
|
||||
|
||||
Три требования к тексту. Первое — про заголовок, два остальных про то, чтобы
|
||||
задачу можно было **оценить, не открывая код**.
|
||||
|
||||
**Заголовок отвечает на вопрос своего типа.** Вопросов три, поэтому и форм три:
|
||||
|
||||
| Тип | Отвечает на | Пример |
|
||||
| --- | --- | --- |
|
||||
| 🎯 `goal` | что приложение будет уметь | Соперником может быть компьютер |
|
||||
| ✨ `feature`, 🐞 `fix`, 🧹 `chore` | что нужно сделать | Печатать поле одним куском кода |
|
||||
| 🔬 `research` | о чём разведка | Подсказка следующего хода |
|
||||
|
||||
Задача — **глаголом в неопределённой форме**, перед ним допускается «не»: «Не
|
||||
отбрасывать молча лишние символы в ходе», а не «Лишние символы молча
|
||||
отбрасываются». Описательный заголовок называет **состояние**, а из состояния не
|
||||
видно, чего от работы ждут: «Ничья объявляется, пока клетки есть» одинаково
|
||||
читается и как жалоба, и как задание, — и в списке, где решают «брать или не
|
||||
брать», это разные вещи. `research` формы действия не несёт **намеренно**: её
|
||||
исход знание, а что делать — ещё неизвестно, и заголовок-действие обещал бы
|
||||
решённость, которой нет.
|
||||
|
||||
Из этого же правила растёт разница индексов: роадмап — список возможностей,
|
||||
беклог — список работ, и если заголовки перепутать формами, каждый из них
|
||||
начинает читаться как другой.
|
||||
|
||||
`check` считает заголовки не в форме действия и печатает **число** в блоке
|
||||
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
|
||||
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
|
||||
Годность формулировки — не машине: её смотрит
|
||||
[агент вычитки](#вычитка-два-прохода-а-не-один).
|
||||
|
||||
**Функции и границы, а не намерения.** Задача называет, что система начнёт
|
||||
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
|
||||
формат на диске, публичный тип пакета, внешний сервис. Перечень живёт разделом
|
||||
«Затрагивает» (форма — [references/task-format.md](references/task-format.md)) и
|
||||
требуется к взятию в работу. Без него задача оценивается по объёму текста, а не
|
||||
по объёму поверхности, — и оценка систематически занижена ровно там, где текст
|
||||
короткий, а границ много. Названы **границы**, а не то, как они изменятся: план
|
||||
реализации живёт в предложении об изменении, а не в задаче.
|
||||
|
||||
**Предметно, но без усложнения.** Текст задачи читает человек, который решает,
|
||||
брать её или нет, и делает это по строке индекса и одному экрану тела.
|
||||
|
||||
Язык — общий для всех проектных текстов, и дом у него один,
|
||||
`shared/language.md` в репозитории плагинов; здесь лежит дословная копия:
|
||||
[references/language.md](references/language.md) (информационный стиль,
|
||||
применённый к задачам и документам канона; там же таблицы англицизмов и жаргона
|
||||
и то, что из стиля отброшено намеренно). Задаче он даёт четыре требования,
|
||||
которые нарушаются чаще прочих:
|
||||
|
||||
- **глагол вместо отглагольного существительного**: «обработчик не проверяет
|
||||
владельца», а не «проверка владельца не осуществляется»;
|
||||
- **факт вместо оценки**: «время ответа доходит до 800 мс», а не «работает
|
||||
медленно». Оценка без факта рядом — настроение, а не сведение;
|
||||
- **англицизм с живым русским аналогом заменяется**: не «зафиксить флоу», а
|
||||
«починить порядок доставки». Имя вещи не переводится: слаг, команда, тип в
|
||||
коде, `API`;
|
||||
- **термин не из документов проекта вводится одной строкой** или не
|
||||
употребляется. Свой словарь у задачи — самый дешёвый способ сделать беклог
|
||||
нечитаемым для того, кто вернётся к нему через квартал.
|
||||
|
||||
И одно требование, которое есть только у задачи: **сложность формулировки — не
|
||||
признак сложности работы.** Задачу, которую не удаётся сказать просто, чаще
|
||||
всего не удаётся и оценить: это либо две задачи, либо сырьё.
|
||||
|
||||
Эти правила — про **язык**, а не про объём: короткая задача без границ хуже
|
||||
длинной с ними.
|
||||
|
||||
## Инструмент (`tasks.py`)
|
||||
|
||||
Пусть `tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"`, а `D` —
|
||||
`tasks` от корня проекта. `--dir` стоит в примерах намеренно: вызов из
|
||||
подкаталога — обычное дело.
|
||||
|
||||
```
|
||||
python3 $tk check --dir D # согласованность индексов + здоровье
|
||||
python3 $tk check --dir D --fix # + починить дрейф (тип, эмодзи, место, заголовок, дубли, «зачем», форма меты)
|
||||
python3 $tk list --dir D [--stale] [--section S] [--type T] [--tag a,b] [--goal S] [--raw] [--index …] [--questions]
|
||||
python3 $tk add --dir D --slug S --title T --type goal|feature|fix|chore|research [--section S] [--goal G] [--why «зачем»] [--tag a,b]
|
||||
python3 $tk edit S --dir D [--title T] [--why «зачем»] [--type T] [--goal G] [--add-tag a,b] [--rm-tag c]
|
||||
python3 $tk move S --dir D [--section S] [--reason R] [--after S | --first] # без --section — текущая секция
|
||||
python3 $tk close S --dir D --reason R # в REJECTED.md + удалить (ушла без реализации)
|
||||
python3 $tk close S --dir D --implemented # просто удалить (реализована и закоммичена)
|
||||
python3 $tk reopen S --dir D --reason R # вернуть закрытую: приёмка не сошлась
|
||||
python3 $tk ready S… --dir D # схема типа выполнена — можно брать в работу
|
||||
python3 $tk init --dir D [--sections …] [--items …] [--backlog …] …
|
||||
python3 $tk adopt scan --from … | apply --plan … # разовая адаптация, references/adopt.md
|
||||
```
|
||||
|
||||
**Коды выхода — единый словарь; на нём ветвятся скиллы, а не на тексте вывода:**
|
||||
|
||||
| Код | Что случилось | Что делать |
|
||||
| --- | --- | --- |
|
||||
| 0 | сошлось / сделано | дальше по сценарию |
|
||||
| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу |
|
||||
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `<каталог задач>/.tasks.json`, повтор не поможет |
|
||||
| 4 | внутренний сбой | дефект скрипта, доложить |
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
|
||||
нет» — нерабочая, и одинаковая реакция на них была бы неверна в обоих случаях.
|
||||
|
||||
Тип — английское ключевое слово `goal` / `feature` / `fix` / `chore` /
|
||||
`research` (как и прочие токены команд), у `add` **обязательное**: без него
|
||||
неизвестно, какой шаблон тела класть. Текст задачи при этом русский, а эмодзи в
|
||||
заголовке ставит скрипт.
|
||||
|
||||
**Мутации правят файл и индексы заодно** — руками строку индекса или мету
|
||||
не пиши, зови `add`/`edit`/`move`/`close`/`reopen`. Смена заголовка, «зачем», типа,
|
||||
цели и **тегов** — это `edit`: он держит H1 (вместе с эмодзи), мету и индекс
|
||||
согласованными. Снятие тега — `--rm-tag` (после ответа на вопрос снимается
|
||||
`question`), смена цели — `--goal`, типа — `--type`; оба заменяют прежнее
|
||||
значение, а не добавляют второе.
|
||||
|
||||
**Переезд между индексами — следствие смены типа, а не отдельная команда.**
|
||||
`edit <slug> --type goal --section <часть роадмапа>` переносит строку из
|
||||
`BACKLOG.md` в `ROADMAP.md` (и обратно — задачным типом плюс
|
||||
`--section <категория беклога>`);
|
||||
`move` двигает только внутри одного индекса и пишет причину. `--section` у
|
||||
`edit` работает **только** при таком переезде — иначе он отсылает к `move`,
|
||||
потому что смена секции без причины и есть тот дрейф, который потом никто не
|
||||
объяснит.
|
||||
|
||||
**`move --after <слаг>` и `move --first` — это и есть расстановка приоритета.**
|
||||
Порядок строк в секции значим (правило 4), и двигают его только этой командой:
|
||||
руками поправленная строка не оставляет причины, а причина здесь и есть половина
|
||||
решения.
|
||||
|
||||
Тело задачи скрипт не трогает:
|
||||
`add` кладёт заголовок, мета-блок и шаблон с подсказками, тело дописываешь
|
||||
редактором (пока плейсхолдер на месте, `check` напоминает).
|
||||
|
||||
`check` — единственный судья согласованности; что именно он ловит, скажет его
|
||||
вывод, здесь не пересказываем. Гоняй его **в начале сессии** и **после каждой
|
||||
правки**, даже если правил мутациями: дрейф мог накопиться раньше. Накопившееся
|
||||
чини `check --fix` — он детерминированно правит то, где истина однозначна (тип в
|
||||
своё поле, эмодзи заголовка, имя поля места, секция, заголовок, дубли, «зачем» из
|
||||
индекса в файл, старая форма меты, пометка `decomposed` у цели с задачами, сырьё
|
||||
в конец категории), а неоднозначное (задача сразу в двух индексах, нечего
|
||||
восстанавливать, **тип, которого неоткуда взять**) печатает отдельной пометкой
|
||||
`НЕОДНОЗНАЧНО` — это тебе, и это идёт строкой доклада. **Ссылка на исчезнувший
|
||||
файл в пометку не попадает:** `--fix` её просто не трогает, и она остаётся
|
||||
`ОШИБКА` обычного `check` — то есть видна, но в докладе её надо назвать отдельно.
|
||||
|
||||
`--fix` правит **и файлы** — там, где источник ровно один и выбирать не из чего:
|
||||
тип переезжает из прежнего дома (тег `kind:`, префикс `[goal]`/`[idea]`) в поле
|
||||
меты, заголовок получает эмодзи, поле места — имя по типу, «зачем», оставшееся
|
||||
только в индексе, переезжает в мету, цель с задачами получает `decomposed`.
|
||||
Каждый случай печатается поимённо.
|
||||
|
||||
**Тип, который не выводится ниоткуда, `--fix` не угадывает.** `feature` от
|
||||
`chore` машина не отличает, и подставленное наугад значение врало бы ровно там,
|
||||
где по нему принимают решение. Такие записи идут в `НЕОДНОЗНАЧНО`, и тип им
|
||||
проставляет человек — `edit <слаг> --type …`.
|
||||
|
||||
**Что механизировано, а что нет.** Схему типа проверяет `ready` на входе в
|
||||
работу — там, где по ней принимают решение; `check` поимённо о ней не говорит, а
|
||||
считает: строка здоровья **«схема типа не выполнена: N из M»** называет число и
|
||||
первые слаги, строка **«готово к взятию»** — сколько задач беклога пройдут
|
||||
`ready` целиком (схема плюс цель плюс отсутствие открытого вопроса). Это две
|
||||
разные строки, и совпадение их чисел — совпадение. У каждой части своя глубина:
|
||||
|
||||
- **тип** — жёстко: назван и из закрытого словаря;
|
||||
- **критерии приёмки** (`feature`, `fix`, `chore`) — число пунктов жёстко
|
||||
(меньше двух отказ, больше пяти замечание), наличие оракула **эвристикой** по
|
||||
слову «оракул» в пункте;
|
||||
- **прочие разделы схемы** (`Затрагивает`, `Воспроизведение`, `Вопрос`,
|
||||
`Куда ляжет ответ`, `Завершение`) — только **наличие непустого**. Содержимое
|
||||
машине не видно: границу, которую забыли назвать, она от отсутствующей не
|
||||
отличает, а шаги, по которым ничего не воспроизводится, — от годных.
|
||||
|
||||
Настоящий оракул от слова «оракул» машина тоже не отличает, поэтому эвристика
|
||||
даёт только замечание, и в докладе это называется как есть: «проверено наличие
|
||||
разделов своего типа и число критериев, годность оракулов и полнота границ —
|
||||
глазами».
|
||||
|
||||
Формат записи, меты, слага, индексов и `REJECTED.md` —
|
||||
[references/task-format.md](references/task-format.md); там же тест «готова к
|
||||
взятию». Схема и алгоритм каждого типа — по файлу на тип:
|
||||
[goal](references/task-goal.md) · [feature](references/task-feature.md) ·
|
||||
[fix](references/task-fix.md) · [chore](references/task-chore.md) ·
|
||||
[research](references/task-research.md).
|
||||
|
||||
## Версия формата
|
||||
|
||||
Формат каталога задач меняется, и проект должен знать, к какой его версии
|
||||
приведён. Число живёт ключом `tasks` в `<каталог задач>/.tasks.json`, журнал
|
||||
версий — [references/changelog.md](references/changelog.md), сверяет их
|
||||
`tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел плагин.
|
||||
|
||||
**Версия своя, а не канона документов.** Плагин ставится в одиночку: проект,
|
||||
взявший учёт работ без `av-dev-docs`, каталога `docs/` не имеет вовсе, а значит
|
||||
не имеет и версии канона — сверять было бы не с чем. Обратной совместимости у
|
||||
формата нет: есть «приведён» и «не приведён».
|
||||
|
||||
**`upgrade` — повысить каталог до текущего формата:**
|
||||
|
||||
1. `python3 $tk check --dir D` — первая же строка расхождений называет версию
|
||||
проекта и версию скрипта. Проект новее скрипта — **обнови маркетплейс**, а не
|
||||
проект: это отстал плагин.
|
||||
2. Иди по [журналу](references/changelog.md) снизу вверх от версии проекта до
|
||||
текущей и делай названное в каждой записи. Записи независимы и применяются по
|
||||
порядку.
|
||||
3. Подними `tasks` в `.tasks.json` до текущей — руками, последним шагом. Раньше
|
||||
времени поднятое число объявляет каталог приведённым к формату, шагов
|
||||
которого никто не делал; `check --fix` этого не пишет намеренно.
|
||||
4. `check --dir D` ещё раз — до отсутствия расхождений.
|
||||
|
||||
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
|
||||
это дефект журнала, и о нём надо сказать, а не догадываться.
|
||||
|
||||
**Канон документов сюда не вмешивается.** Его журнал двигает своё число в
|
||||
`docs/.docs.json` и вправе сказать «позови этот скилл», но не двигать версию
|
||||
формата задач: две версии, ходящие по одному журналу, разъедутся на первом же
|
||||
проекте, где стоит один плагин без другого.
|
||||
|
||||
## Сценарии
|
||||
|
||||
### Завести запись из диалога
|
||||
|
||||
1. **Фильтр.** Делаем прямо сейчас — не заводим. Не пожалеем о потере — не
|
||||
заводим. Родилось три кандидата — покажи их и спроси, какие заводить: молча
|
||||
заведённая пачка и есть тот самый отказ из правила 1.
|
||||
2. **Дедуп.** `list` плюс поиск по слагам, полю «зачем» и телам (`grep -ril`),
|
||||
**включая `REJECTED.md`**. Нашлось среди живых — **дописываем в существующий
|
||||
файл**, а не заводим соседний. Нашлось в `REJECTED.md` — покажи пользователю
|
||||
ту строку и что изменилось с момента отказа (`add` предупредит и сам, но
|
||||
молча заводить нельзя). Две задачи об одном — самая дорогая находка
|
||||
переоценки.
|
||||
3. **Тип** — `--type` обязателен, и он же первое содержательное решение:
|
||||
|
||||
- возможность приложения, а не шаг к ней → `goal`;
|
||||
- снаружи появляется то, чего не было → `feature`;
|
||||
- поведение расходится с заявленным и **воспроизводится** → `fix`
|
||||
(не воспроизводится → `research`);
|
||||
- обслуживание, наблюдаемое поведение не меняется → `chore`;
|
||||
- исход — знание, а не изменение системы → `research`.
|
||||
|
||||
Не подходит ни один — в записи их два, разбирай. Не проходит тест готовности
|
||||
(см. task-format) — это **сырьё**: `--type research`, раздел «Вопрос» пока
|
||||
пуст, место в конце категории. Не делается одним заходом — это не эпик, а
|
||||
несколько задач под одной целью: дроби сразу.
|
||||
4. **Цель — если тип её требует.** У `feature` должен быть `--goal <слаг>`:
|
||||
новая возможность и есть содержание цели. Подходящей нет — либо она
|
||||
заводится (`--type goal`), либо перед тобой не `feature`. У `fix`, `chore` и
|
||||
`research` цели может не быть вовсе, и придумывать её не надо.
|
||||
5. `add …`, затем допиши тело редактором **по схеме своего типа** — шаблон её
|
||||
уже разложил, устав типа объясняет каждый раздел. «Зачем» отвечает «зачем
|
||||
нужна эта задача» — состояние, остаток, боль, — а не пересказывает первый
|
||||
абзац, и пишется **для человека**: не «канонизация внутри транзакции», а
|
||||
«тело 40 МиБ держит блокировку 5 секунд, соседние доставки уходят в отказ».
|
||||
6. `check`.
|
||||
|
||||
### Разобрать находки аудита или ревью
|
||||
|
||||
Ревью и аудиты — тоже источник задач, но с опасностью, зеркальной диалогу: не
|
||||
пять файлов из одной мысли, а сорок файлов из сорока сырых находок. Защита та
|
||||
же, что в самом ревью: кластеризация по причине, дедуп против живых и
|
||||
`REJECTED.md`, находка без свидетельства → сырьё (`research`), а не задача, и карта кластеров
|
||||
пользователю до создания файлов. Порядок, отображение серьёзности и привязка к
|
||||
целям — [references/from-review.md](references/from-review.md).
|
||||
|
||||
### Прийти в репозиторий, где задачи уже как-то ведутся
|
||||
|
||||
Разовая операция: вывести каталог задач из старой раскладки беклога, `TODO.md`,
|
||||
заметок или списка шагов роадмапа — [references/adopt.md](references/adopt.md).
|
||||
Сюда же относится переименование транслитных слагов в английские: оно делается
|
||||
**одним проходом вместе с починкой перекрёстных ссылок**, а не по одному слагу.
|
||||
|
||||
Если переводить надо не только задачи, а весь `docs/` — это скилл
|
||||
`av-dev:doc-canon`, и он зовёт этот сценарий сам на своём шаге.
|
||||
|
||||
### Декомпозиция и штурм сырья
|
||||
|
||||
[references/split.md](references/split.md). Обе операции превращают одну запись в
|
||||
несколько, и у обеих есть проверяемый тест: части должны **мерджиться порознь** и
|
||||
**каждая давать видимую пользу**, а у штурма исход «выкинуть» — полноправный.
|
||||
|
||||
Там же **шов**: где резать, когда допустимых мест несколько. Коротко — по
|
||||
границе, которая одна поднимает метку ревью выше остальных; и не резать, когда
|
||||
обе половины остаются в одной метке, потому что несокращаемый костяк проверок
|
||||
платится за каждую задачу отдельно.
|
||||
|
||||
### Вычитка: два прохода, а не один
|
||||
|
||||
Записи судит **не тот агент, который их написал**: самопроверка текста слабее
|
||||
всего ровно там, где формулировка казалась удачной при написании. Проходов два,
|
||||
и они разные по природе:
|
||||
|
||||
| Проход | Что смотрит | Над чем работает |
|
||||
| --- | --- | --- |
|
||||
| `task-form` | заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность оракулов, предписание процесса, связь со строкой «Завершения» цели | только `items/`, **открывает файл цели** |
|
||||
| `task-wording` | залог и отглагольные, оценка без факта, стоп-слова, англицизмы, жаргон, неизвестный термин, транслит в слаге | `items/` и строки индексов; документы проекта — только как словарь |
|
||||
|
||||
Разделены они не по охвату, а **по глубине**. Язык проверяется по словам и
|
||||
фразам, поштучно; форма записи требует понять, что задача делает, и открыть
|
||||
цель, на которую она ссылается. Слитый проход одну половину делает дорогой, а
|
||||
вторую — поверхностной.
|
||||
|
||||
Модель у обоих одна, `sonnet`, и это не отменяет разреза. Оба судят по
|
||||
**записанному правилу** — семь пунктов формы против правил языка, — а их находка
|
||||
приходит готовой формулировкой, которую читает и отклоняет человек, а не молча
|
||||
реализует оркестратор. Ошибка здесь стоит строки чтения, и платить за неё верхней
|
||||
моделью не за что.
|
||||
|
||||
Каждый устав отказывается от чужой половины прямо: увиденное не по своей части
|
||||
идёт **строкой в границах покрытия**, а не находкой. Две проверки одного места
|
||||
расходятся и начинают спорить, и разнимать их потом дороже, чем не сводить.
|
||||
|
||||
**Порядок — сперва `task-form`.** Его находки меняют решение «брать или не
|
||||
брать», а язык — только цену чтения; и переписанный заголовок бессмысленно
|
||||
вычитывать до того, как он переписан.
|
||||
|
||||
Зовутся они **пачкой, а не на каждую запись**: после заведения нескольких задач,
|
||||
после разбора находок ревью, после того как чужая работа уточнила записи (так
|
||||
делает разведка в `av-dev:code-resolve`), и на переоценке. Передаётся список файлов и — если
|
||||
есть — паспорт, архитектура и конвенции проекта: по ним отличается неизвестный
|
||||
термин от известного.
|
||||
|
||||
Ни один из них ничего не правит. Оба возвращают готовые формулировки, и их
|
||||
подставляет скилл: заголовок — `edit <слаг> --title …`, «зачем» —
|
||||
`edit <слаг> --why …`, остальное редактором. **Заголовок и «зачем» — это то, по
|
||||
чему задачу выбирают, поэтому менять их молча нельзя**: покажи предложенное
|
||||
пользователю вместе с тем, что было. Правки в теле (границы, критерии, язык)
|
||||
применяются сразу.
|
||||
|
||||
Всё, что ловит `tasks.py check`, оба не трогают намеренно.
|
||||
|
||||
### Гигиена полей
|
||||
|
||||
Правится по ходу любой операции, которая задачи касается (но не «заодно» по
|
||||
всему беклогу):
|
||||
|
||||
- **протухшее «зачем»** — задача изменилась, а поле отвечает на старый вопрос;
|
||||
особенно после ответа на вопрос задачи: «Решено: …» на «почему это лежит в
|
||||
беклоге» уже не отвечает. Переписывается `edit <slug> --why …` — он правит
|
||||
мету файла и строку индекса заодно;
|
||||
- **вопрос, застрявший в прозе** — вынимается в раздел «Вопросы» плюс тег
|
||||
`question` (`edit --add-tag question`), иначе он не виден ни `list
|
||||
--questions`, ни правилу «задача с открытым вопросом в работу не берётся»;
|
||||
- **тег, который некому снять** — `question` после ответа снимается `edit
|
||||
--rm-tag question` вместе с записью ответа в тело **и опустошением раздела
|
||||
«Вопросы»**: судит раздел, а не тег (`references/task-format.md`);
|
||||
- **свойство репозитория в рамках** — номер миграции, хеш, версия зависимости:
|
||||
в лежалой задаче протухает молча и становится ложной рамкой. Снимается;
|
||||
снимок берётся при постановке, а не при заведении;
|
||||
- **предписание процесса в теле** — «делать с такой-то меткой ревью», «взять
|
||||
такой-то агент»: это второй дом для правила выбора и путь понизить требования
|
||||
решением, принятым до проектирования. Снимается;
|
||||
- **тип, разошедшийся с задачей** — задача заводилась починкой, а после разбора
|
||||
оказалось, что поведение никогда и не было заявлено: это `feature`, а не `fix`.
|
||||
Правится `edit <slug> --type …`; тип, оставшийся от прошлой формулировки, врёт
|
||||
ровно там, где по нему отбирают, **и требует не тех разделов**: у брошенного
|
||||
`fix` останется «Воспроизведение», которого нечем заполнить;
|
||||
- **сырьё, у которого появился вопрос** — разведка обросла формулировкой, но
|
||||
раздел «Вопрос» так и пуст: она числится сырьём и в работу не берётся.
|
||||
Записывается вопрос, и `check --fix` поднимает строку из конца категории;
|
||||
- **границы, названные вместо реализации** — «переписать хранилище на новый
|
||||
драйвер» в разделе «Затрагивает» это не граница, а замысел. Границы —
|
||||
`таблица points и её миграция`, `эндпоинт POST /ingest`, `формат отпечатка на
|
||||
диске`. Переписывается перечнем;
|
||||
- **англицизм и термин из ниоткуда** — правится по ходу той же операции, что
|
||||
касается задачи (см. «Как написана задача»). Именно по ходу: беклог не
|
||||
переписывают ради языка.
|
||||
|
||||
## Переносимость
|
||||
|
||||
Скилл независим от **языка программирования, сборки, CI и трекера**: он ничего
|
||||
не знает ни про Go, ни про npm, ни про конкретный багтрекер — задачи для него
|
||||
просто каталог markdown. Текст задач — русский (язык документации проекта);
|
||||
зашита только латиница слага. OpenSpec ему тоже не нужен.
|
||||
|
||||
- **Каталог задач — `tasks/` в корне, жёстко**, и `--dir` передаётся явно всегда:
|
||||
раскладка канона одинакова во всех проектах, и искать больше нечего. Каталога
|
||||
нет — код 3 и вопрос человеку; `init` заводит его **только** когда проект
|
||||
действительно новый, а перевод чужой раскладки делает `av-dev:doc-canon`.
|
||||
У скрипта поиск вверх по дереву ещё жив — он для непереведённых проектов, и
|
||||
полагаться на него скилл не должен: молча найденный чужой каталог это дрейф.
|
||||
- **Версия формата и настройки живут в `<каталог задач>/.tasks.json`** — свой
|
||||
файл у своего плагина: ключ `tasks` с версией формата плюс **имена** файлов и
|
||||
заголовков, и последние — только если отличаются от умолчания. Неизвестный
|
||||
ключ — код 3 на любой команде, так что лишнее слово в этом объекте
|
||||
останавливает работу с задачами целиком.
|
||||
|
||||
Дом именно свой, а не `docs/.docs.json`, потому что `docs/` принадлежит
|
||||
плагину канона: проект, поставивший учёт работ без него, каталога `docs/` не
|
||||
имеет вовсе. Прежний ключ `tasks` в `docs/.pm.json` читается, **только когда
|
||||
своего файла нет** — для проектов, заведённых до раскола плагинов; скрипт при
|
||||
этом говорит замечанием, куда его перенести. Есть оба — побеждает свой, и об
|
||||
этом тоже говорится вслух: молча выбранный из двух конфиг это дрейф. Версию
|
||||
прежний дом не знает и знать не может — она читается только из своего файла.
|
||||
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
|
||||
и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет** —
|
||||
второй список разошёлся бы с заголовками молча.
|
||||
|
||||
### Вызов из другого плагина
|
||||
|
||||
`$CLAUDE_PLUGIN_ROOT` раскрывается **только внутри своего плагина**: конвейер
|
||||
задачи, конвейер ревью и любой другой чужой контекст до `tasks.py` по этой
|
||||
переменной не дотянутся. Мост — **вызов скилла через пространство имён**, а не
|
||||
путь:
|
||||
|
||||
> Чужой контекст зовёт `Skill av-dev:task-track` и называет, что нужно сделать
|
||||
> («закрой задачу `<слаг>`, реализована»). Скилл разрешает свой
|
||||
> `$CLAUDE_PLUGIN_ROOT` сам. Путь наружу не выносится вовсе.
|
||||
|
||||
Плагина в проекте нет — вызов не разрешится, и вызывающий **не выдумывает путь и
|
||||
не правит индекс руками**, а сообщает в докладе, что учёт задач остаётся за
|
||||
владельцем.
|
||||
|
||||
## Слоты проекта
|
||||
|
||||
Почти всё, что скиллу нужно знать о проекте, отвечает канон структурой: куда
|
||||
переезжает суть реализованной задачи — `openspec/specs`, `adr/`, архив change;
|
||||
какие в проекте оракулы — семантика гейта в `CLAUDE.md`. Отдельными слотами
|
||||
остаётся то, чего из раскладки не вывести. **Проект дописывает в `CLAUDE.md`**:
|
||||
|
||||
1. **Что такое «сделана»** — чем задача выполняется (конвейер проекта) и что
|
||||
входит в его определение сделанного. Скилл требует лишь **форму**: конвейер
|
||||
проекта пройден + критерии приёмки проверены поимённо.
|
||||
2. **Что считается необратимым** и потому спрашивается у человека всегда
|
||||
(деплой, выкладка наружу, удаление или перезапись данных).
|
||||
|
||||
Ни того ни другого скилл не угадывает: не нашёл — спрашивает пользователя, а не
|
||||
подставляет умолчание.
|
||||
|
||||
## Общее для всех сценариев
|
||||
|
||||
- **Развилки — пользователю.** Через `AskUserQuestion`, с уже сформулированным
|
||||
предварительным суждением (**рекомендация — первым вариантом**). Что выкинуть,
|
||||
под какую цель отнести, какая рамка разведки верна — решение пользователя. Слаг,
|
||||
формулировка, порядок строк в индексе — механика, делаем сами.
|
||||
- **Не больше трёх вопросов за раз.** Пачка длиннее трёх тяжела для ответа;
|
||||
решений больше — веди **несколько итераций** диалога по ≤3, а не один
|
||||
перегруженный запрос. Между итерациями применяй уже решённое.
|
||||
- **Границы покрытия в отчёте.** Любая сессия разбора, штурма или интейка
|
||||
заканчивается строкой «просмотрено N из M, не трогали — …». Отчёт без неё
|
||||
сообщает «беклог разобран», не сообщая, какая его часть осталась нетронутой.
|
||||
- **Ничего не удаляем молча.** Файл исчезает только через `close` — `--reason`
|
||||
(ушла без реализации) или `--implemented` (реализована). Прямого `rm` нет.
|
||||
- **Слаги английские**, kebab-case, не транслит: `tie-break-equal-completeness`,
|
||||
а не `taj-brejk-pri-ravnoj-polnote`. Заголовки, тела и «зачем» — русские.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
Не пишет код, не заводит спеки и предложения об изменении, не берёт задачу в
|
||||
работу — этим занимается конвейер проекта. **Не ведёт очередь:** что делать
|
||||
следующим и что перестало быть важным — скилл `groom`, а этот даёт ему операции.
|
||||
Не решает за пользователя, что важно. Не
|
||||
переоформляет существующие задачи «заодно»: правится то, чего касается операция.
|
||||
@@ -0,0 +1,130 @@
|
||||
# Адаптация каталога задач
|
||||
|
||||
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
|
||||
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
|
||||
после неё проект живёт скиллами `tasks` и `groom`.
|
||||
|
||||
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
|
||||
`av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
|
||||
форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается,
|
||||
когда переводить надо **только** задачи.
|
||||
|
||||
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
|
||||
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
|
||||
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
|
||||
шагов роадмапа проекта.
|
||||
|
||||
## Три правила, из которых всё следует
|
||||
|
||||
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
|
||||
разложилось по целям и **что не разложилось**, — и только после подтверждения
|
||||
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
|
||||
массовое заведение записей без подтверждения — самый дорогой отказ, потому
|
||||
что разгребает его потом переоценка.
|
||||
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
|
||||
сохраняются, кладбище переносится строка в строку. Переименование слага —
|
||||
не правка, а **перенос ссылок**: он делается одним проходом вместе с
|
||||
переименованием, иначе останутся битые ссылки, которых никто не проверяет.
|
||||
3. **Что не классифицировалось — назвать поимённо.** Проглоченный пункт
|
||||
выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад
|
||||
целиком, с причиной по каждому пункту.
|
||||
|
||||
## Форма: карта — суждение — запись
|
||||
|
||||
Механику несёт `tasks.py adopt`, суждение — ты. Разделено ровно по границе
|
||||
«машина умеет / не умеет»:
|
||||
|
||||
```
|
||||
tk="$CLAUDE_PLUGIN_ROOT/skills/tasks/scripts/tasks.py"
|
||||
|
||||
python3 $tk adopt scan --from docs/backlog docs/plan.md TODO.md \
|
||||
--target tasks --out tasks-adopt-plan.json # только чтение
|
||||
python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
||||
--refs docs openspec CLAUDE.md README.md # запись
|
||||
```
|
||||
|
||||
`scan` ничего не пишет, кроме карты: он распознаёт раскладку, собирает записи,
|
||||
поля «зачем», причины, кладбище, помечает похожее на транслит и на открытый вопрос в
|
||||
прозе, и **называет поимённо** то, что не разложилось. `apply` пишет каталог
|
||||
целиком одним проходом и чинит перекрёстные ссылки.
|
||||
|
||||
Между ними — твоя работа, которую машина не сделает:
|
||||
|
||||
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
||||
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
||||
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
||||
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
|
||||
обоснование у них уже есть); тематические скопления задач — цели в
|
||||
**`Направления`** («прочность слияния»,
|
||||
«журнал и пересборка»). Предлагаешь ты, назначает человек;
|
||||
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
||||
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
||||
|
||||
## Порядок
|
||||
|
||||
1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
|
||||
всегда `tasks`. Секции беклога (`--sections`) — по умолчанию
|
||||
`Ядро,Инфра`; если у проекта деление другое по существу, оно называется
|
||||
здесь, а не подгоняется под умолчание, и становится **заголовками `##`
|
||||
индекса** — их единственным домом. В `.tasks.json` секции не пишутся: там
|
||||
версия формата и имена частей, а второй список секций разошёлся бы с
|
||||
заголовками молча.
|
||||
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
|
||||
прохода дадут два несогласованных состояния.
|
||||
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
|
||||
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
|
||||
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
|
||||
работоспособности, а не направлению; у `feature` цель обязательна.
|
||||
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
||||
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
|
||||
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
|
||||
разложилось». Массовые механические решения (слаги, порядок строк) не
|
||||
выносятся — это механика.
|
||||
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
|
||||
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
|
||||
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
|
||||
6. **`tasks.py check`** и доклад.
|
||||
|
||||
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
|
||||
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
|
||||
всё это отказ до того, как на диске появился хотя бы один файл.
|
||||
|
||||
## Переходное состояние — объявляется, а не заминается
|
||||
|
||||
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
|
||||
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
|
||||
быть названо, иначе следующий агент примет пустой беклог за поломку.
|
||||
|
||||
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
|
||||
`check`) и сколько не собрало разделы своего типа (для `check` это не ошибка, а
|
||||
строка здоровья, но `ready` такую задачу не пропустит). Закрывается это
|
||||
**порциями груминга** — скилл
|
||||
`groom`, 5–8 задач за порцию: проставить цели, превратить «готово, когда» в
|
||||
критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». Там же
|
||||
беклогу впервые назначается **порядок**: после адаптации его нет вовсе, а
|
||||
очередь и есть то, ради чего каталог заводят.
|
||||
|
||||
Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
|
||||
верхние строки очереди».
|
||||
|
||||
## Чего адаптация не делает
|
||||
|
||||
- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
|
||||
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
|
||||
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)` —
|
||||
цель поправлена, текст остался; это правится глазами, и таких мест немного.
|
||||
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
|
||||
нет. Придуманная цель хуже отсутствующей: под неё заведут задачи.
|
||||
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
|
||||
- Сколько записей перенесено, сколько целей заведено (порядок / темы) и откуда
|
||||
каждая выведена.
|
||||
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
|
||||
файлах — числом, а не «поправлены ссылки».
|
||||
- **Не разложилось**: поимённо, с причиной.
|
||||
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
|
||||
сколько порций закрывается.
|
||||
- `tasks.py check` — результат строкой.
|
||||
@@ -0,0 +1,61 @@
|
||||
# Журнал версий формата задач
|
||||
|
||||
Одна запись на версию. Проект знает свою версию из ключа `tasks` в `<каталог
|
||||
задач>/.tasks.json`; повышение (`upgrade` в [SKILL.md](../SKILL.md), раздел
|
||||
«Версия формата») идёт по записям снизу вверх от версии проекта до текущей и
|
||||
делает то, что в них названо.
|
||||
|
||||
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
||||
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
||||
повышение.
|
||||
|
||||
Версия — целое число. Обратной совместимости у формата нет: есть «приведён» и «не
|
||||
приведён».
|
||||
|
||||
**Это журнал формата задач, а не канона документов.** Числа у них разные и
|
||||
двигаются порознь: плагин `av-dev-tasks` ставится в одиночку, и у проекта без
|
||||
`av-dev-docs` версии канона нет вовсе. Журнал канона —
|
||||
`references/changelog.md` скилла `av-dev-docs:canon`.
|
||||
|
||||
---
|
||||
|
||||
## Версия 1 — 2026-08-11
|
||||
|
||||
Первая объявленная версия формата. До неё каталог задач версии не имел вовсе:
|
||||
формат менялся, а сказать, к какому его состоянию приведён конкретный проект,
|
||||
было нечем — `tasks.py` о расхождении молчал, и отставший каталог выглядел
|
||||
здоровым ровно до первой команды, которая об него спотыкалась.
|
||||
|
||||
**Что появилось.** Ключ `tasks` в `<каталог задач>/.tasks.json` — целое число,
|
||||
версия формата. Сам файл стал **обязательным**: до сих пор он заводился только
|
||||
ради имён, отличных от умолчания, и проект с умолчаниями жил без него. Версия —
|
||||
не настройка, от которой можно отказаться, поэтому `init` и `adopt apply` теперь
|
||||
пишут файл всегда, а `check` требует числа и сверяет его со своим.
|
||||
|
||||
**Что версия значит, а что нет.** Она отвечает на один вопрос — «по какой записи
|
||||
журнала повышать каталог». Что записи применены **по существу**, из числа не
|
||||
следует: двигают его руками, и соврать им так же легко, как любой другой
|
||||
строкой. `check --fix` недостающее число не приписывает намеренно — это было бы
|
||||
объявлением каталога приведённым к формату, шагов которого никто не делал.
|
||||
|
||||
**Чего в этой записи нет.** Переезды, случившиеся до появления числа, — каталог
|
||||
из `docs/` в корень (канон 11) и отмена спринтов (канон 12) — задним числом сюда
|
||||
не переписаны. Они уже названы журналом канона, и второй перечень тех же шагов
|
||||
разошёлся бы с первым. Версия 1 — это формат на день её появления, что бы
|
||||
проекту ни пришлось пройти до неё.
|
||||
|
||||
**Что сделать проекту.**
|
||||
|
||||
1. **Догнать формат по журналу канона, если каталог отстал.** Признаки известны
|
||||
поимённо: каталог лежит в `docs/tasks/` (канон 11 велит `git mv docs/tasks
|
||||
tasks` и починку относительных ссылок внутри записей), в нём есть `SPRINT.md`
|
||||
или теги `sprint:<слаг>` (канон 12 велит снести файл, вернуть строки в беклог
|
||||
через `check --fix` и расставить порядок грумингом). Ничего из этого нет —
|
||||
каталог уже в сегодняшнем формате, и шаг пропускается.
|
||||
2. **Завести `<каталог задач>/.tasks.json`**, если его нет. Имена частей в него
|
||||
не переписываются: там только то, что отличается от умолчания.
|
||||
3. **Записать версию**: `"tasks": 1` первым ключом.
|
||||
4. `tasks.py check --dir <каталог задач>` — до отсутствия расхождений.
|
||||
|
||||
**Что при этом не трогается.** Записи в `items/`, индексы и `REJECTED.md` не
|
||||
меняются ни строкой: версия 1 объявляет то, что уже есть, а не переделывает его.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Задачи из аудита и ревью
|
||||
|
||||
Ревью и аудиты — код-ревью, архитектурный проход, аудит безопасности, любой
|
||||
разбор другим агентом — порождают находки, часть которых становится задачами.
|
||||
Это отдельный интейк со своей опасностью, **зеркальной** интейку из диалога.
|
||||
|
||||
- Интейк из диалога грешит переполнением: из одной мысли рождается пять файлов.
|
||||
- Интейк из ревью грешит сваливанием: сорок сырых находок превращаются в сорок
|
||||
файлов. Беклог раздувается, а следующая переоценка склеивает их обратно.
|
||||
|
||||
Защита от сваливания — та же, что в самом ревью: **кластеризация по причине, а
|
||||
не файл-на-находку.** Если у ревью был триаж — половина работы уже сделана, бери
|
||||
его выход. Если нет — триажируй сам, прежде чем заводить.
|
||||
|
||||
**Штатный отправитель — `av-dev:code-review`** (и `av-dev:code-resolve`, который
|
||||
его вызывает): задач он не заводит сам, а отдаёт отложенные находки **списком
|
||||
урожая** — формулировка, оракул, провенанс — и хранит отчёт триажа вместе с
|
||||
изменением. Приходит и любой другой разбор, вплоть до пересказа человеком; тогда
|
||||
триажа нет и шаг 1 порядка делается руками.
|
||||
|
||||
## Находка агента — не задача
|
||||
|
||||
Мнение агента — **гипотеза, пока у неё нет свидетельства** (падающий тест,
|
||||
воспроизводимый шаг, положение руководства). Согласие нескольких находок само по себе
|
||||
достоверность не повышает: это один источник, высказавшийся несколько раз.
|
||||
|
||||
Отсюда фильтр входа, поверх обычного «не делаем сейчас + пожалеем о потере»:
|
||||
|
||||
- **Находка со свидетельством**, отложенная к исполнению → **задача**.
|
||||
Свидетельство и последствие переносим в тело — это её «почему», то самое, что
|
||||
переживает запись.
|
||||
- **Находка без свидетельства / низкой уверенности** → **сырьё**: `research`, у
|
||||
которого раздел «Вопрос» и есть недостающее свидетельство («при каких условиях
|
||||
это воспроизводится»). Не `fix`: без `Воспроизведения` его в работу не
|
||||
возьмут, и правильно — чинить нечего, пока непонятно, что ломается. Судьба
|
||||
сырья — штурм, где либо найдётся подтверждение, либо оно уедет в
|
||||
`REJECTED.md`.
|
||||
- **Уже починено по ходу ревью** → **ничего**. Починенное не заводим.
|
||||
- **Развилка, решённая при ревью** → ничего; решённая «потом» → задача с
|
||||
вопросом в разделе «Вопросы» и тегом `question`.
|
||||
|
||||
## Порядок
|
||||
|
||||
1. **Возьми выход триажа, а не сырые находки.** Сырой отчёт — это симптомы до
|
||||
дедупликации; в нём одна причина размазана по нескольким строкам.
|
||||
2. **Кластеризуй по причине.** Пять находок об одном отсутствующем инварианте —
|
||||
одна задача, а не пять. Класс мелочи (nits, косметика) — **один пакетный
|
||||
файл** со списком пунктов, а не файл на каждую запятую.
|
||||
3. **Дедуп против живых задач и `REJECTED.md`.** Аудит переоткрывает уже
|
||||
заведённое и уже выкинутое. Нашлось среди живых — дописываем находку в
|
||||
существующий файл. Нашлось в `REJECTED.md` — это сигнал: причина отказа могла
|
||||
устареть, выноси пользователю, а не заводи молча заново.
|
||||
4. **Разложи по целям — там, где цель нужна.** Большинство находок ревью это
|
||||
`fix` и `chore`, и **цель им не требуется**: они служат работоспособности, а
|
||||
не направлению. Придуманная им цель —
|
||||
ровно то враньё, от которого спасает тип.
|
||||
|
||||
Цель обязательна у находки, которая оказалась **новой возможностью**
|
||||
(`feature`): нашлось поведение, которого никто не заказывал, и его надо
|
||||
либо заказать целью, либо убрать. Подходящей цели нет — заведи её
|
||||
(`add --type goal --section Направления`) в том же проходе.
|
||||
5. **Покажи карту до создания файлов.** Кластер → задача / сырьё / строка в
|
||||
пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через
|
||||
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
|
||||
диалога: массовое заведение файлов без подтверждения — ровно тот отказ, ради
|
||||
которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может
|
||||
заводиться и без поштучного вопроса — но карта пользователю предъявляется
|
||||
всё равно.
|
||||
6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
|
||||
- **тег партии** — `--tag review-ГГГГ-ММ-ДД` (или `audit-<slug>`), чтобы весь
|
||||
заход разбора поднимался одной командой `list --tag …`;
|
||||
- **тип** — `--type`, и он **не по умолчанию `fix`**: починкой считается
|
||||
расхождение с заявленным поведением, а находка «этого свойства никто не
|
||||
заказывал» — это `feature`, находка «не знаем, как поведёт себя драйвер» —
|
||||
`research`. Тип, розданный оптом, врёт ровно там, где по нему потом
|
||||
отбирают, **и требует не тех разделов**: каждому `fix` придётся заполнить
|
||||
`Воспроизведение`, а у находки без свидетельства его нет;
|
||||
- **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством.
|
||||
Без него через месяц не отличить проверенную находку от догадки.
|
||||
7. `tasks.py check`.
|
||||
|
||||
## Куда девается серьёзность находки
|
||||
|
||||
Уровня серьёзности в записи нет — но **выкидывать её нельзя**: серьёзность
|
||||
отображается **в позицию в очереди**, потому что приоритет и есть порядок строк
|
||||
в беклоге (правило 4 [SKILL.md](../SKILL.md)). Отображается через довод, а не
|
||||
напрямую: своей шкалы у интейка нет, доводы расстановки перечислены в
|
||||
[скилле груминга](../../groom/SKILL.md#приоритет-как-его-расставляют), и
|
||||
серьёзность попадает ровно в один из них.
|
||||
|
||||
- **тяжёлая находка со свидетельством о сломанном сейчас** → задача под ту цель,
|
||||
которой она угрожает, и **первой строкой секции**: `move <слаг> --first
|
||||
--reason «сломано сейчас: …»`. Это довод «что сломано сейчас» из перечня
|
||||
груминга — единственный, который не требует сравнения с соседями по очереди,
|
||||
потому что сломанное дорожает само. Позицию всё равно назначает человек, и
|
||||
здесь он её уже назначил: верх очереди для такой находки предъявляется картой
|
||||
шага 5, а не проставляется молча;
|
||||
- **тяжёлая находка о риске, а не о поломке** (дорожает от ожидания,
|
||||
разблокирует остальное) → в конец секции, а довод — причиной в мете
|
||||
(`--reason`). Позицию назначит человек на ближайшем груминге, сравнив её с
|
||||
верхом очереди; без записанного довода сравнивать он будет с нуля;
|
||||
- **находка, которая не ждёт груминга вовсе** (необратимый ущерб, покраснела
|
||||
проверка, которую проект назвал сломанным), — не интейк: это работа прямо
|
||||
сейчас, а в беклог она падает, только если ждать всё-таки можно;
|
||||
- **низкая уверенность или нет свидетельства** → сырьё (`research` с пустым
|
||||
разделом «Вопрос»): его место в очереди производно от типа — конец секции;
|
||||
- **мелочь** → строка в пакетный файл;
|
||||
- **уже починено / развилка решена сейчас** → ничего.
|
||||
|
||||
Словарей серьёзности много, и отображать их механически не на что: при сомнении
|
||||
— вопрос пользователю, а не догадка.
|
||||
|
||||
## Поимённая сверка
|
||||
|
||||
Интейк считается выполненным, только если **каждая** находка триажа получила
|
||||
исход: слаг заведённой задачи, ссылку на существующую, строку пакетного файла
|
||||
или запись «не заведена: причина». Нулевой урожай при непустом отчёте триажа
|
||||
виден сразу — и это единственный способ отличить «находок не было» от «не стал
|
||||
заводить». Список составляет не тот, кто отчитывается о заведении.
|
||||
|
||||
Границы покрытия отчёта — то, что ревью проверить **не смогло**, — не находки и
|
||||
в задачи не идут: у них нет предмета. Их место в докладе, не в беклоге.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Источник (какое ревью/аудит, сколько находок на входе).
|
||||
- Свёрнуто в задачи: N кластеров из M находок, со слагами, целями и тегом партии.
|
||||
- Что не заведено и почему: починено инлайн, уже заведено, стало сырьём, ушло в
|
||||
`REJECTED.md`.
|
||||
- Поимённая сверка: находок на входе N, исход есть у N.
|
||||
- `tasks.py check`.
|
||||
@@ -0,0 +1,213 @@
|
||||
# Язык проектных текстов
|
||||
|
||||
**Копия.** Дом — `shared/language.md` в репозитории плагинов; язык общий для
|
||||
документов канона и для задач, и потому не принадлежит ни одному плагину.
|
||||
Правится дом, а не этот файл: расхождение ловит `copies.py` на гейте коммита.
|
||||
|
||||
<!-- копия: язык-доктрина из av-dev/shared/language.md -->
|
||||
|
||||
Правила — для всего, что пишется словами: задачи и цели, документы канона,
|
||||
решения ADR, записки разведки, сообщения коммитов. Не для кода и не для
|
||||
сообщений программы пользователю — там свои конвенции проекта.
|
||||
|
||||
Основа — **информационный стиль** Максима Ильяхова ([учебник
|
||||
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
|
||||
написан для рекламы, статей и писем, поэтому взят не целиком.
|
||||
|
||||
## Зачем он здесь
|
||||
|
||||
Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
|
||||
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
|
||||
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
|
||||
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
|
||||
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
|
||||
а это и есть цена, которой мы избегаем.
|
||||
|
||||
## Что взято сверх правил вычитки
|
||||
|
||||
Эти три требования судит человек, а не проход вычитки: находка по ним требует
|
||||
увидеть текст целиком, а не фразу.
|
||||
|
||||
**Полезное действие.** У каждого текста есть вопрос, на который он отвечает, и
|
||||
читатель, который этот вопрос задаёт. Не отвечает — не пишется. У задачи это
|
||||
«зачем она нужна» и «что станет наблюдаемо иначе»; у документа канона — его
|
||||
собственный вопрос («что это за система», «как сложено», «почему так решили»).
|
||||
Текст, который не отвечает ни на чей вопрос, сокращается до нуля — это законный
|
||||
исход правки.
|
||||
|
||||
**Параллельность.** Однородное пишется одинаково: пункты списка — одной
|
||||
грамматической формой, разделы одного вида — одним порядком, заголовки одного
|
||||
уровня — одним типом фразы. Разнобой читатель принимает за разницу по существу и
|
||||
ищет её.
|
||||
|
||||
**Заголовок работает.** Заголовок называет содержание раздела, а не тему
|
||||
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
|
||||
столько, чтобы длинный текст можно было просматривать, а не только читать
|
||||
подряд.
|
||||
|
||||
## Что отброшено намеренно
|
||||
|
||||
Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
|
||||
читают потому, что надо, и держать его нечем. Отсюда три расхождения:
|
||||
|
||||
- **Парцелляция и рубленые фразы — нет.** Приём «Коротко. Ещё короче. Вот так»
|
||||
ломает причинную связь, а в решении и в задаче ценность именно в ней:
|
||||
«поэтому», «иначе», «раз так» несут смысл и остаются.
|
||||
- **Не всякое вводное — мусор.** «Если», «иначе», «при таком-то условии»,
|
||||
«в отличие от» — это условия и противопоставления, то есть сведения. Режутся
|
||||
вводные, которые не меняют смысл предложения.
|
||||
- **Скобки и точка с запятой остаются.** В технической записи скобки несут
|
||||
уточнение — имя команды, единицы, слаг, — и запрет на них удлинил бы текст, а
|
||||
не сократил. Запрет на многоточие принимаем: в проектном тексте оно значит
|
||||
«дописать позже», и такой текст лучше не публиковать.
|
||||
|
||||
И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
|
||||
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
|
||||
значит называть состояние и остаток, а не пересказывать, как было интересно
|
||||
разбираться.
|
||||
|
||||
<!-- /копия: язык-доктрина -->
|
||||
|
||||
## Правила
|
||||
|
||||
<!-- копия: язык-правила из av-dev/shared/language.md -->
|
||||
|
||||
У каждого правила названа причина: она же говорит, где правило **не**
|
||||
применяется.
|
||||
|
||||
1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
|
||||
не проверяет владельца», а не «проверка владельца не осуществляется»;
|
||||
«скрипт переписывает индекс», а не «индекс переписывается скриптом».
|
||||
Отглагольное существительное прячет того, кто действует, — а в техническом
|
||||
тексте важен именно он. Страдательный залог **остаётся**, когда деятель
|
||||
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
|
||||
команд.
|
||||
|
||||
2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
|
||||
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
|
||||
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
|
||||
факта это настроение, а не сведение, — и находка тем ценнее, что оценку
|
||||
потом не проверить.
|
||||
|
||||
3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
|
||||
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
|
||||
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
|
||||
синонимы одного качества («понятный и простой»), неопределённое
|
||||
(соответствующий, определённый, некоторый).
|
||||
|
||||
Проверка одна: **вычеркни слово — смысл изменился, оставляй.** И осторожно с
|
||||
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
|
||||
условие и противопоставление, то есть сведения, — их не трогают.
|
||||
|
||||
4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
|
||||
утверждениями делится. **Причинную связь не режут**: «поэтому», «иначе», «раз
|
||||
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
|
||||
|
||||
**Поля меты не делятся.** «Зачем» в мете задачи по формату — одно
|
||||
предложение: оно повторяется строкой индекса, и второму там не поместиться.
|
||||
Тесно — сокращают, но не делят. То же с любым полем вида `- **Имя:** …`.
|
||||
|
||||
5. **Англицизм, у которого есть живое русское слово, заменяется.**
|
||||
|
||||
| Калька | Русский аналог |
|
||||
| --- | --- |
|
||||
| флоу | поток, процесс, сценарий |
|
||||
| фикс, зафиксить | исправление, исправить, починить |
|
||||
| чекать | проверять |
|
||||
| апрув, заапрувить | согласование, согласовать |
|
||||
| best-effort | по возможности |
|
||||
| кейс | случай, сценарий |
|
||||
| перформанс | производительность |
|
||||
| матчинг, смэтчить | сопоставление, сопоставить |
|
||||
| зарелизить | выпустить, выложить |
|
||||
| отрефакторить | переписать, разделить, убрать второй путь |
|
||||
|
||||
Насильно не переводится то, что является **именем вещи**: термины технологий
|
||||
и протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов,
|
||||
полей, таблиц и команд, слаг, а также термин, у которого нет точного русского
|
||||
эквивалента и который в команде уже прижился.
|
||||
|
||||
Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
|
||||
искажает смысл — остаётся термин.
|
||||
|
||||
6. **Слово из своего словаря не трогается — список закрыт.** Оговорка «термин
|
||||
прижился» без списка проверяема на глаз и потому не проверяема: прижившимся
|
||||
выглядит любое слово, встреченное трижды.
|
||||
|
||||
| Термин | Что называет |
|
||||
| --- | --- |
|
||||
| интейк | заведение записи с фильтром и дедупом: «заведение» называет создание файла, слить их — смешать две операции |
|
||||
| триаж | стадия конвейера, сводящая находки в решение |
|
||||
| провенанс | обязательное свойство числа: чем и при каких условиях получено. «Источник» рядом называет саму запись, а не свойство |
|
||||
| дедуп, дедупликация | сверка нового против уже лежащего |
|
||||
| чек-лист | перечень, по которому идут сверху вниз, называя исход каждой строки |
|
||||
| дифф, `--base` | разница между состояниями в git |
|
||||
| промпт | текст, которым зовут модель |
|
||||
| change, capability, spec | сущности OpenSpec, имена вещей чужого инструмента |
|
||||
| generative, applicative | роды проходов ревью, вводятся определением по месту |
|
||||
| чекпоинт | плановый стоп работы, на котором ждут ответа человека. «Остановка» называет любой перерыв, «согласование» — обряд одобрения, а здесь место в процессе, назначенное заранее |
|
||||
| синк | сверка каждого документа канона с только что сделанной работой, с обязательным отрицанием по нетронутым. «Обновление документации» называет исход, а не работу, и молчит о принуждённом отрицании |
|
||||
|
||||
**Список закрыт.** Слово не отсюда и не из таблицы имён вещей выше — находка,
|
||||
а не «принятый стиль»: у него либо есть живой русский аналог, либо оно
|
||||
требует ввода одной строкой при первом употреблении.
|
||||
|
||||
Отсюда же читается снятое. Эти слова из текстов убраны, и возвращать их не
|
||||
надо: **конфляция** (смешение), **декорреляция** (разведённость, разведён с
|
||||
кем-то), **непоймание** (почему не поймали), **эвал-сет** (проверочный
|
||||
набор), **гайд** (руководство), **опиниативный** (проход с мнением). Каждое
|
||||
было латинизмом или калькой при живом русском слове, и каждое к моменту снятия
|
||||
жило в трёх-шести файлах разом — то есть выглядело словарём, не будучи им.
|
||||
|
||||
7. **Жаргон и метафоры заменяются прямым называнием.** Автору образ понятен,
|
||||
читателю — нет.
|
||||
|
||||
| Метафора-жаргон | Прямо |
|
||||
| --- | --- |
|
||||
| рычаг (кэша, отбора) | условие отбора, параметр |
|
||||
| навешен не на тот счётчик | завязан не на тот счётчик |
|
||||
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
|
||||
| костыль | временное решение, обходной путь — и в чём именно |
|
||||
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |
|
||||
|
||||
Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется
|
||||
буквальным описанием того, что происходит.**
|
||||
|
||||
8. **Термин, которого нет в документах проекта, вводится одной строкой или не
|
||||
употребляется.** Термин, не встречающийся ни в паспорте, ни в архитектуре, ни
|
||||
в конвенциях, — свой словарь у отдельной записи, а это самый дешёвый способ
|
||||
сделать беклог нечитаемым для того, кто вернётся к нему через квартал.
|
||||
Заменять незнакомый термин догадкой нельзя: догадка о предметной области
|
||||
дороже непонятного слова, потому что выглядит понятной.
|
||||
|
||||
**Слово, занятое в другом смысле, — то же нарушение.** Термин, который в
|
||||
одном документе проекта значит одно, а здесь другое, ломает оба.
|
||||
|
||||
9. **Имя файла — английское слово по сути, а не транслит.** `queue-as-table`, а
|
||||
не `ochered-tablicej`; `move-parse-strict`, а не `razbor-hoda`. Транслит
|
||||
нечитаем тому, кто ищет по смыслу, и не сокращается, а имя стоит в ссылках,
|
||||
коммитах и путях, которые набирают руками. Переименование — **перенос ссылок
|
||||
одним проходом**, а не правка одного файла.
|
||||
|
||||
<!-- /копия: язык-правила -->
|
||||
|
||||
## Порог правки
|
||||
|
||||
<!-- копия: порог-правки из av-dev/shared/language.md -->
|
||||
|
||||
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
|
||||
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
|
||||
перестают читать весь список, и вместе с ним пропадают настоящие находки.
|
||||
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
|
||||
|
||||
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
|
||||
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
|
||||
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
|
||||
основание для **одной находки на весь набор** («правило N нарушено в пяти
|
||||
записях, перечень: …»), но не как основание промолчать. Принятым считается
|
||||
только то, что назвал зовущий или что записано в конвенциях проекта.
|
||||
|
||||
<!-- /копия: порог-правки -->
|
||||
|
||||
И обратное: язык правится **по ходу той операции, которая записи касается**.
|
||||
Беклог не переписывают ради языка.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Сопровождение и эксплуатация
|
||||
|
||||
**Копия.** Дом — `shared/operations.md` в репозитории плагинов. Словарь общий для
|
||||
роадмапа, архитектуры и темы ревью `operations`, и не принадлежит ни одному из
|
||||
трёх — правится дом, а не этот файл.
|
||||
|
||||
Скиллу задач он нужен для секции `Сопровождение` в `ROADMAP.md`: она отвечает не
|
||||
на «что приложение будет уметь», а на «чем его держат», и путать эти два вопроса
|
||||
нельзя.
|
||||
|
||||
<!-- копия: сопровождение-словарь из av-dev/shared/operations.md -->
|
||||
|
||||
Одна тема живёт в трёх местах, и путать их слова нельзя.
|
||||
|
||||
**Сопровождение** — всё, чем держат проект: инструмент и сборка, процесс,
|
||||
выкладка, метрики и логи, инфраструктура, дежурство. **Эксплуатация** — его
|
||||
часть: работа системы на проде. Целое и часть, и никогда наоборот.
|
||||
|
||||
| Место | Уровень | Что там |
|
||||
| --- | --- | --- |
|
||||
| `ROADMAP.md`, секция `Сопровождение` | план | **работы**, которые собираемся делать: цели и их задачи |
|
||||
| `architecture.md`, раздел «Эксплуатация» | состояние | **как устроено сейчас**: где работает, что рядом, кто перезапускает |
|
||||
| тема ревью `operations` | оптика | **чем проверяем**: «это упало через неделю на проде» |
|
||||
|
||||
Слово **«поддержка» не употребляется вовсе** — в нём слышится помощь
|
||||
пользователю, а это другая работа.
|
||||
|
||||
**Граница с возможностями проходит по тому, кто наблюдает.** «Приложение
|
||||
сообщает о своём состоянии» — возможность приложения, её место среди прочих
|
||||
целей: наблюдает пользователь сервиса. «Дежурный видит состояние на одном
|
||||
экране» — сопровождение: наблюдаем мы. Одни и те же метрики попадают в разные
|
||||
секции роадмапа, и это верно — секции отвечают на разные вопросы.
|
||||
|
||||
<!-- /копия: сопровождение-словарь -->
|
||||
@@ -0,0 +1,116 @@
|
||||
# Декомпозиция и мозговой штурм
|
||||
|
||||
Обе операции превращают одну запись в несколько (или в ноль). Разница во входе:
|
||||
декомпозиция дробит **слишком крупную задачу**, штурм прорабатывает **идею**,
|
||||
которая ещё не задача.
|
||||
|
||||
## Тест декомпозиции
|
||||
|
||||
Задачу можно дробить, только если части удовлетворяют **обоим** условиям:
|
||||
|
||||
1. **Мерджатся независимо.** Часть Б не требует, чтобы часть А была уже влита.
|
||||
Есть порядок «сперва А, потом Б, иначе не собрать» → это не декомпозиция, а
|
||||
план реализации: шаги остаются **внутри одного файла**.
|
||||
2. **Каждая — самостоятельный шаг.** Часть, осмысленная только в комплекте с
|
||||
другой, — не задача. Проверяй тестом «готова к взятию» (task-format): какую
|
||||
строку «Завершения» цели двигает **именно эта часть** и какие у неё
|
||||
собственные критерии приёмки. У операционных частей (`fix`, `chore`,
|
||||
`research`) цели может не быть — тогда достаточно собственных критериев.
|
||||
|
||||
Не проходит хотя бы одно — **не дроби**. Ложная декомпозиция плодит файлы,
|
||||
которые нельзя взять поодиночке, и переоценка потом склеивает их обратно.
|
||||
|
||||
## Где резать, если резать можно
|
||||
|
||||
Тест выше говорит, **допустим** ли разрез. Где его провести из нескольких
|
||||
допустимых мест — отвечает шов.
|
||||
|
||||
**Шов — там, где падает метка ревью.** Раздел «Затрагивает» перечисляет
|
||||
границы; если одна строка перечня поднимает метку выше остальных, эта часть и
|
||||
режется отдельно. Пример: задача перекладывает несколько узлов разом и заодно
|
||||
добавляет два поля в существующий ответ. Целиком это `large` — семь проходов по
|
||||
всему диффу, включая два, что держат машину и идут цепочкой. Разрезанная по шву,
|
||||
она даёт `large` на маленькой переложенной части и `medium` на остатке.
|
||||
|
||||
**Считай костяк, а не файлы.** У каждой задачи есть несокращаемые четыре прохода
|
||||
(гейт, спеки, код, триаж), и они платятся за каждую. Разрез, после которого обе
|
||||
половины остаются в одной метке, делает ревью **дороже**: тот же объём
|
||||
проверяется тем же составом, но костяк оплачен дважды. Отсюда правило: **резать,
|
||||
когда разрез снимает дорогой проход с большей части диффа**, и не резать, когда
|
||||
он просто делает файлы мельче.
|
||||
|
||||
**Это планирование, а не предписание процесса.** Метка ревью выбирается по
|
||||
факту изменения — тем, кто его видит, — и в тело задачи не пишется: строка
|
||||
«делать с меткой medium» это ровно тот второй дом правила выбора, который
|
||||
гигиена полей снимает. Шов пользуется меткой как **признаком**, что в задаче
|
||||
две разнородные работы; решение о метке остаётся за конвейером.
|
||||
|
||||
**Цель наследуется.** Все части несут `goal:` родителя: декомпозиция не меняет
|
||||
того, чему работа служит. Если у части цель другая — это признак, что дробили не
|
||||
по той границе, либо что часть вообще из другой работы.
|
||||
|
||||
## Что делать с родителем
|
||||
|
||||
После разделения родитель **не остаётся** третьей висящей строкой:
|
||||
|
||||
- части полностью замещают его → `close <slug> --reason "разложена на a, b"`.
|
||||
`REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись:
|
||||
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
|
||||
наследников, а не археологией git;
|
||||
- родитель осмыслен как **возможность**, а не как шаг → это цель, и **строка
|
||||
переезжает**: `edit <slug> --type goal --section <часть роадмапа>` снимает её с
|
||||
`BACKLOG.md` и вставляет в `ROADMAP.md`. Файл в `items/` при этом не двигается —
|
||||
он и есть запись. Части получают `--goal <слаг родителя>`, а закрывать родителя
|
||||
нечем и незачем: он не выкинут, он стал целью.
|
||||
|
||||
**Промежуточного зонтика между целью и задачей нет.** Тип `epic` упразднён:
|
||||
роль зонтика играет цель, а слишком крупный шаг дробится на шаги помельче под
|
||||
той же целью. Если частям нужен общий заголовок — значит у них общая
|
||||
возможность, и её надо назвать целью, а не заводить временный тип.
|
||||
|
||||
## Когда декомпозиция случается посреди работы
|
||||
|
||||
Задача, которая **оказалась крупнее задачи**, распознаётся до того, как под неё
|
||||
заведено предложение об изменении: иначе его придётся выбрасывать. Она выходит
|
||||
из работы на декомпозицию, а её строка возвращается в беклог с причиной
|
||||
(`move … --reason "крупнее задачи"`). Части заводятся сразу под той же целью, и
|
||||
**место в очереди им назначает человек**: машина поставит их в конец секции, а
|
||||
крупная задача редко распадается на что-то менее срочное, чем была сама.
|
||||
|
||||
## Мозговой штурм сырья
|
||||
|
||||
Сырьё — запись типа `research`, у которой раздел «Вопрос» пуст: она не проходит
|
||||
тест «готова к взятию», потому что неясно, что именно делаем. Штурм проясняет —
|
||||
и это **generative-операция, а не applicative**.
|
||||
|
||||
Исход штурма и есть заполненный «Вопрос» (тогда разведку можно брать в работу)
|
||||
или набор задач с типами, которые из ответа следуют. Третий законный исход —
|
||||
`close --reason`.
|
||||
|
||||
Applicative-штурм («перечисли задачи, следующие из идеи») выдаёт очевидное:
|
||||
перечисляется то, что уже видно в формулировке. Ценное — на уровень выше.
|
||||
|
||||
1. **Сперва — формы, а не задачи.** Предложи **три разные постановки** идеи и
|
||||
назови **компромисс каждой**: что она даёт, чем платит, что оставляет за
|
||||
бортом. Если получилась одна постановка — штурм не состоялся, это
|
||||
applicative.
|
||||
2. **Вынеси формы пользователю** через `AskUserQuestion` с компромиссами. Рамку
|
||||
выбирает он: это продуктовое решение, не механика.
|
||||
3. **Назови цель.** Выбранная форма служит цели — существующей или новой. Идея,
|
||||
для которой цель не находится, скорее всего уезжает в `REJECTED.md`, а не
|
||||
заводится задачей.
|
||||
4. **Только выбранную форму** дроби по тесту декомпозиции выше и проставь
|
||||
критерии приёмки: без них наследники останутся идеями под другим именем.
|
||||
|
||||
**«Выкинуть» — полноправный исход штурма, а не его неудача.** Проработка, честно
|
||||
показавшая, что пользы нет или она несоразмерна цене, — это результат: идея
|
||||
уезжает с этой самой причиной, и та причина гасит её повторное появление.
|
||||
|
||||
## Доклад
|
||||
|
||||
- Идея/задача на входе, выбранная рамка (для штурма), задачи-наследники со
|
||||
слагами, целями и секциями.
|
||||
- Судьба родителя: удалён / стал целью / выкинут с причиной.
|
||||
- `tasks.py check` после правок.
|
||||
- Границы покрытия: какие постановки рассмотрены и какие сознательно отброшены —
|
||||
чтобы штурм не пришлось повторять с нуля.
|
||||
@@ -0,0 +1,77 @@
|
||||
# 🧹 `chore` — обслуживание, наблюдаемое поведение не меняется
|
||||
|
||||
Зависимости, сборка, перенос, чистка, оснастка. Отвечает на **«что нужно
|
||||
сделать»**, глаголом в неопределённой форме.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать |
|
||||
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | нет: цель — это возможность, а здесь её не появляется |
|
||||
| Индекс | `BACKLOG.md` |
|
||||
| Берётся в работу | да |
|
||||
|
||||
## Адресат — разработчик, и это законно
|
||||
|
||||
Тест готовности спрашивает «что станет наблюдаемо иначе». У `chore` ответ
|
||||
адресован **разработчику**, а не пользователю: «перестанет собираться два раза»,
|
||||
«уедет последний вызов устаревшего API», «проверки гоняются одной командой».
|
||||
Это ответ, а не отговорка.
|
||||
|
||||
**У `chore` тест готовности слабее честно, а не молча.** Пока типа не было,
|
||||
такие задачи либо не заводились вовсе, либо формулировались как выдуманная
|
||||
пользовательская польза — и то и другое хуже, чем сказать прямо, для кого работа.
|
||||
|
||||
Отсюда же граница: если после задачи меняется то, что видит пользователь, — это
|
||||
не `chore`. Тип, оставшийся от первой формулировки, врёт ровно там, где по нему
|
||||
отбирают.
|
||||
|
||||
**Обнаружилось это уже в работе — запись переформулируется, а не дорешивается.**
|
||||
Исполнитель останавливается, называет тип, которым задача оказалась (`fix` —
|
||||
поведение расходится с заявленным, `feature` — снаружи появляется то, чего не
|
||||
было), и человек решает: сменить тип и решать процессом того типа — либо
|
||||
прекратить. Тип меняет этот скилл, а не исполнитель по ходу: у нового типа своя
|
||||
схема разделов, и `ready` проверит её заново.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Проверить, что поведение не меняется.** Меняется — это `feature` или `fix`,
|
||||
и у неё другие требования (цель, воспроизведение).
|
||||
2. **Назвать, что перестанет мешать** — одной фразой, адресуясь разработчику.
|
||||
«Прибраться в модуле X» — не ответ: непонятно, что изменится.
|
||||
3. **Назвать границы** в `Затрагивает`. У обслуживания они часто не в коде:
|
||||
конфиг и его образцы, версия зависимости, команда сборки, файл CI. Границей
|
||||
считается то, у чего есть внешняя сторона и цена изменения.
|
||||
4. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У `chore`
|
||||
оракул обычно самый дешёвый из всех типов: команда, которая раньше падала
|
||||
или требовала трёх шагов, теперь отрабатывает одним.
|
||||
5. **Проверить, что это не «заодно».** Обслуживание любит склеиваться в пачку
|
||||
(«обновить зависимости и переписать сборку и убрать мёртвый код»). Не
|
||||
мерджится порознь — это несколько задач ([split.md](split.md)).
|
||||
6. **Цель не проставлять.** `chore` служит работоспособности, а не направлению.
|
||||
Работа по сопровождению проекта при этом видна в роадмапе — секцией
|
||||
`Сопровождение`, но целью не становится.
|
||||
|
||||
## Кто такую задачу решает
|
||||
|
||||
Решает её конвейер проекта — в плагине `av-dev-code` это скилл `resolve`,
|
||||
**сценарий обслуживания**: он не заводит change и не пишет требований, потому что
|
||||
у работы, не меняющей поведения, дельта-спек нет по построению. Тип записи там
|
||||
только **предлагает** сценарий, а подтверждает его отсутствие дельт: разошлись —
|
||||
работа останавливается, и это тот самый случай, когда тип, оставшийся от первой
|
||||
формулировки, врёт. Плагина нет — задача решается как проект привык, а этот скилл
|
||||
её только заводит и закрывает.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`ready` смотрит на **наличие непустого** `Затрагивает` и на
|
||||
**число** критериев — ровно то же, что у `feature`. Разница между типами здесь не
|
||||
в строгости проверки, а в том, **кому адресован ответ** на «что станет
|
||||
наблюдаемо иначе», — и это судит человек.
|
||||
@@ -0,0 +1,65 @@
|
||||
# ✨ `feature` — снаружи появляется то, чего не было
|
||||
|
||||
Задача, после которой наблюдаемое поведение меняется в сторону новой
|
||||
возможности. Отвечает на **«что нужно сделать»** и пишется глаголом в
|
||||
неопределённой форме.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать («Печатать поле одним куском кода») |
|
||||
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | **обязательна** |
|
||||
| Индекс | `BACKLOG.md` |
|
||||
| Берётся в работу | да |
|
||||
|
||||
**Цель обязательна, и это единственный тип, у которого так.** Новая возможность
|
||||
и есть содержание цели: подходящей нет — либо она заводится, либо перед тобой не
|
||||
`feature`. `ready` без цели откажет.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Найти цель или завести её.** Задача без цели, названная функцией, — самый
|
||||
частый способ пронести в беклог работу, которой никто не заказывал.
|
||||
2. **Назвать границы** в разделе `Затрагивает`: эндпоинт или команда, таблица и
|
||||
миграция, формат на диске, публичный тип пакета, внешний сервис. Названы
|
||||
**границы, а не замысел**: «переписать хранилище на новый драйвер» — замысел,
|
||||
`таблица points и её миграция` — граница. Проверяется вопросом «это можно
|
||||
назвать до того, как решено *как* делать?».
|
||||
3. **Написать критерии приёмки** — 2–5 проверяемых утверждений списком, у
|
||||
каждого назван оракул. Не «работает корректно», а «повторный прогон даёт тот
|
||||
же отпечаток — оракул: команда сверки».
|
||||
4. **Сказать, какую строку «Завершения» цели задача двигает.** Одной строкой в
|
||||
теле. Это защита от задачи «отрефакторить X»: она проваливается не потому,
|
||||
что невидима снаружи, а потому, что не находит строки, к которой относится.
|
||||
5. **Проверить, что задача одна.** Отвечается всё, но задача не делается одним
|
||||
заходом и не мерджится целиком — это несколько задач под одной целью, дроби
|
||||
сразу ([split.md](split.md)). Промежуточного зонтика между целью и задачей
|
||||
нет.
|
||||
6. **Реализация** — дело конвейера проекта, не этого скилла. Закрывается
|
||||
`close <слаг> --implemented`: файл и строка удаляются, суть переезжает в
|
||||
`openspec/specs/` и документацию.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
Схему типа судит `ready` на входе в работу: **наличие непустого** раздела
|
||||
`Затрагивает`, **число** критериев (меньше двух — отказ, больше пяти —
|
||||
замечание) и цель. Наличие оракула проверяется **эвристикой** — словом «оракул»
|
||||
в пункте. `check` этого поимённо не говорит, а считает строкой здоровья
|
||||
(`SKILL.md`, «Что механизировано, а что нет»).
|
||||
|
||||
Полнота перечня границ машине не видна: границу, которую забыли назвать, она от
|
||||
отсутствующей не отличает. Настоящий оракул от слова «оракул» тоже не отличает.
|
||||
Поэтому в докладе это называется как есть: «проверено число пунктов и наличие
|
||||
границ, годность оракулов и полнота границ — глазами».
|
||||
|
||||
**Критерии — пол, но расхождение с ними есть дефект критериев.** Видишь, что
|
||||
критерии закрыты, а суть задачи не достигнута — **правь критерии и возвращай
|
||||
задачу**, а не держи невидимое сверх-требование: иначе исполнитель никогда не
|
||||
знает, закончил ли, и мотивирован занижать критерии заранее.
|
||||
@@ -0,0 +1,69 @@
|
||||
# 🐞 `fix` — поведение расходится с заявленным
|
||||
|
||||
Задача о расхождении между тем, что система делает, и тем, что про неё заявлено
|
||||
— в спеке, в инварианте `CLAUDE.md`, в критериях закрытой задачи. Отвечает на
|
||||
**«что нужно сделать»**, глаголом в неопределённой форме, перед ним допускается
|
||||
«не»: «Не отбрасывать молча лишние символы в ходе».
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что нужно сделать |
|
||||
| Обязательные разделы | **`Воспроизведение`**, `Затрагивает`, `Критерии приёмки` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | необязательна |
|
||||
| Индекс | `BACKLOG.md` |
|
||||
| Берётся в работу | да |
|
||||
|
||||
## `Воспроизведение` — раздел, которого нет у других типов
|
||||
|
||||
**Не воспроизводится — это `research`, а не `fix`.** Правило было записано и
|
||||
раньше, но проверять его было нечем, и «починки» без единого шага повторения
|
||||
уходили в работу наравне с остальными. Раздел делает правило проверяемым: он
|
||||
называет, **что сделать, чтобы расхождение проявилось, и что при этом видно
|
||||
вместо ожидаемого**.
|
||||
|
||||
Пишется двумя частями, обе обязательны по смыслу:
|
||||
|
||||
- **шаги или вход** — команда, запрос, файл, последовательность действий;
|
||||
- **что видно и что ожидалось** — «ввод `а1б2` ходит в `a1`, а должен быть
|
||||
отвергнут с ошибкой».
|
||||
|
||||
Это не критерии приёмки и не дублирует их: воспроизведение описывает **сегодня**,
|
||||
критерии — **завтра**. Пропущенное воспроизведение чаще всего означает одно из
|
||||
двух: расхождение приняли на слово, или его вообще нет, а есть недовольство
|
||||
поведением — и тогда это `feature`, а не `fix`.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Воспроизвести.** Не удаётся — это `research`: заведи вопрос «при каких
|
||||
условиях проявляется» и не притворяйся, что чинить есть что.
|
||||
2. **Найти, чему поведение противоречит.** Спека, инвариант, критерий закрытой
|
||||
задачи. Не противоречит ничему — это `feature`: поведение никогда и не было
|
||||
заявлено, а тип, оставшийся от первой формулировки, врёт ровно там, где по
|
||||
нему отбирают.
|
||||
3. **Записать воспроизведение** — шаги и наблюдаемое против ожидаемого.
|
||||
4. **Назвать границы** в `Затрагивает`: починка часто трогает больше, чем
|
||||
кажется по объёму текста, и оценка систематически занижена именно здесь.
|
||||
5. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У починки
|
||||
почти всегда есть парный критерий: **прежнее поведение не сломалось**
|
||||
(«ввод `а1` принимается по-прежнему»). Без него починка чинит одно и ломает
|
||||
соседнее.
|
||||
6. **Цель не выдумывать.** `fix` служит работоспособности, а не направлению.
|
||||
Придуманная цель — то же враньё, от которого спасает тип.
|
||||
7. **Записать дефект в журнал** `docs/review.md` с пометкой «проскочил / пойман
|
||||
ревью». Проскочившие — проверочный набор для калибровки конвейера; пойманные с
|
||||
оракулом — лучшая опора для прохода ревью: проектные, воспроизводимые,
|
||||
однажды оказавшиеся правдой.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`ready` смотрит на **наличие непустого** `Воспроизведения` и
|
||||
`Затрагивает` и на **число** критериев. Годность воспроизведения — человеку:
|
||||
шаги, по которым ничего не воспроизводится, машина от годных не отличает, и
|
||||
делать вид, что проверено больше проверенного, хуже, чем не проверять вовсе.
|
||||
@@ -0,0 +1,405 @@
|
||||
# Формат записей и индексов
|
||||
|
||||
Заголовок, мета-блок и строку индекса ставит `tasks.py add` — руками их не
|
||||
пишут. Этот файл описывает **общую форму** любой записи и то, что проверяет
|
||||
`check`; тело дописывает агент.
|
||||
|
||||
Чем разделы тела отличаются от типа к типу, какой алгоритм у каждого типа и что
|
||||
у него обязательно — **отдельным файлом на тип**:
|
||||
|
||||
| Тип | Файл | Одной строкой |
|
||||
| --- | --- | --- |
|
||||
| 🎯 `goal` | [task-goal.md](task-goal.md) | возможность приложения |
|
||||
| ✨ `feature` | [task-feature.md](task-feature.md) | снаружи появляется то, чего не было |
|
||||
| 🐞 `fix` | [task-fix.md](task-fix.md) | поведение расходится с заявленным |
|
||||
| 🧹 `chore` | [task-chore.md](task-chore.md) | обслуживание, поведение не меняется |
|
||||
| 🔬 `research` | [task-research.md](task-research.md) | исход — знание, а не изменение |
|
||||
|
||||
## Файл записи
|
||||
|
||||
`items/<slug>.md`:
|
||||
|
||||
```markdown
|
||||
# 🐞 Не отбрасывать молча лишние символы в ходе
|
||||
|
||||
- **Тип:** fix
|
||||
- **Категория:** Ядро — вернулась из работы: остаток писал нерешённое в журнал
|
||||
- **Зачем:** ввод «а1б2» ходит в a1 — игрок не видит, что ошибся, и винит игру
|
||||
- **Теги:** goal:merge-robustness
|
||||
|
||||
Разбор хода читает первые два символа и молча выбрасывает остаток строки.
|
||||
|
||||
## Воспроизведение
|
||||
|
||||
Ввести `а1б2` в свой ход: программа ходит в `a1` и ничего не сообщает.
|
||||
Ожидалось — отказ с ошибкой разбора.
|
||||
|
||||
## Затрагивает
|
||||
|
||||
Разбор строки хода; текст ошибки в выводе партии. Формат сохранения партии
|
||||
не трогается.
|
||||
|
||||
## Критерии приёмки
|
||||
|
||||
- ввод «а1б2» отвергается с ошибкой — оракул: тест разбора
|
||||
- ввод «а1» принимается по-прежнему — оракул: тест разбора
|
||||
|
||||
## Рамки
|
||||
|
||||
Схема не трогается; данные только читаются; перезапуск допустим.
|
||||
|
||||
Связано: решение о канонической форме содержимого.
|
||||
```
|
||||
|
||||
- **Заголовок H1** — он же заголовок строки в индексе, дословно. Начинается
|
||||
**эмодзи типа**, и она **производна**: её ставит `add` и чинит `check --fix`
|
||||
по полю меты. Второго дома у типа нет — эмодзи это его отображение, как
|
||||
строка индекса это отображение файла.
|
||||
- **Форма заголовка — по типу.** Цель отвечает на «что приложение будет уметь»;
|
||||
`feature`, `fix` и `chore` — на «что нужно сделать», глаголом в неопределённой
|
||||
форме, перед ним допускается «не»; `research` называет предмет разведки и
|
||||
формы действия **не несёт намеренно**. Почему так — SKILL.md, «Как написана
|
||||
задача». `check` считает заголовки не в форме действия и печатает число в
|
||||
здоровье; годность формулировки смотрит агент `task-form`.
|
||||
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательны
|
||||
**тип** и **место**, причина после тире желательна (именно она объясняет,
|
||||
почему задача здесь оказалась — в том числе «вернулась из работы: …»), «зачем» и
|
||||
теги необязательны. Нераспознанные поля сохраняются: скрипт правит свои и не
|
||||
трогает чужие.
|
||||
- **Тип — первым полем.** Он решает, что у записи вообще может быть: какие
|
||||
разделы обязательны, нужна ли цель, берётся ли она в работу, — и читается
|
||||
раньше всего остального. Словарь **закрыт**: `goal` | `feature` | `fix` |
|
||||
`chore` | `research`. Не подходит ни один — это сигнал, что в записи их два и
|
||||
её надо разделить.
|
||||
- **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль.
|
||||
Не пересказ задачи: пересказ уже есть по ссылке. Живёт здесь, а не только в
|
||||
индексе: строка индекса его повторяет и производна от него, `check` сверяет,
|
||||
`check --fix` восстанавливает пропавшую строку **вместе с ним**. Пока поле
|
||||
лежало только в индексе, штатная починка дрейфа теряла его молча и
|
||||
навсегда — а это единственное, по чему задачу выбирают, не открывая.
|
||||
- **Тело** — одна фраза «что станет наблюдаемо иначе», дальше разделы по схеме
|
||||
типа. Пишется на языке документации проекта: предметно, без англицизмов, у
|
||||
которых есть русское слово, и без терминов, которых нет ни в паспорте, ни в
|
||||
архитектуре, ни в конвенциях (правило и его причина — в SKILL.md, раздел «Как
|
||||
написана задача»).
|
||||
|
||||
Тело — не план реализации и не спецификация: принятое и реализованное переезжает
|
||||
в документацию проекта, а файл задачи удаляется.
|
||||
|
||||
### Поле места: «Категория» и «Секция»
|
||||
|
||||
Поле называет, **где числится строка**, и имя у него **зависит от типа**:
|
||||
|
||||
| Тип | Поле | Значения | Что это |
|
||||
| --- | --- | --- | --- |
|
||||
| `goal` | **Секция** | `Запланировано`, `Направления`, `Сопровождение` | часть роадмапа: состояние очереди |
|
||||
| прочие | **Категория** | секции беклога проекта (`Ядро`, `Инфра`, …) | полка домена, на которой задача лежит |
|
||||
|
||||
Разные имена потому, что это **разные вещи**. У задачи это полка: куда её
|
||||
положили и куда вернут, если она уйдёт в работу и вернётся. У цели оно называет
|
||||
не полку, а место в очереди работ. Одно имя на два смысла их и смешивало; `check` называет
|
||||
несовпадение дрейфом, `check --fix` переименовывает.
|
||||
|
||||
Имя самого места принадлежит **заголовку индекса** — файл на него лишь
|
||||
ссылается, и принадлежность сверяется по нижнему регистру.
|
||||
|
||||
### Прежние формы, которые читаются, но не пишутся
|
||||
|
||||
Всё это `check` называет дрейфом, а `check --fix` переписывает:
|
||||
|
||||
| Было | Стало |
|
||||
| --- | --- |
|
||||
| префикс `[goal]` / `[idea]` в H1 | поле **Тип** + эмодзи в H1; `[idea]` → `research` |
|
||||
| тег `kind:<род>` | поле **Тип** (род работы стал типом) |
|
||||
| поле **Секция** у задачи | поле **Категория** |
|
||||
| поле **Хук** | поле **Зачем** |
|
||||
| мета одной строкой через `·` | мета списком, поле на строку |
|
||||
|
||||
Единственное, чего `--fix` не делает сам, — **проставить тип записи, у которой
|
||||
его неоткуда взять**: `feature` от `chore` машина не отличает, и подставленное
|
||||
наугад значение врало бы ровно там, где по нему принимают решение. Такие записи
|
||||
он называет поимённо пометкой `НЕОДНОЗНАЧНО`.
|
||||
|
||||
### Затрагивает
|
||||
|
||||
Перечень **границ**, которых изменение касается. Границей считается то, у чего
|
||||
есть внешняя сторона и цена изменения:
|
||||
|
||||
- эндпоинт, команда, форма ответа, код ответа;
|
||||
- таблица, поле, миграция, формат на диске, формат сообщения в очереди;
|
||||
- публичный тип или функция пакета, конфиг и его образцы;
|
||||
- внешний сервис или библиотека, чьё поведение становится нужным.
|
||||
|
||||
Ничего из этого не трогается — так и пишется: «границ не трогает, изменение
|
||||
внутри одного узла». Это ответ, а не пустой раздел.
|
||||
|
||||
**Границы, а не замысел.** «Переписать хранилище на новый драйвер» — замысел;
|
||||
`таблица points и её миграция`, `эндпоинт POST /ingest` — границы. Разница
|
||||
проверяется вопросом «это можно назвать до того, как решено *как* делать?»: если
|
||||
нет, строка описывает реализацию, и её место в предложении об изменении.
|
||||
|
||||
**Свойства репозитория сюда не пишутся** — по той же причине, что и в рамки:
|
||||
имя таблицы стабильно, номер последней миграции протухает молча. Пишется
|
||||
`таблица points и её миграция`, а не `миграция 0042`.
|
||||
|
||||
**Что из этого механизировано.** `ready` смотрит только на
|
||||
**наличие непустого раздела**. Полнота перечня машине не видна: границу, которую
|
||||
забыли назвать, она от отсутствующей не отличает. Раздела нет — отказ во взятии:
|
||||
оценивать нечем.
|
||||
|
||||
**У `goal` и `research` раздела нет** — у первой границы называют её задачи, у
|
||||
второй они становятся известны, когда из разведки родятся задачи.
|
||||
|
||||
### Критерии приёмки
|
||||
|
||||
2–5 проверяемых утверждений **списком** `- …`, **у каждого назван оракул**. Не
|
||||
«работает корректно», а «повторный прогон даёт тот же отпечаток — оракул:
|
||||
команда сверки». Это не второе определение сделанного, а проектная
|
||||
конкретизация вопроса «по чему видно, что закончено» из теста готовности ниже:
|
||||
там сказано «признак завершённости», здесь — «признак плюс чем проверяется».
|
||||
|
||||
**Что из этого механизировано.** `ready` считает пункты: меньше
|
||||
двух — отказ («— работает» одной строкой больше не проходит), больше пяти —
|
||||
замечание, обычно это признак, что задача крупнее задачи. Наличие оракула
|
||||
проверяется **эвристикой** — словом «оракул» в пункте, — и потому даёт только
|
||||
замечание: настоящий оракул от слова «оракул» машина не отличает, и делать вид,
|
||||
что проверено больше проверенного, хуже, чем не проверять вовсе.
|
||||
|
||||
**У `research` критериев нет** — её приёмка это записанный ответ, и описывается
|
||||
она разделами «Вопрос» и «Куда ляжет ответ». **У `goal` их заменяет
|
||||
«Завершение».**
|
||||
|
||||
**Критерии — пол, но расхождение с ними есть дефект критериев.** Если приёмщик
|
||||
видит, что критерии закрыты, а суть задачи не достигнута, он **правит критерии и
|
||||
возвращает задачу исполнителю**, а не держит невидимое сверх-требование. Иначе
|
||||
исполнитель никогда не знает, закончил ли, и мотивирован занижать критерии
|
||||
заранее.
|
||||
|
||||
### Рамки
|
||||
|
||||
Одна строка: чего касаться нельзя, что перезапускается, что считается
|
||||
необратимым, трогается ли схема данных. Раздел **допустим у любого типа задачи и
|
||||
ни у одного не обязателен**. **Свойства репозитория сюда не пишутся** — номер
|
||||
последней миграции, версия зависимости, хеш: в лежалой задаче они протухают
|
||||
молча и становятся ложной рамкой. Снимок берётся при постановке, а не при
|
||||
заведении.
|
||||
|
||||
### Вопросы
|
||||
|
||||
Неразобранное решение человека живёт разделом `## Вопросы` **плюс тегом
|
||||
`question`**. Раздел без тега или тег без раздела — дрейф, `check` о нём скажет.
|
||||
|
||||
Раздел `Вопросы` (о решении человека) и раздел `Вопрос` у `research` (предмет
|
||||
разведки) — **разные вещи и разные слова**: первый блокирует взятие, второй его
|
||||
разрешает.
|
||||
|
||||
**Судит факт, а не метка.** Отказ во взятии даёт **непустой раздел «Вопросы»**,
|
||||
независимо от того, стоит ли тег: иначе забывший тег проходил бы, а поставивший
|
||||
спотыкался — стимул ровно обратный записанному правилу. Тег производен: он нужен
|
||||
отбору снаружи файла (`list --questions`, `list --tag question`), и его
|
||||
отсутствие при непустом разделе — замечание, а не лазейка. Тег без раздела тоже
|
||||
отказ, но с другим советом: либо вопрос записан не туда, либо тег пора снять.
|
||||
|
||||
**Ответ на вопрос — три правки, и первая обязательна.** Раздел «Вопросы»
|
||||
опустошается: ответ переезжает в тело решением, а не остаётся вопросом рядом с
|
||||
ответом. Затем снимается тег (`edit <slug> --rm-tag question`) и переписывается
|
||||
«зачем»: «Решено: …» на вопрос «зачем нужна эта задача» уже не отвечает.
|
||||
|
||||
**Порядок именно такой, потому что судит раздел, а не тег.** `ready`
|
||||
смотрит в непустой раздел и откажет даже при снятом теге, а `check`
|
||||
на снятый тег при непустом разделе посоветует тег вернуть. Снять тег, не
|
||||
опустошив раздел, — значит закольцевать себя между двумя советами.
|
||||
|
||||
## Файл цели
|
||||
|
||||
Форма та же, разделы и алгоритм — [task-goal.md](task-goal.md).
|
||||
|
||||
```markdown
|
||||
# 🎯 Исход слияния не зависит от порядка доставки
|
||||
|
||||
- **Тип:** goal
|
||||
- **Секция:** Направления
|
||||
- **Теги:** decomposed
|
||||
|
||||
Ради чего: точки из разных доставок сходятся в один часовой объект, и сегодня
|
||||
исход столкновения зависит от порядка доставки, а не от содержания.
|
||||
|
||||
## Завершение
|
||||
|
||||
- повторная доставка тех же точек в другом порядке даёт то же состояние;
|
||||
- накопительная метрика за сутки не уменьшается после повторной доставки;
|
||||
- в логе видно, какая из двух точек выиграла и почему.
|
||||
```
|
||||
|
||||
- **Задачи цели здесь не перечисляются.** Перечень даёт
|
||||
`tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и
|
||||
поехал бы на первой же закрытой задаче.
|
||||
- **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи
|
||||
закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет.
|
||||
Пометка именно **тегом**, а не строкой в теле: только так она проверяется.
|
||||
`check` напоминает о нём у цели без задач замечанием — неразобранная цель
|
||||
законна и зелёного прогона не ломает; `check --fix` сам ставит его цели, у
|
||||
которой задачи есть, а цель с тегом и без задач — прямое приглашение закрыть.
|
||||
- Цель живёт в `ROADMAP.md` и **никогда** — в `BACKLOG.md`.
|
||||
- **Достигнутая цель не исчезает.** `close <слаг> --implemented` удаляет файл и
|
||||
переносит строку в секцию `Готово` с датой:
|
||||
`- 2026-08-04 \`merge-order\` — Исход слияния не зависит от порядка доставки. …`
|
||||
Ссылки на файл в ней нет — файл удалён, а битая ссылка это ошибка `check`.
|
||||
Поведение живёт в спеках проекта; роадмап отвечает, **когда и в каком порядке**
|
||||
оно появилось.
|
||||
|
||||
## Слаг
|
||||
|
||||
Латиница и цифры, kebab-case, без ведущих, хвостовых и двойных дефисов
|
||||
(`foo-bar`, не `-foo`, `a--b`). Именуется **по сути, а не по текущей
|
||||
формулировке**: заголовок будет переписан при переоценке, а слаг стоит в ссылках
|
||||
из других задач, коммитов и черновиков. **Транслита не заводим** —
|
||||
`tie-break-equal-completeness`, а не `taj-brejk-pri-ravnoj-polnote`: транслит
|
||||
нечитаем для того, кто ищет по смыслу, и не сокращается.
|
||||
|
||||
Переименование слага — не правка, а перенос ссылок: делается одним атомарным
|
||||
проходом по всем местам, где слаг упомянут, иначе останутся битые ссылки,
|
||||
которых никто не проверяет.
|
||||
|
||||
## Индексы
|
||||
|
||||
Строка везде одной формы:
|
||||
|
||||
```markdown
|
||||
- [🐞 Заголовок дословно](items/slug.md) — зачем
|
||||
```
|
||||
|
||||
«Зачем» отвечает на «зачем нужна эта задача» одним предложением: состояние,
|
||||
остаток, боль. Пересказ первого абзаца бесполезен — он уже есть по ссылке.
|
||||
Эмодзи внутри квадратных скобок не украшение: заголовок копируется **дословно**,
|
||||
и тип виден там, где решают «брать или не брать».
|
||||
|
||||
| Файл | Что отвечает | Секции |
|
||||
| --- | --- | --- |
|
||||
| `ROADMAP.md` | что приложение уже умеет и чего ещё не умеет | канонические и в этом порядке: `Запланировано`, `Направления`, `Сопровождение`, `Готово` (англ. `Planned`, `Directions`, `Operations`, `Done`) |
|
||||
| `BACKLOG.md` | что **можно взять** — только задачи, **в порядке очереди** | категории проекта (по умолчанию Ядро/Инфра) |
|
||||
| `REJECTED.md` | что ушло без реализации и почему | — |
|
||||
|
||||
Секции — **единственные заголовки `##` в индексе**: любой другой `##` в
|
||||
преамбуле проверка сочтёт секцией.
|
||||
|
||||
**Порядок строк внутри секции беклога значим: это очередь.** Первая строка — то,
|
||||
что делают следующим; назначает порядок человек на груминге, и двигают его
|
||||
`move --after` и `move --first`. Одно место из очереди изъято и **производно от
|
||||
типа и заполненности**: **сырьё** (`research` без раздела «Вопрос») стоит в конце
|
||||
своей секции, потому что его не берут, и между берущимся оно каждый раз требует
|
||||
открыть файл, чтобы это понять. Проверяет `check`, переставляет `check --fix`,
|
||||
и человек этот порядок не назначает — иначе он был бы приоритетом, которого
|
||||
здесь нет.
|
||||
|
||||
**Секции «блокеры» среди них нет.** Блокер — состояние, а не полка: он живёт до
|
||||
ответа человека, а следы остаются вопросами в файлах задач.
|
||||
Постоянно пустая секция со старой семантикой «разбираются пачками» противоречила
|
||||
бы правилу «эскалируем немедленно», поэтому `init` её не заводит, а `check`
|
||||
говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её. В секции
|
||||
**`Запланировано`** очередь значима и обосновывается прозой; двигают строку
|
||||
`move <slug> --section Запланировано --after <другой>`. В секции **`Готово`**
|
||||
строки не той формы, что у прочих индексов: дата, слаг, заголовок — как в
|
||||
`REJECTED.md`, и по той же причине (файла уже нет, ссылаться некуда).
|
||||
|
||||
**Секции роадмапа закреплены** — состав, полнота, единство языка и **порядок**
|
||||
проверяются `check`; категории беклога проект называет сам. Почему так —
|
||||
SKILL.md. Порядок закреплён потому, что `Готово` копится: стоя первым,
|
||||
достигнутое отодвигает за экран то, ради чего роадмап открывают чаще всего.
|
||||
|
||||
**Заголовок секции пишется с прописной и отбивается пустой строкой с обеих
|
||||
сторон** — во всех индексах, включая категории беклога, имена которых выбирает
|
||||
проект. Написание канонических секций и отбивку правит `check --fix`; он же
|
||||
сводит написание места в мете файла с заголовком индекса.
|
||||
|
||||
Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`).
|
||||
Строку руками не пишут.
|
||||
|
||||
Отсюда же ответ на «а если оборвётся посередине». Мутация сперва проверяет всё
|
||||
и складывает правки, и только потом пишет: сначала все временные файлы, потом
|
||||
переименования подряд. Полной транзакции на несколько файлов файловая система не
|
||||
даёт, но окно сжато до цепочки переименований, а **всё, что в нём может
|
||||
разъехаться, — производное**: файлы целы, индексы восстанавливает `check --fix`.
|
||||
Поэтому отказ на второй задаче из пяти не оставляет первую переписанной при
|
||||
нетронутых индексах.
|
||||
|
||||
## `REJECTED.md`
|
||||
|
||||
Туда уходит задача, покинувшая беклог **без реализации**. Строку пишет
|
||||
`tasks.py close --reason`, а `check` следит за форматом:
|
||||
|
||||
```markdown
|
||||
- 2026-07-23 `versii-kachestvo-repaki` — Версии и качество одного тайтла.
|
||||
Причина: калибровка болей — не боль, ни разу не возникло за полгода.
|
||||
Была секция: Инфра.
|
||||
```
|
||||
|
||||
Реализованные сюда не попадают: у них остаётся коммит и документация. У
|
||||
выкинутой не остаётся ничего — и через квартал она возвращается тем же текстом.
|
||||
Это первое место, куда смотрит дедупликация при заведении.
|
||||
|
||||
Запись не запрещает завести задачу заново: изменился контекст — заводим и
|
||||
ссылаемся на строку, объясняя, что изменилось.
|
||||
|
||||
## Теги
|
||||
|
||||
Разметка сверх типа. Тип полем, потому что он один и обязателен; теги — потому
|
||||
что их много и `list --tag` уже умеет отбирать по ним порцию разбора.
|
||||
|
||||
- `goal:<слаг>` — цель, которой служит задача. Обязателен **у `feature`**:
|
||||
новая возможность и есть содержание цели. У `fix`, `chore` и `research` его
|
||||
может не быть — они служат работоспособности, а не направлению.
|
||||
- `question` — в файле есть неразобранный раздел «Вопросы».
|
||||
- `decomposed` — на цели: разложена на задачи (см. «Файл цели»).
|
||||
|
||||
Тега `kind:<род>` больше нет: род работы стал типом. Оставшийся в файле `check`
|
||||
называет дрейфом, а `check --fix` снимает, перенеся значение в поле «Тип».
|
||||
|
||||
Отбор — `list --tag a,b`: перечисленные через запятую теги требуются **все
|
||||
сразу** (это И, не ИЛИ). Тег, которого нет ни у одной задачи, `list` называет
|
||||
вслух: молчаливый ноль читается как «таких задач нет», а чаще это опечатка.
|
||||
|
||||
Свои теги проект заводит свободно (партия ревью `review-ГГГГ-ММ-ДД`, тема,
|
||||
источник) — словарь не фиксирован. В индексы теги не выносим: индексы
|
||||
производны, отбор делает `list --tag`, а не глаза.
|
||||
|
||||
## Тест «готова к взятию»
|
||||
|
||||
Задача готова, если из файла отвечаются четыре вопроса. Первый и четвёртый —
|
||||
общие, второй и третий у каждого типа свои и перечислены в его файле.
|
||||
|
||||
1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю,
|
||||
владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет
|
||||
ломаться Y при Z» — ответ. **У `chore` адресат — разработчик, и это
|
||||
законно**: «уедет последний вызов устаревшего API» — ответ, а не отговорка.
|
||||
Тип объявлен как раз затем, чтобы такие задачи не выдумывали себе
|
||||
пользовательскую пользу.
|
||||
2. **Что известно про сегодня** — то, что тип требует знать до работы:
|
||||
у `fix` это `Воспроизведение`, у `research` — `Вопрос`, у `feature` и
|
||||
`chore` — `Затрагивает`.
|
||||
3. **По чему видно, что закончено** — критерии приёмки с оракулами;
|
||||
у `research` вместо них `Куда ляжет ответ`.
|
||||
4. **Какую часть «Завершения» своей цели она двигает** — у задачи с целью.
|
||||
Строкой: «двигает пункт 2 «Завершения» — накопительная метрика перестаёт
|
||||
уменьшаться». Это и есть защита от задачи «отрефакторить X»: она проваливает
|
||||
тест не потому, что невидима снаружи, а потому, что не находит строки, к
|
||||
которой относится. Заодно видно обратное — достаточен ли набор задач для
|
||||
цели: строка «Завершения», к которой не относится ни одна задача, это
|
||||
незакрытая часть возможности.
|
||||
|
||||
**У задачи без цели** (`fix`, `chore`, `research`) вопрос не задаётся: они
|
||||
служат работоспособности, а не направлению.
|
||||
|
||||
Не отвечается первый, второй или третий вопрос → это ещё не задача, а **сырьё**:
|
||||
тип `research` без раздела «Вопрос», место — конец секции, работа над ним —
|
||||
штурм. Не отвечается четвёртый у `feature` → либо цель есть и не проставлена,
|
||||
либо это не новая возможность.
|
||||
|
||||
Отвечается всё, но задача не делается одним заходом и не мерджится целиком →
|
||||
это **несколько задач под одной целью**, дроби сразу. Промежуточного зонтика
|
||||
между целью и задачей нет: тип `[epic]` упразднён, потому что зонтиком стала
|
||||
сама цель.
|
||||
|
||||
Тест применяется при заведении и при переоценке. К старым задачам, которых
|
||||
операция не касается, задним числом не применяется — беклог не переоформляют
|
||||
«заодно».
|
||||
@@ -0,0 +1,93 @@
|
||||
# 🎯 `goal` — возможность приложения
|
||||
|
||||
Цель отвечает на **«что приложение будет уметь»**. Не область работ и не имя
|
||||
подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от порядка
|
||||
доставки». Свойство поведения — тоже возможность.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | что приложение будет уметь |
|
||||
| Обязательные разделы | `Завершение` |
|
||||
| Допустимые сверх того | — |
|
||||
| Поле места | **Секция** — часть роадмапа |
|
||||
| Цель (`goal:<слаг>`) | запрещена: цель и есть цель |
|
||||
| Индекс | `ROADMAP.md`, и никогда `BACKLOG.md` |
|
||||
| Берётся в работу | нет — берутся её задачи |
|
||||
|
||||
Поле места у цели называется **«Секция»**, а не «Категория», и это не разнобой:
|
||||
у задачи оно называет полку домена, на которой она лежит, а у цели
|
||||
— часть роадмапа, то есть состояние очереди. Одно имя на два смысла их и
|
||||
смешивало.
|
||||
|
||||
## «Завершение» — списком, а не абзацем
|
||||
|
||||
Это признаки того, что приложение **уже умеет**, и на строки этого раздела
|
||||
ссылаются задачи цели: «двигает пункт 2 «Завершения» — накопительная метрика
|
||||
перестаёт уменьшаться». Абзацем такая ссылка не берётся, поэтому список.
|
||||
|
||||
Отсюда же читается обратное и более полезное: **строка «Завершения», к которой
|
||||
не относится ни одна задача, — незакрытая часть возможности**. Достаточность
|
||||
набора задач видна из самой цели, а не из чьей-то памяти.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Проверить, что это возможность, а не работа.** Работа, которой держат
|
||||
проект, на вопрос «что приложение будет уметь» не отвечает; состав перечислен
|
||||
[в словаре сопровождения](operations.md). Ей отведена секция
|
||||
`Сопровождение` — там она видна в том же
|
||||
экране и не читается как обещание продукта. Граница проходит по тому,
|
||||
**кто наблюдает**:
|
||||
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
|
||||
состояние на одном экране» — сопровождение.
|
||||
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; про то, чем держат проект,
|
||||
— `Сопровождение`. В `Готово` кладёт сам `close`.
|
||||
3. **Написать «Завершение»** — 2–5 наблюдаемых признаков списком. Пишутся до
|
||||
декомпозиции: иначе задачи придумают себе цель задним числом.
|
||||
4. **Разложить на задачи** и проставить им `goal:<слаг>`. Перечень задач в теле
|
||||
цели **не хранится** — он был бы третьим индексом и поехал бы на первой же
|
||||
закрытой задаче; выводит `tasks.py list --goal <слаг>`.
|
||||
5. **Пометить `decomposed`.** Тег отличает «ещё не разобрана» от «все задачи
|
||||
закрыты» — два состояния с одним внешним признаком. `check --fix` ставит его
|
||||
сам цели, у которой задачи есть.
|
||||
6. **Закрыть достигнутой** — `close <слаг> --implemented`, когда не осталось
|
||||
открытых задач. Файл удаляется, строка с датой переезжает в `Готово`. Скрипт
|
||||
откажет, если задачи ещё живы.
|
||||
|
||||
## Отменённая цель — сперва задачи, потом цель
|
||||
|
||||
Замысел бывает неверен, и цель отменяют, не достигнув. Порядок обратный
|
||||
завершению и держится тем же запретом: цель, закрытая поверх живых задач,
|
||||
оставила бы их сиротами, и `close` этого не даст.
|
||||
|
||||
1. **Разобрать её задачи поштучно.** Задача, теряющая смысл вместе с целью, —
|
||||
`close <slug> --reason "<почему>"`; задача, переживающая цель, — `edit <slug>
|
||||
--goal <другая>`. **Причина обязательна и пишется своя каждой:** «цель
|
||||
отменена» это не причина, а пересказ команды, и в `REJECTED.md` от него нет
|
||||
пользы через квартал.
|
||||
2. **Закрыть саму цель** — `close <слаг> --reason "<почему замысел отменён>"`.
|
||||
Файл удаляется, строка с причиной и датой уходит в `REJECTED.md`. В `Готово`
|
||||
не попадает: `Готово` отвечает «что приложение умеет», а отменённая цель не
|
||||
умеет ничего.
|
||||
|
||||
**Место этому — груминг, а не отдельный заход.** Отмена цели значит
|
||||
разбор всех её задач, а разбор задач и есть шаг 3 груминга
|
||||
(скилл `groom`, «что перестало быть важным»). Отменять на ходу,
|
||||
между делом, — верный способ закрыть скопом то, что стоило перевесить.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`check` считает цели, различает разобранные и пустые, ставит `decomposed`,
|
||||
запрещает закрыть цель с живыми задачами и держит `Секцию` в согласии с
|
||||
заголовком роадмапа. **Годность формулировки — не машине**: «возможность это или
|
||||
область работ» решает [агент вычитки](../SKILL.md#вычитка-два-прохода-а-не-один).
|
||||
|
||||
Достигнутая цель **не исчезает**: «что приложение умеет» — половина вопроса, ради
|
||||
которого роадмап открывают. Вторым домом поведения роадмап при этом не
|
||||
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
|
||||
**когда и в каком порядке** оно появилось.
|
||||
@@ -0,0 +1,87 @@
|
||||
# 🔬 `research` — исход работы знание, а не изменение системы
|
||||
|
||||
Ответ на вопрос, замер, разведка, проработка сырой мысли. Приёмка — **записанный
|
||||
ответ**, а не изменённый код.
|
||||
|
||||
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
|
||||
Здесь только то, что у этого типа своё.
|
||||
|
||||
## Схема
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Заголовок отвечает на | о чём разведка (предмет, а не действие) |
|
||||
| Обязательные разделы | `Вопрос`, `Куда ляжет ответ` |
|
||||
| Допустимые сверх того | `Рамки`, `Вопросы` |
|
||||
| Поле места | **Категория** — полка домена беклога |
|
||||
| Цель (`goal:<слаг>`) | нет |
|
||||
| Индекс | `BACKLOG.md` |
|
||||
| Берётся в работу | да — **но только с заполненным «Вопросом»** |
|
||||
|
||||
**Критериев приёмки у `research` нет, и это не поблажка.** Критерии в форме
|
||||
«оракул: тест» разведке натянуты: проверять нечего, пока ответа нет. Её приёмка
|
||||
описывается раздельно — вопрос, на который отвечаем, и место, куда ляжет ответ.
|
||||
|
||||
**Заголовок формы действия не несёт намеренно.** Что делать, ещё неизвестно, и
|
||||
заголовок-действие обещал бы решённость, которой нет. «Подсказка следующего
|
||||
хода», а не «Сделать подсказку следующего хода».
|
||||
|
||||
## Этот тип вобрал прежний `[idea]`
|
||||
|
||||
Тип `idea` упразднён. Он значил не род работы, а **состояние незаполненности** —
|
||||
«первый, второй или третий вопрос теста готовности не отвечается», — а состояние
|
||||
типом быть не может: оно меняется по мере того, как запись дописывают, а тип
|
||||
меняют командой.
|
||||
|
||||
Теперь это состояние называется честно: **`research` без раздела «Вопрос» — это
|
||||
сырьё**.
|
||||
|
||||
| | сырьё | разведка |
|
||||
| --- | --- | --- |
|
||||
| Раздел `Вопрос` | пуст или отсутствует | заполнен |
|
||||
| `ready` | отказ | берёт |
|
||||
| Место в секции беклога | **конец**, `check --fix` сносит туда сам | среди прочих |
|
||||
| `tasks.py list --raw` | показывает | нет |
|
||||
|
||||
Порядок строк в беклоге назначает человек — это приоритет (правило 4 скилла).
|
||||
Место сырья **из него изъято**: оно производно от типа и заполненности, а не от
|
||||
чьего-то решения, и потому его проверяет и чинит машина. Приоритетом оно не
|
||||
становится: сырьё не берут вовсе, и место в конце говорит именно это.
|
||||
|
||||
Сырьём заводится и **сырая функция**: «Подсказка следующего хода» — ещё не
|
||||
`feature`, потому что неизвестно, что именно делать. Работа над ней — думание, и
|
||||
её исход — либо задачи, либо отказ.
|
||||
|
||||
## Алгоритм
|
||||
|
||||
1. **Записать вопрос одной фразой.** Не тему, а вопрос: не «Разобраться с
|
||||
выводом в терминалах», а «Какими символами рамки печатаются одинаково в
|
||||
Терминале, iTerm и `tmux`». Вопроса ещё нет — запись заводится сырьём и
|
||||
лежит в конце секции, пока вопрос не появится.
|
||||
2. **Назвать, куда ляжет ответ**: `docs/research/<slug>.md`, ADR, тело этой
|
||||
задачи. Место называется **заранее**, иначе ответ остаётся в переписке, а
|
||||
через квартал разведку заказывают заново.
|
||||
3. **Ограничить рамками**, если разведка может утечь: сколько времени, какие
|
||||
источники, что заведомо вне.
|
||||
4. **Провести разведку** и **записать ответ по названному адресу**. Числа — с
|
||||
провенансом: с командой или условиями, которыми получены. Число без источника
|
||||
проход ревью обязан читать как условие, а не как замер. Проводит её конвейер
|
||||
проекта — в плагине `av-dev-code` это скилл `resolve`, сценарий разведки;
|
||||
плагина нет — разведка ведётся как проект привык, а этот скилл её только
|
||||
заводит и закрывает.
|
||||
5. **Разложить исход на задачи** — если он их родил. Разведка кончается одним из
|
||||
трёх: заведены задачи, записано знание, отказ. **Отказ — полноправный исход**:
|
||||
«проверили, не проблема» экономит работу.
|
||||
6. **Закрыть** — `close <слаг> --implemented`, когда ответ записан. Файл
|
||||
удаляется: запись ответа и есть след, второго не нужно. Ушла без ответа —
|
||||
`close --reason`, и строка уезжает в `REJECTED.md`.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
`ready` смотрит на **наличие непустых** разделов `Вопрос` и
|
||||
`Куда ляжет ответ`; `check` считает сырьё отдельной строкой здоровья и держит
|
||||
его в конце секции. Годность вопроса — человеку: «вопрос это или тема» машина не различает,
|
||||
и `check` о годности молчит намеренно.
|
||||
|
||||
Штурм сырья, дробление исхода на задачи и тест «части мерджатся порознь» —
|
||||
[split.md](split.md).
|
||||
Executable
+3302
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user