Spec Workflow MCP

# Руководство по запросам Подробное руководство с примерами и лучшими практиками для взаимодействия с Spec Workflow MCP через AI-ассистентов. ## Краткий справочник ### Основные команды ``` "Создай спецификацию для [функции]" "Покажи все мои спецификации" "Покажи статус [spec-name]" "Реализуй задачу [номер] из [spec]" "Создай управляющие документы" ``` ## Создание спецификаций ### Базовое создание спецификации #### Простой запрос ``` "Создай спецификацию для аутентификации пользователей" ``` AI создаст: - Документ требований - Документ дизайна (после утверждения) - Разбиение задач (после утверждения дизайна) #### Детальный запрос ``` "Создай спецификацию payment-processing с: - Платежи кредитными картами через Stripe - Интеграция с PayPal - Обработка возвратов - Обработка webhook для событий платежей - Учет соответствия PCI" ``` #### Из существующей документации ``` "Создай спецификацию из PRD в @product-requirements.md" ``` ``` "Создай спецификацию на основе документа дизайна в @figma-export.md" ``` ### Продвинутое создание спецификации #### С техническими ограничениями ``` "Создай спецификацию для уведомлений в реальном времени, которая: - Использует WebSockets для обновлений в реальном времени - Откатывается к опросу для старых браузеров - Обрабатывает до 10,000 одновременных соединений - Поддерживает порядок сообщений - Включает поддержку очереди в офлайне" ``` #### С критериями приемки ``` "Создай спецификацию для функции поиска с этими критериями приемки: - Результаты появляются в течение 200мс - Поддерживает нечеткое сопоставление - Включает фильтры по дате, категории и автору - Показывает оценку релевантности - Обрабатывает опечатки и синонимы" ``` #### Спецификация микросервиса ``` "Создай спецификацию для микросервиса инвентаризации, который: - Предоставляет REST API - Использует PostgreSQL для хранения - Публикует события в Kafka - Реализует паттерн CQRS - Включает endpoints проверки здоровья" ``` ## Управление спецификациями ### Список и статус #### Получить обзор ``` "Покажи все мои спецификации" "Покажи все спецификации и их прогресс" "Какие спецификации ждут утверждения?" "Какие спецификации сейчас в работе?" ``` #### Конкретный статус ``` "Покажи статус спецификации user-auth" "Какой прогресс у payment-processing?" "Покажи что осталось сделать в спецификации notification" "Какие задачи выполнены в user-profile?" ``` #### Фильтрация ``` "Покажи спецификации, которые выполнены более чем на 50%" "Покажи спецификации, ожидающие моего утверждения" "Какие спецификации еще не имеют выполненных задач?" "Покажи заблокированные спецификации" ``` ### Управление документами #### Просмотр документов ``` "Покажи требования для user-auth" "Отобрази документ дизайна для payments" "Какие задачи для системы уведомлений?" "Покажи все документы для спецификации search" ``` #### Обновление документов ``` "Обнови требования user-auth, чтобы включить 2FA" "Пересмотри дизайн платежей для использования Stripe Connect" "Добавь задачу для тестирования безопасности в user-profile" "Обнови требования на основе обратной связи: [feedback]" ``` ## Запросы реализации ### Отдельные задачи #### Базовая реализация ``` "Реализуй задачу 1.2 из user-auth" "Выполни задачу 2.1.3 в спецификации payment" "Работай над следующей ожидающей задачей в notifications" ``` #### С контекстом ``` "Реализуй задачу 1.2 из user-auth используя TypeScript и Express" "Выполни задачу миграции базы данных используя Prisma" "Реализуй задачу API endpoint следуя REST соглашениям" ``` ### Пакетная реализация #### По разделу ``` "Реализуй все задачи базы данных из user-auth" "Выполни все задачи фронтенда в спецификации dashboard" "Работай над всеми задачами API для payments" ``` #### По приоритету ``` "Реализуй сначала все критические задачи" "Выполни задачи MVP из user-profile" "Сосредоточься на задачах, необходимых для демо" ``` #### Последовательно ``` "Реализуй задачи с 1.1 по 1.5 из user-auth" "Выполни все подзадачи под разделом 2" "Работай над задачами настройки по порядку" ``` ### Стратегии реализации #### Разработка через тестирование ``` "Для задачи 1.2 сначала напиши тесты, потом реализуй" "Реализуй задачу 2.1 с полным покрытием тестами" "Создай модульные тесты при реализации задачи сервиса" ``` #### С документацией ``` "Реализуй задачу 1.3 и задокументируй API" "Выполни задачу аутентификации с встроенными комментариями" "Реализуй и создай примеры использования для задачи 2.2" ``` ## Управляющие документы ### Создание управления #### Полный набор ``` "Создай управляющие документы для моего проекта электронной коммерции" "Настрой управление для SaaS приложения" "Создай руководство проекта для мобильного приложения" ``` #### Отдельные документы ``` "Создай документ управления продуктом с фокусом на пользовательский опыт" "Создай техническое управление для архитектуры микросервисов" "Создай управление структурой для настройки монорепо" ``` #### Из контекста ``` "Создай управляющие документы на основе @project-brief.md" "Сгенерируй управление из наших технических решений в @architecture.md" ``` ### Обновление управления ``` "Обнови управление продуктом, чтобы включить B2B функции" "Пересмотри техническое управление для использования GraphQL вместо REST" "Обнови управление структурой для новой модульной системы" ``` ## Процессы утверждения ### Запрос обратной связи #### С конкретными проблемами ``` "Запроси утверждение требований user-auth - особенно проверь раздел безопасности" "Попроси проверить дизайн payment - сосредоточься на обработке ошибок" "Запроси обратную связь по разбиению задач - не слишком ли детально?" ``` #### Запросы ревизии ``` "Требования нуждаются в большей детализации по: - Сценариям обработки ошибок - Требованиям производительности - Соображениям безопасности Пожалуйста, пересмотри и переотправь" ``` ### Решения об утверждении #### Утверждение ``` "Утверди требования user-auth" "Дизайн выглядит хорошо, утверди его" "Прими разбиение задач как есть" ``` #### Запрос изменений ``` "Запроси изменения в требованиях: - Добавь поддержку мультитенантности - Включи ограничение частоты запросов - Укажи политику хранения данных" ``` #### Отклонение ``` "Отклони текущий дизайн - нам нужно использовать событийно-ориентированную архитектуру вместо этого" "Начни заново с требованиями - объем слишком широкий" ``` ## Процесс работы с ошибками ### Сообщение об ошибках #### Детальный отчет ``` "Создай отчет об ошибке: Заголовок: Вход не работает со специальными символами Шаги: 1) Введи email с '+' 2) Отправь форму 3) Увидишь ошибку Ожидается: Вход успешен Фактически: Ошибка 500 Приоритет: Высокий Среда: Продакшен" ``` #### Из логов ошибок ``` "Создай отчет об ошибке из этой ошибки: [вставь stack trace]" "Задокументируй эту ошибку из оповещения Sentry: [ссылка]" ``` ### Решение ошибок #### Расследование ``` "Исследуй первопричину ошибки #45" "Проанализируй почему webhook платежа не работает" "Отлажь проблему производительности в endpoint поиска" ``` #### Реализация исправления ``` "Создай исправление для ошибки #45 в аутентификации пользователей" "Реализуй решение для проблемы тайм-аута платежа" "Исправь утечку памяти в сервисе уведомлений" ``` ## Изменения в середине реализации ### Когда спецификации меняются во время разработки Требования и дизайн часто развиваются во время реализации. Когда это происходит, вам нужно поддерживать tasks.md в соответствии с текущей спецификацией, сохраняя завершенную работу. ### Использование функции обновления задач AI имеет доступ к подробным инструкциям по обновлению задач через запрос refresh-tasks. Просто информируйте AI о ваших изменениях: #### Базовое обновление задач ``` "Требования были обновлены. Пожалуйста, обнови tasks.md для соответствия текущим requirements.md и design.md." ``` #### Детальное обновление задач с контекстом ``` "Я обновил спецификацию следующими изменениями: - Удален модуль отчетности - Изменена база данных с MongoDB на PostgreSQL - Добавлена функция социального входа Пожалуйста, обнови tasks.md следуя процессу обновления задач: 1. Сохрани все выполненные и находящиеся в работе задачи 2. Добавь задачи миграции для изменения базы данных 3. Удали ожидающие задачи для модуля отчетности 4. Добавь новые задачи для социального входа" ``` #### Изменение архитектуры, требующее миграции ``` "Мы переходим с REST API на GraphQL. Несколько REST endpoints уже реализованы. Пожалуйста, обнови tasks.md с: 1. Вся выполненная работа по REST сохранена 2. Задачи миграции для оборачивания логики REST в GraphQL resolvers 3. Новые задачи реализации GraphQL 4. Задачи очистки для удаления REST после проверки GraphQL" ``` ### Ожидаемое поведение AI Когда вы запрашиваете обновление задач, AI будет: 1. **Анализировать текущее состояние** - Прочитать requirements.md и design.md для текущей спецификации - Идентифицировать выполненные, в работе и ожидающие задачи - Определить какие функции были добавлены, удалены или изменены 2. **Сохранить выполненную работу** - Сохранить все [x] выполненные задачи без изменений - Сохранить все [-] задачи в работе без изменений - Добавить заметки когда выполненная работа для удаленных функций 3. **Обработать изменения архитектуры** - Добавить задачи миграции после выполненной работы, требующей обновления - Создать переходные задачи для прогрессивной миграции - Включить задачи проверки перед удалением старой реализации 4. **Обновить ожидающие задачи** - Удалить ожидающие задачи для удаленных функций - Обновить ожидающие задачи для измененных требований - Добавить новые задачи для новых функций 5. **Поддерживать структуру задач** - Сохранить последовательную нумерацию - Сохранить формат задач - Включить ссылки на требования - Поддерживать порядок зависимостей ### Примеры сценариев #### Удаление функции ``` "Мы решили удалить модуль отчетности из спецификации. Обнови tasks.md соответственно." ``` Ожидаемое поведение AI: - Сохранить все выполненные задачи отчетности с их статусом [x] - Сохранить все задачи отчетности в работе с их статусом [-] - Удалить только ожидающие [ ] задачи отчетности - Добавить заметку: "_Примечание: Функция отчетности удалена из спецификации, но выполненная работа сохранена_" #### Изменение архитектуры с выполненной работой ``` "Мы переходим с MongoDB на PostgreSQL. Обнови ожидающие задачи базы данных. Обрати внимание, что мы уже реализовали схемы MongoDB и логику подключения." ``` Ожидаемое поведение AI: - Сохранить все выполненные задачи MongoDB в точности как написано - Сохранить все задачи MongoDB в работе в точности как написано - Добавить новые задачи миграции сразу после выполненной работы MongoDB: - Мигрировать схемы MongoDB в таблицы PostgreSQL - Заменить логику подключения MongoDB на клиент PostgreSQL - Обновить запросы базы данных с синтаксиса MongoDB на PostgreSQL - Мигрировать существующие данные MongoDB в PostgreSQL - Обновить конфигурацию окружения для PostgreSQL - Удалить зависимости MongoDB после проверки миграции - Обновить оставшиеся ожидающие задачи базы данных для использования PostgreSQL - Поддерживать последовательность нумерации задач #### Добавление функции ``` "Добавь социальный вход в спецификацию аутентификации. Требования и дизайн были обновлены." ``` Ожидаемое поведение AI: - Проанализировать текущую структуру задач для логической точки вставки - Добавить новые задачи социального входа с соответствующей нумерацией - Ссылаться на конкретные требования для социального входа - Обеспечить, что новые задачи поддерживают порядок зависимостей - Если базовая аутентификация уже реализована, добавить задачи интеграции ## Продвинутые паттерны ### Многоспецификационные рабочие процессы #### Связанные спецификации ``` "Создай спецификацию для admin-dashboard, которая интегрируется с: - спецификацией user-management - спецификацией analytics - спецификацией reporting" ``` #### Зависимости спецификаций ``` "Создай спецификацию для notifications, которая зависит от: - завершения user-auth - реализации message-queue - доступности email-service" ``` ### Инкрементальная разработка #### Сначала MVP ``` "Создай MVP спецификацию для user-profiles только с: - Базовое создание профиля - Отображаемое имя и аватар - Публичный просмотр профиля (Мы добавим социальные функции позже)" ``` #### Спецификации улучшения ``` "Создай спецификацию улучшения для user-auth добавляя: - Социальный вход (Google, GitHub) - Биометрическую аутентификацию - Расширенное управление сессиями - Связывание аккаунтов" ``` ### Сложные сценарии #### Спецификации миграции ``` "Создай спецификацию для миграции с MongoDB на PostgreSQL: - Документируй текущую схему - Спроектируй новую реляционную структуру - Спланируй миграцию с нулевым простоем - Включи процедуры отката" ``` #### Спецификации рефакторинга ``` "Создай спецификацию рефакторинга для: - Разделения монолита на сервисы - Извлечения общих компонентов - Улучшения покрытия тестами до 80% - Поддержания обратной совместимости" ``` ## Советы для эффективного использования запросов ### Будьте конкретны ❌ **Расплывчато**: "Создай спецификацию входа" ✅ **Конкретно**: "Создай спецификацию для входа по email/паролю с 2FA, запомнить меня и сбросом пароля" ### Предоставляйте контекст ❌ **Без контекста**: "Реализуй задачу" ✅ **С контекстом**: "Реализуй задачу 1.2 используя наше существующее Express middleware и базу данных PostgreSQL" ### Устанавливайте четкие ожидания ❌ **Неясно**: "Сделай лучше" ✅ **Ясно**: "Улучши дизайн для обработки 10x текущего трафика с временем отклика менее 200мс" ### Используйте инкрементальные запросы ❌ **Слишком много**: "Создай 5 спецификаций и реализуй все" ✅ **Инкрементально**: "Создай спецификацию user-auth сначала, потом мы проверим перед переходом к следующей" ### Ссылайтесь на существующую работу ❌ **Начиная с нуля**: "Создай новую платежную систему" ✅ **Строя на основе**: "Улучши нашу спецификацию платежей для добавления биллинга подписок" ## Связанная документация - [Руководство пользователя](USER-GUIDE.ru.md) - Общие инструкции по использованию - [Процесс рабочего процесса](WORKFLOW.ru.md) - Понимание рабочего процесса - [Справочник инструментов](TOOLS-REFERENCE.ru.md) - Полная документация по инструментам - [Устранение неполадок](TROUBLESHOOTING.ru.md) - Решение распространенных проблем