Files

T

docs: перевод документации на канон av-dev

- Раскладка docs/ приведена к канону 2: заведены passport/architecture/
  database/security/review и research; docs/specs, drafts, backlog, review/
  и BRIEF.md разобраны и удалены, беклог переехал в docs/tasks (34 задачи,
  6 целей, слаги на английский).
- Нарративы specs удалены как дубли openspec-спек после поимённой сверки;
  остаток заведён задачами (редактор маппинга ревью, крайние случаи
  именования), отказ от сущности title промоутнут в ADR.
- Проектные копии агентов и скиллов ревью/пайплайна удалены в пользу
  плагинов av-dev-pm и av-dev-pipeline; в task gate добавлен шаг canon
  вместо er-schema.

2026-08-04 09:27:26 +03:00

4.2 KiB

Raw Permalink Blame History

[idea] Кандидаты в конвенции кода

Секция: Инфраструктура
Зачем: накоплен список кандидатов (внешние клиенты, конкурентность, тесты, 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. Самый живой пункт: клиентов уже четыре.
Тесты. Table-driven, фикстуры в testdata/, t.Parallel() где безопасно, зафиксировать stdlib testing против testify, разделение быстрых и интеграционных (*_integration_test.go + env-гейты уже есть), что считаем обязательным к покрытию.

Кандидаты в строку-инвариант, а не в документ

БД и миграции. Forward-only, только параметризованные запросы, явные транзакции для многошаговых изменений, context-aware запросы. Сильно стек-специфично.
Конкурентность. Каждая горутина знает, как останавливается (ctx/закрытие канала); errgroup для связанных задач; фоновые процессы гасятся при shutdown. Актуально для воркера, не для всего проекта.
CLI. Данные в stdout, логи и диагностика в stderr, осмысленные коды возврата. Для диагностических команд add/recognize/healthcheck.
Время. Явный TZ всегда, хранение и логи в UTC. Уже частично в CLAUDE.md и conventions/logging.md, а time.Now вне store запрещён линтером — этот пункт, вероятно, закрыт и подлежит вычёркиванию.

4.2 KiB Raw Permalink Blame History Unescape Escape

[idea] Кандидаты в конвенции кода

4.2 KiB

Raw Permalink Blame History