Вайбкодинг: что спроектировать до генерации кода
Перед генерацией кода опишите одну функцию: вход, выход, данные, права, ошибки и проверки. Заполненный пример и пустой проектный лист помогут уточнить поведение.
Прототип может красиво заполнить карточку по одному письму и при этом не знать, что делать с пустым входом, повторной обработкой или недоступной базой. До следующего запроса на генерацию кода опишите одну функцию от входа до проверяемого выхода: данные, правила, права, ошибки, участие человека и способ проверить результат. Это займёт столько места, сколько нужно для конкретного риска. Одностраничный лист помогает увидеть нерешённые вопросы; сам по себе он не делает продукт надёжным и не обещает готовый продукт за вечер.
При работе с кодовым агентом GitHub советует давать ясную задачу, достаточный контекст и проверять результат его работы. Документация относится к GitHub Copilot; ниже — способ подготовить *задачу продукта* независимо от конкретного генератора. Если функцию можно сделать фиксированной формой и правилом, ИИ может вообще не понадобиться.
Назовите функцию и её границу
Не начинайте с «сделай CRM с агентами». Возьмите один сквозной путь: входящее письмо → черновик карточки → проверка менеджером. Укажите пользователя и решение, которое он принимает по карточке. В нашем учебном примере система не отправляет ответ клиенту и не меняет статус заказа. Так граница первой версии остаётся обозримой: проверять нужно подготовку черновика и передачу менеджеру.
Проверьте формулировку на трёх вопросах: где функция начинается, кому нужен выход, какое действие остаётся за человеком? Если на них нет ответа, в задании останутся пробелы, а сгенерированное поведение придётся дополнительно уточнять. Microsoft в руководстве по архитектуре предлагает связывать проектные решения с бизнес-потребностью и требованиями. Это руководство написано для Azure, а здесь важен сам принцип: функция определяется нужным результатом, а не доступной технологией.
Проследите путь данных и продумайте обработку ошибок до написания промпта
Для каждого входа определите источник и разрешённое использование. Для выхода — получателя и место хранения. Затем пройдите неудобный путь: вход пустой, письмо дублируется, модель не смогла уверенно извлечь поле, внешняя система недоступна. Что увидит пользователь? Можно ли повторить операцию без создания второй карточки? Кто исправит запись? Если ответ «разберёмся потом», на листе так и запишите: функция ещё не готова к автоматическому действию.
Отдельно обозначьте секреты и полномочия. Ключ доступа не должен становиться частью текста задачи, учебного примера или вывода модели. До интеграции решите, какая система хранит секрет и какие операции разрешены функции; конкретный способ реализации зависит от платформы. Для первой пробы часто достаточно обезличенного файла и черновика без записи в рабочую систему. Если работа затрагивает реальные клиентские данные, способ их обработки и доступ согласуют с ответственным за них до пробного запуска.
Наконец, запишите критерии проверки *до* генерации. В архитектурной спецификации Microsoft разделяются функциональные и нефункциональные требования и описываются решения для обычной работы и сбоев. Маленькому продукту не нужна тяжёлая спецификация, но нужно различить «поле верно извлечено» и «система вообще продолжает работу после сбоя». AWS относит эксплуатацию и дальнейшее изменение системы к проектным заботам; это повод заранее назвать ответственного за ошибку и обновление, а не переносить облачный стандарт целиком.
Проектный лист: учебный пример одной функции
Ниже вымышленный сценарий. Письмо «Здравствуйте, интересует станок М-12. Позвоните после 15:00» — придуманный вход, а не клиентский материал и не тест работающей модели.
| Решение до кода | Запись для учебной функции | Статус |
|---|---|---|
| Пользователь и граница | Менеджер получает черновик карточки по одному письму. Ответ клиенту и изменение заказа вне функции. | Учебное условие |
| Вход и источник | Текст разрешённого письма и его внутренний идентификатор; для первой пробы — обезличенный файл. | Источник рабочих писем ещё не согласован |
| Преобразование и правило | Извлечь явно названный товар и просьбу о времени звонка. Неизвестные поля оставить пустыми; не придумывать цену или наличие. | Предлагаемое правило, нужно подтвердить у будущего пользователя |
| Выход и получатель | Черновик карточки с полями «товар», «пожелание по звонку», «исходное письмо/ссылка», «требует проверки». Менеджер принимает или исправляет. | Формат ещё не принят |
| Ошибка и восстановление | Пустой вход: карточка не создаётся, видна причина. Повтор того же идентификатора: показать существующий черновик вместо нового. Недоступно хранилище: показать сбой и сохранить возможность повторить без скрытой записи. | Проектное требование; реализация не проверена |
| Доступы и секреты | На пробе нет доступа к рабочей почте и CRM. Для будущего подключения нужны отдельное согласование прав и способ хранения ключей. | Рабочие права неизвестны |
| Человеческое подтверждение | Менеджер сверяет карточку с письмом до любых внешних действий. Жалоба и неоднозначное письмо передаются человеку без автоматического решения. | Граница предложена, подлежит согласованию |
| Проверки | Обычное письмо: «М-12» и «после 15:00» в черновике, цена пустая. Пустое письмо: нет карточки. Повтор: один черновик. Жалоба: передача человеку. | Ожидаемые результаты, пока не результаты теста |
| Поддержка | Сохранить версию правила извлечения, назначить владельца полей и порядок исправления ошибочной карточки; после изменения правила повторять эти проверки. | Владелец ещё не назначен |
По этому листу можно попросить генератор реализовать один ограниченный путь, а затем проверить, что код делает на обычном, пустом и повторном входе. Образец результата известен заранее: карточка с «М-12» и временем звонка, без придуманной цены. Если модель добавляет наличие товара или отправляет сообщение клиенту, это не «почти готово»: она вышла за согласованную границу. Если другой разработчик по листу не может назвать ожидаемое поведение на ошибочном входе, сначала уточните правило, а потом пишите код.
Скопируйте пустой лист и заполните его для своей функции:
| Поле | Ваше решение, основание или «неизвестно» |
|---|---|
| Пользователь, задача, начало и конец функции | |
| Вход, источник, разрешение на использование | |
| Преобразование и правило для неизвестных данных | |
| Выход, получатель, место хранения | |
| Пустой вход, повтор, сбой и восстановление | |
| Доступы, секреты и запрещённые действия | |
| Где человек подтверждает или исправляет | |
| Обычный, ошибочный и спорный тестовый случай | |
| Кто меняет правило и разбирает сбой |
Когда листа недостаточно
Если функция отправляет деньги или сообщения, меняет важные записи, обрабатывает чувствительные данные либо должна работать без постоянного наблюдения, одного листа мало. Потребуются подробные права, проверка отказов, журналирование, восстановление, согласование данных и специалист по соответствующему риску. Даже для маленькой функции после первой реализации нужны просмотр изменений и реальные испытания на разрешённых примерах. План — это записанное ожидание, не свидетельство того, что программа уже ему соответствует.
Начните с самого узкого проверяемого пути. При необходимости сначала нарисуйте карточку вручную и проверьте, помогает ли она человеку; так можно обнаружить неверный формат до затрат на код. После реализации сравните поведение с листом, исправьте расхождения и обновите лист там, где решение осознанно изменилось. Поддерживаемость зависит и от дальнейшей работы с изменениями и сбоями. Если изменения вносит кодовый агент, словарь pull request и других терминов вайбкодинга поможет разобраться, как их передают на просмотр; сам проектный лист проверки кода не заменяет.
Комментарии
Обсуждение этой статьи пока закрыто.