Add test coverage checklist, report template, and stack matrix for ecommerce project
- Created a test coverage checklist to ensure comprehensive testing of backend and frontend components. - Added a test report template to standardize reporting on test execution results and gaps. - Introduced a test stack matrix to guide the selection of testing tools and frameworks for backend and frontend. - Established a skill for repairing failing tests, including a failure triage checklist and a test repair template. - Documented recommended MCP stack for ecommerce development with FastAPI and React/Next.js. - Developed a detailed README outlining the project structure, agent capabilities, and recommended workflows. - Compiled a comprehensive workflow guide detailing step-by-step commands for project setup, testing, and SEO implementation.
This commit is contained in:
ВяткинАртём
@@ -0,0 +1,419 @@
|
||||
# Пошаговый 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`
|
||||
Reference in New Issue
Block a user