---
name: workflow-architecture-change
description: |
  Major architectural shift protocol. ADR creation, migration strategy, 
  rollback plan. For: layer changes, pattern adoption, system redesign, 
  breaking API changes, infrastructure migration. Always 🔴 Complex. 
  NOT for simple refactoring (workflow-refactoring).
---

# 🏗️ Architecture Change Workflow — Архитектурные Изменения

<purpose>
Протокол для значительных архитектурных изменений системы.
Миграции, масштабирование, смена технологий, breaking changes.
</purpose>

---

## Когда Использовать

**Триггеры:**

- Миграция базы данных (смена схемы, новая БД)
- Переход на новый фреймворк/технологию
- Декомпозиция монолита
- Изменение публичных API (breaking changes)
- Масштабирование архитектуры
- Интеграция с новой инфраструктурой

**НЕ использовать для:**

- Новой функциональности без арх. изменений → `feature.md`
- Фикса багов → `debugging.md`
- Рефакторинга без изменения архитектуры → `refactoring.md`
- Анализа legacy без изменений → `legacy-analysis.md`

---

## Ключевой Принцип

> **Архитектурные изменения = высокий риск + высокая цена ошибки.**

**Требуется ВСЕГДА:**

- Research.md (анализ)
- Plan.md (детальный план)
- ADR (Architecture Decision Record)
- STOP-gates (утверждение)
- Rollback strategy

---

## Фаза 1: Анализ и Оценка

### Шаг 1.1: Определение Scope

**Документировать:**

```markdown
## Architecture Change Request

### Цель
[Что хотим изменить и зачем]

### Текущая Архитектура
[Описание текущего состояния]

### Желаемая Архитектура
[Описание целевого состояния]

### Драйверы Изменения
- [Почему нужно менять: масштаб, производительность, maintainability]
```

### Шаг 1.2: Оценка Воздействия

| Область | Вопросы |
|---------|---------|
| **Данные** | Миграция данных нужна? Можно ли откатить? |
| **API** | Breaking changes? Версионирование? |
| **Зависимости** | Какие модули затронуты? |
| **Интеграции** | Внешние системы затронуты? |
| **Инфраструктура** | Новые сервисы/ресурсы нужны? |
| **Команда** | Какие навыки нужны? |

### Шаг 1.3: Классификация Риска

| Уровень | Критерии |
|---------|----------|
| 🟡 Medium | Внутренние изменения, нет breaking changes, данные не мигрируют |
| 🔴 High | Breaking API changes, миграция данных, новая инфраструктура |
| ⚫ Critical | Production data at risk, security implications, irreversible |

> **Для архитектурных изменений 🟢 не существует. Минимум 🟡.**

---

## Фаза 2: Исследование (Research)

### Шаг 2.1: @coder-expert для Анализа

```markdown
## 🤖 Delegation
**Agent:** @coder-expert
**Purpose:** Провести архитектурный анализ для [изменение]
**Expected Output:** Research.md с полным анализом
**Focus:**
- Текущая архитектура (as-is)
- Целевая архитектура (to-be)
- Риски и ограничения
- Альтернативные подходы
- Зависимости
🛑 STOP after completion. Return control to @meta-architect.
```

### Шаг 2.2: Структура Research.md

```markdown
# Research: [Название изменения]
*Created: YYYY-MM-DD*

## Executive Summary
[1-2 абзаца: что, зачем, основные риски]

## Current Architecture (As-Is)
[Диаграммы, описание текущего состояния]

### Компоненты
| Компонент | Роль | Зависимости |
|-----------|------|-------------|
| ... | ... | ... |

### Ограничения Текущей Архитектуры
- [Проблема 1]
- [Проблема 2]

## Target Architecture (To-Be)
[Диаграммы, описание целевого состояния]

### Ключевые Изменения
| Область | Было | Будет |
|---------|------|-------|
| ... | ... | ... |

## Analysis

### Альтернативы
| Вариант | Pros | Cons | Риск | Стоимость |
|---------|------|------|------|-----------|
| A | ... | ... | ... | ... |
| B | ... | ... | ... | ... |

### Риски
| Риск | Вероятность | Impact | Митигация |
|------|-------------|--------|-----------|
| ... | ... | ... | ... |

### Зависимости
- [Внешние системы]
- [Внутренние модули]
- [Инфраструктура]

## Recommendations
[Какой вариант и почему]

---
🛑 **STOP: Требуется review Research.md перед планированием**
```

---

## Фаза 3: Планирование

### Шаг 3.1: STOP Gate #1 — Review Research

> **Не начинать планирование без утверждения Research.md**

### Шаг 3.2: Создание ADR

```markdown
# ADR-NNN: [Название Решения]
*Status: Proposed/Accepted/Deprecated*
*Date: YYYY-MM-DD*

## Context
[Ситуация, проблема, ограничения]

## Decision
[Что решили делать]

## Rationale
[Почему именно так]

## Alternatives Considered
- [Вариант A]: отклонён потому что...
- [Вариант B]: отклонён потому что...

## Consequences

### Positive
- [Плюс 1]
- [Плюс 2]

### Negative
- [Минус 1]
- [Минус 2]

### Risks
- [Риск и митигация]

## Implementation Notes
[Ключевые технические детали]
```

### Шаг 3.3: Создание Plan.md

```markdown
# Plan: [Название изменения]
*Created: YYYY-MM-DD*
*Related: ADR-NNN, Research.md*

## Цель
[Конкретная измеримая цель]

## Стратегия Миграции

### Подход
- [ ] Parallel Run (старое и новое работают одновременно)
- [ ] Big Bang (переключение в один момент)
- [ ] Strangler Fig (постепенная замена)
- [ ] Feature Flags (переключаемое поведение)

### Обоснование
[Почему выбран этот подход]

## Фазы Реализации

### Phase 1: [Название]
**Цель:** [Что достигаем]
**Длительность:** [Оценка]
**Зависимости:** [Что нужно до начала]

| Файл/Модуль | Изменение | Ответственный |
|-------------|-----------|---------------|
| ... | ... | ... |

**Acceptance Criteria:**
- [ ] [Критерий]

**Rollback:**
[Как откатить эту фазу]

---

### Phase 2: [Название]
... [та же структура]

---

## Миграция Данных (если применимо)

### Стратегия
[Описание]

### Скрипты
- `migration_001.sql` — [описание]

### Валидация
- [ ] [Как проверить что данные мигрировали корректно]

### Rollback
- [ ] [Как откатить миграцию]

## Breaking Changes

### API Changes
| Endpoint | Было | Будет | Migration Path |
|----------|------|-------|----------------|
| ... | ... | ... | ... |

### Client Migration
[Как клиенты должны мигрировать]

## Timeline

```

Неделя 1: Phase 1
Неделя 2: Phase 2
Неделя 3: Migration + Validation
Неделя 4: Switch + Monitoring

```

## Rollback Strategy

### При сбое Phase 1
[Действия]

### При сбое Phase 2
[Действия]

### Point of No Return
[Какая точка невозврата, после чего откат невозможен]

## Success Criteria
- [ ] [Измеримый критерий 1]
- [ ] [Измеримый критерий 2]
- [ ] Все тесты проходят
- [ ] Performance не деградировала
- [ ] Мониторинг показывает норму

---
🛑 **STOP: Требуется утверждение плана перед реализацией**
```

---

## Фаза 4: Реализация

### Шаг 4.1: STOP Gate #2 — Plan Approval

> **Не начинать реализацию без утверждения Plan.md**

### Шаг 4.2: Поэтапная Реализация

**Для КАЖДОЙ фазы:**

```
1. Промпт для @coder (только эта фаза)
        ↓
2. @coder реализует
        ↓
3. @reviewer проверяет
        ↓
4. [PASS] → тесты GREEN → commit/checkpoint
   [FAIL] → анализ → исправление → повтор
        ↓
5. Валидация acceptance criteria фазы
        ↓
6. [Если миграция] Тестовый прогон на стейджинге
        ↓
7. 🛑 STOP — подтверждение готовности к следующей фазе
```

### Промпт для @coder (Архитектурные изменения)

```markdown
# Task: [Phase N] — [Название]

## Context
Архитектурное изменение: [описание]
Текущая фаза: [N из M]
Зависит от: [предыдущие фазы завершены]

## Scope (ТОЛЬКО ЭТА ФАЗА)
[Конкретные шаги только для этой фазы]

## Requirements
1. [Требование]
2. [Требование]

## Constraints
❌ НЕ выходить за scope этой фазы
❌ НЕ менять другие модули без явного указания
❌ Сохранять обратную совместимость (если указано)

## Acceptance Criteria
✅ [Критерий этой фазы]
✅ Все тесты проходят
✅ Нет регрессий

## Files to Work With
- `path/to/file` — [изменение]

## Rollback
Если что-то идёт не так: [как откатить]

## Output Format
Код + краткое описание изменений.
```

---

## Фаза 5: Валидация и Деплой

### Шаг 5.1: Предпродакшн Валидация

**Чеклист:**

- [ ] Все фазы завершены
- [ ] Все @reviewer PASS
- [ ] Все тесты проходят
- [ ] Performance тесты (если применимо)
- [ ] Миграция данных протестирована на staging
- [ ] Rollback протестирован

### Шаг 5.2: Деплой Стратегия

| Стратегия | Когда | Риск |
|-----------|-------|------|
| **Feature Flag** | Постепенный rollout | Низкий |
| **Canary** | % трафика на новое | Средний |
| **Blue-Green** | Мгновенное переключение | Средний |
| **Big Bang** | Все сразу | Высокий |

### Шаг 5.3: Мониторинг после Деплоя

**Первые 24 часа:**

- [ ] Error rate норма
- [ ] Latency норма
- [ ] Ключевые метрики норма
- [ ] Нет жалоб пользователей

**Если аномалии:**

```
1. Определить severity
2. [Critical] → немедленный rollback
3. [Major] → оценить, возможно rollback
4. [Minor] → фиксим в hotfix режиме
```

---

## Антипаттерны Архитектурных Изменений

| Антипаттерн | Почему плохо | Как правильно |
|-------------|--------------|---------------|
| **Без Research** | Неизвестные unknowns | Всегда Research.md |
| **Big Bang без rollback** | Невозможно откатить | Всегда rollback strategy |
| **Нет ADR** | Забудут почему так решили | Документировать решения |
| **Все фазы сразу** | Нельзя отследить проблему | Поэтапно с checkpoint'ами |
| **Миграция без backup** | Потеря данных | Backup + тестовый rollback |
| **Skip staging** | Production surprises | Всегда staging сначала |

---

## Чеклист

### Перед Началом

- [ ] Scope определён
- [ ] Риск оценён (🟡/🔴/⚫)
- [ ] Research.md создан и утверждён
- [ ] ADR создан

### Планирование

- [ ] Plan.md создан
- [ ] Фазы определены
- [ ] Rollback для каждой фазы
- [ ] 🛑 STOP-gate пройден (утверждение)

### Реализация

- [ ] Поэтапно
- [ ] @reviewer после каждой фазы
- [ ] Checkpoint'ы между фазами

### Деплой

- [ ] Staging validation
- [ ] Rollback протестирован
- [ ] Мониторинг настроен
- [ ] План отката готов

---

## Quick Reference

```
Архитектурное изменение
         ↓
Research.md (анализ as-is, to-be, риски)
         ↓
🛑 STOP — review Research
         ↓
ADR + Plan.md (фазы, rollback)
         ↓
🛑 STOP — утверждение плана
         ↓
Поэтапная реализация:
  Phase 1 → @coder → @reviewer → checkpoint
  Phase 2 → @coder → @reviewer → checkpoint
  ...
         ↓
Staging validation
         ↓
Deploy (с мониторингом)
         ↓
Post-deploy monitoring
         ↓
DONE
```

---

**Связанные файлы:**

- `references/adr-template.md` — шаблон ADR
- `references/architecture-template.md` — шаблон архитектуры
- `references/system-blocks-template.md` — шаблон системных блоков
- `.claude/skills/workflow-legacy-analysis/SKILL.md` — анализ legacy перед изменениями
- `.claude/skills/role-coder-expert/references/ai-failure-modes.md` — если @coder зацикливается

---

**END OF WORKFLOW**