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.
This commit is contained in:
av
2026-08-04 09:27:26 +03:00
parent 08bef2cac0
commit 42d5b73a04
128 changed files with 1606 additions and 4889 deletions
+47
View File
@@ -0,0 +1,47 @@
# [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` запрещён линтером — этот
пункт, вероятно, закрыт и подлежит вычёркиванию.