Агент чинит одно и тихо ломает другое. Вот защита

01В чём фокус

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

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

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

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

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

02Что нужно до старта

Любой ИИ-агент с доступом к терминалу и файловой системе. Claude Code, Cursor, Codex, Antigravity, OpenCode, без разницы, какой именно. Всё, что ниже, это промпты и правила, а не команды конкретного инструмента.

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

Git. Тесты на уровне сервера, последний, шестой уровень, работают только через git-провайдера: GitHub, GitLab или аналог. Если вы ещё не пользуетесь ветками, отдельный разговор про git с агентом стоит провести раньше, чем внедрять тесты. Часть промптов ниже предполагает, что вы умеете переключаться в новую ветку и откатываться назад.

Честно про объём. За один заход девять промптов не покроют тестами всё приложение. Они дадут базовое покрытие нескольких главных действий и инструменты, чтобы расширять его дальше самостоятельно. Это стартовый комплект, а не разовая процедура «включил и забыл».

03Ядро

Шесть уровней тестирования проверяют разное и стоят по-разному временем на прогон. Каждый следующий даёт больше уверенности, но и занимает дольше, поэтому в связке работают все шесть, а не один самый «полный».

0. линтер и типы        форматирование и базовые несоответствия типов, секунды
1. юнит-тест             одна функция в отрыве от всего приложения
2. api-тест               целый запрос к серверу: авторизация, данные, доступ
3. интеграционный тест    то же самое, но с реальной тестовой базой данных
4. e2e / браузерный тест  интерфейс: клики, экраны, путь настоящего пользователя
5. проверка на сервере    CI на git-провайдере, блокирует слияние веток

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

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

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

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

E2E-тест (end-to-end, «от начала до конца») подключает интерфейс: запускается настоящее приложение, тест кликает по кнопкам и смотрит, что отрисовалось на экране. Самый медленный уровень, зато самый близкий к тому, что реально увидит пользователь.

Проверка на сервере это не новый тест, а место запуска уже написанных. Когда вы создаёте пул-реквест на слияние веток, git-провайдер сам прогоняет все проверки, и если они красные, блокирует слияние. Это последний рубеж: сломанный код физически не попадает в основную ветку через интерфейс git-сервиса.

04Девять промптов: что за чем

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

Нулевой шаг, диагностика. Агент анализирует проект и сам находит самые рискованные места: какие функции критичны, что стоит тестировать в первую очередь. Результат он сохраняет не в чат, а в отдельные файлы. На них будут ссылаться все следующие промпты, поэтому удалять их раньше времени не стоит.

Команда на все проверки разом. Вместо пяти отдельных вызовов одна команда вида npm run check, которая запускает форматирование, типы и тесты последовательно. Агент использует её в конце своей работы, чтобы одним прогоном убедиться, что ничего не сломано.

Правила для агента. Записываются в файл, который агент читает автоматически: AGENTS.md, CLAUDE.md или его аналог в вашем инструменте. Три требования держат всю систему. Задача не считается закрытой, пока проверки не прошли и агент не показал результат. Тест и рабочий код правятся в разных заходах, не одним. Тест, который не проходит, нельзя чинить, ослабляя проверку, это не решение, а маскировка проблемы. В файле это может звучать примерно так:

## Тесты

- Задача не готова, пока не прошла команда `npm run check`.
  Результат прогона показывай в ответе, а не только слово "готово".
- Не редактируй уже существующие тесты в том же заходе,
  где меняешь рабочий код. Новый тест для нового кода — можно.
- Если тест не проходит, ищи причину в коде, а не упрощай
  и не удаляй сам тест ради зелёного цвета.

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

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

Тесты для важной логики (юнит-уровень). Опирается на список из диагностики: какие функции критичны, их и покрываем в первую очередь.

Тесты для ответов приложения (API-уровень). Проверка эндпоинтов: авторизация, создание, доступ только к своим данным.

Браузерный тест. Один тест на главное действие приложения, просто чтобы увидеть, как это вообще работает, дальше расширяется по потребности. Здесь важно различать два инструмента: библиотека вроде Playwright без MCP просто имитирует браузер внутри теста, а Playwright MCP даёт самому агенту возможность открыть настоящий браузер и покликать по нему самостоятельно. Это разные вещи, и нужны обе.

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

Проверка на сервере (CI). Настройка конфига для git-провайдера: при создании пул-реквеста автоматически прогоняются все тесты, и если они красные, слияние веток блокируется. Для GitHub это файл .github/workflows/, и агент обычно собирает его сам, но минимальная логика внутри выглядит так:

name: check
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run check

Сам по себе такой файл только показывает статус проверки рядом с пул-реквестом, но не блокирует кнопку слияния физически. Блокировку даёт отдельная настройка репозитория, правило обязательной проверки перед слиянием (branch protection), и агент может настроить её тоже, если у вас есть права администратора репозитория.

Все девять промптов универсальны и не привязаны к конкретному стеку, подходят и вебу, и мобильным, и десктопным приложениям, хотя инструмент для интерфейсного уровня (Playwright работает только с вебом) в других случаях придётся подбирать вместе с агентом отдельно.

05Три ловушки зелёных тестов

Все тесты зелёные, но это ещё не повод расслабиться. Вот три ситуации, в которых зелёный цвет вводит в заблуждение.

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

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

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

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

06Свой результат за вечер

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

Шаг первый. Диагностика.

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

Шаг второй. Одна команда на все проверки.

Попросите агента настроить единую команду вида npm run check, объединяющую линтер, типы и тесты. Дальше агент будет сам вызывать её в конце работы, а вы сможете проверить его руками, когда захочется.

Шаг третий. Правила и предохранитель базы.

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

Шаг четвёртый. Тесты по уровням, от простого к интерфейсу.

Пройдите промпты для юнит- и API-уровня на самых важных функциях из диагностики, затем добавьте Playwright MCP и один браузерный тест на главное действие приложения. Завершите проверкой на сервере: пул-реквест с намеренно сломанной функцией должен показать красный статус.

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

07Что ты увидишь

Было. Агент отчитывается «готово» после каждой правки. Вы открываете приложение сами, проверяете руками ту функцию, которую он менял, и надеетесь, что остальное не задето. Баг всплывает через неделю, и находит его не автор, а пользователь.

Стало. Агент сам запускает проверку в конце своей работы. Если что-то сломано, он видит красный тест раньше, чем вы вообще узнаете о проблеме, и чаще всего чинит сам. Пул-реквест со сломанным кодом физически не проходит через git-провайдера: видно это на уровне списка коммитов, а не через жалобу пользователя.

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

08Чтобы не споткнуться

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

Не путать библиотеку Playwright и Playwright MCP. Первое, инструмент внутри теста, который имитирует браузер и не требует нейронки вообще. Второе, инструмент для самого агента, чтобы он открывал настоящий браузер и кликал по интерфейсу сам. Нужны оба, но по разным причинам.

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

09А если…

А если у меня уже большой проект с кучей файлов?

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

А если приложение не веб, а мобильное или десктопное?

Playwright и его MCP, инструмент именно для веба. Для другой платформы спросите своего агента напрямую, какой MCP или библиотека подойдёт под ваш стек: принцип шести уровней и девяти промптов от этого не меняется.

А если тесты занимают слишком много времени на каждый прогон?

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

А если пул-реквест с красными тестами всё равно можно смержить?

Это отдельная настройка на стороне git-провайдера, правило обязательной проверки перед слиянием. Без неё статус проверки просто отображается, но не блокирует кнопку слияния физически. Попросите агента настроить это правило отдельно.

А если агент сам предлагает просто удалить тест, который не проходит?

Это тревожный звонок, а не решение. Удаление или чрезмерное упрощение теста убирает сигнал о проблеме, а не саму проблему: она остаётся в коде и всплывёт позже в другом месте.

10Зачем на самом деле

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

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

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

11Источники

Playwright: https://playwright.dev/ Официальная документация библиотеки для браузерных и E2E-тестов.

Playwright MCP: https://github.com/microsoft/playwright-mcp Инструмент, который даёт ИИ-агенту возможность самому открывать браузер и взаимодействовать со страницей.

GitHub Actions: https://docs.github.com/actions Проверки на сервере при пул-реквесте, конфигурация workflow.

Защита веток на GitHub: https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches Правило, которое блокирует слияние при красных тестах: без него статус проверки не более чем индикатор.

Vitest: https://vitest.dev/ Один из инструментов юнит- и интеграционного тестирования для JS/TS-стека.

Исходное видео: «Автотесты для вайбкодера: гайд с нуля. Юнит, API, E2E, Playwright MCP, CI», youtube.com/watch?v=kCct1-2ybBg Первоисточник структуры шести уровней и девяти промптов, изложенных в этом гайде своими словами.