# shop-fullstack Набор кастомизаций для GitHub Copilot в VS Code под ecommerce-проекты: FastAPI backend, React или Next.js frontend, storefront, admin panel, back office, PostgreSQL, mobile-first UX и двухшаговая подготовка через .ai/STORE-BRIEF.md перед генерацией кода. ## Что создано В текущем репозитории: - Агент: .github/agents/shop-fullstack-fastapi-react.agent.md - Инструкции: .github/instructions/ - Промпты: .github/prompts/ - Skills: .github/skills/ecommerce-store-foundation, .github/skills/ecommerce-store-evolution, .github/skills/ecommerce-brief-preparation, .github/skills/ecommerce-build-from-brief, .github/skills/ecommerce-seo-strategy, .github/skills/ecommerce-seo-implementation, .github/skills/ecommerce-seo-review, .github/skills/ecommerce-code-review, .github/skills/ecommerce-test-implementation и .github/skills/ecommerce-test-repair ## Что умеет агент - Создавать ecommerce-сайт с нуля. - Дорабатывать существующий storefront, backend и admin panel. - Работать в monorepo и split repo режиме. - По умолчанию использовать FastAPI, PostgreSQL, React и Next.js. - Сначала собирать нормализованный brief в .ai/STORE-BRIEF.md. - После brief создавать или обновлять AGENTS.md. - Для Python ориентироваться на конфигурацию pyproject и quality-toolchain проекта: mypy или ty, ruff, deptry. - Для React держать код читаемым, предсказуемым и удобным для ручной доработки. - Писать и прогонять автотесты для backend и frontend, а при падениях запускать отдельный fix-loop до зеленого статуса или явных blockers. - Учитывать mobile-first адаптацию, анимации, категории, фильтры, сортировку, корзину, авторизацию, личный кабинет и back office. - Подготавливать prompts для генерации изображений, если готовых ассетов нет. ## Рекомендуемый workflow Основной сценарий теперь такой: 1. Сначала запустить подготовку brief. 2. Агент задает только важные вопросы. 3. Агент создает файл .ai/STORE-BRIEF.md. 4. После согласования brief запускается сборка сайта по .ai/STORE-BRIEF.md. 5. Перед кодом агент создает AGENTS.md, затем реализует backend, storefront и admin panel. ## Как использовать агента ### Вариант 1. Через выбор агента 1. Открой чат Copilot в VS Code. 2. Выбери агент shop-fullstack-fastapi-react. 3. Передай задачу в свободной форме и попроси сначала подготовить .ai/STORE-BRIEF.md. Пример: ```text Подготовь .ai/STORE-BRIEF.md для интернет-магазина косметики в monorepo. Backend на FastAPI и PostgreSQL, frontend на Next.js. Нужны storefront, admin panel, личный кабинет, фильтры, сортировка, корзина, анимации и адаптация под мобильные устройства. После brief я отдельно запущу сборку. ``` ### Вариант 2. Через prompt-файлы Доступны готовые сценарии: - /Ecommerce Prepare Brief - /Ecommerce Build From Brief - /Ecommerce SEO Strategy - /Ecommerce SEO Implementation - /Ecommerce SEO Review - /Ecommerce Code Review - /Ecommerce Test Implementation - /Ecommerce Test Repair - /Ecommerce From Zero - /Ecommerce Extend Existing - /Ecommerce Visual Pack Когда использовать основные новые сценарии: - Ecommerce Prepare Brief: задает важные вопросы и создает .ai/STORE-BRIEF.md. - Ecommerce Build From Brief: читает .ai/STORE-BRIEF.md, создает AGENTS.md и строит проект. - Ecommerce SEO Strategy: создает .ai/SEO-PLAN.md или проводит SEO-аудит и формирует реализационный план. - Ecommerce SEO Implementation: внедряет .ai/SEO-PLAN.md прямо в код проекта. - Ecommerce SEO Review: проводит повторный SEO-аудит проекта и пишет .ai/SEO-REVIEW.md с приоритетами и планом исправлений. - Ecommerce Code Review: делает жесткий code review всего проекта с учетом pyproject, package.json, версий языка и доступных современных возможностей. - Ecommerce Test Implementation: пишет автотесты для backend и frontend, затем запускает их и пишет .ai/TEST-REPORT.md. - Ecommerce Test Repair: разбирает падения тестов, чинит код или тесты, гоняет suite повторно и пишет .ai/TEST-REPAIR.md. Когда использовать: - Ecommerce From Zero: запуск нового магазина с нуля. - Ecommerce Extend Existing: развитие уже существующего проекта. - Ecommerce Visual Pack: подготовка визуального направления и prompts для генерации изображений. ### Вариант 3. Через skills Skills подключаются автоматически по описанию задачи или через slash-команду, если VS Code их показывает. - ecommerce-brief-preparation: превращает сырую идею в .ai/STORE-BRIEF.md. - ecommerce-build-from-brief: строит проект по .ai/STORE-BRIEF.md. - ecommerce-seo-strategy: готовит сильную SEO-стратегию, технический SEO-план, схему страниц, schema markup и измерение результата. - ecommerce-seo-implementation: вносит SEO-изменения прямо в кодовую базу по .ai/SEO-PLAN.md. - ecommerce-seo-review: проверяет фактическую SEO-реализацию и пишет .ai/SEO-REVIEW.md с findings и remediation plan. - ecommerce-code-review: делает жесткий обзор качества Python, React, архитектуры, производительности и dependency hygiene с отчетом в .ai/CODE-REVIEW.md. - ecommerce-test-implementation: добавляет backend и frontend автотесты, запускает их и фиксирует результат в .ai/TEST-REPORT.md. - ecommerce-test-repair: чинит падения тестов и повторно прогоняет suite с отчетом в .ai/TEST-REPAIR.md. - ecommerce-store-foundation: старт нового магазина. - ecommerce-store-evolution: развитие существующего магазина. ## Как агент принимает решения Если вводных не хватает, агент должен уточнить: - monorepo или split repos - нужен ли личный кабинет - нужна ли гостевая корзина - где хранить корзину: localStorage, cookie, серверное состояние - нужен ли checkout или достаточно заявки - какие модули обязательны в admin panel - какой визуальный стиль нужен Если стиль не задан, агент сначала предлагает несколько направлений. Если нет готовых изображений, агент готовит промпты для внешней генерации. ## Логика .ai/STORE-BRIEF.md и AGENTS.md - .ai/STORE-BRIEF.md создается раньше кода и раньше AGENTS.md. - .ai/STORE-BRIEF.md фиксирует нормализованные требования, ответы на вопросы, допущения, scope storefront, scope admin panel, интеграции, визуал и этапы сборки. - На основе .ai/STORE-BRIEF.md агент создает AGENTS.md. - В monorepo агент должен создать один корневой AGENTS.md для frontend и backend. - В split repo агент должен создать отдельный AGENTS.md в frontend repo и backend repo. - В AGENTS.md агент фиксирует архитектуру, структуру репозитория, рабочие правила, контракты, роли, требования к storefront и admin panel, а также правила работы с ассетами. ## Бэкапы перед серьезными изменениями - Перед любым серьезным изменением backend или frontend агент должен создать snapshot в .backup/. - В имени snapshot должна быть дата со временем до секунд, например .backup/20260520-143708-storefront/. - Папка .backup считается append-only: внутри нее можно только создавать новые snapshot, изменять или удалять старые запрещено. - Если сохранять еще нечего, потому что backend или frontend пока не существуют, пустой backup создавать не нужно. ## Архитектура кода - Backend и frontend должны строиться как крупный проект, а не как плоский набор файлов. - На backend код должен быть разложен по своим зонам ответственности: api или routers, models, schemas, services, repositories, db, config или core, integrations, tests. - На frontend код должен быть разложен по своим зонам ответственности: app или routes, pages, features, entities, components, api или services, hooks, config, lib, styles, tests. - Бизнес-логика не должна оседать в route handlers, page-файлах или UI-компонентах, если ей место в service или domain-слое. Рекомендуемая структура FastAPI: ```text backend/ app/ api/ v1/ routes/ dependencies/ core/ db/ models/ schemas/ repositories/ services/ integrations/ utils/ main.py tests/ unit/ integration/ api/ ``` Рекомендуемая структура Next.js или React: ```text frontend/ src/ app/ pages/ widgets/ features/ entities/ shared/ ui/ api/ lib/ hooks/ config/ styles/ tests/ unit/ integration/ public/ ``` Рекомендуемая структура admin panel или back office: ```text frontend/ src/ app/ admin/ widgets/ dashboard/ data-table/ filters/ forms/ features/ catalog-management/ order-management/ customer-management/ role-management/ promotion-management/ content-management/ media-management/ settings-management/ entities/ shared/ ui/ api/ lib/ hooks/ config/ styles/ tests/ unit/ integration/ admin-e2e/ ``` Рекомендуемая структура monorepo: ```text project-root/ .ai/ .backup/ AGENTS.md backend/ frontend/ shared/ types/ contracts/ constants/ infra/ docker/ scripts/ ci/ ``` Рекомендуемая структура split repo: ```text frontend-repo/ .ai/ .backup/ AGENTS.md src/ public/ backend-repo/ .ai/ .backup/ AGENTS.md app/ tests/ alembic/ ``` Что хранить в слоях: - api или routes: HTTP endpoint-ы, wiring зависимостей, transport-level логика, маппинг ответа. - models: ORM-модели и persistence-структуры. - schemas: request/response контракты и DTO. - repositories: прямой доступ к данным, query-логика, чтение и запись. - services: бизнес-правила, orchestration, сценарии, транзакции. - db: session, engine, base metadata, migrations, подключение к базе. - core или config: settings, security, logging, bootstrap и глобальные конфиги. - integrations: платежки, CRM, ERP, email, storage, search и другие внешние системы. - app или pages: route entry points, layouts и page-level composition. - widgets: крупные UI-блоки, собранные из features и shared ui. - features: конкретные сценарии вроде auth, cart, checkout, filters, admin actions. - entities: доменные frontend-модули вроде product, category, cart, order, user. - shared ui: переиспользуемые UI-компоненты и design-system primitives. - shared api: typed clients, fetchers, query adapters, transport helpers. - hooks: переиспользуемое stateful-поведение на клиенте. - shared styles: tokens, themes, global styles, mixins, animation primitives. - tests: unit, integration, api и ui или e2e тесты по слоям. Правила импортов и границ слоев: - На backend импорты должны быть абсолютными от корня `app`, например `from app.utils.slug import build_slug`, а не `from ..utils import ...`. - На backend не нужно писать `__all__ = ...`; лучше использовать явные прямые импорты. - Направление зависимостей на backend должно быть односторонним: api или routes -> services -> repositories -> models или db. - models не должны импортировать api, routes или services. - repositories работают с данными и запросами, но не должны тянуть HTTP-логику или presentation concerns. - services содержат бизнес-логику и orchestration, а route handlers должны оставаться тонкими. - На frontend лучше использовать alias от корня `src`, например `@/shared/ui/button`, а не глубокие относительные цепочки вроде `../../../../shared/ui/button`. - Направление зависимостей на frontend должно быть таким: app или pages -> widgets -> features -> entities -> shared. - shared не должен зависеть от entities, features, widgets, pages или app. - Barrel exports лучше не использовать там, где они скрывают ownership, размазывают ответственность или создают циклические зависимости. - Тесты могут импортировать production-код, но production-код не должен импортировать тестовые модули. ## Рекомендуемый шаблон запроса для первого этапа ```text Нужно подготовить .ai/STORE-BRIEF.md для ecommerce-проекта. Формат: monorepo или split repo. Ниша: ... Аудитория: ... Дизайн: ... Нужны страницы: ... Нужен личный кабинет: да или нет. Нужна админка: да. Нужна гостевая корзина: да или нет. Интеграции: ... Особые требования: ... Сначала задай только важные вопросы и создай .ai/STORE-BRIEF.md. ``` ## Рекомендуемый шаблон запроса для второго этапа ```text Используй .ai/STORE-BRIEF.md как источник правды. Сначала создай или обнови AGENTS.md. После этого полностью собери проект: backend, storefront, admin panel, UX-состояния, анимации и недостающие asset prompts. ``` ## Что можно расширить дальше - Добавить отдельные prompts под monorepo и split repo. - Добавить skill под интеграции платежей, CRM и ERP. - Добавить шаблоны seed-данных, demo-каталога и дизайн-системы. ## Quality rules - Для Python агент сначала смотрит на `pyproject.toml` и только потом принимает решение по quality gates. - Если проект настроен на `mypy`, код должен соответствовать его конфигурации и по умолчанию тяготеть к strict discipline. - Если проект настроен на `ty`, агент должен ориентироваться на `ty`, а не механически советовать `mypy`. - Если настроены `ruff` и `deptry`, агент должен учитывать их как реальные ограничения проекта. - Для React и Next.js код должен оставаться читаемым и легко изменяемым программистом без лишней магии и чрезмерной абстракции. ## Code review workflow Если нужен жесткий review всего проекта: 1. Запусти /Ecommerce Code Review. 2. Агент сначала прочитает конфигурацию проекта: `pyproject.toml`, `package.json`, `tsconfig.json` и related configs. 3. Затем он проверит Python-часть по реальным правилам проекта, включая `mypy` или `ty`, а также `ruff` и `deptry` при наличии. 4. React-часть будет проверена на читаемость, поддержку, корректность паттернов и уместное использование современных возможностей версии. 5. В результате агент создаст .ai/CODE-REVIEW.md с жесткими findings, приоритетами и планом исправлений. ## Test workflow Если нужно покрыть проект автотестами и прогнать их: 1. Запусти /Ecommerce Test Implementation. 2. Агент сначала определит текущий backend и frontend test stack. 3. Затем он добавит или обновит автотесты для backend и frontend и прогонит relevant suites. 4. Результат он запишет в .ai/TEST-REPORT.md. 5. Если есть падения, запусти /Ecommerce Test Repair. 6. Этот шаг разберет реальные ошибки, починит код или тесты, снова прогонит тесты и создаст .ai/TEST-REPAIR.md. Правильный принцип: тесты не должны зеленеть за счет ослабления полезных проверок. ## SEO workflow Если нужно отдельно проработать органический рост: 1. Запусти /Ecommerce SEO Strategy. 2. Агент прочитает .ai/STORE-BRIEF.md, если он есть. 3. Для широкого SEO-задачи агент создаст .ai/SEO-PLAN.md. 4. В план войдут технический SEO, архитектура страниц, keyword-intent mapping, metadata, schema markup, internal linking, Core Web Vitals и measurement. 5. После этого запусти /Ecommerce SEO Implementation, чтобы агент внедрил .ai/SEO-PLAN.md в код проекта. 6. После внедрения запусти /Ecommerce SEO Review, чтобы агент создал .ai/SEO-REVIEW.md и зафиксировал найденные пробелы, риски и приоритет исправлений. Важно: skill оптимизирует сайт под максимально сильную органическую базу, но не обещает гарантированное первое место в поиске, так как это зависит не только от кода и структуры сайта. ## Пошаговая инструкция Пошаговый порядок команд и рекомендованный workflow описаны в [WORKFLOW-GUIDE.md](WORKFLOW-GUIDE.md).