Конспект: Spec-Driven Development: Как проектировать AI-проекты через спецификации — VibCoderZ - VibeCoderz

Загрузка...

🎯 О чём этот конспект: Разбор методологии Spec-Driven Development (разработка на основе спецификаций) для AI-агентов. Сравнение популярных инструментов (OpenSpec, Spec Kit, Agent OS, BMAD) и демонстрация авторского воркфлоу для создания структуры проекта, базы данных и списка задач перед написанием кода.

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

✨ Что получите: Пошаговый алгоритм превращения сырого ТЗ в детализированный план разработки, схему БД и приоритизированный список задач, который AI-агент сможет выполнить без ошибок.

1. Проблема планирования в AI-кодинге

Контекст: Большинство разработчиков используют AI в режиме «один промпт — одна фича». Однако при создании крупных SaaS-проектов AI быстро теряет контекст, забывает о существующих связях в БД и начинает плодить технический долг. Инструменты Spec-Driven Development решают проблему отсутствия единого «источника правды» (Source of Truth) для всего проекта. Вместо того чтобы сразу писать код, вы создаете и поддерживаете актуальную документацию в Markdown-файлах, на которые опирается AI-агент. Это позволяет разделять проект на фазы и гарантировать, что каждая новая фича соответствует общей архитектуре.

Выгода: Сокращение времени на рефакторинг и исправление ошибок интеграции на 40-60% за счет четкого проектирования «на берегу».

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

Шаг 1: Осознание роли — Перестаньте быть просто «кодером», станьте архитектором и менеджером спецификаций. Ваша задача — валидировать планы, которые строит AI.
Шаг 2: Выбор модели — Для качественного планирования используйте только топовые модели (например, Claude 3.5/3.7 Sonnet или Opus), так как они лучше справляются с логическим проектированием.

2. OpenSpec: Минималистичный подход к спецификациям

Контекст: OpenSpec — это один из самых простых инструментов для внедрения Spec-Driven Development. Он создает структуру папок и файлов внутри вашего проекта, которые служат инструкциями для AI-агентов (Claude Code, Cursor). Процесс строится циклично: инициализация проекта -> создание предложения по изменению (Proposal) -> реализация (Apply) -> архивация выполненной задачи. Это позволяет держать папку с активными задачами чистой и фокусировать внимание AI только на текущем изменении.

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

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

Шаг 1: Инициализация — Установите OpenSpec глобально и запустите в корне проекта:

npm install -g openspec
openspec init

Шаг 2: Наполнение контекста — Откройте созданный файл project.md и вставьте туда описание проекта (например, из Upwork или ваше ТЗ).
Шаг 3: Генерация техспека — Запустите Claude Code и попросите его дополнить технические детали на основе структуры проекта:

/openspec proposal "Add user authentication using Laravel Breeze"

Шаг 4: Применение — После того как AI создаст список задач (tasks.md) и вы его одобрите, примените изменения:

/openspec apply add-auth

Шаг 5: Архивация — Переместите выполненную задачу в архив, чтобы она не занимала контекстное окно:

/openspec archive add-auth

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

3. Альтернативные фреймворки: От Spec Kit до BMAD

Контекст: Существует спектр инструментов разной сложности. Agent OS предлагает более строгий цикл (Shape -> Write -> Create Tasks -> Orchestrate). Spec Kit (от GitHub) вводит корпоративные стандарты: конституцию проекта, принципы и автоматическую нумерацию фич. Самый сложный — BMAD, который имитирует работу целого IT-отдела с 21 специализированным AI-агентом (архитектор, аналитик, разработчик и т.д.). Однако автор видео отмечает, что избыточная сложность часто мешает разработке, заставляя тратить время на обслуживание самого инструмента, а не на продукт.

Выгода: Возможность выбрать инструмент под масштаб команды — от соло-разработчика до крупного энтерпрайза.

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

Для соло-разработчиков: Используйте OpenSpec или кастомные промпты.
Для команд: Рассмотрите Spec Kit для внедрения единых стандартов кодинга.
Для сложных систем: Изучите методологию BMAD, если вам нужно глубокое аналитическое сопровождение каждой фичи.

4. Авторский метод: 3-шаговая трансформация ТЗ в код

Контекст: Вместо использования внешних CLI-инструментов, можно использовать систему «умных» промптов, которые создают документацию в папке docs/. Этот метод дает больше свободы и не привязывает к конкретным командам терминала. Весь процесс делится на 3 критических этапа: создание User Stories (пользовательских историй), проектирование схемы БД и формирование финального списка фаз проекта.

Выгода: Полный контроль над архитектурой без необходимости учить синтаксис новых инструментов.

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

Шаг 1: User Stories — Используйте промпт для превращения описания проекта в список историй. Это поможет AI понять «зачем» и «для кого» делается продукт.
Шаг 2: Database Schema — На основе историй попросите AI спроектировать схему БД. Важно: проверьте индексы, типы полей и связи вручную.

Based on the project description and user stories, provide the database schema in Markdown format. Follow Laravel best practices (or your framework).

Шаг 3: Project Phases — Финальный промпт объединяет всё вышеперечисленное в нумерованный список задач.

Using project_description.md, user_stories.md and database_schema.md, generate a detailed task list divided into phases. Use the legend: [ ] Not Started, [/] In Progress, [x] Completed.

Результат: У вас есть файл project_phases.md, который служит дорожной картой. Вы просто просите AI: «Выполни задачу 1.2 из списка фаз».

FAQ

В: Зачем нужны эти инструменты, если Claude Code и так неплохо пишет код? О: Для маленьких скриптов они не нужны. Но как только проект растет, AI начинает забывать контекст и совершать архитектурные ошибки. Спецификации служат «внешней памятью» и жесткими рамками, которые не дают агенту уйти в сторону.

В: Какой инструмент выбрать новичку в вайбкодинге? О: Начните с OpenSpec. Он дает минимально необходимую структуру (init -> proposal -> apply) и отлично интегрируется с Claude Code. Если почувствуете, что этого мало — переходите к более сложным методологиям.

В: Можно ли использовать Spec-Driven Development в Cursor? О: Да. Большинство этих инструментов (OpenSpec, Spec Kit) — это просто CLI, которые создают Markdown-файлы. Вы можете добавить эти файлы в .cursorrules или просто упоминать их через @, чтобы Cursor всегда видел актуальный план.

В: Не тратится ли на написание спеков больше времени, чем на сам код? О: На начальном этапе — да. Но это инвестиция. Без спека вы потратите в 5 раз больше времени на отладку, когда AI решит переписать половину базы данных, потому что «забыл», как она работает.

В: Что делать, если клиент изменил требования в середине проекта? О: В этом прелесть Spec-Driven подхода. Вы сначала обновляете project.md или user_stories.md, просите AI перегенерировать tasks.md, и только потом он приступает к изменению кода. Это гарантирует, что документация и код всегда синхронизированы.

Конспект создан на основе видео «Spec-Driven Development for AI Coding Agents: OpenSpec, Spec Kit, BMAD and more» канала Povilas Korop. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=d3Glwdf_xA8