Идеи
Арена решений/design/concept.md

Концепция «Арены решений» (v0)

Четыре сущности

Сущность Что это Где живёт
Задача Подробное ТЗ плюс список требований с id (REQ-shop-01...). Требования и есть контракт: по ним пишутся тесты, по ним оценивает граф. arena/tasks/<task>/ в репо Арены
Вариант Одно решение задачи. Отличается от других ровно одной осью: модель, архитектура, библиотека или стек. ветка <task>/<variant> в репо Арены
Прогон Один акт оценки варианта: скрытые тесты + граф + ручные заметки. Вариант можно прогнать повторно после правок. results/<task>/<variant>.md в папке идеи
Оценка Числа и выводы прогона. Числа в results.json, выводы в ADR. папка идеи, попадает на сайт

Оси экспериментов

Меняется одно, остальное фиксировано. Иначе непонятно, что дало разницу.

Ось Меняем Держим Пример варианта
Модель / агент исполнитель ТЗ, тесты, стек, промпт shop/claude-fable, shop/gpt-5
Архитектура структура кода ТЗ, тесты, стек shop/feature-sliced, shop/flat
Библиотека одна зависимость всё остальное, берём эталон shop/redux → shop/context
Стек фреймворк ТЗ, тесты shop/next → shop/vue

Эталон: первый вариант, который прошёл тесты и тебя устроил. От него ответвляются варианты по осям «библиотека» и «архитектура».

Правило скрытых тестов

Исполнитель получает ТЗ и список требований. Тесты он не видит до сдачи. После сдачи тесты запускаются один раз, результат фиксируется. Если исполнителю дать тесты, он оптимизирует под них, и ось «качество решения» превращается в ось «подгонка».

Тесты лежат в репо Арены в arena/tests/<task>/, но ветки вариантов создаются от ветки tasks-only, где папки tests/ нет. Исполнитель-агент работает в ветке и физически не видит тестов.

Как подключается граф-оценщик (Twin)

Twin из product-digital-twin пока идея, но контракт с ним можно зафиксировать сейчас, чтобы потом ничего не переделывать:

flowchart LR
  TZ[ТЗ + REQ-список] --> V[Вариант: ветка]
  TZ --> T[Скрытые тесты<br/>помечены REQ-id]
  V --> R[Прогон]
  T --> R
  V --> G[Граф Twin:<br/>REQ ↔ код ↔ тесты ↔ правила]
  G --> R
  R --> S[results.json + ADR]
  S --> Site[Страница идеи на сайте]

Что Арена даёт графу (и ты сам, пока графа нет):

  1. Список требований с устойчивыми id в tasks/<task>/requirements.md (frontmatter, как в паспорте фичи Twin).
  2. Тесты, помеченные id: в названии теста или комментарии стоит REQ-shop-04. Так граф или скрипт считают покрытие: какое требование каким тестом проверено и прошёл ли он.
  3. Правила (rules.md): что запрещено независимо от требований. Например «UI-компонент не импортирует слой данных напрямую». Это вход для проверки «загрязнение архитектуры» у Twin.

Что граф отдаёт (ручной чеклист до появления Twin):

  • требования без реализации (по REQ-id в коде, коммитах, тестах);
  • требования без тестов и тесты без требований;
  • нарушения правил;
  • impact: сколько файлов трогает одно требование (косвенная мера связности).

Пока Twin нет, эти четыре пункта ты заполняешь руками по чеклисту в scoring.md. Когда Twin появится, он заполняет то же самое и формат результата не меняется.

Хранение вариантов

Способ Плюсы Минусы
Ветка на вариант в репо Арены дёшево, diff между вариантами одной командой, история есть ветки не мержатся, их много
Папка на вариант всё видно сразу, легко сравнить файлы репо раздувается, зависимости дублируются, CI тяжёлый
Репо на вариант полная изоляция много репо, сравнивать неудобно

Рекомендация: ветки в отдельном репо arena. Ветки не мержатся никогда. Мержится только результат прогона, и не в репо Арены, а сюда, в папку идеи solutions-arena/results/. Репо Арены хранит ТЗ, тесты и варианты. Репо идей хранит выводы и показывает их на сайте.

Структура репо arena:

arena/
  tasks/shop/
    brief.md            ТЗ человеческим языком
    requirements.md     REQ-список с id (frontmatter)
    rules.md            архитектурные правила
  tests/shop/           Playwright, видны только в main и run-веткaх
  tools/run.mjs         поднять вариант, прогнать тесты, выдать results.json
  .gitignore

Ветки: main (всё), tasks-only (без tests/), shop/<variant> (от tasks-only).

Формат ADR

Один файл на вывод, не на вариант. Вывод обычно рождается из сравнения двух-трёх вариантов.

# ADR-003: Контекст вместо Redux в магазине на 5 экранах

Дата: 2026-11-10. Варианты: shop/redux (эталон), shop/context.

## Контекст
Что сравнивали и зачем.

## Наблюдение
Числа из прогонов: тесты 19/20 против 18/20, бандл −38 КБ, 3 нарушения правил против 0.

## Вывод
Одно предложение, которое можно применить на работе.

## Границы
Где вывод не работает (размер проекта, команда, стек).

Лежит в solutions-arena/adr/ADR-NNN-slug.md. На сайте попадает в «Подробнее» страницы идеи, самые важные дублируются в раздел Итог.