Старт проекта с AI

Новый проект кажется идеальным местом для агента: нет легаси, чистый лист, типовой стек. На практике всё наоборот — именно здесь размытый промпт «сделай приложение» превращается в сотни строк правдоподобного кода, который нужно полностью вычитать. Эта статья о том, как запускать greenfield-проект через спецификацию: Spec-Driven Development и GitHub Spec Kit, plan mode, настройку контекста агента с первого коммита и design-to-code через Figma MCP и v0.

Содержание

Старт проекта как отдельная задача
SDD на практике: Specify, Plan, Tasks, Implement
Spec Kit: constitution, spec, plan, tasks
Plan mode и human-in-the-loop
Bootstrap репозитория под агента
Design-to-code: Figma MCP и v0
Стек и версии: что делегировать агенту
Кейс: от конституции до первого PR
Ключевые тезисы для интервью
Заключение
Полезные ссылки

Старт проекта как отдельная задача

В существующем проекте агенту есть за что зацепиться: конвенции, соседние файлы, тесты, доменные правила в коде. Агент читает их инструментами и подстраивается. У нового проекта всего этого нет — и тогда он подставляет то, что видел в обучающих данных: своё представление о структуре, стеке, именовании и даже о поведении продукта.

Отсюда главный риск greenfield: объём неверных решений растёт пропорционально объёму сгенерированного кода. Пять файлов можно переписать; пятьдесят превращаются в проект, который вы не читали, но уже поддерживаете.

Prompt-first против spec-first

	Prompt-first	Spec-first
Что получает агент	Одно предложение о продукте	Спецификация, план, задачи, конституция
Поведение продукта	Додумывается агентом	Зафиксировано и проверяемо
Стек	Случайный «разумный»	Явно выбран и запинован
Стоимость правки	Перечитывание диффа по файлам	Правка текста до генерации
Ревью	«Разберись, что тут произошло»	Сверка кода с критериями приёмки

Важно: vibe coding не запрещён — он просто для другого. Прототип, proof of concept, разовая утилита, когда вы ещё не знаете, что нужно, — это законный сценарий быстрой генерации без спецификации. Но если проект будет жить, развиваться и передаваться людям, порядок обратный: сначала артефакты, потом код.

Почему это не «процесс ради процесса»

Три причины, по которым spec-first окупается именно на старте:

Артефакты дешевле кода. Убрать неверный пункт из плана — минута. Убрать неверную архитектуру — рефакторинг.
Артефакты становятся контекстом. Каждая следующая сессия агента стартует не с нуля: spec, plan и tasks читаются как постоянный контекст проекта (см. Контекст-инжиниринг агентов).
Артефакты — это документация. Требования, решения и структура живут в репозитории, а не в переписке.

SDD на практике: Specify, Plan, Tasks, Implement

Методология Spec-Driven Development (SDD) подробно разобрана в AI в рабочем процессе фронтендера: спецификация — единственный источник истины, LLM генерирует код и тесты, тесты служат критерием готовности. Здесь важна не теория, а то, как эти фазы разворачиваются при запуске нового проекта.

Specify  →  Plan  →  Tasks  →  Implement  →  Converge
(что/зачем) (как)   (шаги)    (код)          (сверка)

Граница «что» и «как»

Ключевая дисциплина SDD, которую чаще всего нарушают: спецификация описывает, что и зачем, и не трогает технологии. Стек, фреймворки, базы и архитектура — это следующий шаг. Если смешать их, спецификация теряет устойчивость: она становится заложником решения, которое может измениться.

Фаза	Отвечает на вопрос	Что попадает	Что не попадает
Specify	Что и зачем?	Поведение, user stories, критерии приёмки, границы	Стек, библиотеки, структура кода
Plan	Как?	Стек, архитектура, модели данных, контракты, зависимости	Новые требования, которых не было в spec
Tasks	В каком порядке?	Задачи по фазам с зависимостями, оценкой и параллельностью	Перепроектирование архитектуры

Критерии приёмки вместо пожеланий

Разница между «пожеланием» и спецификацией — в проверяемости. Плохая формулировка оставляет агенту свободу додумать; хорошая — задаёт наблюдаемое поведение.

Плохо:  Форма логина должна валидировать email и пароль.

Хорошо:
- email: обязателен, соответствует /^\S+@\S+\.\S+$/, иначе сообщение «Введите корректный email».
- пароль: минимум 8 символов, обязательно цифра и буква, иначе — текст ошибки под полем.
- submit заблокирован, пока форма невалидна (кнопка disabled).
- успешный вход → редирект на /dashboard, ошибка сети → инлайн-сообщение без перезагрузки.

Именно из таких пунктов агент генерирует тесты, а тесты — объективный признак готовности. Принцип, который стоит запомнить: качество спецификации = качество результата. Агент не улучшает неоднозначное требование — он его интерпретирует.

Тесты — внутри каждой пользовательской истории

В задачах SDD тесты не выносятся в отдельную фазу «потом», а генерируются внутри истории, к которой относятся. Так обратная связь приходит раньше, а упавший тест возвращается агенту с выводом ошибки — это и есть механизм самокоррекции, а не «похоже, работает».

Spec Kit: constitution, spec, plan, tasks

GitHub Spec Kit — open-source-тулкит, который превращает SDD в набор agent skills: вместо ручного «напиши мне спецификацию» вы вызываете команды, а агент последовательно создаёт артефакты. Инструмент кросс-агентный — по документации поддерживает десятки интеграций (Copilot, Claude, Codex, Cursor, Gemini и другие) и переключается между ними одной командой.

Что создаётся при инициализации

uv tool install specify-cli
specify init my-project --integration copilot

После этого в проекте появляются две вещи:

.specify/ — шаблоны артефактов, скрипты и memory/constitution.md;
папка под конкретного агента (например, .github/) с промптами и агентами, которыми вызываются команды.

Если проект не в git, init создаст репозиторий. Все артефакты — обычный Markdown: их можно править руками, читать в ревью и версионировать.

Четыре артефакта и их роли

Артефакт	Когда	Что содержит	Кто оценивает
`constitution.md`	Один раз на проект	Принципы, стандарты качества, opinionated-стек, запреты	Все последующие фазы
`spec.md`	На фичу	Что и зачем: поведение, истории, критерии приёмки	Человек, до плана
`plan.md`	На фичу	Как: стек, архитектура, модели, контракты	Подчинён конституции
`tasks.md`	На фичу	Задачи по фазам, упорядоченные по зависимостям	Реализуются по порядку

Конституция — не формальность. Это набор нерушимых принципов, против которых проверяется каждый следующий шаг: например, «TypeScript strict обязателен», «никаких новых зависимостей без RFC», «каждый публичный компонент проходит a11y-проверку». Для организации это способ зафиксировать opinionated-стек и требования безопасности до первой строки кода.

# Конституция проекта

## Стек
- TypeScript strict, React 19, Vite, Tailwind CSS.
- Данные — TanStack Query; локальный UI-state — React.

## Качество
- Тесты на каждую фичу: Vitest + Testing Library.
- Публичные компоненты проходят a11y-проверку.

## Запреты
- Не добавлять зависимости без явного одобрения.
- Не менять lockfile вручную.

Последовательность команд

Spec Kit поставляет два маршрута: короткий — для небольших фич, полный — с дополнительными quality-gate’ами.

/speckit-constitution   # один раз на проект
/speckit-specify        # что и зачем (без технологий)
/speckit-clarify        # снять неоднозначности вопросами
/speckit-plan           # как: стек, архитектура, контракты
/speckit-checklist      # проверить полноту спецификации
/speckit-tasks          # задачи по фазам, по зависимостям
/speckit-analyze        # согласованность spec ↔ plan ↔ tasks
/speckit-implement      # реализация по tasks.md
/speckit-converge       # сверка кода со спекой, добить пробелы

Короткий маршрут — это specify → plan → tasks → implement → converge. Каждый шаг создаёт Markdown, который «скармливается» следующему. /clarify, /checklist и /analyze — необязательные ворота для всего, где есть неоднозначность: /analyze делает read-only проверку согласованности между артефактами и показывает расхождения, пока их дёшево исправить.

/implement выполняет tasks.md в порядке зависимостей и перед стартом читает состояние чек-листов как gate — если пункты не отмечены, он спросит, прежде чем продолжать. tasks.md организован по фазам: Setup → Foundational (блокирующие предпосылки) → по одной фазе на пользовательскую историю → Polish.

Процесс расширяемый: Spec Kit поддерживает presets, extensions и workflows, а саму модель можно адаптировать или заменить — включая сценарии вне разработки. Для greenfield это означает, что стандартную последовательность можно подогнать под команду, не переписывая методологию.

Plan mode и human-in-the-loop

Plan mode переводит агента в режим исследования без изменений: он читает код, задаёт уточняющие вопросы и возвращает план, который вы правите; правки начинаются только после одобрения. Механика режима у разных инструментов — в статье Агентские инструменты разработки; здесь важна его роль именно на старте.

Почему планирование критично на старте

Чем раньше принято решение, тем больше кода оно на себя натянет. Архитектурная ошибка в первой неделе проекта стоит не один файл, а структуру всего приложения. Plan mode и артефакты SDD выносят решения в текст, где они ещё дешёвы.

План — это абзац, который можно переписать за минуту.
Сгенерированная структура — это дифф по десяткам файлов, который надо перечитать и откатить.

Контрольные точки, а не один большой заход

В SDD human-in-the-loop встроен в сам процесс: spec, plan и tasks — отдельные артефакты, каждый из которых вы просматриваете до следующего шага. Не стоит запускать /implement на весь проект сразу: реализации по фазам (Setup и Foundational сначала, потом истории по одной) дают точки, где ошибку ещё видно локально.

Артефакт	Что проверяет человек	Что оставляет агенту
`spec.md`	Требования и критерии приёмки	Формат и полноту изложения
`plan.md`	Стек, границы, зависимости, соответствие конституции	Детали реализации внутри границ
`tasks.md`	Порядок и размер задач, наличие тестов	Декомпозицию технически
Дифф	Архитектуру, безопасность, размер изменений	Boilerplate и рутину

Практическое правило: если вам нужно прочитать весь код, чтобы понять, что произошло, — планирование уже было недостаточным. План делает намерение явным заранее.

Bootstrap репозитория под агента

Контекст-инжиниринг начинается не с первой задачи, а с первого коммита. Если агент узнаёт правила проекта из диалога, они теряются между сессиями; если из репозитория — работают всегда. Устройство rules-файлов, skills и hooks подробно разобрано в Контекст-инжиниринге агентов, поэтому ниже — короткий чек-лист именно для старта.

Артефакт	Зачем	Где
`AGENTS.md` (или `CLAUDE.md`)	Постоянные инструкции: стек, команды, соглашения, запреты	Корень репозитория
`constitution.md`	Нерушимые принципы и opinionated-стек	`.specify/memory/`
CI	`lint` + `typecheck` + `test` как объективный критерий	`.github/workflows/`
Hooks	Авто-формат после правок, блокировка опасных команд	Конфиг агента
Команды проекта	`dev`/`test`/`lint`/`build`, чтобы агент сам себя проверял	`package.json`

Пример минимального AGENTS.md:

# AGENTS.md

## Команды
- dev:  `pnpm dev`
- test: `pnpm test`
- lint: `pnpm lint && pnpm typecheck`

## Соглашения
- Компоненты — в `src/components`, фичи — в `src/features/<name>`.
- Каждая фича идёт с тестами (Vitest + Testing Library).

## Запреты
- Не менять `pnpm-lock.yaml` вручную.
- Не добавлять зависимости без одобрения (см. constitution).

Два принципа, которые отличают работающий файл от декоративного:

Короткий файл — лучше. Цель порядка 100–200 строк: длинные правила «растворяются», и агент перестаёт учитывать их целиком. AGENTS.md — карта проекта, а не энциклопедия.
Правило, которое агент регулярно нарушает, повышается из прозы в механику — линтер, структурный тест или хук, а не абзац, который он снова забудет.

Хуки на старте дают детерминированную защиту: PostToolUse на изменённые файлы форматирует их, PreToolUse на Bash блокирует опасные команды. Это то, чего не может дать ни одна инструкция в тексте.

Design-to-code: Figma MCP и v0

Макет — главный источник требований для фронтендера, и его тоже можно отдавать агенту. Есть два принципиально разных входа: Figma MCP приносит дизайн-контекст прямо в вашего агента, v0 принимает ссылку на макет и собирает приложение как единый поток. Про протокол MCP в целом — отдельная статья MCP: Model Context Protocol; здесь — практика запуска.

Figma MCP: контекст вместо скриншота

Основной инструмент — get_design_context: по ссылке на фрейм он возвращает не картинку, а структурированное дерево слоёв, переменные, стили и подсказки по коду (по умолчанию — React + Tailwind). Возвращённый код — это референс, а не финальный код: его нужно адаптировать под язык, фреймворк и токены проекта, а не вставлять дословно.

Ключ к качеству — Code Connect, маппинг компонентов Figma на реальные компоненты репозитория. Когда он настроен, сервер подставляет в контекст настоящие импорты, prop-маппинги и примеры использования: агент переиспользует вашу Button, а не генерирует новую. Без Code Connect всё сводится к «угадай компонент по картинке».

Обратный поток — code to canvas (generate_figma_design): агент поднимает локальный сервер, открывает вашу страницу и переносит отрендеренный интерфейс в Figma как редактируемые слои. Так замыкается петля «код → канвас для обсуждения → снова код».

v0: из ссылки в приложение

v0 принимает ссылку на Figma-файл или фрейм и читает из него страницы, фреймы, переменные и токены, auto layout, текст и ассеты — без плагина и desktop-приложения. Для больших файлов в промпте называют конкретную страницу или фрейм, а для точного экрана дают ссылку на выделение.

Практика от самой Vercel — итеративный подход: сначала отдельные компоненты (навбар, сайдбар, форма), проверка и уточнение каждого, и только потом сборка в целые экраны. По умолчанию v0 использует дизайн-систему shadcn/ui, но подстраивается под кастомный Tailwind-конфиг и публичные npm-пакеты.

Где design-to-code ломается

Порядок в дизайн-системе. Токены вместо сырых значений, семантические имена слоёв (CardContainer, а не Group 5), auto layout и компоненты вместо прямоугольников — без этого агент угадывает.
Размер фрейма. Компонент на фрейм работает заметно лучше, чем «весь лендинг в одном фрейме»: чем больше поверхность, тем больше ошибок в размерах и отступах.
Вывод — черновик. И Figma MCP, и v0 дают качественный старт, но не заменяют дисциплину дизайн-системы — они её умножают.

Инструмент	Что даёт	Когда брать
Figma MCP	Дизайн-контекст и реальные компоненты в вашем агенте	Работаете в своём инструменте и репозитории
v0	Быстрый прототип приложения из ссылки на Figma	Нужен каркас/лендинг целиком, стек близок к React + Tailwind

Стек и версии: что делегировать агенту

На старте нужно принять много технических решений сразу, и соблазн отдать их агенту велик. Но надёжность агента неравномерна: он силён там, где задача паттерновая и изолированная, и ненадёжен там, где нужен контекст проекта или свежие знания.

Решение	Агенту?	Почему
Скаффолдинг, boilerplate, CRUD, конфиги	Да	Устоявшиеся паттерны, ничего доменного
Настройка типового стека (Vite + React + TS + Tailwind)	Да	Тысячи примеров в обучающих данных
Генерация тестов из спецификации	Да	Поведение уже зафиксировано в spec
Выбор архитектуры и границ модулей	Нет	Трейдоффы зависят от контекста проекта
Конкретные версии библиотек	С осторожностью	Модель может взять устаревший или несуществующий API
Ограничения безопасности и доменные правила	Нет	Их негде взять, кроме конституции

Практическое следствие: версии и зависимости фиксируют явно. В плане и конституции указывают точный стек и версии, а спорные библиотеки вносят в approved-список, чтобы агент не выбирал сам. plan.md — правильное место для этих решений, потому что он подчинён конституции и проходит ревью до генерации.

Кейс: от конституции до первого PR

Стартуем дашборд с тикетами и фильтрами.

Инициализация. specify init выбирает интеграцию под вашего агента, создаёт .specify/ и репозиторий.
Конституция. /speckit-constitution: TypeScript strict, Vitest, доступность, запрет зависимостей без одобрения, фиксированный стек.
Спецификация. /speckit-specify: что и зачем для MVP — список тикетов, фильтры, пагинация; критерии приёмки без единого слова о технологиях.
Уточнение и план. /speckit-clarify снимает неоднозначности, /speckit-plan выбирает Vite + React + TS, TanStack Query, REST и описывает контракты.
Задачи. /speckit-tasks разбивает работу по фазам, /speckit-analyze проверяет согласованность spec ↔ plan ↔ tasks.
Bootstrap. Короткий AGENTS.md, CI (lint, typecheck, test), хук на авто-формат — первым коммитом, до генерации фичи.
Дизайн. get_design_context для макета дашборда; через Code Connect агент переиспользует существующие таблицу и кнопки, а не рисует новые.
Реализация. /speckit-implement в объёме Setup + Foundational + первой истории; /speckit-converge находит пробелы и дописывает задачи, пока не покажет Converged.
PR. Вы сверяете дифф с критериями приёмки, зелёные тесты идут в ревью. Следующие истории — тем же циклом.

Ключевой момент кейса — шаг 8 сужается сознательно: реализация по фазам оставляет ошибки локальными, а сверка converge не даёт истории «тихо» остаться недоделанной.

Ключевые тезисы для интервью

Greenfield не даёт агенту ни конвенций, ни тестов, ни доменных правил: без спецификации он придумывает поведение, стек и структуру, а риск растёт вместе с объёмом диффа.
В SDD spec описывает что и зачем, plan — как (стек, архитектура, контракты), tasks — упорядоченные по зависимостям шаги, а тесты внутри историй служат definition of done.
Spec Kit превращает SDD в agent skills: конституция — один раз, затем specify → plan → tasks → implement → converge; артефакты — plain Markdown в git, а инструмент кросс-агентный.
constitution.md фиксирует нерушимые принципы и opinionated-стек и служит фильтром для каждого последующего плана.
Plan mode и артефакты SDD — контрольные точки: правка плана стоит минуту, правка сгенерированной архитектуры — рефакторинг.
Контекст агента настраивается первым коммитом: короткий AGENTS.md, команды, CI и хуки; повторяющиеся нарушения поднимаются из текста в механические проверки.
Design-to-code (Figma MCP, v0) работает настолько хорошо, насколько дисциплинирована дизайн-система: токены и Code Connect, компонент на фрейм, а вывод — референс, а не финальный код.
Качество спецификации = качество результата: агенту надёжно делегируется boilerplate и типовой стек, а архитектура, версии и ограничения безопасности остаются за человеком.

Заключение

Старт проекта — это не «попросить агента сделать приложение», а сначала зафиксировать замысел в артефактах, а потом генерировать код против них.

Пишите спецификацию до кода. constitution → specify → plan → tasks переносят необратимые решения в дешёвый текст.
Используйте структуру, а не ручные промпты. Spec Kit даёт проверенную последовательность и качественные ворота между фазами.
Делайте ревью частью процесса. Plan mode и артефакты — точки контроля, где ошибка ещё локальна.
Настраивайте контекст агента сразу. AGENTS.md, CI и хуки с первого коммита работают лучше любых инструкций в диалоге.
Помните про design-to-code. Figma MCP и v0 ускоряют старт, если дизайн-система в порядке.

Попробуйте начать следующий проект с конституции и одной спецификации — и сравните объём правок после первой сгенерированной фичи с обычным промптом.