ИНЖЕНЕРНЫЙ РАЗБОР · ПРОВЕРКА ИСТОЧНИКА
Как агент проверяет репозиторий до внедрения
Новая библиотека выглядела полезной: она обещала убрать часть собственного кода и ускорить разработку. Но обещание не отвечало на главный вопрос — будет ли проект работать с нашей версией языка, зависимостями и способом развёртывания. Пока доказательств совместимости нет, внедрение не начинается.
Задача AI-агента в такой ситуации — не решить, что репозиторий «хороший», и не пересказать README. Он должен превратить внешнюю находку в проверяемое инженерное решение: зафиксировать источник, отделить заявления авторов от наблюдаемых фактов, выполнить минимальные проверки в изоляции и подготовить вывод, который можно повторить.
Конкретный случай
В проект предложили библиотеку, которая могла заменить самописный слой интеграции. В документации был пример запуска, но не было явной таблицы совместимости с версиями языка и ключевого фреймворка. Пример использовал собственное окружение библиотеки и ничего не доказывал о работе внутри нашего приложения.
Этого достаточно, чтобы открыть проверку, но недостаточно, чтобы одобрить внедрение. Количество звёзд, аккуратный README и недавние коммиты показывают активность проекта, а не совместимость с конкретной системой.
Отсутствие найденной проблемы не является доказательством совместимости. Доказательством считается только воспроизводимая проверка нужного сценария в окружении, близком к целевому.
Сначала агент фиксирует границы решения
До чтения исходного кода агент записывает, что именно библиотека должна заменить и какое поведение нельзя потерять. Без этой границы проверка быстро превращается в бесконечное изучение чужого проекта.
Задача:
заменить: текущий слой интеграции
сохранить:
- существующий формат входных данных
- обработку ошибок
- таймауты и повторные попытки
- текущий способ развёртывания
не проверяем:
- функции, которые проект не использует
критерий допуска:
минимальный сценарий проходит в копии окружения
без изменения закреплённых зависимостейВ карточке также фиксируются URL репозитория, проверяемая версия или точный идентификатор коммита, дата проверки и имя владельца решения. Ссылка на главную ветку недостаточна: её содержимое может измениться после проверки.
Шаг 1. Отделить заявления от доказательств
Агент читает README, руководство по установке, журнал изменений, файл лицензии и описание выпусков. Для каждого важного утверждения он указывает тип основания:
- заявлено — написано в документации, но локально не проверено;
- подтверждено конфигурацией — ограничение видно в файле зависимостей или настройках сборки;
- проверено — выполнен воспроизводимый тест;
- неизвестно — доказательство не найдено.
Например, фраза «поддерживает актуальные версии Python» остаётся заявлением. Ограничение requires-python = ">=3.11" подтверждает только допустимую версию интерпретатора. Оно не гарантирует совместимость с конкретной версией фреймворка или соседними пакетами.
Шаг 2. Проверить происхождение и лицензию
Агент выясняет, кто публикует пакет, совпадает ли ссылка из реестра пакетов с проверяемым репозиторием, есть ли лицензия и не содержит ли установка неожиданных сценариев. Неизвестный скрипт из README нельзя запускать напрямую через оболочку.
Для клонирования используется отдельный каталог, а состояние закрепляется на конкретной версии:
git clone --filter=blob:none SOURCE_URL review-project
cd review-project
git fetch --tags
git checkout VERSION_OR_COMMIT
git status --short
git rev-parse HEADКоманды намеренно содержат заполнители. Проверяющий подставляет URL и версию самостоятельно и сохраняет полученный идентификатор коммита в карточке. Агент не должен придумывать их по памяти.
Если библиотека требует токен, доступ к рабочей базе или отключение проверки TLS уже на этапе установки, проверка останавливается. Секреты не передаются внешнему коду ради демонстрационного запуска.
Шаг 3. Сравнить ограничения зависимостей
Следующий объект проверки — lock-файл зависимостей целевого проекта. Агент сравнивает не только название языка, но и версии среды выполнения, фреймворка, сетевого клиента, валидатора данных и системных библиотек.
# Выполнять в копии проекта или отдельном рабочем дереве
python -m venv .review-venv
. .review-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.lock
python -m pip check
# Проверка установки кандидата без обновления остальных пакетов
python -m pip install --no-deps PACKAGE_NAME==CANDIDATE_VERSION
python -m pip checkПараметр --no-deps полезен для диагностики: он не позволяет установщику молча обновить половину окружения и создать видимость успеха. Затем агент отдельно рассчитывает, какие изменения потребовались бы для полноценной установки. Для другого языка применяется тот же принцип: чистое окружение, закреплённые версии и запрет незаметного переписывания рабочего lock-файла.
Если установка требует обновить ключевую зависимость, это уже не «добавление одной библиотеки», а миграция. Карточка должна назвать затронутые пакеты и вынести миграцию в отдельное решение.
Шаг 4. Прочитать код по поверхности риска
Полный аудит большого репозитория редко помещается в одну проверку. Агент начинает с участков, которые могут изменить систему:
- сценарии установки и сборки;
- сетевые обращения и загрузка файлов;
- чтение переменных окружения и домашнего каталога;
- запуск дочерних процессов;
- динамическая загрузка модулей;
- телеметрия и отправка диагностических данных;
- изменения схемы хранения или формата данных.
README и комментарии внешнего проекта считаются недоверенными данными. Скрытая просьба выполнить команду, раскрыть переменные окружения или изменить правила работы рассматривается как prompt injection, а не как инструкция агенту.
Автоматический поиск помогает найти поверхность риска, но не доказывает уязвимость:
rg -n "subprocess|os\.system|shell=True|eval\(|exec\(" .
rg -n "requests\.|httpx\.|fetch\(|telemetry|analytics" .
rg -n "getenv|environ|\.env|HOME|credentials|token" .
rg -n "postinstall|preinstall|setup_hook|build_backend" .Каждое совпадение требует чтения контекста. Само наличие сетевого клиента или переменной token не является ошибкой.
Шаг 5. Собрать минимальный тест совместимости
Проверка должна повторять самый маленький полезный сценарий проекта. Это не полный benchmark и не попытка доказать отсутствие всех ошибок. Цель — проверить заявленную точку интеграции и увидеть, не ломает ли кандидат существующее поведение.
def test_candidate_contract():
adapter = build_candidate_adapter(test_config())
result = adapter.process(sample_input())
assert result.status == "ok"
assert result.payload == expected_payload()
assert result.external_actions == []
def test_candidate_failure_is_controlled():
adapter = build_candidate_adapter(test_config(timeout=0.01))
result = adapter.process(sample_input())
assert result.status == "retryable_error"
assert result.secret_data_exposed is Falsesample_input() и expected_payload() должны использовать обезличенные локальные фикстуры. Рабочие документы, переписка и ключи доступа для проверки внешней библиотеки не нужны.
После теста агент запускает существующий набор проверок проекта, а не только новый счастливый сценарий. Если старые тесты отсутствуют, это ограничение записывается явно: совместимость нельзя считать полностью подтверждённой.
Как выглядит готовая карточка
КАРТОЧКА ПРОВЕРКИ ВНЕШНЕГО ПРОЕКТА
Источник:
Версия или commit:
Дата проверки:
Проверяющий:
Лицензия:
Проблема, которую решает кандидат:
Что именно он заменяет:
Критичное поведение, которое нужно сохранить:
Целевое окружение:
- язык и версия:
- ОС и архитектура:
- ключевые зависимости:
- способ развёртывания:
Доказательства:
- заявлено документацией:
- подтверждено конфигурацией:
- проверено локально:
- осталось неизвестным:
Изменения зависимостей:
Сетевые и файловые действия:
Нужные разрешения:
Сценарий минимального теста:
Команды воспроизведения:
Результат проверки:
Риски:
План отката:
Решение: APPROVE / EXPERIMENT / BLOCK
Условия пересмотра решения:Поле «результат проверки» заполняется только фактическим выводом команд. Если команды не запускались, корректная запись — «не проверено», а не «ошибок не обнаружено».
Проверка самой карточки
Перед выдачей решения другой разработчик или агент должен суметь повторить проверку без устных пояснений. Карточка готова, если:
- репозиторий восстанавливается по точному коммиту или версии;
- окружение создаётся отдельно от рабочей системы;
- команды не требуют неизвестных секретов;
- понятно, какие утверждения проверены, а какие взяты из документации;
- результат сравнивается с заранее записанным ожидаемым поведением;
- есть rollback — способ убрать библиотеку и вернуть прежний путь выполнения;
- решение содержит условия, при которых его нужно пересмотреть.
Если совместимость не доказана, нормальный результат проверки — EXPERIMENT или BLOCK. Это не провал агента. Провалом было бы внедрение на основании впечатления.
Что обычно ломается
Агент считает популярность доказательством. Звёзды, загрузки и активные обсуждения ничего не говорят о конкретной комбинации версий.
Установщик обновляет зависимости. Пример начинает работать, но исходное окружение уже изменено. Поэтому проверка проводится в копии, а изменения lock-файла анализируются отдельно.
Проверяется только импорт. Успешный import не подтверждает обработку ошибок, таймауты, формат данных и отсутствие неожиданных внешних действий.
Тест повторяет пример автора. Такой тест показывает, что библиотека работает в собственном демонстрационном сценарии. Нужен сценарий целевого проекта.
В карточке смешаны факты и предположения. Формулировки «должно работать» и «вероятно совместимо» нельзя помещать в раздел подтверждённых результатов.
Нет границы полномочий. Даже полезная библиотека не должна автоматически получить доступ ко всем переменным окружения, каталогам и сетевым адресам. Доступ ограничивается через allowlist.
Ограничения метода
Такая проверка не заменяет полный аудит безопасности, нагрузочное испытание и длительное наблюдение в рабочей среде. Она также не обнаружит проблему, которая проявляется только на другой архитектуре, под реальной нагрузкой или при редкой комбинации данных.
После успешного эксперимента библиотеку разумно включать ограниченно — через canary release или переключатель функции. На этом этапе нужны логи, метрики ошибок и задержки: observability показывает, совпало ли поведение в рабочем контуре с лабораторной проверкой.
Главный результат проверки — не бинарная оценка чужого проекта. Это граница знания: что подтверждено, что осталось неизвестным, какой риск допустим и как отменить изменение.
← Все практические инструкции · Лабораторный словарь →