Конспект: GitHub SpecKit: Пошаговое руководство по Spec-Driven Development для вайбкодеров — VibCoderZ - VibeCoderz

Загрузка...

🎯 О чём этот конспект: Разбор нового open-source фреймворка SpecKit от GitHub, который внедряет методологию Spec-Driven Development (разработка на основе спецификаций) в работу с AI-агентами. Вместо хаотичного промптинга («вайбкодинга»), SpecKit предлагает структурированный процесс из четырех фаз, превращая AI в дисциплинированного исполнителя.

👤 Кому будет полезно: Разработчикам и вайбкодерам, использующим Cursor, Claude Code или GitHub Copilot, которые сталкиваются с галлюцинациями AI и «кривым» кодом в больших проектах.

✨ Что получите: Вы научитесь использовать SpecKit для создания сложных приложений с предсказуемым результатом, минимизируя ошибки за счет четкого планирования и поэтапного выполнения задач под контролем AI-агента.

1. Концепция Spec-Driven Development (SDD) vs Вайбкодинг

Контекст: Традиционный «вайбкодинг» страдает от недостатка ясности: когда вы просите AI «добавить функцию обмена фото», модель додумывает тысячи деталей, которые могут не совпадать с вашим видением. Spec-Driven Development переворачивает процесс: сначала создается «живая» исполняемая спецификация (Spec), которая становится единым источником истины для всех стейкхолдеров и AI-инструментов. Это устраняет разрыв между намерением и реализацией.

Выгода: Код становится чище, безопаснее и надежнее, так как AI не гадает, а следует строгому техническому заданию, которое вы утвердили заранее.

Как применить:

Шаг 1: Установка SpecKit — [Terminal] — Установите инструмент и инициализируйте проект, выбрав фреймворк агента (например, GitHub Copilot, Claude Code или Gemini CLI).
Шаг 2: Инициализация проекта — [CLI] — Запустите команду создания проекта:

npx @githubnext/speckit init my-pokedex-app

Шаг 3: Выбор модели — [Config] — Для лучших результатов автор рекомендует использовать мощные модели, такие как Claude 3.5 Sonnet или Grok-1, так как качество следования спецификациям напрямую зависит от когнитивных способностей модели.

Результат: Создана структура проекта с папками scripts и templates, готовая к генерации документации.

2. Фаза 1: Specify (Определение намерений)

Контекст: На этом этапе вы описываете «что» и «зачем» вы строите, фокусируясь на пользовательских путях и результатах. SpecKit использует ваш промпт для генерации подробного Markdown-файла спецификации. Важно, что AI сам выделяет «зоны уточнения» (Needs Clarification), где ему не хватает данных для принятия решения.

Выгода: Вы получаете профессиональное ТЗ, включая Edge Cases (краевые случаи), о которых могли забыть, не тратя часы на его написание вручную.

Как применить:

Шаг 1: Запуск генерации спецификации — [CLI] — Введите общую идею проекта.

# Пример команды (в интерфейсе агента)
specify "Создай Pokedex Team Builder, где можно искать покемонов через API и добавлять их в команду. Используй Shadcn UI."

Шаг 2: Ревью файла spec.md — [VS Code] — Откройте созданный файл. Проверьте разделы User Stories, Acceptance Scenarios и Functional Requirements.
Шаг 3: Уточнение — [Markdown] — Если в блоке Needs Clarification есть вопросы, впишите ответы прямо в файл или обновите спецификацию новым промптом.

Результат: Утвержденный документ спецификации, который служит «законом» для AI на всех следующих этапах.

3. Фаза 2: Plan (Архитектурное планирование)

Контекст: После утверждения «что» строить, нужно определить «как». В фазе планирования задается стек технологий и архитектурные ограничения. SpecKit генерирует технический план, который включает схему данных, контракты объектов и даже исследовательский документ (Research Document) с обоснованием выбора тех или иных библиотек.

Выгода: Предотвращение архитектурного хаоса. AI заранее продумывает структуру данных (например, Zod-схемы) и учитывает ваши требования (например, использование Debounce для API-запросов).

Как применить:

Шаг 1: Определение стека — [CLI] — Передайте технические требования.

plan "Используй Next.js, Tailwind CSS, и Zod для валидации. Добавь debounce на поиск (500ms), чтобы не спамить API покемонов."

Шаг 2: Анализ Research Document — [Markdown] — Изучите файл research.md. Там AI объяснит, почему выбраны конкретные решения и какие были альтернативы.
Шаг 3: Проверка контрактов — [Markdown] — Убедитесь, что типы данных в плане соответствуют вашим ожиданиям.

Результат: Пошаговый технический план реализации с чек-листом готовности.

4. Фаза 3 и 4: Tasks & Implement (Исполнение)

Контекст: План разбивается на мелкие, атомарные задачи (Tasks). Каждая задача имеет уникальный номер. Вместо того чтобы просить AI «напиши всё приложение», вы заставляете его выполнять задачи по очереди. SpecKit по умолчанию часто следует подходу TDD (Test-Driven Development), сначала создавая тесты, а затем код.

Выгода: Гранулярный контроль. Вы видите прогресс по каждой задаче и можете остановить процесс, если AI свернул не туда, не переписывая весь проект целиком.

Как применить:

Шаг 1: Генерация списка задач — [CLI] — Попросите создать список задач для MVP.

tasks "Создай список задач для реализации MVP версии согласно плану."

Шаг 2: Поэтапная реализация — [CLI] — Используйте команду implement с номерами задач.

implement tasks 1-4

Шаг 3: Итерация — [CLI] — После завершения первых задач, переходите к следующим:

implement tasks 5-10

Результат: Полностью рабочее приложение, где каждая функция протестирована и соответствует исходной спецификации.

FAQ

В: Чем SpecKit отличается от обычного промпта в Cursor? О: Cursor работает в режиме «чат-код», где контекст быстро теряется. SpecKit принуждает AI сначала зафиксировать требования в документах (spec.md, plan.md), которые агент обязан перечитывать перед каждым изменением кода. Это исключает ситуацию, когда AI «забывает» логику проекта через 10 сообщений.

В: Можно ли использовать SpecKit с Claude Code? О: Да, SpecKit — это открытый инструментарий, разработанный GitHub для работы с любыми агентскими фреймворками, включая Claude Code, GitHub Copilot и специализированные CLI-агенты.

В: Что делать, если AI сгенерировал плохую спецификацию? О: Вы можете вручную отредактировать файл спецификации в Markdown. SpecKit спроектирован так, чтобы человек мог вмешаться на любом из 4-х этапов. Ваши правки в файле станут новыми инструкциями для AI.

В: Обязательно ли использовать TDD (тесты перед кодом)? О: По умолчанию шаблоны SpecKit склоняют AI к TDD, так как это повышает надежность. Однако вы можете изменить это в фазе Plan, указав в промпте: «Реализуй функции без написания предварительных тестов».

В: Какую модель лучше выбрать для работы со SpecKit? О: Автор отмечает, что GPT-4o иногда справляется хуже, чем модели семейства Grok или Claude 3.5 Sonnet, в вопросах строгого следования сложным спецификациям. Рекомендуется использовать наиболее «умные» модели для фаз Specify и Plan.

Конспект создан на основе видео «GitHub SpecKit: The Future of AI Coding?» канала Better Stack. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=em3vIT9aUsg