Вайбкодинг против спека: наши принципы разработки с AI

Искусственный интеллект пишет код быстрее, чем человек успевает его читать. Это и главная возможность последних лет, и главный риск. Когда написание кода стало почти бесплатным, единственное, что осталось по-настоящему дорогим — понимание того, что в этом коде происходит. Разбираем, почему «просто вайбкодить» плохо, и показываем принцип, по которому работаем сами.

Что такое вайбкодинг

Термин предложил Андрей Карпаты ещё в начале 2025 года: «полностью отдаёшься вайбу и забываешь, что код вообще существует». На практике это выглядит так: вы описываете нейросети, что хотите, она пишет код, вы соглашаетесь со всеми правками, запускаете — и описываете следующую хотелку. Код при этом вы не читаете. Никогда.

Для прототипа, демо или внутренней поделки — отлично, так и надо. Беда начинается, когда вайбкодинг становится способом разработки продукта, за который кто-то платит и которым кто-то пользуется каждый день.

Демо за минуту. Задуманное — никогда

Дайте модели широкий промт в одну строку — и через минуту на экране работающее демо. Это и есть главная ловушка: кажется, что задача решена.

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

Команда BrainGrid в июле 2026 года разобрала экономику этого эффекта: размытый промт — это не «мало деталей», а отсутствие границ. Каждый незакрытый вопрос — это решение, которое агент принимает молча, и эти решения накапливаются по экспоненте. Их формула: «Ограниченный промт строится и проверяется один раз. Размытый перезапускается снова и снова, пока вы случайно не специфицируете его сами». Настоящая цена вайбкодинга — не токены, а тройной налог: повторное выведение контекста каждой сессией, проверка результата (по данным Business Insider, разработчики тратят на ревью AI-кода на 20% больше времени, чем экономят) и переделки, потому что «готово» никто не определил. Генерация дешёвая. Дорогая — понимание, проверка и исправление того, что нагенерировано.

Forbes Tech Council формулирует итог одной строкой: «AI радикально ускорил создание ПО — но не отменил его сложность». Демо стало мгновенным. Задуманное — нет.

Чем это плохо: риски вайбкодинга

1. Иллюзия готовности. Код «работает» — значит «готово»? Нет. Нейросети по умолчанию пишут happy path: всё хорошо, входные данные корректны, сеть доступна, пользователь один. Граничные случаи, обработка ошибок, одновременные запросы, пустые списки — всё это остаётся за бортом и всплывает в проде в самый неподходящий момент.

2. Архитектуру решают за вас. Код-агент не просто пишет код — он по умолчанию генерирует архитектуру: выбирает фреймворк, базу данных, схему аутентификации, способ деплоя. Исследователи называют это «вайб-архитектурой» (vibe architecting) — архитектурой, продиктованной промтами, а не осознанным проектированием. В работе «Architecture Without Architects» одна и та же задача, сформулированная по-разному, дала структурно разные системы: от 141 строки кода и двух файлов до 827 строк и шести файлов — единственным различием был текст промта. Такие решения принимаются за секунды, приходят единым пакетом и не оставляют записи: ни ADR, ни дизайн-документа, ни обоснования. У модели нет контекста организации, представления о рисках и ответственности за последствия — а значит, она не может ответственно принимать решения, которые переживают любой отдельный спринт. Команда vFunction формулирует ещё жёстче: «Агенты отлично строят код, который работает, но они не умеют строить системы, которые живут». Поэтому архитектуру проекта, принимаемые на старте решения и вопросы вокруг них нельзя отдавать модели в духе «пусть сама решит» — она примет их неверно.

Это не мнение, а уже измеренный факт. В статье «Why LLMs will be always Terrible at Software Architecture» (Devforth, май 2026) собраны свежие бенчмарки. Апрельский тест генерации архитектуры из требований: модели хорошо находят «коробки» — компоненты (Node F1 у GPT-5 равен 0,67), но почти не умеют строить связи между ними (Edge F1 — 0,15; у Claude Sonnet 4.6 — 0,09). «Диаграмма с правдоподобными сервисами и неверными связями — это не хорошая архитектура, это просто убедительная картинка». Там же: генерация обоснований решений — F1 около 0,35, то есть модель толком не может объяснить, почему решение именно такое; агенты генерации архитектурных представлений дают до 90% ошибок согласованности и ноль точности по человеческой оценке. Причина фундаментальная: код — локален, архитектура — глобальна. LLM отлично работают на коротких, хорошо специфицированных задачах с быстрой проверкой. Архитектура — это долгосрочное планирование в условиях неполной информации: обратная связь запаздывает, состояние видно частично, а цена ранних ошибок накапливается годами.

3. Поддерживать некому. Ни разработчик, ни модель не понимают, как устроена система в целом. Любой баг превращается в расследование, любое изменение — в лотерею «что ещё сломается». Новый человек в команде включается месяцами, потому что документации нет, а код никто не читал.

4. Безопасность. Модель может оставить в коде захардкоженный ключ, небезопасный паттерн, непроверенные пользовательские данные в запросе. Эти строки никто не увидит на ревью — потому что ревью не было. В сочетании с тем, что вайбкодер не понимает кода, который запускает, это прямой путь к утечке.

5. Технический долг со скоростью AI. LLM любят генерировать абстракции «на всякий случай», дублировать уже существующую в проекте логику, создавать функции, которые вызываются ровно один раз. Кодинг-агент без правил и контроля раздувает кодовую базу быстрее, чем классический разработчик, а смысла в ней со временем всё меньше.

6. Недетерминизм результата. Один и тот же промт сегодня и завтра даёт разный код. Результат невозможно воспроизвести, невозможно объяснить заказчику и невозможно протестировать: сегодня всё было хорошо, после «небольшой правки от модели» всё перестало работать — и никто не знает, что именно изменилось.

7. Неконтролируемые зависимости. Модель «заботливо» добавляет библиотеки, о которых вы ничего не знаете: какая лицензия, жив ли проект, есть ли известные уязвимости. Каждая такая библиотека — это чужое архитектурное решение, за которое никто не спрашивал вашего согласия. Правило отсюда жёсткое: каждая новая библиотека и каждая новая зависимость должны быть одобрены человеком — а не «модель добавила, ну ладно».

8. Потерянные требования. Договорённости о том, что и зачем делаем, живут только в истории чата. Через две недели никто не вспомнит, почему принято именно такое решение. А модель на новом витке «развития» придумает всё заново — по-своему.

Наш принцип

Мы в Лаборатории Павла Жукова формулируем так: модель пишет, спек решает, человек понимает. Из этого вырастают пять правил:

1. AI — исполнитель, а не архитектор. Архитектурное решение первично — это фундамент, на котором держится весь последующий код, и самая дорогая вещь для переделки. Архитектуру проекта, выбор подхода и решения на старте принимает человек. Модель может предлагать варианты и раскладывать их по полочкам — но решать должна не она. У модели нет контекста вашего проекта, его целей и принципов, и «просто пусть сама решит» заканчивается неверными решениями, последствия которых придётся расхлёбывать годами.
2. Спек раньше кода. До первой строчки реализации существует документ: что делаем, зачем, как, и как именно проверим результат.
3. Спек должен быть детерминированным на 100%. Ключевое требование: если у формулировки в спеке есть две разумные интерпретации, ведущие к разному коду, — это развилка, которую закрывает человек ещё до реализации. Детерминированный спек отключает «фантазии» модели. Модель великолепна в том, что умеет, насмотревшись на миллиарды строк кода, — но она плохо знает контекст, цели и принципы именно вашего проекта. Каждое неуточнённое место в спеке — это место, где модель начнёт додумывать «как у всех». Цель — спек, по которому любая модель, от MinimaxM3 до Fable 5, выдаст примерно одинаковый результат.
4. Код должен быть понят и осознан. После реализации разработчик сверяет её со спеком и осознанно читает полученный код — и тем самым возвращает себе то, что отнимает вайбкодинг: понимание собственного продукта.
5. Документация — часть цикла, а не «потом». Спек описывает, что мы хотели. Документация — что получилось по факту. Оба артефакта обновляются в том же цикле, что и код, иначе следующая итерация начинается вслепую.

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

Пайплайн: восемь шагов от задачи до коммита

Работаем в OpenSpec — фреймворке spec-driven разработки для AI-ассистентов — плюс набор открытых скиллов, которые мы выложили на GitHub: zeus/devdoc. Типичная задача проходит такой путь:

Шаг 1. /opsx-propose — ставим задачу и оцениваем подход

Описываем задачу — и OpenSpec создаёт изменение в openspec/changes/<имя>/ с четырьмя артефактами:

• proposal.md — что и зачем делаем;
• design.md — технические решения;
• specs/ — требования в формате сценариев «когда → тогда»;
• tasks.md — чек-лист шагов реализации.

Уже на этом этапе видно, насколько подход вообще верный, — и решает это человек, а не модель. Модель предлагает варианты, человек оценивает: туда ли мы идём в принципе. Отбросить неудачный подход на уровне предложений стоит минут. Переделывать его в готовом коде — дни работы и испорченный моральный дух команды.

Шаг 2. /openspec-ambiguity-review — делаем спек детерминированным

Ключевой шаг нашего пайплайна. Спек, написанный на скорую руку, понятен человеку с контекстом, но модели он оставляет пространство для интерпретаций. Скилл проходит по всем артефактам с чек-листом из двенадцати категорий неясностей:

• размытые определители: «быстрый», «удобный», «оптимальный», «при необходимости»;
• требования без проверяемого критерия приёмки;
• неявные технические решения («добавить кеширование» — какое? где? чем?);
• открытые варианты и TBD («можно использовать X или Y» — так что в итоге?);
• контракты данных без типов, обязательности и правил валидации;
• неуказанные граничные случаи: пустые данные, ошибки, повторные вызовы;
• размытые границы скоупа — что явно НЕ делаем;
• противоречия и терминологический дрейф между артефактами;
• и другие.

Каждая находка — это конкретный вопрос человеку с вариантами интерпретаций, а не «выберу разумный вариант по умолчанию». Решение принимает человек, и оно записывается обратно в артефакты. Сканирование повторяется, пока не останется ни одной формулировки с двумя толкованиями.

Итог шага: 100% детерминированный спек, по которому любая модель от MinimaxM3 до Fable 5 выдаст примерно похожий результат. Именно здесь отключаются «фантазии» модели: каждое неуточнённое место в спеке — это место, где модель додумала бы по-своему, опираясь на усреднённый опыт из миллиардов строк чужого кода, а не на контекст, цели и принципы вашего проекта. Чем больше развилок закрыто сейчас, тем меньше угадывания в реализации.

Шаг 3. /opsx-apply — реализация

Модель выполняет задачи из tasks.md по одной, опираясь на спек и код проекта. Пространства для самодеятельности уже не осталось, поэтому можно взять не самую дорогую модель, а подходящую по скорости и цене. Это осознанный инженерный расчёт, а не экономия на спичках.

Шаг 4. /opsx-verify — скилл проверяет, человек осознаёт

/opsx-verify — отдельный скилл, который делает проверку: проходит по артефактам изменения и сверяет реализацию со спеком — всё ли из спека на месте, нет ли лишнего вне скоупа, работают ли сценарии.

Это быстро — именно потому, что спек всё определил заранее. Не нужно гадать, хорош ли код: есть чек-лист и по нему сверяем. Верификация отвечает на вопрос «соответствует ли реализация тому, что договорились».

Но отдельно от верификации — понимание кода человеком и осознание того, что сделано. Это разные вещи. Скилл подтвердит соответствие спеку, но не заменит понимания: разработчик должен прочитать дифф и осознавать принятые решения — что, как и почему легло в код. Спек делает такое чтение дешёвым, потому что перед глазами готовый замысел, а не загадка. Но заменить осознание не может ничто. Именно понимание собственного продукта — то, что отнимает вайбкодинг и что возвращает этот шаг: после него вы можете объяснить каждую строчку, а не «ну вроде работает, погнали дальше».

Шаг 5. /rules-check — проверяем правила и типичные ошибки LLM

Скилл сверяет несохранённые изменения с правилами окружения (глобальные правила, AGENTS.md проекта) и дополнительно ловит типичные ошибки, которые оставляют за собой модели:

• Оверинжиниринг — «можно ли то же самое написать короче и понятнее»: лишние абстракции, обёртки без ценности, конфигурация ради конфигурации, защитный код от невозможных ситуаций;
• Функции-сироты — мелкие функции, вызываемые один раз; для каждой скилл отвечает на вопрос «зачем её выделили» и выносит вердикт: инлайнить или оставить;
• Отсутствующее «зачем» — модули и функции без описания назначения. Это первое, что забывают LLM, и первое, что делает код неподдерживаемым.

Основные правила, которые мы рекомендуем зафиксировать в любом проекте, — ниже.

Шаг 6. /opsx-archive — спеки в историю проекта

Изменение архивируется, а его дельта-спеки сливаются с основными спеками проекта. Спек не растворяется в чате после реализации — он живёт вместе с кодом и накапливается как история принятых решений. Через год вы открываете архив и видите не «магию», а логику каждой фичи.

Шаг 7. /devdocs-sync — документация AS IS

Обновляем README и docs/ инкрементально: только те разделы, которые затронуло изменение. Документация описывает систему AS IS — как есть сейчас, а не планы на будущее. Если документации в проекте ещё нет вовсе, сначала выполняется /devdocs-bootstrap и собирает её с нуля.

Зачем это нужно, помимо очевидного «чтобы люди понимали проект»? Документация — это контекст, который вы кормите следующему AI-агенту. Контекстное окно у любой модели ограничено: без документации агент начинает с того, что сканирует всю кодовую базу — медленно, дорого и с закономерным результатом «я не вижу всей картины». С документацией агент заходит в проект готовым: архитектура, назначение модулей, откуда растут ключевые решения и почему они именно такие — всё уже записано. Обратите внимание на акцент: документировать нужно «зачем», а не только «что» — код агент прочитает сам, а вот намерения, ограничения и отвергнутые варианты из кода не вытащить. Поэтому документация AS IS обновляется в одном цикле с кодом: устаревший контекст хуже его отсутствия — он уверенно ведёт агента не туда.

Шаг 8. Коммит

Атомарный коммит в репозиторий: одна логическая задача — один коммит, conventional-сообщение (feat:, fix:, refactor:, docs:, chore:). Всё, что попало в коммит, прошло спек, верификацию, правила и документацию.

Правила, которые мы рекомендуем зафиксировать в каждом проекте

Чек-лист /rules-check не возник из воздуха — это правила, которые мы написали для себя и соблюдаем во всех проектах. Минимальный набор, который стоит завести любому, кто пишет код с AI:

1. Документируйте «зачем». Каждый модуль начинается с комментария о его назначении и роли в проекте. Каждая функция — с докстринга о том, зачем она нужна. Функции длиннее тридцати строк — дополнительно краткое описание хода работы. Это самый недооценённый барьер против расползания кода.
2. Никаких секретов в коде. Ключи, пароли, токены — только через переменные окружения. Проверьте, что .env, *.key и credentials.json в .gitignore.
3. Каждая новая библиотека и каждая зависимость одобряются человеком. Без исключений. Модель обожает тащить в проект новые пакеты — а вместе с ними чужие архитектурные решения, неизвестные лицензии и будущие проблемы с обновлением. Порядок простой: сначала проверяем, нельзя ли решить задачу тем, что уже есть в проекте или в разрешённых библиотеках; если нельзя — человек явно одобряет новую зависимость до того, как она попадёт в код.
4. Типы и структурированные данные. Публичный API — с type hints, структурированные данные — в dataclasses/TypedDict, а не в безликих словарях. Так и человеку, и следующей модели понятно, что там лежит.
5. Следуйте конвенциям проекта. Перед изменением кода — посмотрите, как написан код рядом: те же библиотеки, тот же стиль, те же паттерны. Не смешивайте подходы на одной странице и в одном модуле.
6. Тесты для критичной бизнес-логики — модели, сериализаторы, ключевые API. Тесты независимые и воспроизводимые.
7. Линтер и форматтер перед коммитом — ruff, prettier, что угодно по стеку. Форматирование — не тема для обсуждения на ревью.
8. Мёртвый код удаляется сразу: неиспользуемые импорты, функции, параметры конфигурации. «Потом разберёмся» не наступит никогда.
9. Git-гигиена. Атомарные conventional-коммиты, никакого force push, никаких прямых пушей в мастер.

Секрет в том, что эти правила написаны в формате, понятном модели, — в AGENTS.md или глобальном файле правил. Тогда они превращаются из памятки для людей в автоматический фильтр на стороне AI-агента.

Что даёт такой подход

• Воспроизводимость. Результат не зависит от модели и от дня недели — его определяет спек.
• Быстрая верификация. Минуты сверки с готовым чек-листом вместо перечитывания всей кодовой базы.
• Понимание кода. Человек возвращается в точку контроля: это главное отличие инженерного процесса от лотереи.
• Живая документация. Спеки — что хотели, AS IS документация — что получилось. Оба источника актуальны всегда и служат готовым контекстом для следующего AI-агента вместо чтения всей кодовой базы.
• Дешёвый онбординг. Новый сотрудник или новый агент заходит в проект по спекам и README, а не по археологии в git-истории.

Вместо заключения

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

Наш принцип в одной строке: модель пишет, спек решает, человек понимает. Все наши скиллы — devdocs-bootstrap, devdocs-sync, devdocs-enhance, openspec-ambiguity-review, rules-check — открыты и лежат на GitHub: zeus/devdoc. OpenSpec, на котором построен пайплайн, — Fission-AI/OpenSpec. Берите, адаптируйте под свой стек, спорьте с нами. Главное — не вайбкодите свой продукт.