github-copilot/site-fullstack

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.

Пример:

Подготовь .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:

backend/
	app/
		api/
			v1/
				routes/
				dependencies/
		core/
		db/
		models/
		schemas/
		repositories/
		services/
		integrations/
		utils/
		main.py
	tests/
		unit/
		integration/
		api/

Рекомендуемая структура Next.js или React:

frontend/
	src/
		app/
		pages/
		widgets/
		features/
		entities/
		shared/
			ui/
			api/
			lib/
			hooks/
			config/
			styles/
		tests/
			unit/
			integration/
	public/

Рекомендуемая структура admin panel или back office:

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:

project-root/
	.ai/
	.backup/
	AGENTS.md
	backend/
	frontend/
	shared/
		types/
		contracts/
		constants/
	infra/
		docker/
		scripts/
		ci/

Рекомендуемая структура split repo:

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-код не должен импортировать тестовые модули.

Рекомендуемый шаблон запроса для первого этапа

Нужно подготовить .ai/STORE-BRIEF.md для ecommerce-проекта.
Формат: monorepo или split repo.
Ниша: ...
Аудитория: ...
Дизайн: ...
Нужны страницы: ...
Нужен личный кабинет: да или нет.
Нужна админка: да.
Нужна гостевая корзина: да или нет.
Интеграции: ...
Особые требования: ...
Сначала задай только важные вопросы и создай .ai/STORE-BRIEF.md.

Рекомендуемый шаблон запроса для второго этапа

Используй .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.