Проблема обычно не в том, чтобы получить код. Гораздо сложнее понять, действительно ли он работает.
В проектах на MegaIndex BrowserAPI это особенно важно. Изменения могут выглядеть корректно в diff, но ломаться при запуске в реальном удаленном браузере. Скрипт может успешно подключаться, но оставлять незакрытые сессии, проходить модульные тесты и падать при работе через CDP, бесконечно повторять запросы, выводить адрес подключения в логи или возвращать пустой результат, не считая это ошибкой.
Чем меньше вы контролируете агента вручную, тем больше проверок должно выполняться автоматически.
Практическая схема состоит из трех уровней:
- CLAUDE.md задает правила работы с проектом;
- skills описывают повторяемые процедуры;
- hooks запускают обязательные проверки, которые нельзя пропустить.
Основной принцип:
Инструкция подсказывает агенту, как действовать. Хук решает, можно ли принять результат.
Проблема не в генерации кода
Предположим, Node.js-сервис использует Playwright для подключения к MegaIndex BrowserAPI. Вы просите Claude Code добавить постоянные браузерные профили, повторять неудачные переходы и сохранять результаты задач в структурированном формате.
Изменения могут затронуть:
- модуль подключения к BrowserAPI;
- создание браузерных контекстов;
- выбор профиля;
- настройки прокси;
- повторные попытки;
- закрытие сессий;
- проверку результатов;
- модульные и интеграционные тесты.
После этого Claude может выдать аккуратный отчет:
Добавлены постоянные браузерные профили. Реализованы повторные попытки. Обновлены тесты. Все проверки пройдены.
Но такой отчет сам по себе ничего не доказывает.
Он не подтверждает, что:
- подключение к удаленному браузеру действительно проверялось;
- сессия закрывается после исключения;
- лимит повторных попыток соблюдается;
- один профиль не используется несколькими задачами одновременно;
- результат содержит реальные данные;
- тесты не были ослаблены ради успешного прохождения;
- учетные данные не попали в логи;
- команды из отчета действительно запускались.
При автономной работе слова агента не должны считаться доказательством.
Три уровня надежного процесса
Инструкции лучше разделить на правила проекта, повторяемые процедуры и обязательные проверки.
| Уровень | Назначение | Пример для BrowserAPI |
|---|---|---|
| CLAUDE.md | Правила, действующие для большинства задач | Параметры подключения к BrowserAPI загружаются только из переменных окружения |
| Skill | Процедура для определенного типа работы | Запустить тесты, изучить diff, выполнить smoke-тест BrowserAPI и приложить результаты |
| Hook | Обязательная проверка | Не разрешать завершение задачи, пока тесты падают или появились новые пропущенные тесты |
Хранить все инструкции в одном большом файле не стоит. Чем длиннее документ, тем проще пропустить отдельное требование.
Лучше распределить правила так:
- постоянные соглашения проекта хранить в CLAUDE.md;
- процедуры для конкретных задач — в .claude/skills/;
- условия, которые нельзя нарушать, — в hooks.
Сделайте CLAUDE.md коротким и проверяемым
Слабое правило выглядит так:
Следуй лучшим практикам при работе с BrowserAPI.
Оно слишком общее. Его невозможно проверить, и оно не объясняет, что именно должен сделать Claude.
Лучше сформулировать конкретное требование:
Загружай URL подключения к MegaIndex BrowserAPI из переменной MEGAINDEX_BROWSER_WS_ENDPOINT. Никогда не добавляй его в исходный код, тестовые данные, скриншоты, логи или конфигурационные файлы, которые попадают в репозиторий.
Еще один неудачный пример:
Правильно управляй браузерными сессиями.
Проверяемая версия:
Каждое подключение к BrowserAPI должно закрываться в блоке finally. Не создавай новое подключение, если активную сессию можно безопасно использовать повторно.
CLAUDE.md для проекта BrowserAPI может содержать такие правила:
# Правила браузерной автоматизации - Храни код подключения к BrowserAPI в src/browser/connection.ts. - Загружай URL подключения только из MEGAINDEX_BROWSER_WS_ENDPOINT. - Не выводи в логи URL подключения, cookies, данные прокси и заголовки авторизации. - Закрывай каждое браузерное подключение в блоке finally. - Для каждого цикла повторных попыток устанавливай явный лимит. - Возвращай результаты браузерных задач в виде структурированных объектов. - Считай пустой результат ошибкой, если задача явно не допускает отсутствие данных. - Размещай интеграционные тесты удаленного браузера в tests/browserapi/. - Не удаляй, не пропускай и не ослабляй существующие тесты ради успешного прохождения. - Перед завершением задачи запускай модульные тесты и smoke-тест BrowserAPI.
Такие инструкции легко проверить при просмотре кода.
Указывайте правильную замену
Одного запрета недостаточно. Агент должен понимать, какой вариант считается правильным.
Вместо:
Не прописывай адрес браузера прямо в коде.
Используйте:
Загружай адрес браузера из MEGAINDEX_BROWSER_WS_ENDPOINT.
Вместо:
Не используй бесконечные повторные попытки.
Используйте:
Используй общий helper из src/browser/retry.ts и явно задавай максимальное количество попыток.
Вместо:
Не возвращай неструктурированные данные.
Используйте:
Возвращай BrowserTaskResult с полями status, finalUrl, data, errors и completedAt.
Так Claude получает не только ограничение, но и конкретный способ реализации.
Не выделяйте каждое правило
Если каждую строку пометить как IMPORTANT, выделение перестанет работать.
Сильный акцент стоит оставлять только для ошибок с высокой ценой:
- утечки учетных данных;
- незакрытых удаленных сессий;
- ослабления тестов;
- опасных действий с production-аккаунтами.
Остальные требования достаточно сформулировать прямо и однозначно.
Создайте skill для проверки изменений BrowserAPI
Проверка не должна зависеть от того, вспомнили ли вы попросить Claude запустить тесты.
Для этого можно создать отдельный skill, который используется после изменения кода и перед завершением задачи.
Пример файла:
.claude/skills/verify-browserapi/skill.md
Пример содержимого:
--- name: verify-browserapi description: Запускай после изменений, связанных с BrowserAPI, и перед завершением задачи. --- Проверь изменения по следующей процедуре: 1. Запусти модульные тесты. 2. Запусти проверку типов TypeScript. 3. Выполни smoke-тест BrowserAPI на настроенной тестовой странице. 4. Изучи полный git diff. 5. Убедись, что ни один тест не был удален, пропущен, ослаблен или заменен менее строгой проверкой. 6. Убедись, что в diff нет адресов BrowserAPI, cookies, паролей, данных прокси и заголовков авторизации. 7. Убедись, что браузерные подключения закрываются как при успешном выполнении, так и при ошибках. 8. Убедись, что все циклы повторных попыток имеют конечный лимит. 9. Убедись, что созданные файлы результатов содержат обязательные поля. 10. Сообщи итог проверки с выводом команд, списком измененных файлов, количеством тестов и найденными рисками. Не сообщай об успешном завершении, если хотя бы одна обязательная команда не была выполнена.
Такой skill нужен не ради сложной логики. Его задача — каждый раз применять одну и ту же процедуру проверки.
Без него одна сессия может запустить тесты, но не посмотреть diff. Другая изучит diff, но не подключится к реальному браузеру. Третья примет нулевой код завершения, хотя скрипт вернул пустой объект.
Что должен проверять smoke-тест BrowserAPI
Smoke-тест должен быть небольшим, стабильным и полностью контролироваться проектом.
Не стоит использовать случайный сторонний сайт как единственную тестовую цель. Внешняя страница может измениться, заблокировать запрос или вернуть другой контент в зависимости от региона.
Хороший smoke-тест должен:
- подключиться к MegaIndex BrowserAPI;
- открыть контролируемую тестовую страницу;
- дождаться известного элемента;
- выполнить простое действие через JavaScript;
- проверить изменение DOM;
- сохранить скриншот;
- вернуть структурированный результат;
- закрыть браузерное подключение.
Пример ожидаемого результата:
{ "status": "passed", "finalUrl": "https://staging.example.com/browser-test", "heading": "Browser test page", "interactionCompleted": true, "consoleErrors": [], "screenshot": "artifacts/browserapi-smoke.png" }Тест должен завершаться ошибкой, если:
- не удалось подключиться к браузеру;
- истекло время ожидания навигации;
- нужный элемент отсутствует;
- действие не изменило страницу;
- результат не содержит обязательных полей;
- сессию не удалось корректно закрыть.
Нулевого кода завершения недостаточно, если скрипт вернул пустой объект.
Добавьте Stop hook
Skill напоминает Claude выполнить проверку. Stop hook не позволяет ее пропустить.
Он запускается, когда Claude пытается завершить работу. Если проверка не пройдена, хук блокирует завершение и возвращает ошибку агенту.
Пример скрипта:
#!/usr/bin/env bash set -uo pipefail FAILED=0 echo "Запуск модульных тестов..." npm test || FAILED=1 echo "Проверка типов..." npm run typecheck || FAILED=1 echo "Запуск smoke-теста BrowserAPI..." npm run test:browserapi || FAILED=1 echo "Проверка форматирования diff..." git diff --check || FAILED=1 echo "Поиск новых пропущенных тестов..." if git diff --unified=0 -- '*.ts' '*.tsx' '*.js' '*.mjs' \ | grep -E '^\+.*\b(test|it|describe)\.skip\b|^\+.*\b(xit|xdescribe)\b' then echo "Обнаружены новые пропущенные тесты." FAILED=1 fi echo "Поиск возможных секретов BrowserAPI..." if git diff --unified=0 \ | grep -E '^\+.*(ws://|wss://).+@|^\+.*(proxy_password|browser_password|authorization).*=.+' then echo "В diff обнаружены возможные учетные данные." FAILED=1 fi if [ "$FAILED" -ne 0 ]; then echo "Проверка не пройдена. Claude должен продолжить работу." exit 2 fi echo "Проверка пройдена." exit 0
Главная деталь здесь — код завершения.
Код 1 не блокирует завершение Claude Code через hook. Если работу нужно остановить, используйте код 2.
На этом легко ошибиться. Скрипт может завершиться с ошибкой в терминале, но Claude все равно получит возможность закончить задачу, если хук вернул неверный код.
Почему auto mode недостаточно
Auto mode позволяет Claude работать с меньшим количеством запросов на подтверждение. В нем используется классификатор безопасности, который оценивает характер выполняемых действий.
Он может обнаружить:
- неожиданное развертывание в production;
- force push;
- передачу конфиденциальных данных на внешний адрес;
- разрушительные команды вне поставленной задачи.
Но этот классификатор не проверяет корректность реализации.
Ошибочный селектор, незакрытая сессия или пустой результат не обязательно выглядят опасно. Поэтому auto mode может разрешить технически неверное изменение.
Надежная схема выглядит так:
| Механизм | Что он проверяет |
|---|---|
| Классификатор auto mode | Не выглядит ли действие опасным и не выходит ли оно за пределы запроса |
| Stop hook | Проходят ли тесты, проверка типов, smoke-тест BrowserAPI и остальные проверки проекта |
Классификатор оценивает действие. Хук проверяет результат.
Используйте plan mode перед крупными изменениями
Plan mode полезен, когда задача затрагивает несколько частей браузерной инфраструктуры.
Например:
- постоянные браузерные профили;
- выбор прокси для каждой задачи;
- изменение логики повторного использования сессий;
- параллельный запуск браузеров;
- новый формат результатов;
- возобновляемый сбор данных;
- биллинг или лимиты трафика.
Пример запроса:
Перейди в plan mode. Изучи интеграцию с BrowserAPI и подготовь план добавления постоянных браузерных профилей. В плане укажи: - все файлы, которые потребуется изменить; - как создаются и выбираются профили; - как предотвращается одновременное использование одного профиля; - как закрываются браузерные сессии; - как повторяются неудачные операции; - какие тесты необходимо добавить или обновить; - как изменения будут проверяться через MegaIndex BrowserAPI. Не изменяй файлы, пока план не будет проверен.
План нужно внимательно прочитать до начала работы. Его цель — обнаружить ошибочную архитектуру до того, как она распространится по проекту.
Например, Claude может предложить создавать новое удаленное подключение для каждой страницы вместо повторного использования одной сессии. Исправить это в плане значительно проще, чем после реализации.
Не считайте /goal доказательством
Команда /goal помогает Claude продолжать работу до выполнения заданного условия.
Например:
/goal Тесты BrowserAPI проходят, ошибок типов нет, все браузерные сессии корректно закрываются
Это удобно для длинных задач, но не заменяет реальную проверку.
Оценщик анализирует историю сессии. Он видит вывод команд, который показал Claude, но не проверяет независимо репозиторий, браузерную сессию или тестовое окружение.
Поэтому убедительный отчет может удовлетворить условию, даже если работа завершена не полностью.
Используйте следующую схему:
- через /goal опишите, когда Claude должен прекратить исправления;
- через hook запускайте реальные проверки;
- позволяйте hook блокировать завершение при ошибке.
Goal описывает готовый результат. Хук его подтверждает.
Контролируйте длинные сессии
Работа с Browser API часто приводит к длинным сессиям Claude Code, особенно при исправлении селекторов, разборе ошибок навигации и изменениях в нескольких модулях.
Здесь полезны три подхода.
Планируйте до редактирования
Используйте plan mode для архитектурных задач и изменений, затрагивающих несколько файлов.
Сжимайте контекст с указанием приоритетов
Обычное сжатие может удалить важные детали.
Вместо:
/compact
Используйте:
/compact Сохрани контекст о жизненном цикле профилей BrowserAPI, правилах закрытия сессий, падающем интеграционном тесте и файлах, измененных в src/browser/.
Так меньше вероятность, что Claude забудет причину принятого ранее решения.
Возвращайтесь к контрольной точке
Если Claude выбрал неверный архитектурный подход, попытки исправить его внутри той же реализации часто только усложняют код.
В такой ситуации лучше вернуться к моменту до ошибочного решения, сохранить полезный контекст и начать заново.
Это особенно важно, если Claude:
- заменил общий менеджер подключений дублирующимся кодом;
- смешал хранение профилей с состоянием задач;
- добавил повторные попытки сразу на нескольких уровнях;
- переписал тесты под реализацию вместо проверки требуемого поведения.
Используйте worktrees для параллельной работы
Несколько сессий Claude могут конфликтовать, если одновременно изменяют один репозиторий.
Например:
- одна сессия меняет управление подключениями;
- другая добавляет прокси;
- третья обновляет тесты Playwright.
Git worktrees дают каждой сессии отдельное рабочее дерево при общей истории репозитория.
Для каждой сессии также нужны отдельные:
- каталоги результатов;
- тестовые артефакты;
- браузерные профили;
- файлы состояния задач.
Дополнительно можно использовать файл:
.worktreeinclude
В нем перечисляются локальные игнорируемые файлы, которые нужно копировать в каждый worktree, например файл окружения или тестовую конфигурацию.
Не используйте один профиль в нескольких параллельных тестах. Общие cookies, вкладки и состояние аккаунта могут сделать результаты нестабильными.
Используйте структурированный вывод для headless-проверок
На раннем этапе обычно достаточно интерактивного Claude Code и hooks.
Headless-режим становится полезен, когда проверку браузерного кода нужно запускать из CI или отдельных скриптов.
Вместо обычного текста:
Изменения выглядят хорошо. Обнаружен один небольшой риск.
Claude может вернуть структурированный результат:
{ "verdict": "fail", "filesChanged": [ "src/browser/connection.ts", "tests/browserapi/session.test.ts" ], "tests": { "unit": "passed", "typecheck": "passed", "browserapiSmoke": "failed" }, "risks": [ { "severity": "high", "file": "src/browser/connection.ts", "issue": "Browser connection is not closed when page.goto throws" } ] }Такой результат можно:
- сохранить как артефакт CI;
- обработать через jq;
- использовать для остановки pipeline;
- сохранить для последующего анализа;
- сравнить с предыдущими запусками.
Этот уровень стоит добавлять после того, как базовый процесс разработки уже работает стабильно.
Что внедрять сразу, а что отложить
| Возможность | Решение | Причина |
|---|---|---|
| Короткий CLAUDE.md | Внедрить сейчас | Сразу делает изменения более предсказуемыми |
| Skill для проверки BrowserAPI | Внедрить сейчас | Фиксирует единый порядок проверки |
| Stop hook | Внедрить сейчас | Не позволяет завершить работу при провале автоматических проверок |
| Plan mode | Использовать для крупных изменений | Помогает заранее обнаружить архитектурные ошибки |
| Сфокусированный /compact и rewind | Использовать при необходимости | Упрощают длинные сессии отладки и рефакторинга |
| Worktrees | Добавить при параллельной работе | Не нужны, пока с проектом работает одна сессия |
| /goal | Использовать осторожно | Помогает вести итерации, но не заменяет проверку |
| Структурированный headless-вывод | Добавить после MVP | Полезен для CI и автоматических ревью |
| Routines | Отложить | Нужны для регулярных проверок, но не для первого цикла разработки |
| Plugins и Agent SDK | Пока не использовать | Добавляют сложность, не решая основную задачу проверки |
Распространенные ошибки
Код 1 в блокирующем hook
Хук выводит ошибку, но Claude может продолжить работу. Если завершение нужно заблокировать, используйте код 2.
Bypass permissions вне изолированной среды
Bypass mode отключает защитные проверки. Его нельзя использовать на обычной рабочей машине с доступом к реальным репозиториям и учетным данным.
Для автономной работы лучше ограничиться auto mode. Bypass допустим только в полностью изолированном и одноразовом окружении.
Доверие к /goal без внешней проверки
Условие, основанное на истории сессии, может быть выполнено убедительным отчетом. Тесты и smoke-проверка BrowserAPI должны запускаться независимым процессом.
Потеря полей при изменении входных данных
Если hook переписывает входные данные инструмента, новый объект полностью заменяет исходный. Поэтому в нем должны присутствовать все обязательные поля.
Использование imports для сокращения контекста
Imports упрощают организацию файлов, но импортированный текст все равно попадает в контекст. Разделяйте инструкции ради удобства сопровождения, а не ради экономии токенов.
Установка plugins без проверки hooks
Plugin может добавлять собственные hooks, агентов и MCP-конфигурации, работающие с локальными разрешениями.
Наличие автоматического ревью не делает сторонний код безопасным. Для первого надежного процесса BrowserAPI плагины не нужны.
Практическая первая версия
Для начала не требуется сложная автономная система.
Достаточно трех шагов.
1. Обновите CLAUDE.md
Оставьте только конкретные правила:
- где хранится код BrowserAPI;
- откуда загружается адрес подключения;
- как закрываются сессии;
- как ограничиваются повторные попытки;
- в каком формате возвращаются результаты;
- какие тесты необходимо запускать;
- какие действия запрещены.
Удалите формулировки, которые невозможно проверить.
2. Добавьте skill verify-browserapi
Он должен запускать:
- модульные тесты;
- проверку типов;
- smoke-тест удаленного браузера;
- просмотр полного diff;
- проверку строгости тестов;
- поиск секретов;
- проверку закрытия сессий;
- формирование отчета с результатами.
3. Добавьте блокирующий Stop hook
Хук должен:
- запускать обязательные команды;
- обнаруживать новые пропущенные тесты;
- проверять diff на наличие учетных данных;
- возвращать код 2 при ошибке;
- передавать результат Claude для дальнейшего исправления.
Этих трех изменений достаточно, чтобы изменить подход к работе.
Результат принимается не потому, что Claude написал убедительный отчет, а потому, что проверки проекта разрешили завершить задачу.
Заключение
Надежная настройка Claude Code для MegaIndex BrowserAPI строится не вокруг максимальной автономности, а вокруг четкого разделения ответственности:
- CLAUDE.md задает правила;
- skills описывают порядок работы;
- hooks проверяют результат.
Plan mode, worktrees, структурированный вывод и routines можно добавлять по мере роста проекта. Plugins и Agent SDK имеют смысл только тогда, когда появляется реальная необходимость упаковать или встроить этот процесс.
На первом этапе важнее другое: состояние «готово» должно подтверждаться тестами и проверками, а не текстом в отчете агента.
Обсуждение