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

• в плане фигурируют unrelated-файлы, не связанные с задачей.

Реакция на красный флаг — не «перепиши всё», а точечная правка. Например: «План слишком широкий. Убери изменения в src/users/. Не трогай auth — используй существующий guard. Сократи список файлов до минимально необходимого». Вы правите план, а не код.

Выполнение после утверждения

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

ПРАВИЛО УТВЕРЖДЕНИЯ

Код можно писать только после явной команды вроде: «План утверждён. Выполняй шаг 1». Никакой генерации до этой фразы.

Выполнение по шагам, а не «сделай всё разом», даёт вам точки контроля. После каждого шага можно остановиться, посмотреть diff и решить, продолжать ли. Это и есть контролируемая генерация: вы держите руку на рубильнике, а не наблюдаете, как агент за минуту переписывает полпроекта.

Мини-ревью результата

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

Сравни реализованный diff с PLAN_CREATE_TASK.md.

Покажи:

1. где реализация соответствует плану;

2. где отклонилась;

3. какие файлы были изменены вне плана;

4. какие тесты покрывают новую логику.

Особенно внимательно — к пункту 3. «Файлы, изменённые вне плана» — это самый частый канал, по которому в проект просачивается технический долг. Если агент «заодно» поправил src/users/user.entity.ts, хотя в плане этого не было, — это повод не принимать diff, а разобраться.

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

Обратите внимание, что в этой главе вы ни разу не писали код руками — и при этом проделали инженерную работу. За один цикл вы примерили четыре роли:

• Product owner — сформулировали намерение и границы задачи;

• Архитектор — проверили план на соответствие слоям и запретам;

• Security officer — спросили про права доступа раньше, чем агент про них забыл;

• QA — потребовали тесты и сверили diff с планом.

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

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

Добавьте фичу «создание задачи» в TaskFlow AI через текущий агентный интерфейс Cursor / Plan Mode, строго по циклу этой главы:

создайте PROJECT_RULES.md, ARCHITECTURE.md, TESTING.md;

отправьте инженерный запрос с требованием PLAN_CREATE_TASK.md до кода;

проверьте план по шести вопросам, верните на доработку при красных флагах;

утвердите план и выполните его по шагам;

проведите мини-ревью: сравните diff с планом.

УСЛОЖНЕНИЕ

Добавьте в задачу ограничение и проследите, чтобы оно дошло до плана, кода и тестов:

Пользователь не может создать задачу с пустым title или с title длиннее 120 символов.

Проверьте: появился ли в плане соответствующий пункт валидации? Появились ли негативные тесты на пустой и слишком длинный заголовок? Если агент добавил валидацию, но забыл тесты на неё — план не принят.

Артефакты главы

Главные артефакты фичи после этой главы — два файла. Первый — PLAN_CREATE_TASK.md (шаблон выше). Второй — отчёт о мини-ревью TASK_FEATURE_REVIEW.md. Кроме них, в проекте уже остаётся минимальный контекстный набор: PROJECT_RULES.md, ARCHITECTURE.md, TESTING.md:

# TASK_FEATURE_REVIEW.md

## Фича

Создание задачи (Task).

## Ссылка на план

PLAN_CREATE_TASK.md

## Соответствие плану

- что совпало с планом;

## Отклонения

- где реализация ушла от плана и почему;

## Изменения вне плана

- файлы, затронутые без согласования (в идеале — пусто);

## Покрытие тестами

- какие тесты добавлены, включая негативные;

## Решение

- approve / request changes / regenerate from plan.

Эти два файла — не отчётность ради отчётности. PLAN_CREATE_TASK.md фиксирует намерение, TASK_FEATURE_REVIEW.md фиксирует, что намерение было исполнено. Вместе они дают то, чего не хватало в эпоху «навайбил и забыл»: прослеживаемую связь между тем, что вы хотели, и тем, что оказалось в репозитории.

Что дальше

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

В следующей главе мы развернём ИИ в обратную сторону — будем использовать его не для генерации, а для понимания существующей кодовой базы. Возьмём модуль задач, который уже есть, но никто толком не помнит, как он устроен, и проведём над ним «ИИ-археологию» с помощью Devin Desktop (бывший Windsurf).

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

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

Используем ИИ не для генерации, а для понимания чужого кода

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

Разворачиваем ИИ в обратную сторону

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

Здесь в своей стихии другой режим — глубокий контекст. Devin Desktop (бывший Windsurf) с его агентным режимом полезен не потому, что «знает всё», а потому что помогает навигировать по проекту, связывать файлы, зависимости и места использования в одну проверяемую картину. Но эту мощь мы направим не на генерацию, а на археологию: реконструировать, как устроен незнакомый модуль, и — что важнее — отличить то, что агент действительно вычитал из кода, от того, что он убедительно придумал.

ЦЕЛЬ ГЛАВЫ

Научиться использовать ИИ для понимания существующей кодовой базы. Не «Windsurf видит проект», а «как с помощью глубокого контекста разобрать чужой модуль и не поверить агенту на слово».

Рабочий материал — модуль задач TaskFlow AI. Представим, что он уже существует (его «написал кто-то до вас»), работает, но документация по нему мертва. Наша задача — восстановить карту.

Когда нужен глубокий контекст

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

• вы пришли в legacy-проект, который видите впервые;

• документация устарела и врёт;

• фича работает, но никто не знает, почему именно так;

• изменение в одном файле необъяснимо ломает другой модуль;

• нужно провести ревью перед доработкой, а не доработать вслепую.

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

Плохой подход: «объясни мне весь проект»

Первое, что хочется сделать в незнакомом проекте, — попросить:

Объясни мне весь проект.

Звучит разумно, а на деле это худший возможный запрос. Почему:

• слишком широко — агент не сможет быть конкретным;

• он будет обобщать — выдаст правдоподобное описание «типичного проекта», а не вашего;

• появятся галлюцинации — на широком вопросе модель додумывает связи, которых нет;

• результат невозможно проверить — вы не отличите правду от выдумки, потому что сами проект ещё не знаете.

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

Хороший подход: ограниченный анализ

Сузьте область до одного модуля и потребуйте конкретики со ссылками на файлы:

Проанализируй только модуль tasks.

Код не менять.

Выведи:

1. какие файлы участвуют в создании задачи;

2. где проверяются права доступа;

3. где находится бизнес-логика;

4. какие зависимости есть у модуля;

5. какие места выглядят рискованными;

6. какие утверждения ты можешь подтвердить ссылкой на файл.

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

ГЛАВНЫЙ ПРИЁМ АРХЕОЛОГИИ

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

Карта модуля: MODULE_MAP_TASKS.md

Результат анализа читатель оформляет в артефакт — карту модуля. Это не пересказ кода, а структурированная схема: что где живёт, как течут данные, где слабые места. Шаблон:

# MODULE_MAP_TASKS.md

## Назначение модуля

## Основные файлы

## Поток данных

## Где создаётся задача

## Где проверяются права

## Где пишутся данные в БД

## Зависимости

## Потенциальные риски

## Что неясно

## Что нужно уточнить у человека

Обратите внимание на два последних раздела — Что неясно и Что нужно уточнить у человека. В обычном пересказе их нет, и зря: именно они отличают честную карту от красивой галлюцинации. Карта без зон неизвестности почти всегда означает, что агент чего-то недопонял и закрасил пробел догадкой.

Ловушка: убедительные галлюцинации

Вот парадокс глубокого контекста, который нужно прочувствовать на собственной шкуре:

ЗАПОМНИТЕ

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

Разберём на конкретном примере. Агент уверенно заявляет:

Права доступа проверяются в TasksService.

Звучит логично — бизнес-логика и должна быть в сервисе. Но прежде чем записать это в карту, проверьте четыре вещи:

Файл существует? Откройте tasks.service.ts. Он вообще есть, и так ли он называется?

Проверка реально там? Найдите в файле собственно проверку роли. Может оказаться, что её там нет — она в guard'е или в контроллере.

Нет ли дублирования? Частая беда: проверка прав размазана и по контроллеру, и по сервису. Тогда «проверяется в сервисе» — полуправда.

Реальная архитектура или желаемая? Это главный вопрос. Агент мог описать, как права должны проверяться по канону, а не как они проверяются на самом деле.

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

Правила работы с глубоким контекстом

ЧЕТЫРЕ ПРАВИЛА АРХЕОЛОГА

• просите файлы и строки;

• отделяйте факты от предположений;

• требуйте список «не уверен»;

• анализ не должен менять код.

Финальный запрос: карта с разметкой достоверности

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

На основе анализа модуля tasks создай MODULE_MAP_TASKS.md.

Раздели выводы на четыре категории:

- подтверждено кодом (со ссылкой на файл);

- предположение;

- риск;

- вопрос к человеку.

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

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

Проведите «ИИ-археологию» модуля задач TaskFlow AI:

запустите ограниченный анализ только модуля tasks с запретом менять код;

потребуйте ссылки на файлы для каждого утверждения;

проверьте минимум одно утверждение агента руками (по схеме из раздела про галлюцинации);