С возрастанием возможностей AI-агентов для программирования заметна устойчивая тенденция: вы описываете цель, получаете фрагмент кода — он может выглядеть правдоподобно, но часто не работает. Этот подход, похожий на “vibe-coding”, годится для быстрых прототипов, но малоэффективен для серьёзных задач или работы с существующим кодом: код может не компилироваться, не до конца соответствовать логике, или архитектура окажется далека от предпочтительной.
Проблема не в способности AI-кодера, а в нашем подходе. Мы используем код-агентов как поисковик, хотя они работают лучше как точные парные программисты: запоминают паттерны, но требуют чётких указаний. Поэтому стоит пересмотреть, как работать со спецификацией — не как разовой документ, а как активный и живой артефакт, который развивается вместе с проектом. Спецификация становится источником правды: один из её принципов — возвращаться к ней в случае сомнений, адаптировать при росте проекта и делить на задачи по мере надобности.
Spec Kit — новый открытый набор инструментов для разработки по спецификации с AI. Он интегрируется с GitHub Copilot, Claude Code и Gemini CLI и предлагает структурированный процесс работы:
Что такое spec-driven разработка?
Спецификация становится основой разработки. Это не просто документация — это контракт, определяющий, как должен вести себя код, и служит основой для AI, описаний, тестов и задач. Такой подход уменьшает догадки, сокращает количество ошибок и повышает качество.
Как работает процесс с Spec Kit?
- Specify — задаёте, что хотите сделать и зачем (user stories, ожидаемое поведение), AI создаёт подробную спецификацию. Это не о стеке — это о целях и взаимодействиях.
- Plan — описываете архитектуру, ограничения и технологии, AI генерирует технический план с возможностью нескольких вариантов.
- Tasks — AI разбивает архитектурный план на конкретные шаги, доступные для реализации и тестирования по отдельности.
- Implement — AI последовательно реализует задачи, а вы проверяете результат на каждом шаге: соответствует ли спецификации, покрывает ли требования, подходят ли архитектурные решения.
Почему такой подход работает
LLM отлично распознают шаблоны, но плохо угадывают намерение. Неаккуратный запрос вроде “добавь фото” ведёт к большому количеству предположений, часть из которых неверна. Ясная спецификация, технический план и список задач дают агенту чёткое представление о том, что и как нужно строить. А ещё — гарантированность учёта требований по безопасности, требованиям, интеграции и дизайну, если всё задокументировано в спецификации.
Где это особенно эффективно
- Новые проекты — минимизирует риск получить не то, что нужно.
- Фичи в существующие проекты — гарантирует, что новое впишется в архитектуру, а не будет на неё нашито.
- Перепроектирование legacy-систем — помогает сохранить бизнес-логику и построить обновлённую архитектуру с нуля.
Взгляд вперёд
Мы переходим от парадигмы «код — источник истины» к «намерение — источник истины». Спецификация становится активным исполнителем: меняешь спецификацию — код меняется вместе с ней.
Spec Kit — экспериментальный инструмент, но он отражает более масштабное изменение в том, как мы работаем с AI. Ключевой результат — не просто код, а качественная, управляемая разработка, где AI становится надёжным помощником, а не источником хаоса.
🔧 Как использовать Spec Kit в работе с AI-агентами
Spec Kit работает с кодовыми агентами, такими как GitHub Copilot, Claude Code и Gemini CLI. Ключевая идея — управлять агентом через последовательность простых команд, а он в ответ формирует необходимые артефакты (спецификацию, техплан, задачи).
📦 Установка и запуск
Установка простая. Сначала устанавливается CLI-инструмент specify, который инициализирует проект и создаёт нужную структуру:
uvx --from git+https://github.com/github/spec-kit.git specify init <ИМЯ_ПРОЕКТА>
После инициализации:
- Используйте команду /specify, чтобы дать общее описание проекта (что и зачем). Агент создаёт полную спецификацию.
- Затем используйте /plan — агент формирует технический план на основе введённых ограничений и архитектурных предпочтений.
- Командой /tasks агент разбивает спецификацию и план на конкретные задачи, которые можно реализовывать.
Такой подход превращает расплывчатые подсказки в понятные намерения, с которыми агент может работать последовательно и предсказуемо.
🤔 Почему это работает лучше обычных подсказок
Большинство генеративных моделей отлично завершают шаблоны, но не читают мысли. Когда вы просто просите «добавить обмен фотографиями в приложение», агенту приходится угадывать сотни скрытых требований. Некоторые из них он определит правильно, но ошибки часто проявляются уже в процессе реализации.
Когда же вы изначально формулируете спецификацию, дополняете её планом и списком задач, агент получает чёткую структуру: что делать, как, в каком порядке — и вы получаете более качественный результат.
Это работает вне зависимости от технологии — будь то Python, JavaScript или Go. Главное — чётко зафиксировать намерение и перевести его в структуру, с которой агент умеет работать.
🛡 Как решаются более сложные задачи
В крупных командах возникает другой вопрос — куда девать требования по безопасности, соответствию, дизайну, интеграциям? Обычно они разрозненны: кто-то держит их в голове, кто-то — в вики, кто-то — в Slack.
С Spec Kit всё это помещается в спецификацию и план. ИИ использует эти данные с первого этапа. Требования по безопасности не добавляются потом — они учитываются сразу. Дизайн-система — не надстройка, а часть архитектурного плана.
И главное — процесс итеративный. В отличие от классического подхода, где после начального выбора архитектуры сложно что-либо изменить, здесь можно обновить спецификацию, пересоздать план и дать агенту новую задачу.
🧩 Три сценария, где метод особенно полезен
- Новые проекты (Greenfield) — помогает сразу задать нужное направление, а не получать «генерик»-решения по шаблону.
- Новые функции в текущем коде — позволяет встроить новое в существующую архитектуру так, чтобы оно «чувствовалось нативно», а не как заплатка.
- Модернизация легаси — фиксирует бизнес-логику в новой спецификации, строит свежую архитектуру и позволяет агенту восстановить систему «с нуля», без техдолга.
Ключевая ценность — отделить устойчивое «что» от гибкого «как». Это упрощает эксперименты, облегчает масштабирование и снижает затраты на переработки.
🚀 Куда всё движется
Мы уходим от принципа «код — источник истины» к формуле «намерение — источник истины». Спецификация теперь не просто текст — она исполняется ИИ, и именно она определяет, что будет построено.
Это не возврат к документации ради документации. Это шаг к тому, чтобы сделать спецификацию живым рабочим элементом процесса.
Spec Kit — это эксперимент, но он демонстрирует, как может выглядеть новая культура разработки, в которой спецификация становится управляющим центром.