Перейти к основному содержимому

ADR 0077 — Рейтинг моделей по возможностям, без выдуманной оценки

  • Статус: принят
  • Дата: 2026-08-15
  • Контекст: PROGRAMA 28, Волна 2, направление H2 — handoff дизайна, Configurações пункт 5 ("Melhores modelos por capacidade") и пункт 6 ("Modelos por agente", выпадающий список с меткой "ideal")
  • Расширяет: ADR 0041 (capability объявляется только при доказательстве), ADR 0042 (курирование всегда ручное), ADR 0051 (uses как курирование workspace, а не capability — RN-057)

Контекст​

Handoff (design_handoff_brabo/README.md, раздел 7) просит две вещи, которых на экране Configurações не было:

  1. Таблицу РЕЙТИНГА — "Melhores modelos por capacidade" — с колонками возможность, рекомендуемая, альтернатива, score и "используется". Пример макета показывает числа вроде "código → claude-sonnet-4 / qwen2.5-coder:14b (9.4)".
  2. Зелёную метку ideal в выпадающем списке ModelPicker, "когда модель покрывает ВСЕ возможности, требуемые агентом".

Обе требуют одного и того же вида данных, которых у продукта нет, и исследование до написания кода подтвердило это ДВУМЯ независимыми путями.

Score фиктивен​

"9.4", "9.1", "8.7"... — числа МАКЕТА, без соответствия ни в одном каталоге provider, ни в одной метрике, которую вычисляет продукт. Ни один provider не публикует "качество кода", а продукт не измеряет долю успеха, удовлетворённость или любой их заменитель. Копирование чисел макета в продакшен означало бы показ сфабрикованных данных как измеренных — та же "догадка, переодетая в данные", которую ADR 0041 запрещает для capability МОДЕЛИ, теперь применительно к качеству.

"Возможностей, требуемых агентом" нет в домене​

Поиск в коде (web и api) не нашёл НИ ОДНОЙ структуры, связывающей AgentKey с набором требуемых возможностей. Более того: сам ModelsSection (ProjectSettingsTab.tsx) уже решил это до этого направления — колонка дизайна была "Agente · capacidades", а код переименовал её просто в "Agente" с комментарием "as capacidades exigidas por agente não existem no domínio, e prometer uma coluna que não tem conteúdo é pior que não prometer". Выдумать сейчас таблицу AgentKey → UsoDeModelo[], даже "объявленную" вручную, как color/icon/initials в agents.ts, противоречило бы этому решению, не отменяя его, — и это ровно тот вид продуктовой классификации, который CLAUDE.md оставляет за явным решением пользователя, с ADR.

Есть второй, структурный барьер, закрывающий вопрос даже без первого: ModelPicker, используемый для привязки модели к агенту, читает GET /projects/:projectId/models (роль viewer), который возвращает ЧИСТУЮ Model. Курирование (uses, ADR 0051) существует только в ModelComCuradoria, отдаваемой GET /workspaces/:workspaceId/models/catalog, — который требует maintainer. Нарисовать метку, зависящую от uses, в этом picker потребовало бы либо (a) поднять уровень доступа picker агента до maintainer (откат RBAC, о котором никто не просил), либо (b) открыть новый маршрут, раскрывающий uses на более низком уровне, — оба варианта являются изменением границы доступа, продуктовым решением как таковым.

Решение​

Метка "ideal" НЕ строится. Это задокументировано в apps/web/src/components/ModelPicker.tsx, в том месте, где её просил handoff, с двумя причинами выше. Это не регрессия: метки никогда не было. Это объявленный ожидающий пункт, как те, что FASE 26 уже оставляла для blame/PR до 26b.

Блок "Melhores modelos por capacidade" СТРОИТСЯ, с двумя РЕАЛЬНЫМИ сигналами и без какой-либо оценки:

колонка handoffчто теперь показывает экраноткуда берётся
score(удалена)данных нет — см. выше
рекомендуемая / альтернативадве первые модели среди тех, что курирование (uses) отметило для этой возможностиworkspace_models.uses (ADR 0051), никогда не вычисляется
используетсячисло агентов ЭТОГО проекта, чей действующий binding разрешается в эту модельтот же каскад, который уже читает ModelsSection (getAgentModelBinding по агенту)

Разрешение ничьей между кандидатами — по СТОИМОСТИ (inputPricePerMillionMicros по возрастанию) — реальной, из каталога, никогда не заменителю качества. ПОРЯДОК приоритета — сначала реальное использование (сколько агентов проекта уже разрешаются в эту модель), затем стоимость: "что команда уже выбрала" — самый честный доступный сигнал без выдумывания оценки. Возможность без единой курируемой модели показывает "sem cobertura curada" — строка никогда не исчезает, тот же шаблон, что fallbackDe/колонка Origem в ModelsSection.

Раздел (MelhoresModelosPorCapacidadeSection, apps/web/src/routes/ProjectSettingsTab.tsx) читает GET /workspaces/:workspaceId/models/catalog — тот же маршрут, что ModelCatalogSection, и поэтому наследует ТУ ЖЕ видимость (maintainer): это не новый экран с собственным правилом доступа, а тот же вопрос ("как этот workspace курировал каталог?"), отвеченный по-другому.

Последствия​

  • Тот, кто не является maintainer workspace, не видит этот раздел — так же, как уже существовавший CatalogoDeModelos. Это не новое правило.
  • "Рекомендуемая" меняется, когда команда меняет модель (реальное использование) или когда owner вручную меняет цену (manualPricing), — никогда сама по себе: нет job, что-либо пересчитывающего, это выводится при чтении.
  • Если когда-нибудь продукт получит реальную метрику качества (доля успеха proposed_action по модели, например), она войдёт как НОВАЯ КОЛОНКА, не заменяя "используется"/стоимость — два вопроса ("что использует команда" и "что работает лучше") различны, тот же аргумент, что в ADR 0063 против слияния разных вопросов в одну метрику.
  • Метка "ideal" остаётся в backlog docs/explanation/backlog.md-эквиваленте, только если пользователь решит, что "возможности, требуемые агентом" стоит иметь как данные, — это продуктовое решение, а не автоматическое возобновление этого направления.