Spec Workflow MCP

# Руководство пользователя Комплексное руководство по использованию Spec Workflow MCP для разработки с помощью AI. ## Начало работы ### Что такое Spec Workflow MCP? Spec Workflow MCP - это сервер Model Context Protocol, который предоставляет структурированные инструменты разработки на основе спецификаций для AI-ассистентов. Он помогает вам: - Создавать подробные спецификации перед кодированием - Отслеживать прогресс реализации - Управлять утверждениями и ревизиями - Поддерживать документацию проекта ### Базовый рабочий процесс 1. **Создайте спецификацию** - Определите, что вы хотите создать 2. **Проверьте и утвердите** - Убедитесь, что спецификации соответствуют требованиям 3. **Реализуйте задачи** - Выполните план реализации 4. **Отслеживайте прогресс** - Мониторьте статус выполнения ## Создание спецификаций ### Простое создание спецификации Попросите вашего AI-ассистента создать спецификацию: ``` "Создай спецификацию для аутентификации пользователей" ``` AI автоматически: 1. Создаст документ требований 2. Спроектирует технический подход 3. Разобьет реализацию на задачи ### Детальное создание спецификации Предоставьте больше контекста для лучших спецификаций: ``` "Создай спецификацию с названием payment-gateway со следующими функциями: - Обработка кредитных карт - Интеграция с PayPal - Управление подписками - Обработка вебхуков для платежных событий" ``` ### Из существующих документов Используйте существующие PRD или документы дизайна: ``` "Создай спецификацию из @product-requirements.md" ``` ## Управление спецификациями ### Список всех спецификаций ``` "Покажи все мои спецификации" ``` Возвращает: - Имена спецификаций - Текущий статус - Процент прогресса - Состояния документов ### Проверка статуса спецификации ``` "Покажи статус спецификации user-auth" ``` Предоставляет: - Статус утверждения требований - Статус утверждения дизайна - Прогресс выполнения задач - Детальное разбиение задач ### Просмотр документов спецификации Используйте панель управления или расширение VSCode для: - Чтения документов требований - Просмотра документов дизайна - Просмотра списков задач - Отслеживания прогресса реализации ## Работа с задачами ### Структура задач Задачи организованы иерархически: - **1.0** - Основные разделы - **1.1** - Подзадачи - **1.2** - Подзадачи - **1.2.1** - Детальные шаги ### Реализация задач #### Метод 1: Прямая реализация ``` "Реализуй задачу 1.2 из спецификации user-auth" ``` #### Метод 2: Копирование из панели управления 1. Откройте панель управления 2. Перейдите к вашей спецификации 3. Нажмите вкладку "Задачи" 4. Нажмите кнопку "Копировать запрос" рядом с любой задачей 5. Вставьте в ваш разговор с AI #### Метод 3: Пакетная реализация ``` "Реализуй все задачи настройки базы данных из спецификации user-auth" ``` ### Статус задач Задачи имеют три состояния: - ⏳ **Ожидает** - Не начата - 🔄 **В процессе** - В настоящее время работают - ✅ **Завершена** - Закончена ## Процесс утверждения ### Запрос утверждения Когда документы готовы к проверке: 1. AI автоматически запрашивает утверждение 2. Панель управления показывает уведомление 3. Проверьте документ 4. Предоставьте обратную связь или утвердите ### Действия утверждения - **Утвердить** - Принять документ как есть - **Запросить изменения** - Предоставить обратную связь для ревизии - **Отклонить** - Начать заново с новыми требованиями ### Процесс ревизии 1. Предоставьте конкретную обратную связь 2. AI пересматривает документ 3. Проверьте обновленную версию 4. Утвердите или запросите дальнейшие изменения ## Процесс работы с ошибками ### Сообщение об ошибках ``` "Создай отчет об ошибке для сбоя входа при использовании SSO" ``` Создает: - Описание ошибки - Шаги воспроизведения - Ожидаемое против фактического поведения - Приоритет и серьезность ### Решение ошибок ``` "Создай исправление для ошибки #123 в спецификации user-auth" ``` Генерирует: - Анализ первопричины - План реализации исправления - Требования к тестированию - Шаги развертывания ## Система шаблонов ### Использование шаблонов Spec Workflow включает шаблоны для: - Документов требований - Документов дизайна - Списков задач - Отчетов об ошибках - Управляющих документов ### Пользовательские шаблоны Создайте свои собственные шаблоны в `.spec-workflow/templates/`: ```markdown # Пользовательский шаблон функции ## Обзор [Описание функции] ## Пользовательские истории [Пользовательские истории] ## Технические требования [Технические детали] ``` ## Расширенные функции ### Управляющие документы Создайте руководство проекта высокого уровня: ``` "Создай управляющие документы для моего проекта электронной коммерции" ``` Генерирует: - **Управление продуктом** - Видение и цели - **Техническое управление** - Архитектурные решения - **Управление структурой** - Организация проекта ### Система архивирования Управление завершенными спецификациями: - Перемещение готовых спецификаций в архив - Поддержание чистоты активного рабочего пространства - Доступ к архивным спецификациям в любое время - Восстановление спецификаций при необходимости ### Многоязычная поддержка Изменение языка интерфейса: 1. **Панель управления**: Настройки → Язык 2. **Расширение VSCode**: Настройки расширения → Язык 3. **Конфигурационный файл**: `lang = "ru"` (или другой код языка) ## Лучшие практики ### 1. Начните с управляющих документов Перед созданием спецификаций: ``` "Создай управляющие документы для руководства проектом" ``` ### 2. Будьте конкретны в требованиях Хорошо: ``` "Создай спецификацию для аутентификации пользователей с: - Вход по email/паролю - OAuth2 (Google, GitHub) - Поддержка 2FA - Процесс сброса пароля" ``` Не идеально: ``` "Создай спецификацию входа" ``` ### 3. Проверяйте перед реализацией Всегда проверяйте и утверждайте: 1. Документ требований 2. Документ дизайна 3. Разбиение задач ### 4. Реализуйте постепенно - Выполняйте задачи по порядку - Тестируйте после каждого крупного раздела - Регулярно обновляйте статус задач ### 5. Используйте панель управления Панель управления предоставляет: - Визуальное отслеживание прогресса - Легкую навигацию по документам - Быстрые действия утверждения - Обновления в реальном времени ## Общие рабочие процессы ### Разработка функций 1. Создайте спецификацию: `"Создай спецификацию для функции корзины покупок"` 2. Проверьте требования на панели управления 3. Утвердите или запросите изменения 4. Проверьте документ дизайна 5. Утвердите дизайн 6. Реализуйте задачи последовательно 7. Отслеживайте прогресс на панели управления ### Исправление ошибок 1. Сообщите об ошибке: `"Создай отчет об ошибке для ошибки оформления заказа"` 2. Проанализируйте: `"Проанализируй первопричину ошибки #45"` 3. Спланируйте исправление: `"Создай план исправления для ошибки #45"` 4. Реализуйте: `"Реализуй исправление"` 5. Проверьте: `"Создай план тестирования для исправления ошибки #45"` ### Рефакторинг 1. Создайте спецификацию: `"Создай спецификацию для оптимизации базы данных"` 2. Документируйте текущее состояние 3. Спроектируйте улучшения 4. Спланируйте шаги миграции 5. Реализуйте постепенно 6. Проверяйте каждый шаг ## Советы и хитрости ### Эффективное управление задачами - Используйте группировку задач для связанных элементов - Копируйте запросы из панели управления для точности - Отмечайте задачи как выполненные сразу после завершения ### Управление документами - Держите требования краткими, но полными - Включайте критерии приемки - Добавляйте технические ограничения в дизайне - Ссылайтесь на внешние документы при необходимости ### Совместная работа - Используйте комментарии утверждения для обратной связи - Делитесь URL панели управления с командой - Экспортируйте документы для внешней проверки - Отслеживайте изменения через историю ревизий ## Интеграция с AI-ассистентами ### Контекстная осведомленность AI-ассистент автоматически: - Знает структуру вашего проекта - Понимает взаимосвязи спецификаций - Отслеживает прогресс реализации - Поддерживает согласованность ### Команды на естественном языке Говорите естественно: - "Какие у меня есть спецификации?" - "Покажи что осталось сделать" - "Начни работу над следующей задачей" - "Обнови дизайн для лучшей производительности" ### Непрерывный рабочий процесс AI поддерживает контекст между сеансами: - Возобновление с того места, где остановились - Ссылка на предыдущие решения - Построение на существующей работе - Поддержание целостности проекта ## Связанная документация - [Процесс рабочего процесса](WORKFLOW.ru.md) - Подробное руководство по рабочему процессу - [Руководство по запросам](PROMPTING-GUIDE.ru.md) - Примеры запросов - [Руководство по интерфейсам](INTERFACES.ru.md) - Подробности панели управления и расширения - [Справочник инструментов](TOOLS-REFERENCE.ru.md) - Полная документация по инструментам