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 из сырого текста

Команда:

/Ecommerce Prepare Brief

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

Нужно подготовить .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. При необходимости определить визуальное направление и ассеты

Команда:

/Ecommerce Visual Pack

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

Когда запускать:

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

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

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

Что должно появиться после шага:

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

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

Команда:

/Ecommerce Build From Brief

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

Используй .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. Доработать или переделать существующий проект

Команда:

/Ecommerce Extend Existing

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

Когда запускать:

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

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

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

Что делает этот шаг:

• анализирует текущий код
• не ломает архитектуру без причины
• вносит точечные или структурные изменения

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

Команда:

/Ecommerce Test Implementation

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

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

Что делает этот шаг:

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

Что должно появиться после шага:

• тестовый код
• .ai/TEST-REPORT.md

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

Команда:

/Ecommerce Test Repair

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

Когда запускать:

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

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

Разбери текущие падения тестов, прочитай .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 проекта

Команда:

/Ecommerce Code Review

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

Сделай жесткий 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-стратегию

Команда:

/Ecommerce SEO Strategy

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

Построй 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 в код

Команда:

/Ecommerce SEO Implementation

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

Внедри .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 после внедрения

Команда:

/Ecommerce SEO Review

Какой агент лучше всего подходит:

• shop-fullstack-fastapi-react

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

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

Что делает этот шаг:

• проверяет, что SEO действительно внедрено корректно
• пишет список рисков, пробелов и улучшений

Что должно появиться после шага:

• .ai/SEO-REVIEW.md

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

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

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-внедрения, если было много изменений в коде

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

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