architect/arh/analysis/2026-01-17-roles-optimization/OPTIMAL_ARCHITECTURE.md

ОПТИМАЛЬНАЯ АРХИТЕКТУРА РОЛЕЙ

Дата: 2026-01-17
Принцип: Простой интерфейс, умная автоматика


ИСХОДНЫЕ ДАННЫЕ

Как пользователь работает:

Единственная проблема:

Что работает хорошо:


АНАЛИЗ ВАРИАНТОВ

❌ ВАРИАНТ 1: Только 3 режима (упростить)

Идея: Удалить system/agents/, оставить только CLAUDE.md

Плюсы:
- ✅ Максимально просто
- ✅ Нет дублирования

Минусы:
- ❌ Теряем специализацию (business, technical, etc)
- ❌ Если Claude использует их автоматически — сломаем

Вердикт: Слишком радикально


✅ ВАРИАНТ 2: Умная иерархия (РЕКОМЕНДУЕТСЯ)

Идея: Оставить архитектуру, но формализовать автоопределение

Структура:

Пользователь видит:
    Оператор ● | Проектор ◆ | Архитектор ▲

Claude определяет автоматически:
    ↓
    Тип работы (research/plan/code/ops)
    ↓
    Output Style (Default/SafeDialog/Coder/Architect)
    ↓
    L1-L4 правила (да/нет)
    ↓
    [при необходимости] Специалист (business/technical/etc)
    ↓
    [при необходимости] Исполнитель (coder/infra/etc)

Плюсы:
- ✅ Просто для пользователя (3 режима)
- ✅ Умно внутри (автоопределение)
- ✅ Решает проблему L1-L4
- ✅ Сохраняет существующую структуру

Минусы:
- ⚠️ Нужно научить Claude автопереключать Output Style

Вердикт: ОПТИМАЛЬНО


❌ ВАРИАНТ 3: Плоские роли

Идея: 10+ ролей вместо 3 режимов

Плюсы:
- Точность выбора

Минусы:
- ❌ Слишком сложно выбирать
- ❌ Пользователь сказал "всё само работает"

Вердикт: Не подходит


⚠️ ВАРИАНТ 4: Контекст + Режим (2D)

Идея: @проект + mode (research/plan/code/ops)

Плюсы:
- ✅ Гибко
- ✅ Явное разделение ЧТО и КАК

Минусы:
- ⚠️ Два параметра (сложнее)
- ⚠️ Пользователь не хочет явно переключать

Вердикт: Хорошо, но избыточно для текущего workflow


ОПТИМАЛЬНОЕ РЕШЕНИЕ

Архитектура: Вариант 2 + Output Styles

СНАРУЖИ (что видит пользователь):

3 режима:
     Оператор     Инфра, серверы, БД
     Проектор     Проекты, код, фичи
     Архитектор   Методология, стандарты

ВНУТРИ (что делает Claude автоматически):

1. Определяет ТИП РАБОТЫ по запросу:
   - research (найди, покажи, где используется)
   - plan (давай обсудим, как лучше, создать план)
   - code (создай, исправь, рефактор)
   - ops (настрой, запусти, проверь статус)
   - docs (создай стандарт, запиши решение)

2. Выбирает OUTPUT STYLE:
   - research  Default (без подтверждений)
   - plan  SafeDialog (показать план  ждать ок)
   - code  Coder (план один раз  код без остановок)
   - ops  SafeDialog (L3-L4 полный)
   - docs  Architect (L1 + варианты)

3. Применяет L1-L4:
   - research  L0 (без подтверждений)
   - plan  показать варианты + план
   - code  план в начале, потом L0
   - ops  L3-L4 полный
   - docs  L1

4. [опционально] Использует специалистов/исполнителей:
   - Если нужна специализация  загружает agent
   - Если базовых знаний хватает  не загружает

МАТРИЦА: РЕЖИМ × ТИП РАБОТЫ

Режим Тип работы Output Style L1-L4 Пример
Оператор ● ops SafeDialog L3-L4 полный "настрой nginx"
Оператор ● research Default L0 "покажи статус сервисов"
Проектор ◆ research Default L0 "найди где используется TelegramClient"
Проектор ◆ plan SafeDialog План "давай добавим auth в проект"
Проектор ◆ code Coder План → L0 "создай 5 компонентов" (после плана)
Проектор ◆ ops SafeDialog L3 "задеплой на сервер"
Архитектор ▲ research Default L0 "найди стандарты по security"
Архитектор ▲ plan Architect Варианты "как лучше организовать агентов"
Архитектор ▲ docs Architect L1 "создай стандарт для credentials"

КАК ЭТО РАБОТАЕТ (ПРИМЕРЫ)

Пример 1: Оператор — настройка nginx

Пользователь: "режим оператор"
Пользователь: "настрой nginx для docs.0kt.ru"

Claude:
1. Определяет: ops (настрой = операция)
2. Выбирает: SafeDialog
3. Применяет: L3

Вывод:
┌─────────────────────────────────────┐
 L3 | Сервер                         
 Изменю: /etc/nginx/sites-available/
 Действие: создам конфиг для docs   
 Откат: rm конфиг && reload         
 Риск: нет (новый сайт)             
└─────────────────────────────────────┘

Оценка: 5 минут
 Делаем?

Пример 2: Проектор — поиск (research)

Пользователь: "режим проектор"
Пользователь: "найди где используется OzonClient"

Claude:
1. Определяет: research (найди = исследование)
2. Выбирает: Default
3. Применяет: L0 (без подтверждений)

Вывод:
[использует Grep, находит файлы]

OzonClient используется в:
- projects/org/pirotehnika/app/api/ozon_reports.py:12
- projects/org/pirotehnika/app/services/sync.py:45
- library/connectors/api/ozon/__init__.py:8

[никаких подтверждений, сразу результат]

Пример 3: Проектор — планирование → код

Пользователь: "режим проектор"
Пользователь: "давай добавим auth в проект pirotehnika"

Claude:
1. Определяет: plan (давай = планирование)
2. Выбирает: SafeDialog
3. Применяет: План

Вывод:
ЗАДАЧА: Добавить auth
УРОВЕНЬ: L2 (код)

ВАРИАНТЫ:

1. JWT токены (рекомендуется)
   Плюсы: стандарт, stateless, масштабируемый
   Минусы: нужна rotация токенов

2. Session-based
   Плюсы: просто, безопасно
   Минусы: stateful, сложнее масштабировать

3. OAuth2 + JWT
   Плюсы: enterprise ready
   Минусы: сложно

Выбери: 1/2/3

[пользователь: 1]

План:
1. Создать auth middleware (5 мин)
2. Endpoints login/logout (10 мин)
3. JWT utils (encode/decode) (5 мин)
4. Защитить роуты (5 мин)
5. Тесты (10 мин)

Оценка: 35 минут
→ Делаем?

[пользователь: да]

Claude:
1. Определяет: code (после подтверждения плана)
2. Выбирает: Coder
3. Применяет: L0 (план уже согласован)

[Создаёт ВСЕ 5 пунктов БЕЗ остановок]

ВЫПОЛНЕНО:
• auth/middleware.py
• auth/routes.py
• auth/utils.py
• Защищены 12 роутов
• 8 тестов (все ✅)

Build: ✅
Tests: ✅

Пример 4: Архитектор — обсуждение

Пользователь: "режим архитектор"
Пользователь: "как лучше организовать структуру агентов?"

Claude:
1. Определяет: plan (как лучше = обсуждение)
2. Выбирает: Architect
3. Применяет: Варианты

Вывод:
ВАРИАНТЫ СТРУКТУРЫ:

1. Плоская (все агенты в agents/)
   Плюсы: просто, всё в одном месте
   Минусы: нет группировки, 20+ файлов

2. По типу (agents/specialists/, agents/workers/)
   Плюсы: логическая группировка
   Минусы: нужно знать где искать

3. По домену (agents/business/, agents/infra/)
   Плюсы: ясно какой агент для чего
   Минусы: один агент может быть в нескольких доменах

4. Иерархическая (agents/ → specialists/ → business/)
   Плюсы: чёткая иерархия, масштабируемо
   Минусы: глубокая вложенность

Выбери: 1/2/3/4 или предложи свой вариант

[никаких подтверждений, просто обсуждение]

РЕАЛИЗАЦИЯ

1. Output Styles (создать)

Файлы:

.claude/output-styles/
    Default.md        БЕЗ подтверждений (research)
    SafeDialog.md     L1-L4 полный (ops, plan) [уже есть]
    Coder.md          План  код без остановок (code)
    Architect.md      Варианты + L1 (docs, plan в архитекторе)

Default.md:

---
name: Default
description: Research mode - no confirmations
---

# Research Mode

You are Claude Code in research mode.

## Behavior
- Read, analyze, search without asking
- No confirmations for read-only operations
- Provide direct answers
- Use specialized tools (Grep, Glob, Read)

## When to use
- User asks: "find", "show", "where is", "what is"
- Read-only operations
- Analysis without changes

Coder.md:

---
name: Coder
description: Code mode - plan once, then implement without stops
---

# Coder Mode

You are Claude Code in implementation mode.

## Behavior

### Planning phase
1. Show full plan with:
   - What will be created/changed
   - File structure
   - Estimates per item
   - Total time
2. Wait for confirmation

### Implementation phase (after plan approved)
3. Execute ALL items WITHOUT stopping
4. Run tests automatically
5. Report results at the end

## No confirmations during implementation
- ❌ Don't ask before creating each file
- ❌ Don't ask before each function
- ✅ Do everything from approved plan

## Example

Plan:
- Create Header.tsx (3 min)
- Create Footer.tsx (3 min)
- Create Layout.tsx (5 min)
Total: 11 minutes

[user: ok]

[Creates ALL without asking]

DONE:
- Header.tsx ✅
- Footer.tsx ✅
- Layout.tsx ✅
Tests: ✅

Architect.md:

---
name: Architect
description: Architecture mode - options + L1 for docs
---

# Architect Mode

You are Claude Code in architecture mode.

## Behavior

### For discussions
- Always provide 2-4 options
- Each with pros/cons
- Wait for choice

### For documentation (L1)
- Show what will be created/changed
- Brief confirmation
- Create document

## No code
- Focus on methodology, standards, decisions
- "Without code until approved" principle

2. Автоопределение типа работы (в CLAUDE.md)

Добавить секцию:

## АВТООПРЕДЕЛЕНИЕ ТИПА РАБОТЫ

Claude автоматически определяет тип работы по триггерам в запросе:

| Тип | Триггеры | Output Style | L1-L4 |
|-----|----------|--------------|-------|
| **research** | найди, покажи, где, что такое, как работает | Default | L0 |
| **plan** | давай, как лучше, нужно, предложи, обсудим | SafeDialog/Architect | План/Варианты |
| **code** | создай, исправь, рефактор, добавь (после плана) | Coder | План → L0 |
| **ops** | настрой, запусти, проверь, перезапусти, deploy | SafeDialog | L3-L4 |
| **docs** | создай стандарт, запиши, документируй | Architect | L1 |

### Алгоритм

1. Прочитать запрос
2. Определить тип работы по триггерам
3. Если нужна смена Output Style → выполнить `/output-style XXX`
4. Применить соответствующие правила L1-L4
5. Продолжить работу

### Переходы

**plan → code:**

[планирование в SafeDialog]
План согласован
/output-style Coder
[реализация без остановок]

**code → plan:**

[кодинг]
Появился новый вопрос требующий обсуждения
/output-style SafeDialog
[обсуждение]



3. Обновить описания режимов

CLAUDE.md — режимы:

## РЕЖИМ: ОПЕРАТОР ●

**Зона:** Инфра, серверы, БД, операции

**Типичная работа:**
- ops (настройка, запуск) → SafeDialog (L3-L4)
- research (статус, проверки) → Default (L0)

**Output Style:** Автоматически (ops → SafeDialog, research → Default)

---

## РЕЖИМ: ПРОЕКТОР ◆

**Зона:** Проекты, код, фичи

**Типичная работа:**
- research (поиск в коде) → Default (L0)
- plan (обсуждение фичи) → SafeDialog (план)
- code (реализация) → Coder (план → L0)
- ops (деплой) → SafeDialog (L3)

**Output Style:** Автоматически по типу работы

---

## РЕЖИМ: АРХИТЕКТОР ▲

**Зона:** Методология, стандарты, архитектура

**Типичная работа:**
- research (анализ) → Default (L0)
- plan (обсуждение подхода) → Architect (варианты)
- docs (создание стандарта) → Architect (L1)

**Output Style:** Автоматически (research → Default, plan/docs → Architect)

ПРЕИМУЩЕСТВА РЕШЕНИЯ

✅ Для пользователя

Просто:
- 3 режима (как сейчас)
- Не нужно думать о подрежимах
- Не нужно явно переключать Output Style

Понятно:
- Оператор = инфра
- Проектор = проекты
- Архитектор = методология

Быстро:
- Никаких лишних подтверждений при кодинге
- Подтверждения только когда реально опасно


✅ Для Claude

Умно:
- Автоопределение типа работы
- Правильный Output Style автоматически
- L1-L4 только когда нужно

Гибко:
- Может использовать system/agents/ когда нужна специализация
- Может не использовать если базовых знаний хватает

Безопасно:
- L3-L4 для инфры
- Планирование перед кодингом
- Откаты, бэкапы


✅ Для архитектуры

Сохраняет существующее:
- 3 режима остаются
- system/agents/ остаётся (используется автоматически)
- Не нужно всё переделывать

Формализует неявное:
- Явные правила автоопределения
- Явная связь режим → тип → style → L1-L4
- Документировано

Масштабируемо:
- Легко добавить новый тип работы
- Легко добавить новый Output Style
- Легко добавить новый режим


МИГРАЦИЯ

Шаг 1: Создать Output Styles (1 час)

Шаг 2: Обновить CLAUDE.md (30 мин)

Шаг 3: Удалить settings.local.json → outputStyle (5 мин)

Шаг 4: Протестировать (30 мин)

Шаг 5: Документировать (15 мин)

ИТОГО: ~2.5 часа (для AI ~15 минут реального времени)


ИТОГО

Оптимальное решение:
- ✅ Простой интерфейс (3 режима)
- ✅ Умная автоматика (автоопределение типа → style → L1-L4)
- ✅ Решает проблему (L1-L4 не мешает кодингу)
- ✅ Сохраняет существующую архитектуру
- ✅ Масштабируемо

Делаем?