01 — BRD: ORCH-081 (ORCH-52h)

Work Item: ORCH-081 Эпик: ORCH-052 (продолжение ORCH-52a / ORCH-074) Тип: Багфикс (конфигурация эффорта агентов) Приоритет: HIGH Repo: orchestrator (self-hosting)

1. Контекст и проблема

При проверке ORCH-074 (08.06) обнаружено: resolve_agent_effort() для всех 6 агентов в проде возвращает пустую строку '', хотя в src/config.py заданы осмысленные дефолты (agent_effort_default="high", per-agent high/medium). Итог: флаг --effort не передаётся в Claude CLI, и каждый агент бежит на встроенном CLI-дефолте эффорта, а не на заявленном high/medium.

Корень (диагностика)

В проде env-переменные ORCH_AGENT_EFFORT_DEFAULT и ORCH_AGENT_EFFORT_{ANALYST,ARCHITECT,DEVELOPER,REVIEWER,TESTER,DEPLOYER} выставлены в пустую строку (VAR= без значения). Pydantic Settings трактует присутствующую env-переменную (даже пустую) как явное значение и перебивает дефолт класса: agent_effort_* = ''. В цепочке резолва (launcher._resolve_agent_attr):

per-agent '' → falsy → пропуск (уровень 2);
default '' → falsy → пропуск (уровень 3);
→ возврат '' (уровень 4, «без флага»).

Поскольку и default тоже пуст, привычный откат «per-agent пуст → взять default» не спасает: откатываться не на что. Это ключевой нюанс — фикс обязан давать каждой роли непустой «пол» (floor) даже когда И per-agent, И default env пусты.

2. Бизнес-ценность / зачем важно

Для Opus 4.8 (канон Anthropic) уровень reasoning-эффорта влияет на качество вывода сильнее, чем у прежних моделей. Coding/agentic роли (особенно developer) должны идти минимум на high, а developer — кандидат на xhigh. Сейчас фактически работает неконтролируемый CLI-дефолт → прямой удар по стратегии надёжности и предсказуемости качества всего конвейера (включая enduro-trails из общего инстанса).

3. Решение (бизнес-уровень)

Принят вариант (c) (решение Славы, 08.06): пустая строка эффорта трактуется как «не задано» и откатывается на осмысленный per-role дефолт (а не на CLI-дефолт), устойчиво к пустым env. Дополнительно — зафиксировать целевые дефолты в config.py и .env.example.

Целевые значения эффорта (единственный апгрейд — `developer`)

Агент	Эффорт	Обоснование
analyst	high	intelligence-роль
architect	high	intelligence-роль
developer	xhigh	coding/agentic, канон Opus 4.8 → апгрейд с `high`
reviewer	high	intelligence-роль
tester	medium	механическая роль
deployer	medium	механическая роль

developer → xhigh — единственное изменение относительно текущих config-дефолтов; остальные значения подтверждают текущий замысел и фиксируются устойчиво.

4. Грабли / ограничения (из бизнес-запроса)

Хост-репо / env-правки НЕ переживают деплой, если положены в git-managed файл (урок 08.06 про docker-compose + TZ). Источник правды для реальных значений — .env на хосте (gitignored), канон-шаблон — .env.example. Фикс обязан быть code-side robust: даже если прод-.env снова окажется с пустыми ORCH_AGENT_EFFORT_*, эффорт всё равно резолвится в целевые значения.
Self-hosting: правка касается инструмента, который сейчас в проде обслуживает и другие проекты. Прод-контейнер orchestrator не ронять в рамках задачи; деплой — через штатный deploy-staging → Confirm Deploy.

5. Не-цели

НЕ трогать model-резолв (resolve_agent_model — сделан в ORCH-074).
НЕ включать G3 model-routing — все 6 агентов остаются на claude-opus-4-8.
НЕ менять значения эффорта сверх согласованных (high/medium/xhigh для developer). Иные значения — отдельное взвешенное решение.

6. Затронутые стороны

Все агенты конвейера (analyst → deployer) во всех проектах общего инстанса.
Операторы (правка прод-.env), документация (README таблица, .env.example).

5.7 KiB Raw Blame History Unescape Escape