jellybit/docs/tasks/items/convention-candidates.md

🔬 Кандидаты в конвенции кода

• Тип: 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: кандидат разошёлся с проектом (обещал фикстуры в 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, отчёт триажа, находка R2 прохода architecture). Язык вывода живёт в пяти местах четырёх пакетов, и теста, связывающего множество кодов языка с мапперами, нет: забытая ветка молча даст английский вывод вместо ошибки. Кандидат в правило internal/archrules, а не в прозу. Дешёвый паллиатив, если правило окажется дорогим: строка «язык вывода» в docs/architecture.md → «Единые точки проекта» — тогда расхождение хотя бы спросит проход по теме architecture. Число мест перед правкой перепроверить: оно снято ревью одной задачи и с тех пор могло измениться.