Начните с наблюдаемого результата
Кодовый агент может выдать убедительный экран ещё до того, как вы решили, что он должен делать. Начните с небольшого пользовательского результата: вошедший пользователь редактирует профиль, сохраняет его и видит сохранённое имя после перезагрузки. Это даёт и реализации, и ревью конкретную цель.
Включите в бриф текущее поведение, желаемое поведение и важные случаи отказа. Назовите существующий модуль, владеющий работой. Просьба добавить редактирование профиля должна указывать на слой аутентификации, а не позволять агенту изобрести второе хранилище пользователей. Держите креденшелы вне промптов и скриншотов — вставленный apps/web/.env.local или сессионная кука становится частью записи разговора.
Рабочий бриф читается так: «На экране аккаунта позвольте вошедшему пользователю редактировать отображаемое имя и видеть его после перезагрузки. Модуль аутентификации владеет записью пользователя; таблицу не добавляйте. Пустое имя или запрос, называющий запись другого пользователя, должны отклоняться. Докажите это pnpm test и одним ручным сохранением на узкой ширине». Пять предложений — и большая часть догадок исчезла.
- Видимый пользователем результат, сформулированный так, чтобы его можно было проверить в запущенном приложении.
- Файл или модуль, который владеет поведением сегодня, — и области, которые должны остаться нетронутыми.
- Хотя бы один случай отказа: неаутентифицированная попытка, невалидный ввод или повторный запрос.
- Проверка, которая это доказывает, — тестовая команда, фикстура или явный ручной прогон.
Пусть репозиторий объясняет себя сам
Задокументируйте, как запускать приложение, какие проверки детерминированы и где обеспечивается владение. В supastack AGENTS.md фиксирует границу воркспейса, а .ai/ — решения на уровне файлов. Эти заметки полезнее всего, когда они объясняют следующему участнику — человеку или агенту — почему реализация существует, а не только какие файлы изменились. Руководство по настройке агента показывает, как кит раскрывает этот материал, а руководство по локальной установке — тот проход, которому агент реально последует.
Просите агента читать соответствующий код перед редактированием. Узкое изменение обычно требует UI, его серверную границу и тесты вокруг неё. Загружать весь репозиторий менее полезно, чем понять несколько мест, решающих, корректно ли новое поведение: проверку владения, схему и право доступа.
Когда функция затрагивает конфигурацию, называйте файл, а не переписывайте его — «добавьте ключ в apps/web/.env.local» оставляет секреты на диске. Та же дисциплина касается панелей провайдеров: описывайте назначение, а не вставляйте креденшел.
Работайте маленькими, проверяемыми изменениями
Агенты надёжнее всего, когда у изменения один владелец и один проверяемый результат. «Добавить редактирование профиля» — проверяемо; «улучшить область аккаунта» — приглашение к рефакторингам, о которых никто не просил. Если функция раскладывается на изменение схемы, серверную границу и экран, запускайте их отдельными брифами, каждый из которых оставляет сборку зелёной.
Коммитьте или ставьте контрольную точку перед каждым запуском агента. Чистая базовая линия превращает плохой результат в удалённый diff, а не в археологические раскопки, и даёт ревью стабильную пару «до и после» для сравнения.
Проверяйте по одному полному изменению
Напишите приёмочную проверку до изменения поведения. Для редактирования профиля покройте валидное обновление и неавторизованную попытку. Постройте минимальную реализацию, удовлетворяющую этим случаям, затем проверьте реальное взаимодействие с реалистичным текстом и узким вьюпортом.
Проверяйте diff так же, как результат. Ищите дублированную бизнес-логику, широкую обработку исключений и новые зависимости, решающие проблему, которую стек уже покрывает. Запускайте проверки проекта и фиксируйте, что они устанавливают. Браузерная фикстура может проверить взаимодействие формы; она не может установить, что продакшен-база или внешний провайдер настроены правильно.
Каждая команда отвечает на свой вопрос. pnpm test прогоняет поведение на детерминированных fake- и локальных адаптерах, pnpm check покрывает линт, проверку типов и форматирование, а pnpm build вскрывает интеграционные ошибки, которые проявляются только при сборке бандла. Вместе они — минимальный уровень для ревью; чек-лист запуска покрывает то, что ещё предстоит доказать в реальной среде.
pnpm test
pnpm check
pnpm buildКогда агент ошибается
Когда результат неверен, не нагромождайте уточняющие промпты поверх плохого diff. Откатитесь к контрольной точке, уточните бриф вокруг того, что было неправильно понято, — обычно это несказанное ограничение или отсутствующий владелец — и запускайте снова. Каждая повторная попытка должна нести новую информацию, а не только новую срочность.
Упорный провал обычно означает, что бриф предполагает контекст, которого в репозитории нет. Если агент продолжает изобретать второе место для хранения пользователей, исправление — предложение в AGENTS.md о том, где живёт идентичность, а не более твёрдый тон. Обновите документ и повторите задачу — руководство по агентам — место, где кит держит этот процесс.
Частые вопросы о работе с кодовым агентом
Несколько вопросов возникают всякий раз, когда основатель начинает доверять кодовому агенту настоящую продуктовую работу.
- Может ли кодовый агент построить целый SaaS самостоятельно? — Видимые части он соберёт быстро, но долговечные — авторизация, жизненный цикл биллинга, изоляция данных — по-прежнему требуют брифа, проверки и ревью. Скорость без этого цикла превращается в переделку.
- Насколько большой должна быть задача для кодового агента? — Достаточно маленькой, чтобы результат можно было проверить в запущенном приложении за минуты: один видимый пользователем результат, один владеющий модуль, одна приёмочная проверка.
- Что никогда не должно попадать в промпт? — Секреты провайдеров, сессионные куки, содержимое
.env.localи данные клиентов. Называйте файлы и позволяйте инструменту читать их локально вместо копирования значений в лог чата. - Меняет ли написанный агентом код то, как я провожу ревью? — Ревью смещается от набора кода к чтению: ищите в diff дублированную логику, широкую обработку исключений и зависимости, заново решающие проблему, которую стек уже покрывает.
- Какие тесты важнее всего для результата агента? — Те, что закрепляют владение и поведение при сбоях: неавторизованные запросы, невалидный ввод и повторные отправки, а не только удачный путь из демо.