Комфортный вайб-кодинг для новичков

«Выглядит нормально» не позволяет проверить задачу. Критерий готовности описывает наблюдаемое поведение.

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

• пустое имя вызывает сообщение рядом с полем;

• телефон с недопустимыми символами не отправляется;

• корректная заявка появляется в базе;

• повторное нажатие не создаёт две записи;

• на узком экране форма не выходит за границы;

• пользователь получает подтверждение.

Промпт 17. Критерии приёмки

Составь критерии готовности для функции [ФУНКЦИЯ].

Описание: [ТРЕБОВАНИЯ].

Включи:

- обычный успешный сценарий;

- пустые и неверные данные;

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

- поведение при недоступном сервере или внешнем API;

- мобильный экран, если есть интерфейс;

- проверку прав доступа, если функция работает с личными данными.

Каждый критерий должен быть проверяемым действием, а не общей фразой о качестве.

Когда план проверен, поручение должно содержать контекст, границы, требования и проверку. Не нужно писать роман. Достаточно убрать двусмысленность.

Промпт 18. Реализация этапа

Реализуй только этап [НОМЕР И НАЗВАНИЕ] из утверждённого плана.

Требования этапа:

[ТРЕБОВАНИЯ]

Перед изменениями:

1. изучи связанные файлы;

2. перечисли файлы, которые планируешь менять;

3. предупреди, если обнаружишь противоречие с текущей архитектурой.

После изменений:

- запусти доступные проверки;

- сообщи, что проверено автоматически;

- дай мне короткий ручной сценарий проверки;

- не переходи к следующему этапу.

Как проверять работу

Agent

Новичок часто смотрит только на красивую страницу. Проверка должна охватывать четыре уровня.

Первый — видимый сценарий. Нажмите кнопки, заполните форму неверно, обновите страницу. Второй — терминал. Нет ли красных ошибок при запуске и сборке? Третий — данные. Создалась ли нужная запись, принадлежит ли она правильному пользователю? Четвёртый — изменения. Не удалил ли Agent рабочую функцию и не добавил ли секрет в публичный файл?

Промпт 19. Проверка результата

Проверь реализацию функции [ФУНКЦИЯ] по требованиям:

[ТРЕБОВАНИЯ]

Сначала изучи фактические изменения. Затем:

1. запусти подходящие автоматические проверки;

2. проверь сборку;

3. перечисли непроверенные вручную сценарии;

4. найди изменения вне согласованного объёма;

5. укажи риски, которые ещё остались.

Ничего дополнительно не улучшай без отдельного запроса.

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

После работы попросите Agent перечислить фактические изменения и объяснить одну новую конструкцию в JavaScript. Не пытайтесь выучить весь файл. Разберите только тот механизм, который появился из-за вашей функции.

Читать код как карту действий

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

Начните с вопроса: какой файл отвечает за экран или команду? Затем найдите точку входа — место, где приложение начинает работу. В простом сайте это index.html. В проекте с фреймворком точка входа может быть страницей, маршрутом или конфигурацией. В Telegram-боте запуск обычно создаёт экземпляр бота, подключает обработчики и начинает получать обновления.

Дальше проследите одно действие. Пользователь нажал кнопку. Какая функция вызывается? Какие данные она получает? Отправляет ли запрос? Где ответ меняет экран? Такой маршрут полезнее чтения файлов подряд.

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

Имена дают половину понимания

Хорошие имена снижают зависимость от комментариев. submitBooking понятнее, чем handle2, а isOwner точнее, чем check. Если Agent создаёт десятки переменных data, item и value, попросите уточнить названия в ограниченном участке.

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

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

Значения, функции и условия

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

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

• Какие данные входят?

• Как они проверяются?

• Что меняется?

• Что возвращается при успехе и ошибке?

Если функция одновременно проверяет форму, отправляет письмо, пишет в базу и формирует HTML, её трудно тестировать и исправлять. Попросите разделить ответственности, но только после фиксации текущего поведения.

Состояние интерфейса

Состояние — данные, от которых зависит текущий вид приложения. Форма может быть пустой, заполняться, отправляться, завершиться успешно или показать ошибку. Если разработчик учитывает только «пусто» и «готово», пользователь получает двойные отправки и непонятные зависания.

Для сетевого действия обычно нужны состояния:

• исходное;

• загрузка;

• успех;

• ожидаемая ошибка пользователя;

• техническая ошибка сервера.

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

Массивы и объекты

Объект объединяет свойства одной сущности. Заказ может содержать id, title, status и createdAt. Массив хранит несколько заказов. JSON передаёт похожую структуру в текстовом виде между браузером и сервером.

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

Не храните разные значения в одном поле только ради скорости. Строка «Иван; +998...; завтра вечером» сложнее проверяется и ищется, чем отдельные поля. Но не дробите адрес на двадцать колонок, если приложение его только показывает. Структура следует реальным операциям.

Типы как ранняя проверка

TypeScript описывает форму данных. Если функция ожидает заказ, а ей передали пользователя, проверка типов может остановить сборку. Типы не доказывают правильность бизнеса: строка типа string всё ещё может быть пустой или содержать неверный телефон.

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

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

Импорты и зависимости между файлами

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

Циклическая зависимость возникает, когда файл A зависит от B, а B прямо или через цепочку зависит от A. Иногда среда её терпит, иногда появляются неопределённые значения и странные ошибки запуска. Исправление обычно требует вынести общую часть в третий модуль, а не добавить ещё один импорт.

Синхронная и асинхронная работа

Запрос к серверу, базе или файлу занимает время. Асинхронный код позволяет приложению ждать результат, не блокируя всё остальное. Ключевые слова async и await помогают описать последовательность, но ошибки ожидания остаются частой причиной проблем.

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

При анализе сетевого пути проверьте:

• установлен ли тайм-аут;

• что происходит при медленном ответе;

• обрабатывается ли неуспешный код;

• можно ли повторить действие;

• не создаст ли повтор дубль;

• отменяется ли устаревший запрос при уходе с экрана.

Клиент и сервер

Клиентский код доставляется на устройство пользователя. Его можно просмотреть и изменить. Поэтому клиентская проверка не является доказательством права или правильности данных.

Сервер получает запрос и применяет доверенные правила. Он проверяет сессию, формат, принадлежность записи и ограничения. После этого обращается к базе или внешнему API. Даже если кнопка удаления скрыта, злоумышленник может вызвать адрес операции вручную; сервер обязан отказать.

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

HTTP

без таблицы кодов

HTTP-запрос содержит метод, адрес, заголовки и иногда тело. Метод сообщает намерение: получить данные, создать или изменить. Сервер отвечает кодом, заголовками и телом.

Различайте категории:

• успех;

• ошибка входных данных;

• пользователь не вошёл;

• действие запрещено;

• объект не найден;

• конфликт текущего состояния;

• ограничение частоты;

• внутренняя ошибка.

Если сервер возвращает один и тот же успешный ответ даже при провале, интерфейс не сможет правильно сообщить результат. Если возвращает внутренний текст базы, раскрывает устройство системы.

База как источник сохранённого состояния

Таблица содержит строки одного типа. Первичный ключ однозначно определяет строку. Внешний ключ связывает её с другой таблицей. Ограничения базы защищают правила даже при ошибке приложения.

Запрос на выборку должен ограничиваться текущим пользователем на сервере или политикой базы. Фильтр только после загрузки всех строк в браузер уже раскрыл данные.

Транзакция объединяет несколько изменений: либо выполняются все, либо ни одно. Она нужна, когда создание заказа и уменьшение остатка не должны расходиться. Не каждое действие требует транзакции, но Agent должен заметить связанную операцию.

Миграции вместо ручных изменений

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

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

Логи, ошибки и сообщения пользователю

Ошибка имеет три аудитории. Пользователю нужно понять, что делать. Разработчику нужен контекст диагностики. Системе мониторинга нужны тип и время.

Пользователю: «Не удалось сохранить заявку. Проверьте соединение и попробуйте ещё раз».

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

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

Тест как исполняемое требование

Тест готовит данные, выполняет действие и проверяет результат. Хорошее имя описывает правило: «пользователь не может изменить чужой заказ». Если реализация меняется, правило остаётся.

Не просите Agent повысить процент покрытия любой ценой. Тест конструктора без бизнес-логики может увеличить цифру и ничего не защитить. Сначала покрывайте права, деньги, сохранность данных и главный сценарий.

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

Сборка и среда выполнения

Режим разработки оптимизирован для быстрых изменений и подробных ошибок. Production-сборка оптимизирует код и применяет другие настройки. Поэтому локально открытая страница ещё не означает готовность к публикации.

Команда сборки выявляет пропущенные импорты, ошибки типов и неподдерживаемые зависимости. После сборки полезно запустить production-версию локально, если стек это поддерживает.

Среда выполнения — версия Node.js, Python или другой платформы, где код работает. Локальная и облачная версии должны совпадать в поддерживаемом диапазоне. Зафиксируйте требование в конфигурации, чтобы хостинг не выбрал случайную старую версию.

Как разбирать незнакомый файл

Не просите пересказать каждую строку. Используйте порядок:

1. Назначение файла.

2. Что он импортирует и кому нужен.

3. Главные данные и функции.

4. Входы и выходы.

5. Ошибки и побочные действия.

6. Связь с пользовательским сценарием.

7. Риски изменения.

После объяснения закройте ответ и попытайтесь сами рассказать путь в двух абзацах. Если не получается, задайте один конкретный вопрос. Такое чтение постепенно создаёт техническую интуицию без зубрёжки синтаксиса.

Когда остановить

Agent

Остановитесь, если он:

• меняет стек без согласования;

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

• предлагает отключить проверку типов или безопасности;

• просит поместить секрет в публичный файл;

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

• обновляет много зависимостей во время локальной ошибки;

• выполняет destructive-команду с широкой целью;

• заявляет об успешной проверке, не запустив её;

• добавляет функции за пределами ТЗ.

Остановка не означает провал. Вернитесь к последней контрольной точке, уменьшите задачу и соберите факты.

Проект сайта для локального бизнеса

Создание каркаса

Дизайн через ограничения

Адаптивность

Форма заявки