# Lab 06: Итоговый практикум курса

## Цель

Пройти полный цикл курса на одном небольшом фрагменте приложения:

```text
complexity → interface → depth → agent task → design plan → implementation → acceptance
```

К концу практикума у вас должен быть один оформленный артефакт: решение о модуле и бриф для AI-агента
с критериями приёмки и результатами проверки.

## Мини-пример

Ситуация:

```text
В нескольких местах приложения по-разному проверяется роль пользователя:
UI скрывает кнопки, API запрещает действие, письмо строит текст по роли, а тесты повторяют часть правил.
```

Слабый ход:

```text
Агент, вынеси роли в отдельный сервис и почини всё.
```

Почему слабый: агент может создать новый `RoleService`, но оставить правила размазанными, расширить интерфейс
и добавить pass-through слой без глубины.

## Задание

Выберите один небольшой фрагмент реального или учебного приложения. Хорошо подходят:

- роли пользователя;
- скидки и промокоды;
- загрузка файла;
- отправка письма;
- ошибки формы;
- интеграция с внешним провайдером;
- настройки уведомлений.

Пройдите 7 шагов.

## Шаг 1. Найти сложность

Опишите, какая сложность мешает:

- когнитивная нагрузка: что приходится держать в голове;
- усиление изменений: где маленькая правка расползается;
- скрытые правила: что знают только “по памяти”;
- повторение знания: где одно правило живёт в нескольких местах.

Короткий шаблон:

```text
Проблемный фрагмент:

Какая сложность:
- cognitive load:
- change amplification:
- hidden rules:
- duplicated knowledge:
```

## Шаг 2. Назвать текущий интерфейс

Опишите, что сейчас должен знать вызывающий код:

- входные данные;
- результат;
- ошибки;
- порядок вызовов;
- ограничения;
- побочные эффекты.

Если интерфейс не назван явно, опишите фактический интерфейс: что приходится знать, чтобы не ошибиться.

## Шаг 3. Проверить глубину

Ответьте:

- это deep module или shallow module;
- что модуль реально скрывает;
- что произойдёт по deletion test;
- есть ли pass-through слой;
- какой leverage получает вызывающий код;
- где появляется locality.

Короткая оценка:

```text
Depth:
Deletion test:
Pass-through risk:
Leverage:
Locality:
```

## Шаг 4. Сформулировать целевое изменение

Выберите один маленький дизайн-шаг. Не переписывайте всё.

Хорошие варианты:

- собрать правило в один модуль;
- сузить интерфейс;
- спрятать ошибочные состояния;
- заменить pass-through слой на модуль с настоящим поведением;
- добавить тест через публичное поведение;
- убрать гипотетический seam.

## Шаг 5. Написать бриф агенту

Соберите запрос агенту:

```text
Цель:

Контекст:

Текущий интерфейс:

Желаемый дизайн-шаг:

Ограничения:

Перед кодом покажи дизайн-план:
- какой модуль меняешь;
- какой интерфейс сохраняешь или вводишь;
- какое знание будет скрыто;
- почему это не pass-through;
- как проверишь поведение.

Критерии приёмки:
- поведение:
- тесты/проверка:
- дизайн:
- дифф:
```

## Шаг 6. Принять результат

После работы агента заполните:

```text
Что изменилось:

Какая проверка запущена:

Что показал дифф:

Стало ли меньше знания у callers:

Не появился ли новый shallow/pass-through модуль:

Что осталось следующим шагом:
```

## Шаг 7. Зафиксировать вывод

Одним абзацем напишите, чему научил этот фрагмент:

```text
Главный вывод:

Какой сигнал сложности я теперь замечу раньше:

Какую фразу агенту я буду использовать в похожей ситуации:
```

## Хороший ответ

```text
Проблемный фрагмент:
Роли пользователя проверяются в UI, API и генерации письма.

Сложность:
- cognitive load: нужно помнить список ролей и ограничения в трёх местах;
- change amplification: новая роль требует менять UI, API, письмо и тесты;
- hidden rules: архивный пользователь не может выполнять действие, но правило не названо;
- duplicated knowledge: список ролей повторяется в нескольких файлах.

Текущий интерфейс:
Callers сами знают допустимые роли, ошибки и часть правил доступа.

Depth:
Сейчас модуль shallow: интерфейс широкий, callers знают много правил.

Deletion test:
Если удалить текущую прослойку, почти ничего не изменится: правила уже живут снаружи.

Целевой дизайн-шаг:
Собрать проверку роли в один модуль с публичным интерфейсом:
canUserPerformAction(user, action) -> result.

Бриф агенту:
Сначала найди callers проверки роли. Перед кодом покажи дизайн-план:
какой интерфейс будет у модуля, какие правила он скроет, какие ошибки вернёт,
почему это не pass-through, как проверишь публичное поведение.

Критерии приёмки:
- UI и API используют один интерфейс проверки;
- архивный пользователь получает понятный отказ;
- список ролей не повторяется в callers;
- тесты проверяют публичное поведение canUserPerformAction;
- дифф не затрагивает unrelated файлы.

Вывод:
Я увидела, что “разнести код” не равно “сделать модуль глубже”.
Следующий раз сначала попрошу агента назвать callers, интерфейс и deletion test.
```

## Самопроверка

- Я выбрала маленький фрагмент, а не весь проект.
- Я назвала форму сложности.
- Я описала текущий интерфейс.
- Я проверила depth и deletion test.
- Я сформулировала один дизайн-шаг.
- Я дала агенту бриф с дизайн-планом до кода.
- Я приняла результат по поведению, тестам, диффу и дизайну.
- Я записала личный вывод, который смогу применить позже.