Claude Agent SDK позволяет встроить агента проверки репозитория в собственное приложение: программа задаёт задачу, доступные инструменты, правила подтверждения и получает результат для разработчика. Для безопасного первого сценария агент читает разрешённые файлы, объясняет найденные риски и показывает diff как материал для проверки. Решение о правке, запуске команд и дальнейшем использовании результата принимает человек через сервер приложения.
SDK внутри приложения
Claude Agent SDK предоставляет программный агентный цикл, инструменты работы с файлами, правила разрешений и сессии для Python и TypeScript. Внутреннее приложение определяет доступ к репозиторию и маршрут подтверждения действий.
В официальном обзоре SDK библиотека описана как способ встроить возможности Claude Code в приложение на Python или TypeScript. Это другой рабочий вход по сравнению с установкой Claude Code для разработчика: там человек запускает терминальный интерфейс, здесь приложение само создаёт запрос и обрабатывает поток результатов. У команды появляются собственные экран проверки, журнал разрешений и связь с задачей в разработке.
Для начала сформулируйте одну проверяемую задачу: найти изменения, способные нарушить обработку ошибки в выбранном модуле. Приложение передаёт путь к разрешённой копии репозитория и формулировку вопроса. Агент читает код и связанные тесты, после чего возвращает находки с путями файлов и объяснением. Разработчик открывает названные строки и сверяет вывод. Такая схема помогает заметить полезную подсказку модели, сохраняя исходным источником сам код. Каждую находку связывайте с конкретной версией файла: при изменении ветки прежняя ссылка на строку может вести к другому коду.
SDK включает инструменты чтения, редактирования и запуска команд, поэтому границу задачи следует задавать до старта сессии. Право на вызов каждого инструмента задаёт политика конкретного приложения. Для обзорного режима оставьте путь к чтению и поиску по выбранному дереву файлов; запись, сетевые вызовы и команды обрабатывайте по отдельной политике. Полезный контекст общего процесса есть в статье об ИИ-агентах для разработки.
Права инструментов
Перед запуском определите границы файлов, доступные операции и владельца подтверждения. Приложение выдаёт агенту изолированную копию нужного фрагмента репозитория, исключает секреты и задаёт политику вызовов. Сервер проверяет, кто запросил анализ и какое дерево файлов ему положено видеть. Настройки SDK дополняют этот барьер: они управляют разрешениями инструментов, а промпт с просьбой «работай осторожно» остаётся текстовым напоминанием. Отдельно закрепите, кто вправе расширять область файлов и кто принимает предложения о записи. Эти роли должны совпадать с реальными полномочиями команды.
| Действие | Решение политики | Проверка человека |
|---|---|---|
| Чтение файла | Допуск только в выбранном дереве | Сверить путь и актуальную версию |
| Поиск по коду | Ограничение областью задачи | Проверить контекст найденного совпадения |
| Запуск команды | Отдельное разрешение по типу команды | Оценить влияние на окружение |
| Редактирование | Черновик в изолированной копии | Проверить diff перед применением |
Документация по разрешениям различает правила допуска и запрета, режимы и обработчик решения во время вызова. Важная деталь: остальные инструменты сохраняются в наборе агента при отсутствии явных запретов. Для строгой области нужны явные запреты, настройка режима и проверка вызовов на стороне приложения. Операции, которые требуют согласования, показывайте уполномоченному разработчику с именем инструмента, аргументами и ожидаемым эффектом.
Файлы репозитория могут содержать текст, обращённый к агенту как инструкция. Относитесь к нему как к данным проекта. Проверка пути и полномочий происходит до вызова инструмента, а подтверждение действия хранится на сервере. Такой порядок помогает удержать границу даже при ошибочной подсказке внутри комментария к коду.
Сессия и след
Сессия связывает вопрос, вызовы инструментов, результаты и ответ агента. В официальном руководстве по сессиям указано, что историю можно продолжить; при этом история разговора отличается от снимка файловой системы. Поэтому приложение записывает идентификатор версии репозитория рядом с результатом проверки. При продолжении обсуждения разработчик видит, к какой версии кода относилась прежняя находка.
- Получите запрос разработчика и зафиксируйте идентификатор версии кода.
- Проверьте права пользователя на выбранный репозиторий и подготовьте ограниченную рабочую копию.
- Запустите анализ с разрешёнными инструментами чтения и поиска; записывайте запрошенные вызовы.
- Соберите находки с путями файлов, исходными фрагментами и объяснением причины риска.
- Покажите результат разработчику и сохраните его решение по каждой находке.
Идентификатор сессии нужен для продолжения разговора, а журнал действий — для разбора того, на чём основан вывод. Храните в журнале запрос, версию кода, тип инструмента, решение по допуску и ссылку на результат. Секреты и лишние фрагменты кода туда переносить незачем; доступ к журналу определяют роли приложения. Если состояние рабочей копии изменилось, повторите чтение спорного участка перед утверждением вывода. При повторном запросе приложение поднимает прежний журнал и сначала сравнивает версию репозитория. Сравнивайте и содержимое файла: одинаковое название встречается у разных редакций.
Для формул в коде и полной выгрузки результатов тестов используйте парсер или скрипт. Языковая модель объясняет закономерность и предлагает гипотезы о дефекте, разработчик сверяет расчёт и исходные строки. Такой раздел ответственности особенно полезен, когда короткое объяснение звучит убедительно, а фактическое условие ошибки скрыто в соседнем модуле.
Проверка diff
Если задача предполагает изменение файла, сначала получайте предложение в изолированной рабочей копии. Покажите разработчику diff с контекстом, исходным заданием и результатом проверок. Модель может объяснить мотив правки, но корректность подтверждают чтение кода и подходящие тесты. Сервер приложения проверяет право пользователя принять изменение и фиксирует явное решение. Без такой проверки совет агента остаётся черновиком.
Отдельно сверяйте область изменения. Правка, относящаяся к одной функции, может затронуть соседний файл, конфигурацию или тестовую фикстуру. В карточке находки перечислите все изменённые пути и причину каждого изменения. Если появились неожиданные файлы, верните предложение на разбор. Сборка, тесты и статический анализ дают технические сигналы; владелец кода оценивает смысл и совместимость с требованиями проекта. Для спорной правки сохраните замечание разработчика рядом с diff. Это даёт владельцу следующей проверки контекст и показывает, почему предложение отклонили.
Предложите пилот на изолированном модуле с понятным владельцем. Начните с анализа без записи, затем сравните выводы агента с исходным кодом и замечаниями разработчика. Возможность редактирования добавляйте после утверждения маршрута diff и прав на подтверждение.
Если требуется связать проверку репозитория с задачами команды, это уже сценарий внедрения ИИ-агента. Состав работ зависит от структуры репозитория, правил доступа, набора проверок и способа хранения результатов. Напишите нам, посчитаем под вашу задачу после разбора рабочего контура и требований к подтверждению. Перед обсуждением подготовьте обезличенное описание процесса проверки кода.
Хотите проверить маршрут diff для вашего репозитория?
Приёмка пилота
Проверка пилота начинается с контрольного набора: изменение с явной ошибкой, безопасная правка, спорный случай и файл за пределами разрешённого дерева. Заранее запишите ожидаемый результат для каждого случая. Агент должен обосновать находки фрагментами кода, показать неопределённость в споре и получить отказ при попытке доступа к закрытому пути. Журнал подтверждает, что запрет сработал до выдачи содержимого. Зафиксируйте также реакцию на запрос запуска команды без разрешения. Проверка проходит успешно, когда сервер блокирует действие и сохраняет понятную причину отказа.
Проверьте также переход между сессиями. Продолжение разговора должно сохранять связь с исходным запросом, а новая версия репозитория требует повторной сверки. История сессии сохраняет диалог; состояние файлов восстанавливают отдельным механизмом, как прямо указано в документации SDK. Если приложение сравнивает diff после обновления ветки, оно сначала фиксирует новую версию и проверяет изменившиеся участки. Разработчик получает обе ссылки и понимает, какая находка относится к какой редакции.
После пилота сохраните принятые правила доступа, список запрещённых действий, образцы карточек находок и решения владельцев. Для дальнейшего расширения подготовьте контрольные вопросы по новым модулям и сверяйте ответы с кодом. Подход к таким проверкам раскрыт в статье о тестировании ИИ-агентов. Главный критерий здесь практический: вывод можно воспроизвести по версии репозитория и журналу действий, а применение правки подтверждено человеком с полномочиями. При расширении на новый репозиторий согласуйте его владельца и отдельную область доступа. Копирование прежней настройки допустимо лишь после проверки путей и ролей.