docs: канон поднят с версии 7 до 12
- каталог задач переехал в tasks/ в корне, спринт упразднён — приоритет теперь порядок строк в BACKLOG.md, четыре задачи набора вернулись в беклог - гейт: путь docs.py переведён на av-dev-docs вместо снесённого av-dev-pm, добавлены шаги tasks.py check и openspec.py check - относительные ссылки внутри задач и ссылки из docs/ на задачи починены
This commit is contained in:
@@ -0,0 +1,59 @@
|
||||
# 🔬 Кандидаты в конвенции кода
|
||||
|
||||
- **Тип:** research
|
||||
- **Категория:** Инфраструктура
|
||||
- **Зачем:** накоплен список кандидатов (внешние клиенты, конкурентность, тесты, CLI, время) — надо решить, что из них стало реальным трением, а что выдумано вперёд
|
||||
- **Теги:** goal:dev-process-quality
|
||||
|
||||
Список копился в черновике `docs/drafts/conventions-backlog.md` (удалён при
|
||||
переводе на канон, текст в истории git) под правилом «пишем по мере реального
|
||||
трения, а не вперёд». Правило соблюдено — но список с тех пор не пересматривали,
|
||||
а часть пунктов за это время либо реализовалась, либо механизировалась правилом
|
||||
и должна из кандидатов выпасть, а не переехать в прозу.
|
||||
|
||||
Разобрать по одному: стало реальным трением → в `docs/conventions/`; выражается
|
||||
правилом → в `.golangci.yml` или `internal/archrules` и в таблицу
|
||||
«Механизировано»; выдумано вперёд → выбросить.
|
||||
|
||||
**Кандидаты в отдельный документ**
|
||||
|
||||
- **Раскладка пакетов и направление зависимостей.** `cmd/<bin>` +
|
||||
`internal/<компонент>` по доменам, домен не импортирует транспорт, без свалок
|
||||
`util`/`common`/`helpers`. *Частично уже механизировано* тестами
|
||||
`internal/archrules` — проверить, что осталось прозой.
|
||||
- **`context.Context`.** Первый параметр, не хранить в структурах, в `Value`
|
||||
только request-scoped данные (не зависимости), дедлайны и отмена тянутся
|
||||
сквозь стадии. Протяжка логгера уже сделана (`internal/logctx`).
|
||||
- **Внешние клиенты.** Таймаут на **каждый** исходящий вызов, не
|
||||
`http.DefaultClient`, ретраи с backoff и потолком, HTTP-прокси из конфига.
|
||||
Кандидат на общий конструктор клиента вместо копипасты в
|
||||
`qbt`/`llm`/`jellyfin`/`metadata`. Самый живой пункт: клиентов уже четыре.
|
||||
- ~~**Тесты.**~~ Вынесены отдельной задачей —
|
||||
[tests-convention](tests-convention.md): кандидат разошёлся с проектом
|
||||
(обещал фикстуры в `testdata/`, которого нет), и разбирать его надо вместе с
|
||||
тем, что накопилось в самих тестах.
|
||||
|
||||
**Кандидаты в строку-инвариант, а не в документ**
|
||||
|
||||
- **БД и миграции.** Forward-only, только параметризованные запросы, явные
|
||||
транзакции для многошаговых изменений, context-aware запросы. Сильно
|
||||
стек-специфично.
|
||||
- **Конкурентность.** Каждая горутина знает, **как** останавливается
|
||||
(ctx/закрытие канала); `errgroup` для связанных задач; фоновые процессы
|
||||
гасятся при shutdown. Актуально для воркера, не для всего проекта.
|
||||
- **CLI.** Данные в `stdout`, логи и диагностика в `stderr`, осмысленные коды
|
||||
возврата. Для диагностических команд `add`/`recognize`/`healthcheck`.
|
||||
- **Время.** Явный TZ всегда, хранение и логи в UTC. Уже частично в `CLAUDE.md`
|
||||
и `conventions/logging.md`, а `time.Now` вне `store` запрещён линтером — этот
|
||||
пункт, вероятно, закрыт и подлежит вычёркиванию.
|
||||
- **Язык вывода связан с мапперами.** Провенанс — ревью `tvdb-title-locale`
|
||||
(2026-08-07,
|
||||
[отчёт триажа](../../openspec/changes/archive/2026-08-07-tvdb-title-locale/review/report.md),
|
||||
находка R2 прохода `architecture`). Язык вывода живёт в пяти местах четырёх
|
||||
пакетов, и теста, связывающего множество кодов языка с мапперами, нет:
|
||||
забытая ветка молча даст английский вывод вместо ошибки. Кандидат в правило
|
||||
`internal/archrules`, а не в прозу. **Дешёвый паллиатив, если правило окажется
|
||||
дорогим:** строка «язык вывода» в `docs/architecture.md` → «Единые точки
|
||||
проекта» — тогда расхождение хотя бы спросит проход по теме `architecture`.
|
||||
Число мест перед правкой перепроверить: оно снято ревью одной задачи и с тех
|
||||
пор могло измениться.
|
||||
Reference in New Issue
Block a user