С небольшими правками Claude Code обычно справляется хорошо. Поправить селектор Playwright, добавить тайм-аут, обновить тест или сделать сообщение об ошибке понятнее можно почти без контроля.
Полная интеграция с MegaIndex BrowserAPI требует другого подхода.
В ней одновременно участвуют аутентификация, удаленное подключение, профили, прокси, повторные попытки, переиспользование сессий, логирование, очистка ресурсов и тесты. Эти части связаны между собой, поэтому локальное изменение легко затрагивает весь сценарий.
Неудачная логика повторных подключений может открыть несколько браузеров вместо одного. Пользовательский прокси — нарушить работу профиля. Отладочный вывод — раскрыть пароль из WebSocket URL.
Чтобы не потерять контроль над задачей, достаточно соблюдать четыре правила:
- заранее описать нужное поведение;
- проверить план до начала изменений;
- автоматизировать обязательные проверки;
- после работы изучить Git diff.
Сначала опишите поведение
Запрос:
Добавь поддержку профилей MegaIndex BrowserAPI.
слишком общий.
Из него непонятно:
- где формировать URL подключения;
- какой прокси использовать;
- какие ошибки можно повторять;
- кто отвечает за закрытие браузера.
Лучше сразу задать точные правила:
Добавь поддержку профилей MegaIndex BrowserAPI в существующий клиент Playwright. По умолчанию используй прокси из профиля. Если вместе с задачей передан пользовательский прокси, он должен иметь приоритет. Ошибка аутентификации должна завершать выполнение без повторных попыток. Временные ошибки подключения можно повторять не более двух раз. Каждый удаленный браузер должен закрываться после успешного выполнения, ошибки, тайм-аута или отмены задачи.
Такой запрос сразу задает схему подключения, приоритет прокси, лимит повторных попыток и правила очистки ресурсов.
Отдельно укажите, что менять нельзя:
Не перерабатывай очередь задач. Не изменяй файлы окружения. Не переноси логику подключения в модули автоматизации.
Без этих ограничений локальная задача легко превращается в рефакторинг всего проекта.
Начинайте с режима Plan
Если задача затрагивает несколько модулей, сначала попросите Claude разобраться в существующей архитектуре.
В режиме Plan он может изучить код и подготовить план, не изменяя файлы.
Попросите его выяснить:
- где создается удаленное подключение;
- откуда загружаются учетные данные;
- как формируется WebSocket URL;
- где выбираются профиль и прокси;
- какой компонент владеет браузером;
- как устроены повторные попытки;
- где закрывается сессия;
- какие тесты уже покрывают этот сценарий.
Пример запроса:
Изучи существующую архитектуру браузерной автоматизации и подготовь план добавления поддержки профилей MegaIndex BrowserAPI. План должен включать: 1. Текущую схему подключения к удаленному браузеру. 2. Файлы, которые потребуется изменить. 3. Место формирования WebSocket URL. 4. Правила приоритета пользовательского прокси над прокси профиля. 5. Обработку ошибок аутентификации и временных ошибок подключения. 6. Закрытие браузера после успешного выполнения, ошибки, тайм-аута и отмены. 7. Тесты, которые нужно добавить. 8. Файлы, которые должны остаться без изменений. Не изменяй файлы.
Хороший план должен описывать весь путь: от входных данных задачи до закрытия браузера.
Фраза «обновить клиент и добавить тесты» слишком расплывчата. Из плана должно быть понятно:
- кто создает сессию;
- какой компонент отвечает за нее после создания;
- как разделяются временные и постоянные ошибки;
- где выполняются повторные попытки;
- как исключается создание лишних браузеров;
- где освобождаются ресурсы.
Ошибку в плане проще исправить до начала разработки.
Задавайте конкретные правила в CLAUDE.md
Claude Code читает инструкции из CLAUDE.md и связанных файлов.
Формулировки вроде этих почти бесполезны:
- следуй лучшим практикам;
- пиши чистый код;
- используй правильную архитектуру;
- корректно обрабатывай ошибки.
Проверить их по итоговому diff невозможно.
Намного полезнее конкретные ограничения:
- Формируй WebSocket URL MegaIndex BrowserAPI только в src/browser/connection.ts. - Модули автоматизации должны получать уже инициализированный браузер. - Модули автоматизации не должны самостоятельно создавать URL удаленного браузера. - Не записывай в логи пароли BrowserAPI, пароли прокси и полные WebSocket URL с учетными данными. - Ошибки аутентификации не должны запускать повторное подключение. - Каждый созданный браузер должен закрываться в блоке finally. - Существующие тесты нельзя удалять, пропускать или ослаблять.
Такие правила легко проверить после изменений.
Разделение инструкций на несколько файлов может упростить навигацию, но не уменьшает объем контекста Claude. Полезнее убрать дубли, устаревшие требования и общие фразы, которые нельзя проверить.
Сделайте проверку обязательной
Не стоит каждый раз отдельно напоминать Claude о тестах.
Для BrowserAPI лучше создать постоянную процедуру проверки. Она должна оценивать не только результат выполнения, но и сами изменения.
Это важно, потому что ошибочную реализацию можно формально «починить», удалив тест или ослабив assertion.
Проверка должна:
- запустить тесты BrowserAPI;
- выполнить typecheck или lint;
- проверить git diff;
- убедиться, что тесты не удалены и не пропущены;
- найти ослабленные проверки;
- показать изменения вне утвержденного плана;
- вывести использованные команды и результаты.
Пример отчета:
Проверка: PASS Тесты: - 46 успешно - 0 ошибок - Команда: npm test -- browser Проверка типов: - Успешно - Команда: npm run typecheck Diff: - Изменено 5 файлов - Тесты не удалялись - Тесты не пропускались - Проверки не ослаблялись - Файлы окружения не изменялись Поведение BrowserAPI: - Ошибки аутентификации не повторяются - Пользовательский прокси переопределяет прокси профиля - Браузер закрывается при любом сценарии завершения
Фраза «все работает» ничего не подтверждает. Нужны команды, результаты и список проверенных сценариев.
Проверяйте весь жизненный цикл браузера
Одного теста успешного подключения недостаточно.
Основные проблемы обычно возникают при ошибках, тайм-аутах, повторных попытках и отмене задачи.
Успешное подключение
Клиент должен:
- сформировать правильный WebSocket URL;
- создать только один браузер;
- передать его задаче;
- закрыть после завершения.
Неверные учетные данные
В этом сценарии:
- ошибка должна возвращаться сразу;
- повторного подключения быть не должно;
- логирование не должно раскрывать логин и пароль.
Временная ошибка подключения
Важно проверить:
- ограничено ли число повторных попыток;
- не создается ли новая задача или лишняя сессия;
- содержит ли итоговая ошибка достаточно данных для диагностики.
Переопределение прокси
Правила должны быть однозначными:
- без пользовательского прокси используется прокси профиля;
- пользовательский прокси имеет приоритет;
- неверные данные отклоняются до подключения к BrowserAPI.
Закрытие браузера
Очистка ресурсов должна срабатывать после:
- успешного выполнения;
- ошибки навигации;
- тайм-аута;
- падения страницы;
- разрыва удаленного соединения;
- отмены задачи.
Переиспользование сессий
Если сессии можно использовать повторно, убедитесь, что:
- одна задача не открывает несколько браузеров;
- просроченная сессия не используется снова;
- одна задача не может закрыть браузер другой.
Именно эти сценарии чаще всего приводят к зависшим сессиям, лишнему расходу трафика и ошибкам, которые сложно воспроизвести локально.
Блокируйте завершение при упавших тестах
Claude может попытаться закончить работу, даже если часть проверок не проходит.
Для этого используется Stop hook. Он запускается перед завершением хода и блокирует его при ошибке.
Схема проста:
- Claude вносит изменения.
- Пытается завершить работу.
- Stop hook запускает проверки.
- Один из тестов падает.
- Завершение блокируется.
- Claude получает текст ошибки.
- Работа продолжается.
Чтобы hook действительно остановил действие, он должен завершиться с кодом 2. Код 1 может зарегистрировать ошибку, но не всегда блокирует выполнение.
Пример:
#!/usr/bin/env bash set -u npm test -- browser status=$? if [ "$status" -ne 0 ]; then echo "Тесты BrowserAPI завершились с ошибкой. Исправь их перед завершением задачи." >&2 exit 2 fi npm run typecheck status=$? if [ "$status" -ne 0 ]; then echo "Проверка типов завершилась с ошибкой. Исправь ошибки перед завершением задачи." >&2 exit 2 fi exit 0
Конфигурация hooks может различаться между версиями Claude Code, но принцип остается тем же:
Пока обязательные проверки не проходят, задача не завершена.
Не допускайте утечки учетных данных
URL BrowserAPI может содержать логин и пароль. Пользовательский прокси — еще одну пару учетных данных.
Они могут попасть в:
- команды оболочки;
- отладочный вывод;
- сообщения об ошибках;
- скопированную конфигурацию;
- снимки тестов;
- логи CI.
Hook PreToolUse позволяет проверить команду до ее запуска.
С его помощью можно блокировать или изменять команды, которые раскрывают:
- содержимое .env-файлов;
- пароли BrowserAPI;
- пароли прокси;
- полные WebSocket URL с авторизацией;
- заголовки Authorization.
Безопасный лог:
Подключение к MegaIndex BrowserAPI Профиль: profile_123 Режим прокси: пользовательский Попытка: 1 из 3
Небезопасный лог:
Подключение к ws://username:[email protected]:9222
Полный URL с учетными данными не должен появляться в приложении, терминале или CI.
Если hook изменяет входные данные инструмента, он должен вернуть весь объект, включая неизмененные поля. Иначе часть аргументов может потеряться.
Выбирайте режим разрешений под задачу
Для разных этапов интеграции нужен разный уровень доступа.
| Режим | Когда использовать | Ограничение |
|---|---|---|
| Plan | Первичная интеграция, аутентификация, прокси, сессии, миграции и production-конфигурация | Claude не может изменять файлы |
| Accept edits | Небольшие исправления, тесты, документация и логирование | Нужен контроль разработчика |
| Auto | Продолжительная работа после настройки hooks и тестов | Не проверяет правильность реализации |
| Bypass permissions | Изолированные контейнеры и одноразовые виртуальные машины | Отключает стандартные ограничения |
Plan
Этот режим подходит для задач, связанных с:
- первичной интеграцией BrowserAPI;
- аутентификацией;
- маршрутизацией прокси;
- жизненным циклом браузера;
- хранением профилей;
- миграциями;
- production-конфигурацией.
Claude сможет изучить проект, но не сможет менять файлы.
Accept edits
Используйте его для работы под наблюдением разработчика:
- небольших исправлений;
- добавления тестов;
- изменения логирования;
- обновления документации;
- локальных улучшений автоматизации.
Auto
Переходить в Auto стоит только после настройки hooks и обязательных проверок.
Режим может остановить действие, которое явно выходит за рамки задачи или выглядит опасно. Но он не определяет, правильно ли работает код.
Например, Claude может добавить повторное подключение, которое открывает новый браузер при каждой попытке. Для локальной системы такое действие не выглядит опасным, хотя сама реализация неверна.
Рабочая схема:
- утвержденный план;
- режим Auto;
- Stop hook;
- автоматическая проверка;
- ручной анализ diff.
Bypass permissions
Не используйте этот режим на рабочем компьютере с реальными данными BrowserAPI, прокси, базы данных или платежных сервисов.
Он подходит только для изолированной среды с одноразовыми учетными данными.
Не теряйте контекст в длинных сессиях
Большая интеграция часто требует нескольких циклов изменений и тестирования. Чем длиннее сессия, тем выше риск потерять решения, принятые в начале работы.
Указывайте, что сохранить при /compact
Не запускайте /compact без пояснений.
Лучше сразу перечислить детали, которые должны остаться в сводке:
/compact Сохрани информацию о жизненном цикле MegaIndex BrowserAPI, приоритете прокси, лимитах повторных попыток, защите учетных данных и закрытии браузера.
Важно сохранить:
- где формируется WebSocket URL;
- какой прокси имеет приоритет;
- какие ошибки можно повторять;
- кто владеет браузерной сессией;
- где выполняется очистка;
- какие тесты нельзя менять.
Откатывайте неудачные изменения
Если Claude выбрал неправильный подход, новые уточнения часто оставляют в проекте лишние функции, классы и ветки логики.
В такой ситуации лучше вернуться к точке до ошибочной реализации.
Откат оправдан, если Claude:
- заменил работающий менеджер сессий;
- добавил вторую систему повторных попыток;
- перенес учетные данные в код;
- без причины изменил очередь задач;
- переписал тесты под неправильное поведение.
Удалить неудачный подход обычно быстрее, чем исправлять его частями.
Задавайте измеримый результат
Условие завершения должно проверяться автоматически.
Хороший вариант:
/goal все тесты подключения BrowserAPI, переопределения прокси, повторных попыток и закрытия браузера проходят, а проверка типов завершается без ошибок
Плохой вариант:
/goal сделать интеграцию BrowserAPI надежной
Первую цель можно проверить. Вторую — нет.
При этом успешных тестов недостаточно. Нужно убедиться, что Claude не удалил часть проверок и не ослабил assertions.
Сначала diff, потом отчет
В финальном сообщении Claude может написать, что поддержка профилей добавлена, повторные попытки исправлены, тесты написаны и все проверки проходят.
Но из этого не видно, какие файлы он изменил и что именно сделал внутри.
Проверяйте репозиторий напрямую:
git status git diff --stat git diff
Начните с файлов, указанных в плане.
Удобный порядок проверки:
- подключение и аутентификация;
- профили и прокси;
- повторные попытки;
- владение браузером и очистка ресурсов;
- тесты;
- конфигурация и зависимости.
Обратите внимание на:
- учетные данные в логах;
- дублирование логики подключения;
- повторные попытки после ошибок аутентификации;
- отсутствующие блоки finally;
- бесконечные циклы;
- общее изменяемое состояние профиля;
- удаленные тесты;
- ослабленные проверки;
- несвязанные изменения зависимостей.
Результат работы — это diff. Итоговое сообщение Claude — только его описание.
Проверяйте изменения в новой сессии
Сессия, которая писала код, уже привыкла к выбранному решению. Новая сессия смотрит на diff без этого контекста и чаще замечает спорные места.
Пример:
git diff main | claude -p --bare
Запрос для ревью:
Проверь этот diff интеграции MegaIndex BrowserAPI. Обрати внимание на: - создание нескольких удаленных браузеров для одной задачи; - отсутствие закрытия браузера; - учетные данные в логах; - неправильный приоритет прокси; - повторные попытки после ошибок аутентификации; - бесконечные циклы повторного подключения; - общее изменяемое состояние профилей; - удаленные, пропущенные или ослабленные тесты; - изменения, не относящиеся к задаче. Верни только конкретные замечания с именами файлов и уровнем критичности.
Для CI удобнее использовать структурированный формат:
{
"severity": "high",
"file": "src/browser/connection.ts",
"line": 84,
"issue": "Ошибка аутентификации попадает в цикл повторных подключений",
"recommendation": "Завершать выполнение сразу после отклонения учетных данных сервером"
}Такой вывод проще фильтровать, сохранять и публиковать в pull request.
Рабочий процесс интеграции BrowserAPI
Шаг 1. Опишите поведение
Укажите:
- как создается подключение;
- какой прокси имеет приоритет;
- сколько раз можно повторить подключение;
- когда закрывается браузер;
- как обрабатываются ошибки;
- какие файлы нельзя менять.
Шаг 2. Запустите Plan
Попросите Claude изучить архитектуру и назвать файлы, которые потребуется изменить.
Шаг 3. Проверьте план
Убедитесь, что в нем учтены сессии, учетные данные, прокси, повторные попытки, очистка ресурсов и тесты.
Шаг 4. Разрешите изменения
Используйте Accept edits для работы под контролем или Auto после настройки hooks.
Шаг 5. Запустите проверки
Выполните тесты, typecheck и анализ diff.
Шаг 6. Заблокируйте завершение при ошибке
Настройте Stop hook, который не позволит закончить задачу с упавшими проверками.
Шаг 7. Проверьте diff вручную
Сопоставьте каждый измененный файл с утвержденным планом.
Шаг 8. Проведите независимое ревью
Откройте новую сессию Claude и передайте ей итоговый diff.
Пример запроса для MegaIndex BrowserAPI
Добавь поддержку профилей MegaIndex BrowserAPI в этот проект. Требования: 1. Используй существующий клиент удаленного браузера Playwright. 2. Формируй WebSocket URL с учетными данными только в модуле подключения к браузеру. 3. По умолчанию используй прокси из профиля. 4. Пользовательский прокси, переданный вместе с задачей, должен иметь приоритет над прокси профиля. 5. Ошибка аутентификации должна завершать выполнение без повторных попыток. 6. Временные ошибки подключения можно повторять не более двух раз. 7. Каждый созданный браузер должен закрываться после успешного выполнения, ошибки, тайм-аута или отмены. 8. Не записывай в логи пароли BrowserAPI, пароли прокси и полные WebSocket URL с учетными данными. 9. Добавь тесты для успешного подключения, неверных учетных данных, переопределения прокси, ограничения повторных попыток и закрытия браузера. 10. Не удаляй, не пропускай и не ослабляй существующие тесты. 11. Не изменяй .env-файлы и код очереди задач, не связанный с интеграцией. Начни в режиме Plan без изменения файлов. Верни: - текущий жизненный цикл браузера; - файлы, которые потребуется изменить; - план реализации; - список новых тестов; - возможные риски; - файлы, которые останутся без изменений. Не изменяй файлы до утверждения плана.
Claude Code можно использовать и для крупных задач по интеграции MegaIndex BrowserAPI. Но полагаться только на его итоговый отчет не стоит.
Нужны точные требования, проверенный план, обязательные тесты, защита учетных данных и ручная проверка diff. Иначе даже рабочая на первый взгляд реализация может оставить после себя лишние браузеры, неверную логику повторных подключений или утечку доступа.
Обсуждение