Вайб-кодинг. Практический курс

Содержание

Введение. Похмелье после вечеринки

ЧАСТЬ 1. ИНСТРУМЕНТЫ НОВОЙ ЭРЫ

Глава 1. Cursor: первая фича через управляемую генерацию

Глава 2. Devin Desktop (бывший Windsurf): глубокий контекст и ИИ-археология

Глава 3. Claude Code: безопасный терминальный агент

Глава 4. Спецификация как код: от желания к контракту

ЧАСТЬ 2. МЕТОДОЛОГИЯ ВАЙБ-КОДИНГА 2.0

Глава 5. Контекстная инженерия: строим среду, а не промпт

Глава 6. Plan Mode: как читать и править планы ИИ

Глава 7. MCP: подключаем ИИ к реальности

ЧАСТЬ 3. КРИЗИС ДОВЕРИЯ

Глава 8. Security Lab: почему ИИ пишет дырявый код

Глава 9. AI Code Review: аудит чёрного ящика

Глава 10. Техническая инфляция: учим ИИ удалять код

ЧАСТЬ 4. БУДУЩЕЕ ПРОФЕССИИ

Глава 11. От джуниора к архитектору: дирижируем флотом агентов

Глава 12. Командный стандарт: дисциплина, которая работает без вас

Заключение. Похмелье прошло. Начинается ремесло.

Мы научились генерировать, но разучились понимать

Февраль 2025-го был временем почти детской эйфории. Мы все чувствовали себя волшебниками. Термин «вайб-кодинг», который Andrej Karpathy (Андрей Карпати) бросил в одном твите, за пару месяцев превратился из шутки в религию индустрии. Мы описывали желание словами, жали «Generate» в Cursor или тогдашнем Windsurf (с июня 2026-го — Devin Desktop) — и получали рабочее приложение. Прототип за обеденный перерыв. Стартап за выходные. Казалось, что синтаксис скоро станет таким же архаизмом, как перфокарты.

Это была грандиозная вечеринка. Но к началу 2026-го эйфория сменилась инженерным похмельем. Публичные опросы разработчиков показывают: ИИ-инструменты стали массовой частью рабочего процесса, но доверие к их точности остаётся ограниченным. Например, Stack Overflow Developer Survey 2025 фиксирует, что 46% разработчиков скорее не доверяют точности AI tools, 33% доверяют, а полностью доверяют только около 3%. Узкое место всё чаще переезжает из написания кода в его чтение, ревью, проверку безопасности и сопровождение. Мы научились очень быстро бежать — и всё чаще вынуждены останавливаться, чтобы понять, куда именно бежим и какой груз несём за спиной.

Похмелье у всех одинаковое. Симптомы такие:

• код генерируется быстрее, чем его кто-либо успевает прочитать;

• пул-реквесты пухнут до тысяч строк, которые невозможно осмысленно проверить;

• люди принимают код, который не понимают, нажимая не «Merge», а «верю на слово»;

• тесты проверяют не бизнес-правила, а то, что ИИ сам решил проверить;

• архитектура тихо расползается — пока в три часа ночи что-то не падает в продакшене из-за пограничного случая, который никто не продумал.

Проблема не в том, что ИИ пишет плохой код. Проблема в том, что он может писать слишком много кода быстрее, чем команда успевает его понять. Раньше технический долг копился месяцами из-за лени и сроков. Теперь он может появиться за один сеанс генерации — и стоимость чтения, отладки и поддержки никуда не делась. Она просто стала заметнее.

Договор с читателем

Эта книга не будет сборником магических промптов и не будет обзором модных IDE, который устареет через полгода. Обзоры инструментов гниют быстрее, чем выходят из печати. Эта книга — практический курс по управлению ИИ-разработкой. Курс, после которого вы не «знаете про ИИ», а умеете им управлять.

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

Какую проблему она решает. Как генерировать код с помощью ИИ и при этом не терять контроль над системой, безопасностью и архитектурой.

Кому она подходит. Разработчикам, тимлидам и архитекторам, которые уже пользуются ИИ-агентами и устали от хаоса. Не нужно быть сеньором; нужно быть готовым работать руками.

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

Какой проект соберёте. Один сквозной учебный сервис, который будет расти в сложности от главы к главе.

Что унесёте с собой. Набор файлов и навыков, которые можно в понедельник принести в свою реальную команду.

КАК ПОЛЬЗОВАТЬСЯ КУРСОМ

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

Как устроен этот курс

В основе книги — один принцип. Запомните его, он определяет всё остальное:

ГЛАВНЫЙ ПРИНЦИП

Один сквозной проект. Одна растущая сложность. Практический артефакт или небольшой набор артефактов после каждой главы.

Мы не будем перескакивать с примера на пример. Через всю книгу проходит один проект, и каждая глава добавляет к нему ровно столько сложности, сколько нужно, чтобы показать новый навык: роли и права, API, базу данных, авторизацию, безопасность, логи, баги, технический долг, ревью и рефакторинг. Сложность растёт вместе с вами, а после каждой главы в репозитории остаётся один главный артефакт или небольшой набор файлов.

И ещё одно важное обещание. Мы переписали этот курс так, чтобы практика не была пришита к концу теоретических глав. Каждая глава построена вокруг действия. Скелет главы один и тот же:

• плохой запрос — как сделать не надо и что при этом ломается;

• инженерный подход — как переформулировать то же самое в управляемую задачу;

• шаблоны файлов — что именно вы создаёте;

• практическое задание и усложнение;

• артефакт главы — файл или небольшой набор файлов, который остаётся у вас в проекте.

Сквозной проект: TaskFlow AI

Наш учебный проект — TaskFlow AI, сервис управления задачами для команды. Он выбран не случайно: на нём естественно вырастают все темы курса — от прав доступа до безопасной загрузки файлов. В нём будут:

• пользователи и роли admin, manager, member;

• команды: у manager и member есть teamId; для курса считаем, что пользователь состоит в одной команде;

• задачи со статусами todo, in_progress, done и отдельной архивацией через archivedAt, комментарии и вложения;

• REST API и база данных;

• права доступа и авторизация;

• тесты, аудит безопасности и рефакторинг.

Стек — Node.js + TypeScript на NestJS с базой PostgreSQL. Архитектура классическая, слоёная: контроллер принимает HTTP-запрос, сервис содержит бизнес-логику, репозиторий работает с базой. Если вы пишете на другом стеке — не страшно. Навыки этого курса (спецификация до кода, ревью плана, threat model, аудит PR) переносятся на любой язык и фреймворк с небольшой адаптацией. NestJS здесь — просто конкретные декорации, чтобы примеры были настоящими, а не «псевдокодом из вакуума».

Доменная оговорка для следующих глав: «своя команда» означает совпадение teamId у manager, задачи и assignee; archived task = archivedAt != null, а не status=done; Guard отвечает за аутентификацию, TaskAccessPolicy/TaskAccessService — за бизнес-правила доступа.

ЧТО ВАЖНЕЕ СТЕКА

Мы учим не «как писать на NestJS». Мы учим думать системами и управлять ИИ-агентом так, чтобы он не разрушил вашу систему. Код в этой книге — дёшев. Ценны решения о том, что и почему строить.

Что вы соберёте

К концу курса в репозитории TaskFlow AI появится отдельный пласт — инженерный контекст и инструменты управления ИИ. Вот полная карта основных артефактов; пока она выглядит как список незнакомых файлов, но каждый из них появится в соответствующей главе:

docs/ai-context/

PROJECT_RULES.md

ARCHITECTURE.md

SECURITY.md

TESTING.md

DOMAIN_GLOSSARY.md

API_CONTRACT.md

features/

SPEC_TASK_ASSIGNMENT.md

SPEC_REVIEW.md

SPEC_FILE_UPLOAD.md

PLAN_CREATE_TASK.md

TASK_FEATURE_REVIEW.md

PLAN_COMMENTS.md

PLAN_REVIEW_NOTES.md

PLAN_FILE_UPLOAD.md

THREAT_MODEL_FILE_UPLOAD.md

SECURITY_REVIEW_FILE_UPLOAD.md

NEGATIVE_TEST_PLAN.md

AI_PR_REVIEW.md

REFACTORING_PLAN.md

analysis/

MODULE_MAP_TASKS.md

CONTEXT_HALLUCINATION_CHECK.md

TEST_FAILURE_INVESTIGATION.md

CONTEXT_GAP_REPORT.md

CONTEXT_BUNDLE.md

BUG_DIAGNOSIS_PLAN.md

DUPLICATION_REPORT.md

context/

# временная папка с логами, схемами, тикетами и другими источниками для диагностики

process/

AGENT_SANDBOX_RULES.md

MCP_ACCESS_POLICY.md

ARCHITECT_PLAYBOOK.md

TEAM_STANDARD.md

.github/

pull_request_template.md

BASELINE_COMPARISON.md

Это не «домашки ради домашек». Это рабочие документы, которые в настоящей команде превращают ИИ из источника хаоса в управляемый инструмент.

Первый контраст: ленивый вайб против инженерного запроса

Практическое задание

Выполните один и тот же запрос двумя способами в вашем любимом ИИ-инструменте:

ленивым промптом («Сделай мне сервис задач»);

инженерным запросом с ограничениями (из примера выше).

Затем сравните оба результата по пяти критериям и заполните таблицу. Отвечайте честно — «да», «нет» или «частично»:

Критерий

Ленивый промпт

Инженерный запрос

Права доступа учтены?

Есть тесты?

Есть edge cases?

Есть план?

Агент изменил лишнее?

УСЛОЖНЕНИЕ

Дайте инженерный запрос дважды с интервалом — например, в начале и в конце рабочего дня — и сравните оба плана между собой. Где агент «доехал» до разных решений? Это ваш первый личный замер дрейфа намерений, к которому мы вернёмся в главе 4.

Артефакт введения: BASELINE_COMPARISON.md

Зафиксируйте результат сравнения в первом артефакте курса — файле BASELINE_COMPARISON.md в корне проекта. Это ваша точка отсчёта: к ней вы вернётесь в конце книги, чтобы увидеть, насколько изменился ваш способ работать с ИИ. Используйте такой скелет:

# BASELINE_COMPARISON.md

## Дата

## Инструмент и модель

## Запрос 1: ленивый промпт

Текст запроса:

Наблюдения:

- что сгенерировал агент;

- что пошло не так.

## Запрос 2: инженерный запрос

Текст запроса:

Наблюдения:

- что изменилось;

- какие риски агент назвал сам.

## Таблица сравнения

| Критерий | Ленивый | Инженерный |

| --- | --- | --- |

| Права доступа учтены? | | |

| Есть тесты? | | |

| Есть edge cases? | | |

| Есть план? | | |

| Агент изменил лишнее? | | |

## Вывод

Один абзац: что я понял про разницу между вайбом и инженерией.

Пора протрезветь

Похмелье — это неприятно, но это признак того, что вечеринка закончилась и пора браться за серьёзную работу. Мы больше не играем с ИИ. Мы строим с его помощью системы, за которые отвечаем.

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

В следующей главе мы добавим в TaskFlow AI первую фичу — создание задач — но не «навайбим» её, а проведём через управляемую генерацию: контекст, план, ревью, минимальный diff. Переверните страницу. Начинаем строить по-настоящему.

ЧАСТЬ 1

Инструменты новой эры

Соблазн первой части любой книги про ИИ-разработку — устроить парад инструментов: вот Cursor, вот Devin Desktop (бывший Windsurf), вот Claude Code, вот spec-first инструменты вроде Traycer, у каждого свои кнопки. Проблема в том, что такой обзор устаревает быстрее, чем читатель дойдёт до середины. Кнопки переименуют, меню переедет, появится новый модный редактор.

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

• Cursor — контролируемая генерация: понятная задача, ограниченный контекст, предсказуемый diff.

• Devin Desktop (бывший Windsurf) — глубокий контекст: понять чужой, плохо документированный код (глава 2).

• Claude Code — автономный терминальный цикл: запустить тесты, найти причину, починить (глава 3).

• Traycer и подход «спецификация до кода» — заморозить намерение раньше, чем оно поплывёт (глава 4).

Названия поменяются. Режимы — нет. Начнём с самого частого: управляемой генерации новой фичи.

ЧАСТЬ 1 · ГЛАВА 1

Cursor: первая фича через управляемую генерацию

Добавляем создание задач в TaskFlow AI — без хаоса

Вайб-кодинг: Практический курс

Что Cursor делает хорошо

Не будем пересказывать историю инструмента. Достаточно знать главное: Cursor удобен, когда агенту нужно работать не с изолированным фрагментом, а с контекстом проекта — открытыми файлами, правилами, поиском по кодовой базе и текущим diff. В актуальных версиях у Cursor есть Plan Mode: режим, в котором агент сначала формирует проверяемый план реализации. Не считайте это магической защитой от ошибок; считайте это удобной точкой контроля, где человек должен остановиться и прочитать план до изменения кода.

Практический вывод одной фразой:

КОГДА CURSOR В СВОЕЙ СТИХИИ

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

И обратное тоже важно. Cursor — не лучший выбор, когда нужно разобраться в огромной чужой системе, где правка в одном сервисе каскадом роняет три других (это работа для главы 2), или когда задача — не добавить код, а удалить лишний (глава 10). Каждому режиму своё.

Почему «сделай фичу» — плохая команда

Самый частый способ испортить себе день — открыть Composer и написать что-то вроде:

Добавь задачи в приложение.

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

• создаст лишние файлы, которых вы не просили;

• выберет странную архитектуру — например, размажет логику по контроллеру;

• не добавит тесты или добавит тесты на то, что ему удобно проверять;

• смешает слои: контроллер полезет в базу мимо сервиса и репозитория;

• забудет про права доступа — кто вообще может создавать задачи?

• притащит новую зависимость «чтобы было проще», без всякой причины.

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

Минимальный контекст перед генерацией

Практика: добавляем сущность Task

Теперь — тот же самый запрос «добавь задачи», но переписанный как инженерная задача. Сравните с «Добавь задачи в приложение» из начала главы:

Нужно добавить сущность Task.

Контекст:

- пользователь может создавать задачу;

- задача имеет title, description, status, createdById;

- assigneeId пока может существовать в модели как nullable-поле, но CreateTaskDto его не принимает;

- status: todo, in_progress, done;

- пока без комментариев, вложений и назначения задачи;

- использовать текущую архитектуру проекта;

- не добавлять новые зависимости.

Сначала составь PLAN_CREATE_TASK.md.

Код не писать.

Разберём, что мы сделали:

• Сузили задачу. Только сущность Task и её создание — без комментариев и вложений. Это страховка от того, что агент «заодно» сделает половину приложения.

• Зафиксировали модель данных. Перечислили поля и значения статуса, чтобы не получить случайный набор колонок.

• Запретили вольности. «Использовать текущую архитектуру», «не добавлять зависимости» — два самых частых источника мусора.

• Потребовали план до кода. Главная фраза: Сначала составь PLAN_CREATE_TASK.md. Код не писать. Пока нет плана — нет генерации.

Как проверять план

Агент вернёт план. Не принимайте его рефлекторно. Хороший план обязан отвечать на шесть вопросов:

какие файлы будут изменены;

какие файлы будут созданы;

какие решения агент сознательно не принимает (что вне задачи);

где будет жить бизнес-логика;

какие нужны тесты;

какие есть риски.

Вот как выглядит план, который проходит проверку. Это и есть ваш будущий артефакт PLAN_CREATE_TASK.md:

# PLAN_CREATE_TASK.md

## Задача

Добавить создание задачи (entity Task) в модуль tasks.

## Что НЕ входит в задачу

- комментарии;

- вложения;

- назначение задачи (assign);

- уведомления.

## Будут созданы

- src/tasks/dto/create-task.dto.ts

- src/tasks/task.entity.ts

- src/tasks/tasks.controller.ts

- src/tasks/tasks.service.ts

- src/tasks/tasks.repository.ts

- src/migrations/*-create-task.ts

- test/tasks/create-task.e2e-spec.ts

## Будут изменены

- src/tasks/tasks.module.ts (регистрация провайдеров)

## НЕ будут затронуты

- src/users/*

- src/auth/* (используем существующий guard только для аутентификации)

## Где бизнес-логика

- TasksService.createTask(): валидация, выбор teamId создателя и запись;

- бизнес-решения доступа — через TaskAccessPolicy/TaskAccessService, если такой слой уже есть; если нет — не создавать его в этой главе, а только не дублировать будущие правила.

## Модель данных

Task { id, title, description, status, createdById, teamId, assigneeId: uuid | null, archivedAt: Date | null, createdAt }

status: 'todo' | 'in_progress' | 'done' (default 'todo')

archivedAt != null означает архивную задачу; это не то же самое, что status='done'.

CreateTaskDto: title, description. assigneeId и archivedAt не принимать на этом этапе.

Лишние поля в DTO запрещаются через ValidationPipe whitelist + forbidNonWhitelisted или явно игнорируются и покрываются тестом.

## Тесты

- member может создать задачу;

- созданная задача принадлежит создателю (createdById);

- задача получает teamId создателя;

- статус по умолчанию 'todo';

- archivedAt по умолчанию null;

- неавторизованный запрос отклоняется;

- попытка передать assigneeId или archivedAt при создании не приводит к назначению или архивации.

## Риски

- дублирование проверки прав, если не использовать общий policy layer;

- расширение DTO лишними полями, особенно assigneeId до отдельной фичи assign.

## Rollback

- удалить новые файлы, откатить миграцию task.

## Порядок реализации

1. entity + DTO + миграция;

2. repository + service;

3. controller + маршрут POST /tasks;

4. тесты.

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

Ошибки плана: красные флаги

Чаще проверять план придётся не на полноту, а на самодеятельность агента. Верните план на доработку, если видите хотя бы один из признаков:

КРАСНЫЕ ФЛАГИ

• агент хочет переписать архитектуру ради одной фичи;

• в плане нет тестов;

• нет списка файлов или нет раздела «что не делаем»;

• нет rollback;

• безопасность вынесена «на потом»;

• добавляется библиотека без объяснения причины;