Spec Workflow MCP

# Руководство по процессу рабочего процесса Это руководство объясняет полный процесс разработки на основе спецификаций и лучшие практики использования Spec Workflow MCP. ## Обзор Рабочий процесс на основе спецификаций следует структурированному подходу: ``` Управление → Спецификации → Реализация → Проверка ``` Каждая фаза строится на предыдущей, обеспечивая систематическую и хорошо документированную разработку. ## Фаза 1: Настройка проекта с управляющими документами ### Зачем нужны управляющие документы? Управляющие документы обеспечивают руководство высокого уровня, которое поддерживает согласованность вашего проекта. Они действуют как путеводная звезда для всех решений по разработке. ### Создание управляющих документов ``` "Создай управляющие документы для моего проекта" ``` Это генерирует три ключевых документа: #### 1. Управление продуктом (`steering/product.md`) - Видение и миссия продукта - Целевые пользователи и персоны - Основные функции и приоритеты - Метрики успеха и KPI - Цели и ограничения #### 2. Техническое управление (`steering/tech.md`) - Архитектурные решения - Выбор технологического стека - Требования к производительности - Соображения безопасности - Подход к масштабируемости #### 3. Управление структурой (`steering/structure.md`) - Организация проекта - Соглашения о файлах и папках - Стандарты именования - Границы модулей - Структура документации ### Лучшие практики для управления 1. **Создавайте рано** - Настройте управление перед любыми спецификациями 2. **Держите обновленным** - Пересматривайте по мере развития проекта 3. **Ссылайтесь часто** - Используйте для принятия решений 4. **Делитесь широко** - Обеспечьте согласованность команды ## Фаза 2: Создание спецификации ### Система из трех документов Каждая спецификация состоит из трех последовательных документов: ``` Требования → Дизайн → Задачи ``` ### Документ требований **Цель**: Определить ЧТО нужно создать **Содержание**: - Обзор функции - Пользовательские истории - Функциональные требования - Нефункциональные требования - Критерии приемки - Ограничения и предположения **Пример создания**: ``` "Создай требования для системы уведомлений пользователей, которая поддерживает: - Email уведомления - Уведомления в приложении - Push уведомления - Пользовательские предпочтения - История уведомлений" ``` ### Документ дизайна **Цель**: Определить КАК это будет создано **Содержание**: - Техническая архитектура - Дизайн компонентов - Модели данных - Спецификации API - Точки интеграции - Подход к реализации **Автоматическая генерация**: Создается после утверждения требований ### Документ задач **Цель**: Определить ШАГИ для создания **Содержание**: - Иерархическое разбиение задач - Зависимости - Оценки усилий - Порядок реализации - Требования к тестированию **Пример структуры**: ``` 1.0 Настройка базы данных 1.1 Создать таблицы уведомлений 1.2 Настроить индексы 1.3 Создать скрипты миграции 2.0 Реализация бэкенда 2.1 Создать сервис уведомлений 2.1.1 Обработчик email 2.1.2 Обработчик push 2.2 Создать API endpoints 2.3 Добавить аутентификацию 3.0 Реализация фронтенда 3.1 Создать компоненты уведомлений 3.2 Интегрировать с API 3.3 Добавить UI предпочтений ``` ## Фаза 3: Проверка и утверждение ### Процесс утверждения 1. **Создание документа** - AI генерирует документ 2. **Запрос проверки** - Утверждение запрашивается автоматически 3. **Проверка пользователем** - Проверка на панели управления/расширении 4. **Решение** - Утвердить, запросить изменения или отклонить 5. **Ревизия** (если нужно) - AI обновляет на основе обратной связи 6. **Окончательное утверждение** - Документ заблокирован для реализации ### Принятие решений об утверждении #### Когда утверждать - Требования полные и ясные - Дизайн решает заявленную проблему - Задачи логичны и всеобъемлющи - Нет серьезных проблем или пробелов #### Когда запрашивать изменения - Отсутствуют важные детали - Неясные спецификации - Доступен лучший подход - Требуется согласование со стандартами #### Когда отклонять - Фундаментальное непонимание - Полностью неправильный подход - Требуется полное переосмысление ### Предоставление эффективной обратной связи Хорошая обратная связь: ``` "Процесс аутентификации должен использовать JWT токены вместо сессий. Добавь ограничение частоты запросов к API endpoints. Включи обработку ошибок для сетевых сбоев." ``` Плохая обратная связь: ``` "Это выглядит неправильно. Исправь это." ``` ## Фаза 4: Реализация ### Стратегия выполнения задач #### Последовательная реализация Лучше для зависимых задач: ``` "Реализуй задачу 1.1 из спецификации user-auth" "Теперь реализуй задачу 1.2" "Продолжи с задачей 1.3" ``` #### Параллельная реализация Для независимых задач: ``` "Реализуй все UI задачи из спецификации dashboard, пока я работаю над бэкендом" ``` #### Реализация по разделам Для логических группировок: ``` "Реализуй все задачи базы данных из спецификации payment" ``` ### Отслеживание прогресса Мониторинг реализации через: - Вид задач на панели управления - Полосы прогресса - Индикаторы статуса - Проценты выполнения ### Обработка блокировщиков Когда заблокирован: 1. Документируйте блокировщик 2. Создайте подзадачу для решения 3. Переходите к параллельным задачам если возможно 4. Обновите статус задачи на "заблокирована" ## Фаза 5: Проверка ### Стратегия тестирования После реализации: 1. **Модульное тестирование** ``` "Создай модульные тесты для сервиса уведомлений" ``` 2. **Интеграционное тестирование** ``` "Создай интеграционные тесты для API endpoints" ``` 3. **Сквозное тестирование** ``` "Создай E2E тесты для полного процесса уведомлений" ``` ### Обновления документации Держите документацию актуальной: ``` "Обнови документацию API для новых endpoints" "Добавь примеры использования в README" ``` ## Структура файлов и организация ### Стандартная структура проекта ``` your-project/ ├── .spec-workflow/ │ ├── steering/ │ │ ├── product.md │ │ ├── tech.md │ │ └── structure.md │ ├── specs/ │ │ ├── user-auth/ │ │ │ ├── requirements.md │ │ │ ├── design.md │ │ │ └── tasks.md │ │ └── payment-gateway/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── approval/ │ └── [файлы отслеживания утверждений] ├── src/ │ └── [ваша реализация] └── tests/ └── [ваши тесты] ``` ### Соглашения об именовании **Имена спецификаций**: - Используйте kebab-case: `user-authentication` - Будьте описательны: `payment-processing` а не `payments` - Избегайте версий: `user-profile` а не `user-profile-v2` **Имена документов**: - Всегда: `requirements.md`, `design.md`, `tasks.md` - Согласованность во всех спецификациях ## Продвинутые рабочие процессы ### Итерации функций Для развивающихся функций: 1. Создайте начальную спецификацию 2. Реализуйте MVP 3. Создайте спецификацию улучшения 4. Ссылайтесь на оригинальную спецификацию 5. Стройте на существующей работе Пример: ``` "Создай спецификацию улучшения для user-auth, которая добавляет: - Социальный вход (Google, Facebook) - Биометрическую аутентификацию - Улучшения управления сессиями" ``` ### Процесс рефакторинга 1. **Документируйте текущее состояние** ``` "Создай спецификацию, документирующую текущую систему аутентификации" ``` 2. **Спроектируйте улучшения** ``` "Спроектируй рефакторинг для улучшения производительности аутентификации" ``` 3. **Спланируйте миграцию** ``` "Создай задачи миграции для рефакторинга" ``` 4. **Реализуйте постепенно** ``` "Реализуй задачи рефакторинга с обратной совместимостью" ``` ### Процесс решения ошибок 1. **Отчет об ошибке** ``` "Создай отчет об ошибке для проблемы тайм-аута входа" ``` 2. **Расследование** ``` "Исследуй первопричину ошибки #45" ``` 3. **Дизайн решения** ``` "Спроектируй исправление для проблемы тайм-аута" ``` 4. **Реализация** ``` "Реализуй исправление ошибки" ``` 5. **Проверка** ``` "Создай регрессионные тесты для ошибки #45" ``` ## Лучшие практики ### 1. Поддерживайте детализацию спецификаций **Хорошо**: Одна спецификация на функцию - `user-authentication` - `payment-processing` - `notification-system` **Плохо**: Слишком широкие спецификации - `backend-system` - `all-features` ### 2. Последовательное создание документов Всегда следуйте порядку: 1. Требования (что) 2. Дизайн (как) 3. Задачи (шаги) Никогда не пропускайте вперед. ### 3. Полное утверждение перед реализацией - ✅ Утвердить требования → Создать дизайн - ✅ Утвердить дизайн → Создать задачи - ✅ Проверить задачи → Начать реализацию - ❌ Пропустить утверждение → Проблемы реализации ### 4. Держите спецификации обновленными Когда требования меняются: ``` "Обнови требования для user-auth, чтобы включить поддержку SSO" ``` ### 5. Используйте согласованную терминологию Поддерживайте согласованность в: - Именах спецификаций - Именах компонентов - Терминологии API - Именовании базы данных ### 6. Архивируйте завершенные спецификации Держите рабочее пространство чистым: ``` "Архивируй завершенную спецификацию user-auth" ``` ## Общие паттерны ### От MVP до полной функции 1. Начните со спецификации MVP 2. Реализуйте основную функциональность 3. Создайте спецификации улучшения 4. Стройте постепенно 5. Поддерживайте обратную совместимость ### Разработка микросервисов 1. Создайте документ управления сервисом 2. Определите границы сервиса 3. Создайте спецификацию на сервис 4. Определите точки интеграции 5. Реализуйте сервисы независимо ### Разработка API-first 1. Сначала создайте спецификацию API 2. Спроектируйте контракты 3. Сгенерируйте документацию 4. Реализуйте endpoints 5. Создайте клиентские SDK ## Устранение проблем рабочего процесса ### Спецификации становятся слишком большими **Решение**: Разбейте на меньшие спецификации ``` "Разбей спецификацию электронной коммерции на: - product-catalog - shopping-cart - checkout-process - order-management" ``` ### Неясные требования **Решение**: Запросите уточнение ``` "Требования нуждаются в большей детализации по: - Ролям пользователей и разрешениям - Сценариям обработки ошибок - Требованиям к производительности" ``` ### Дизайн не соответствует требованиям **Решение**: Запросите ревизию ``` "Дизайн не учитывает требование мультитенантности. Пожалуйста, пересмотри, чтобы включить изоляцию арендаторов." ``` ## Интеграция с процессом разработки ### Процесс Git 1. Создайте ветку функции для каждой спецификации 2. Коммитьте после завершения каждой задачи 3. Ссылайтесь на спецификацию в сообщениях коммитов 4. PR когда спецификация завершена ### Интеграция CI/CD - Запускайте тесты для завершенных задач - Проверяйте соответствие требованиям - Разворачивайте завершенные функции - Мониторьте метрики успеха ### Командная совместная работа - Делитесь URL панели управления - Назначайте спецификации членам команды - Проверяйте спецификации друг друга - Координируйтесь через утверждения ## Связанная документация - [Руководство пользователя](USER-GUIDE.ru.md) - Общие инструкции по использованию - [Руководство по запросам](PROMPTING-GUIDE.ru.md) - Примеры запросов и паттернов - [Справочник инструментов](TOOLS-REFERENCE.ru.md) - Полная документация по инструментам - [Руководство по интерфейсам](INTERFACES.ru.md) - Подробности панели управления и расширения