github-copilot/site-fullstack/WORKFLOW-GUIDE.md

# Пошаговый Workflow

Этот файл нужен как практическая инструкция: что запускать по порядку, какой prompt использовать, какой агент подходит лучше всего и какой результат должен появиться после каждого шага.

## Какого агента использовать

Лучший основной агент для всей цепочки в этом проекте: `shop-fullstack-fastapi-react`.

Почему именно он:
- он уже заточен под ecommerce
- он знает workflow через `.ai/STORE-BRIEF.md` и `AGENTS.md`
- перед серьезными backend/frontend изменениями он сначала делает append-only snapshot в `.backup/`
- он учитывает storefront, admin panel, backend, SEO, code review и quality rules
- он умеет работать с FastAPI, React, Next.js, PostgreSQL, monorepo и split repo
- он должен держать backend и frontend в нормальной крупнопроектной архитектуре с разнесением по слоям и папкам

Практически это означает следующее:
- если ты запускаешь slash-команды из этого репозитория, нужный агент уже привязан в prompt-файлах
- если запускаешь задачу вручную через обычный чат, лучше явно выбрать агент `shop-fullstack-fastapi-react`

## Если команда запущена почти без подробностей

Если пользователь запускает команду почти без контекста, правильное поведение теперь такое:
- агент не додумывает молча все важные требования
- агент задает короткий и конкретный набор вопросов
- вопросы зависят от текущего шага

Обычно это выглядит так:
- для brief: что за магазин, какой формат репозитория, какие страницы, нужна ли авторизация, корзина, админка, интеграции, стиль
- для build: есть ли готовый `.ai/STORE-BRIEF.md`, что собирать в первую очередь, есть ли ограничения
- для extend: что менять, что не ломать, какие текущие части критичны
- для SEO: стратегия нужна, внедрение или review
- для code review: проверять весь проект или только backend, frontend, SEO, performance, архитектуру

Если деталей почти нет совсем, агент должен сначала задать 3-7 самых важных вопросов и только потом продолжать работу.

## Главный порядок команд

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

1. `/Ecommerce Prepare Brief`
2. `/Ecommerce Visual Pack` при необходимости
3. `/Ecommerce Build From Brief`
4. `/Ecommerce Test Implementation`
5. `/Ecommerce Test Repair` если тесты упали
6. `/Ecommerce Extend Existing` для следующих итераций и изменений
7. `/Ecommerce Code Review`
8. `/Ecommerce SEO Strategy`
9. `/Ecommerce SEO Implementation`
10. `/Ecommerce SEO Review`
11. `/Ecommerce Code Review` повторно перед релизом при крупных изменениях

Если проект уже существует, цепочка обычно такая:

1. `/Ecommerce Extend Existing`
2. `/Ecommerce Test Implementation`
3. `/Ecommerce Test Repair` если тесты упали
4. `/Ecommerce Code Review`
5. `/Ecommerce SEO Strategy`
6. `/Ecommerce SEO Implementation`
7. `/Ecommerce SEO Review`
8. `/Ecommerce Code Review` повторно, если после SEO было много изменений в коде

## Подробно по шагам

### Шаг 1. Подготовить нормальный brief из сырого текста

Команда:

```text
/Ecommerce Prepare Brief
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Нужно подготовить .ai/STORE-BRIEF.md для ecommerce-проекта.
Формат: monorepo.
Ниша: магазин косметики.
Аудитория: женщины 24-45.
Дизайн: современный premium, mobile-first.
Нужны страницы: главная, каталог, категории, карточка товара, корзина, checkout, auth, account, admin panel.
Интеграции: платежи, email, analytics.
Сначала задай только важные вопросы и создай .ai/STORE-BRIEF.md.
```

Что делает этот шаг:
- берет твой сырой текст
- задает только важные вопросы
- нормализует требования
- создает `.ai/STORE-BRIEF.md`

Что должно появиться после шага:
- `.ai/STORE-BRIEF.md`

Когда переходить дальше:
- когда `.ai/STORE-BRIEF.md` уже заполнен и тебя устраивает

### Шаг 2. При необходимости определить визуальное направление и ассеты

Команда:

```text
/Ecommerce Visual Pack
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

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

Что писать в запросе после запуска:

```text
Подготовь визуальное направление для магазина по .ai/STORE-BRIEF.md. Нужны 2-3 сильных варианта стилистики, рекомендации по типографике, цветам, motion и prompts для генерации hero и category images.
```

Что должно появиться после шага:
- визуальное направление в ответе
- при необходимости prompts для генерации изображений

### Шаг 3. Собрать проект по brief

Команда:

```text
/Ecommerce Build From Brief
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Используй .ai/STORE-BRIEF.md как источник правды.
Сначала создай или обнови AGENTS.md.
После этого полностью собери проект: backend, storefront, admin panel, UX-состояния, анимации и недостающие asset prompts.
```

Что делает этот шаг:
- читает `.ai/STORE-BRIEF.md`
- создает `AGENTS.md`
- строит backend, storefront и admin panel
- учитывает quality rules проекта

Что должно появиться после шага:
- `AGENTS.md`
- код проекта

### Шаг 4. Доработать или переделать существующий проект

Команда:

```text
/Ecommerce Extend Existing
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Когда запускать:
- когда проект уже собран и нужно что-то изменить
- когда нужно добавить модули, переделать UX, расширить backend, доработать admin panel

Что писать в запросе после запуска:

```text
Доработай существующий проект: добавь wishlist, расширь фильтры каталога, улучши личный кабинет и добавь управление промокодами в admin panel. Сохрани текущую архитектуру, если она адекватна.
```

Что делает этот шаг:
- анализирует текущий код
- не ломает архитектуру без причины
- вносит точечные или структурные изменения

### Шаг 5. Написать и прогнать автотесты

Команда:

```text
/Ecommerce Test Implementation
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Добавь и обнови автотесты для backend и frontend. Сначала определи текущий test stack проекта. Покрой самые рискованные ecommerce-флоу, затем запусти relevant suites и создай .ai/TEST-REPORT.md.
```

Что делает этот шаг:
- определяет backend и frontend test stack
- пишет или расширяет автотесты
- гоняет тесты
- фиксирует результат в `.ai/TEST-REPORT.md`

Что должно появиться после шага:
- тестовый код
- `.ai/TEST-REPORT.md`

### Шаг 6. Починить падения тестов и прогнать их заново

Команда:

```text
/Ecommerce Test Repair
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Когда запускать:
- если после предыдущего шага есть падающие тесты
- если после изменений в проекте test suite стал красным

Что писать в запросе после запуска:

```text
Разбери текущие падения тестов, прочитай .ai/TEST-REPORT.md и фактический output test runner. Почини корневую причину, затем снова прогони relevant suites и создай .ai/TEST-REPAIR.md.
```

Что делает этот шаг:
- читает реальные падения
- определяет, проблема в коде или в тестах
- чинит root cause
- гоняет тесты повторно
- пишет `.ai/TEST-REPAIR.md`

Что должно появиться после шага:
- исправления в коде или тестах
- `.ai/TEST-REPAIR.md`

### Шаг 7. Провести жесткий code review проекта

Команда:

```text
/Ecommerce Code Review
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Сделай жесткий review всего проекта. Сначала прочитай pyproject.toml, package.json, tsconfig и другие конфиги. Проверь Python по mypy или ty, ruff и deptry, если они настроены. React проверь на читаемость, поддержку, производительность и уместность современных возможностей версии. Создай .ai/CODE-REVIEW.md.
```

Что делает этот шаг:
- читает конфиги проекта
- проверяет Python по реальным quality gates проекта
- проверяет React на читаемость и поддержку
- пишет жесткий отчет

Что должно появиться после шага:
- `.ai/CODE-REVIEW.md`

Когда запускать:
- после крупных этапов разработки
- перед релизом
- после большой переработки архитектуры

### Шаг 8. Построить SEO-стратегию

Команда:

```text
/Ecommerce SEO Strategy
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Построй SEO-стратегию для проекта на основе .ai/STORE-BRIEF.md. Нужны technical SEO, keyword intent mapping, структура страниц, metadata, schema markup, internal linking и measurement. Создай .ai/SEO-PLAN.md.
```

Что делает этот шаг:
- создает SEO-план
- определяет архитектуру SEO
- формирует приоритеты по органическому росту

Что должно появиться после шага:
- `.ai/SEO-PLAN.md`

### Шаг 9. Внедрить SEO в код

Команда:

```text
/Ecommerce SEO Implementation
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Внедри .ai/SEO-PLAN.md в код проекта. Примени metadata, canonicals, schema markup, sitemap, robots, internal linking, template-level SEO и indexation rules.
```

Что делает этот шаг:
- превращает SEO-план в реальные изменения в коде
- внедряет schema, metadata, canonical rules, sitemap и SEO-логику шаблонов

### Шаг 10. Проверить SEO после внедрения

Команда:

```text
/Ecommerce SEO Review
```

Какой агент лучше всего подходит:
- `shop-fullstack-fastapi-react`

Что писать в запросе после запуска:

```text
Проведи повторный SEO-аудит проекта после внедрения. Прочитай .ai/SEO-PLAN.md и проверь фактическую реализацию в коде. Создай .ai/SEO-REVIEW.md с приоритетами и remediation plan.
```

Что делает этот шаг:
- проверяет, что SEO действительно внедрено корректно
- пишет список рисков, пробелов и улучшений

Что должно появиться после шага:
- `.ai/SEO-REVIEW.md`

## Самая правильная цепочка для нового проекта

Если нужна короткая версия без лишних развилок, запускай так:

```text
1. /Ecommerce Prepare Brief
2. /Ecommerce Visual Pack
3. /Ecommerce Build From Brief
4. /Ecommerce Test Implementation
5. /Ecommerce Test Repair
6. /Ecommerce Code Review
7. /Ecommerce SEO Strategy
8. /Ecommerce SEO Implementation
9. /Ecommerce SEO Review
10. /Ecommerce Code Review
```

Пояснение:
- test implementation и test repair должны пройти до жесткого review
- первый review проверяет качество архитектуры и кода после сборки
- SEO-шаги идут после того, как структура страниц уже существует
- финальный review полезен после SEO-внедрения, если было много изменений в коде

## Самая правильная цепочка для уже существующего проекта

```text
1. /Ecommerce Extend Existing
2. /Ecommerce Test Implementation
3. /Ecommerce Test Repair
4. /Ecommerce Code Review
5. /Ecommerce SEO Strategy
6. /Ecommerce SEO Implementation
7. /Ecommerce SEO Review
8. /Ecommerce Code Review
```

## Когда можно использовать ручной запуск без prompt-файлов

Если не хочешь использовать slash-команды, можно просто выбрать агент `shop-fullstack-fastapi-react` вручную и писать задачу текстом.

Но правильнее использовать именно prompt-файлы, потому что:
- в них уже зашит правильный агент
- в них уже зашиты ожидания по шагу
- снижается шанс запустить не тот workflow

## Что должно лежать в корне проекта по ходу работы

В идеале после прохождения всей цепочки у тебя появятся такие файлы:
- `.ai/STORE-BRIEF.md`
- `AGENTS.md`
- `.ai/TEST-REPORT.md`
- `.ai/TEST-REPAIR.md`
- `.ai/SEO-PLAN.md`
- `.ai/SEO-REVIEW.md`
- `.ai/CODE-REVIEW.md`

Не все из них появляются сразу:
- `.ai/STORE-BRIEF.md` появляется после подготовки brief
- `AGENTS.md` появляется перед сборкой
- `.ai/TEST-REPORT.md` появляется после шага с написанием и прогоном тестов
- `.ai/TEST-REPAIR.md` появляется после шага исправления падений
- `.ai/SEO-PLAN.md` появляется на этапе SEO strategy
- `.ai/SEO-REVIEW.md` появляется после SEO review
- `.ai/CODE-REVIEW.md` появляется после code review

## Короткая памятка

- Хочешь превратить сырую идею в нормальное ТЗ: `/Ecommerce Prepare Brief`
- Хочешь собрать проект по brief: `/Ecommerce Build From Brief`
- Хочешь доработать существующий проект: `/Ecommerce Extend Existing`
- Хочешь жесткий review: `/Ecommerce Code Review`
- Хочешь написать и прогнать автотесты: `/Ecommerce Test Implementation`
- Хочешь починить падения тестов и снова прогнать suite: `/Ecommerce Test Repair`
- Хочешь SEO-план: `/Ecommerce SEO Strategy`
- Хочешь внедрить SEO в код: `/Ecommerce SEO Implementation`
- Хочешь проверить SEO после внедрения: `/Ecommerce SEO Review`
- Хочешь сначала определить визуал и prompts для изображений: `/Ecommerce Visual Pack`