Claude Code для итерации UI в Flutter: практический рабочий процесс

Проблема: быстрая итерация UI, которая не превращается в хаос

Быстрая работа с Flutter часто начинается хорошо. Вы подправляете верстку, добавляете кнопку, сдвигаете поле — и экран быстро становится лучше. Проблемы проявляются через несколько итераций, когда скорость превращается в гору изменений, которые никто не хочет ревьюить.

Команды обычно сталкиваются с одинаковыми провалами:

• Дерево виджетов растёт без плана, и «маленькое» изменение требует правок в куче файлов.
• Состояние прикрученo к UI‑коду, ререндеры непредсказуемы, отладка сложнее.\
• Логика навигации разбросана (push здесь, pop там), пока потоки перестают соответствовать реальному поведению пользователей.
• Имена дрейфуют, компоненты дублируются, никто не уверен, какой виджет — «истинный».
• Дифы становятся огромными, ревьюеры пролистывают, баги проходят, и регрессии появляются позже.

Большая причина — подход «один большой промпт»: описать фичу целиком, попросить все экраны и принять большой вывод. Ассистент пытается помочь, но трогает слишком много мест в коде одновременно. Изменения становятся грязными, их сложно ревьюить и рискованно мёржить.

Повторяемая петля решает это, заставляя думать и ограничивая радиус поражения. Вместо «построить фичу» делайте это циклично: выберите одну пользовательскую историю, сгенерируйте минимальный UI‑срез, который её подтверждает, добавьте только то состояние, что нужно этому срезу, затем пробросьте навигацию для одного пути. Каждый проход остаётся достаточно маленьким, чтобы его можно было ревьюить, а ошибки легко откатить.

Цель — практичный рабочий процесс, превращающий истории в конкретные экраны, обработку состояния и навигационные потоки без потери контроля. При хорошем подходе вы получите модульные куски UI, меньшие диффы и меньше сюрпризов при изменении требований.

Превратите пользовательские истории в понятный UI‑спек, который можно построить

Пользовательские истории написаны для людей, а не для дерева виджетов. Прежде чем генерировать что‑то, преобразуйте историю в небольшой UI‑спек, описывающий видимое поведение. «Готово» должно быть тестируемым: что пользователь видит, на что нажимает и что подтверждает — а не то, что дизайн «кажется современным».

Простой способ сохранить объём конкретным — разбить историю на четыре блока:

• Экраны: что меняется, что остаётся прежним.
• Компоненты: какие новые элементы UI появляются и где они живут.
• Состояния: загрузка, успех, ошибка, пусто и что показывает каждое из них.
• События: тапы, свайпы, pull‑to‑refresh, навигация назад, повторы.

Если история всё ещё мутная, ответьте на эти вопросы простым языком:

• Какие экраны меняются, а какие нет?
• Какие новые компоненты появляются и где они принадлежат?
• Какие состояния существуют и что показывает каждое?
• Какие события приводят к смене состояний?
• Какой чек‑лист приёмки можно выполнить за 30 секунд после запуска приложения?

Добавляйте ограничения заранее — они направляют каждое решение по верстке: базовые темы (цвета, отступы, типографика), адаптивность (сначала телефон в портрете, затем планшеты) и минимумы доступности — размер таргета для тапов, масштабируемость текста, понятные метки для иконок.

Наконец, решите, что стабильно, а что гибко, чтобы не трясти кодовую базу. Стабильные вещи — те, от которых зависят другие фичи: имена маршрутов, модели данных, существующие API. Гибкие — безопаснее для итераций: структура верстки, микрокопирайт, точный состав виджетов.

Пример: «Как пользователь, я могу сохранить товар в Избранное со страницы деталей.» Понятный UI‑спек может быть:

• На странице деталей есть иконка закладки.
• По тапу состояние сохранено/несохранено переключается.
• Пока идёт сохранение — показывать небольшой индикатор прогресса.
• При ошибке — показать строчное сообщение с действием Повтор.
• Навигация остаётся прежней (без новых роутов).

Этого достаточно, чтобы построить, ревьюить и итеративно править без домыслов.

Настройте цикл итераций так, чтобы диффы оставались маленькими

Маленькие диффы не означают медленную работу. Они делают каждое изменение лёгким для ревью, простым для отката и трудным для разрушения. Самое простое правило: одна страница или одно взаимодействие за итерацию.

Выберите узкий срез перед началом. «Добавить пустое состояние в Orders screen» — хороший срез. «Переделать весь Orders flow» — нет. Цель — дифф, который коллега поймёт за минуту.

Стабильная структура папок тоже помогает держать изменения локализованными. Простая «feature‑first» раскладка предотвращает разброс виджетов и маршрутов по проекту:

lib/
  features/
    orders/
      screens/
      widgets/
      state/
      routes.dart

Держите виджеты маленькими и составными. Когда виджет имеет ясные входы и выходы, вы можете менять верстку без правки логики состояния, и менять состояние без переписывания UI. Предпочитайте виджеты, которые принимают простые значения и callbacks, а не тянут глобальное состояние.

Цикл, который остаётся ревью‑дружественным:

• Напишите 3–6 строк UI‑спека для среза (что появляется, что делает тап, как выглядит loading/error).
• Генерируйте или правьте только минимально нужные файлы (обычно один экран и один‑два виджета).
• Запустите экран, затем один проход по чистке (именование, отступы, удаление неиспользуемых пропсов).
• Сделайте коммит с сообщением, соответствующим срезу.

Установите жёсткое правило: каждое изменение должно быть легко откатимо или изолируемо. Избегайте «drive‑by» рефакторов во время итерации экрана. Если замечаете посторонние проблемы — запишите их и исправьте в отдельном коммите.

Если инструмент поддерживает snapshotы и откат, используйте каждый срез как точку снимка. Некоторые платформы включают snapshot/rollback, что безопаснее при смелых экспериментах с UI.

Ещё одна привычка, которая смягчает ранние итерации: предпочитайте добавлять новые виджеты, а не править общие. Общие компоненты — именно место, где маленькие изменения превращаются в большие диффы.

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

Быстрая работа с UI безопасна, когда вы отделяете размышление от набора кода. Начните с чёткого плана дерева виджетов перед генерацией кода.

1. Попросите только outline дерева виджетов. Хотите имена виджетов, иерархию и что каждая часть отображает. Никакого кода. Здесь вы находите пропущенные состояния, пустые экраны и странные решения по верстке, пока всё ещё дешево менять.

2. Попросите разбиение компонентов с их ответственностями. Держите каждый виджет сфокусированным: один рендерит заголовок, другой — список, третий — пустое/ошибочное состояние. Если что‑то потребует состояния позже, отметьте это сейчас, но не реализуйте.

3. Сгенерируйте scaffold экрана и stateless виджеты. Начните с одного файла экрана с плейсхолдерами и понятными TODO. Держите входы явными (параметры конструктора), чтобы позже подставлять реальное состояние без переписывания дерева.

4. Сделайте отдельный проход для стилизации и деталей верстки: отступы, типографика, тема, адаптивность. Трактуйте стили как отдельный дифф, чтобы ревью было проще.

Рабочий паттерн промпта

Ставьте ограничения в начале, чтобы ассистент не выдумал несоответствующий UI:

• Целевые устройства (только телефон, планшет тоже, ориентация)
• Ограничения дизайна (Material 3, существующие цвета темы, правила отступов)
• Ожидания навигации (поведение кнопки назад, deep links, если есть)
• Критерии приёмки (что должно быть видно и на что нажимать)
• Границы существующего кода (какие файлы/виджеты должны остаться, соглашения по именованию)

Конкретный пример: история — «Как пользователь, я могу просматривать сохранённые товары и удалять один.» Попросите дерево виджетов с app bar, списком строк и пустым состоянием. Затем запросите разбиение: SavedItemsScreen, SavedItemTile, EmptySavedItems. Только после этого генерируйте scaffold со stateless виджетами и фейковыми данными, а стили добавляйте отдельно (divider, padding, явная кнопка удаления).

Добавляем состояние, не раздувая UI‑код

Итерация UI рушится, когда каждый виджет начинает принимать решения. Держите дерево «глупым»: оно должно читать состояние и рендерить, а не содержать бизнес‑правила.

Начните с именования состояний словами. Большинству фич нужно больше, чем просто «loading» и «done»:

• Loading (первичная загрузка или обновление)
• Empty (нет данных)
• Error (ошибка запроса, отказ в доступе)
• Success (данные готовы)
• Partial input (форма начата, но не валидна)

Затем перечислите события, которые могут менять состояние: тапы, отправка формы, pull‑to‑refresh, назад, retry, «пользователь изменил поле». Проработка этого заранее предотвращает догадки позже.

Держите состояние отдельно от виджетов

Выберите один подход к состоянию для фичи и придерживайтесь его. Цель не «лучший паттерн», а согласованные диффы.

Для небольшого экрана простого контроллера (ChangeNotifier или ValueNotifier) часто достаточно. Поместите логику в одно место:

• Входы: события из UI (submit, refresh, edit)
• Выход: единый объект состояния, который UI рендерит
• Побочные эффекты: вызовы API и навигационные запросы

Прежде чем писать код, опишите переходы состояний простыми предложениями. Пример для экрана логина:

"Когда пользователь нажимает Sign in: поставить Loading. Если email невалиден: остаться в Partial input и показать строчное сообщение. Если пароль неверен: установить Error с сообщением и включить Retry. При успехе: установить Success и навигировать на Home."

Дальше сгенерируйте минимальный Dart‑код, соответствующий этим правилам. Ревью остаётся простым, потому что дифф можно сравнить с набором правил.

Добавляйте тестируемые правила валидации

Сделайте валидацию явной. Решите, что делать при неверных вводах:

• Блокируете ли submit или допускаете отправку и показываете ошибки?
• Какие поля показывают ошибки и когда?
• Сбрасывает ли навигация назад частичный ввод или сохраняет?

Когда эти ответы задокументированы, UI остаётся чистым, а код состояния — компактным.

Проектируйте навигационные потоки, соответствующие реальному поведению пользователей

Хорошая навигация начинается с маленькой карты, а не из кучи роутов. Для каждой пользовательской истории опишите четыре момента: где пользователь входит, какой следующий наиболее вероятный шаг, как отменить, и что означает «назад» (вернуться к предыдущему экрану или к безопасному домашнему состоянию).

Сначала карта маршрутов, затем фиксируйте, что передаётся между экранами

Простая карта маршрутов должна отвечать на вопросы, которые обычно вызывают переделки:

• Entry: какой экран открывается первым и откуда (вкладка, нотификация, deep link)
• Next: основной дальнейший путь после главного действия
• Cancel: куда попадает пользователь при отказе от потока
• Back: разрешён ли возврат и что он сохраняет
• Fallback: куда идти, если недостаёт данных

Затем опишите параметры, передаваемые между экранами: идентификаторы (productId, orderId), фильтры (диапазон дат, статус) и черновые данные (частично заполненная форма). Если этого не зафиксировать, в итоге вы спрячете состояние в глобальные синглтоны или будете перестраивать экраны, чтобы «найти» контекст.

Планируйте deep links и паттерны «вернуть результат»

Deep links важны даже если вы не выпускаете их в день 1. Решите, что происходит, когда пользователь попадает в середину потока: можно ли подгрузить недостающие данные или нужно перенаправить на безопасный входной экран?

Также определите, какие экраны возвращают результат. Пример: экран «Выбрать адрес» возвращает addressId, и экран оформления заказа обновляется без полного рефреша. Держите форму возвращаемых данных маленькой и типизированной, чтобы изменения было легко ревьюить.

Перед кодом обозначьте пограничные случаи: несохранённые изменения (показать подтверждение), требующая авторизация (приостановить и возобновить после логина), удалённые данные (показать ошибку и понятный выход).

Делайте UI‑изменения рецензируемыми и модульными

Когда вы итеративно правите быстро, реальный риск — не «неправильный UI», а неревьюируемый UI. Если коллеге непонятно, что изменилось, почему и что осталось стабильным, каждая следующая итерация замедляется.

Правило, которое помогает: сначала зафиксируйте интерфейсы, затем позволяйте двигать внутренности. Стабилизируйте публичные пропсы виджетов (входы), маленькие UI‑модели и аргументы маршрутов. Как только они именованы и типизированы, вы можете перестраивать внутреннее дерево без ломки остальной части приложения.

Предпочитайте маленькие стабильные швы

Попросите план, удобный для диффа, перед генерацией кода. Вы хотите план, который указывает, какие файлы изменятся, а какие должны остаться нетронутыми. Это фокусирует ревью и предотвращает случайные рефакторы, меняющие поведение.

Паттерны, которые держат диффы маленькими:

• Делайте публичные виджеты тонкими: принимайте только нужные данные и callbacks, не лезьте в синглтоны.
• Рано выносите бизнес‑правила из виджетов: поместите решения в контроллер/вьюмодель, UI просто рендерит состояние.
• Когда часть UI перестаёт часто меняться — извлеките её в переиспользуемый виджет с явным API.
• Делайте аргументы маршрутов явными (один объект аргументов часто чище, чем много опциональных полей).
• Добавляйте короткий changelog в описание PR: что поменялось, зачем и что тестировать.

Конкретный пример, который любят ревьюеры

Пусть история: «Как покупатель, я могу изменить адрес доставки из checkout.» Сначала зафиксируйте аргументы маршрута: CheckoutArgs(cartId, shippingAddressId) должен оставаться стабильным. Затем итеративно правьте внутри экрана. Когда верстка устаканится, разбейте её на AddressForm, AddressSummary и SaveBar.

Если обработка состояния меняется (например, валидация уходит из виджета в CheckoutController), ревью остаётся читабельным: UI‑файлы в основном меняют рендеринг, а контроллер показывает логику в одном месте.

Распространённые ошибки и ловушки при итерации с AI‑ассистентом

Самый быстрый путь замедлиться — просить ассистента изменить всё сразу. Если один коммит трогает верстку, состояние и навигацию, ревьюеры не поймут, что сломалось, и откат станет сложным.

Более безопасная привычка — одно намерение за итерацию: сначала дерево, затем состояние, затем навигация.

Ошибки, создающие грязный код

Одна распространённая проблема — позволять генерируемому коду придумывать новый паттерн для каждой страницы. Если одна страница использует Provider, вторая — setState, а третья вводит кастомный контроллер, проект быстро становится непоследовательным. Выберите небольшой набор паттернов и поддерживайте их.

Ещё одна ошибка — запуск асинхронной работы прямо в build(). В демо это может выглядеть ок, но это вызывает повторные вызовы при ререндере, мерцание и трудноуловимые баги. Перенесите вызов в initState(), view‑model или контроллер и храните build() для рендера.

Именование — тихая ловушка. Код, который компилируется, но выглядит как Widget1, data2 или temp, делает будущие рефакторы болезненными. Понятные имена помогают ассистенту генерировать лучшее последующее изменение, потому что намерение ясно.

Ограждения, предотвращающие худшие исходы:

• Меняйте только одно из: верстка, состояние или навигация за итерацию
• Переиспользуйте один и тот же паттерн состояния в рамках фичи
• Никаких сетевых или БД вызовов в build()
• Переименуйте плейсхолдеры перед добавлением функциональности
• Предпочитайте извлекать виджеты, а не добавлять уровни вложенности

Ловушка вложенности

Классический фикс визуальной проблемы — добавить ещё Container, Padding, Align и SizedBox, пока всё не выровняется. Через несколько проходов дерево становится нечитаемым.

Если кнопка не выровнена, сначала попробуйте убрать обёртки, использовать один родительский layout‑виджет или извлечь небольшой виджет со своими ограничениями.

Пример: на странице оформления заказа итоговая сумма прыгает при загрузке. Ассистент мог бы обернуть строку цены дополнительными виджетами, чтобы «стабилизировать» её. Более чистый фикс — зарезервировать пространство простым плейсхолдером загрузки, сохранив структуру строки.

Быстрая чек‑лист‑проверка перед коммитом следующей UI‑итерации

Перед коммитом сделайте двухминутный проход, который проверит ценность для пользователя и убережёт от сюрпризов. Цель не совершенство, а убедиться, что итерация легко ревьюится, тестируется и откатывается.

Готовность к коммиту — чек‑лист

Прочитайте историю и сверяйте эти пункты с запущенным приложением (или хотя бы с простым widget‑тестом):

• Дерево виджетов соответствует истории: ключевые элементы из acceptance criteria видимы. Текст, кнопки и пустые места выглядят осмысленно.
• Все состояния достижимы: loading, error и empty не просто намечены — вы можете их вызвать (пусть и через debug‑флаг) и они выглядят приемлемо.
• Навигация и поведение кнопки назад логичны: назад возвращает ожидаемый экран, диалоги закрываются корректно, deep links (если есть) попадают в разумное место.
• Диффы маленькие и локализованы: изменения ограничены небольшим набором файлов с ясной ответственностью. Никаких drive‑by рефакторов.
• Откат чист: если вы откатите этот коммит, другие экраны всё ещё собираются и запускаются. Уберите временные флаги или плейсхолдеры, которые могут поломать позже.

Быстрая проверка в реальности: если вы добавили новый экран Order details, вы должны суметь (1) открыть его из списка, (2) увидеть спиннер загрузки, (3) симулировать ошибку, (4) увидеть пустой заказ, и (5) нажать назад и вернуться в список без странных скачков.

Если ваш процесс поддерживает snapshot/rollback, делайте снимок перед большими изменениями верстки — это поможет итеративно двигаться быстрее, не рискуя веткой main.

Реалистичный пример: из истории в экраны за три итерации

История: «Как покупатель, я могу просматривать товары, открывать страницу детали, сохранять товар в избранное и потом просматривать избранное.» Цель — перейти от текста к экранам в трёх маленьких, ревью‑дружественных шагах.

Итерация 1: сосредоточьтесь на экране списка. Создайте дерево виджетов, достаточно полное для рендера, но не привязанное к реальным данным: Scaffold с AppBar, ListView с плейсхолдерными рядами и явные UI для loading и empty. Держите состояние простым: loading (показывать CircularProgressIndicator), empty (сообщение и кнопка Try again), ready (показывать список).

Итерация 2: добавьте экран деталей и навигацию. Явно: onTap пушит маршрут и передаёт небольшой объект параметров (например: id товара, title). Начните details как read‑only с заголовком, плейсхолдером описания и кнопкой Favorite. Цель — соответствовать истории: list -> details -> back, без лишних потоков.

Итерация 3: введите состояние избранного и UI‑фидбек. Добавьте единую точку правды для избранного (пусть пока в памяти) и подключите её к обоим экранам. Тап по Favorite сразу обновляет иконку и показывает короткий SnackBar. Затем добавьте экран Favorites, который читает то же состояние и обрабатывает пустое состояние.

Типичный ревью‑дружественный дифф выглядит так:

• browse_list_screen.dart: дерево виджетов + loading/empty/ready UI
• item_details_screen.dart: разметка и приём navigation params
• favorites_store.dart: минимальный хранилище состояния и методы обновления
• app_routes.dart: маршруты и типизированные хелперы навигации
• favorites_screen.dart: читает состояние и показывает empty/list UI

Если какой‑то файл стал «местом, где происходит всё», вынесите части до продолжения. Маленькие файлы с понятными именами ускоряют следующую итерацию и делают её безопасной.

Следующие шаги: сделайте цикл повторяемым для всех фич

Если рабочий процесс действует только когда вы «в зоне», он развалится, как только вы переключитесь на другую задачу или кто‑то ещё тронет фичу. Сделайте цикл привычкой: опишите его и поставьте ограждения по размерам изменений.

Сделайте переиспользуемый шаблон промпта

Одна командная форма начала итерации даёт одинаковые входы и похожий вывод. Держите шаблон коротким, но специфичным:

• Пользовательская история + acceptance criteria (что значит «готово»)
• UI‑ограничения (дизайн‑система, отступы, компоненты, которые нужно переиспользовать)
• Правила состояния (где живёт состояние, что локальное, а что общее)
• Правила навигации (маршруты, deep links, поведение назад)
• Правила вывода (какие файлы трогать, какие тесты обновить, что объяснить в диффе)

Это уменьшает шанс, что ассистент придумает новый паттерн посреди фичи.

Определите «маленький», чтобы диффы были предсказуемыми

Выберите определение «маленького», которое легко применять в код‑ревью. Например, ограничьте итерацию количеством файлов и разделите рефакторы UI и поведенческие изменения.

Простые правила:

• Не более 3–5 файлов в одной итерации
• Одна новая компонента или один шаг навигации за итерацию
• Не вводите новый подход к управлению состоянием в середине цикла
• Каждое изменение должно компилироваться и запускаться перед следующей итерацией

Добавьте чекпоинты, чтобы можно было быстро откатить плохой шаг. Минимально — тэги коммитов или локальные контрольные точки перед крупными рефакторами. Если процесс поддерживает snapshot/rollback, используйте их активно.

Если хотите чат‑ориентированный процесс, который генерирует и уточняет Flutter‑приложения end‑to‑end, некоторые платформы предлагают режим планирования, где вы сначала ревьюите план и ожидаемые файлы до применения изменений.