Агенты и большой код — реестр проблем, методов и инструментов

7 октября 2026 · 15 минут чтения

Как подобрать контекст, сохранить поведение старой системы и проверить результат агента: рабочая карта из 29 проблем с методами, инструментами и контрольными сценариями.

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

Статья о больших существующих системах независимо от языка: монорепозиториях, отдельных приложениях и взаимодействующих сервисах. Вопросы у них общие — поиск контекста, последствия изменения, сохранение поведения и приёмка результата. Способ проверки зависит от языка, фреймворка и устройства приложения.

Исходный разбор появился в закрытом Telegram-сообществе «ИЫшница» на созвоне 30 сентября 2026 года. Я проверил его на полноту и дополнил документацией инструментов и исследовательскими работами. Получилась карта из 29 проблем, а не отчёт об испытаниях: документация прочитана, сравнительный запуск инструментов на одном проекте ещё впереди. Рассказ участника, описание продукта и измеренный эффект — разные основания для вывода, и в тексте я их различаю.

Четыре вопроса перед правкой

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

Перед правкой нужно ответить на четыре отдельных вопроса:

1. Где реализовано поведение? Это задача поиска и чтения контекста.
2. Что затронет изменение? Это задача анализа связей и потребителей.
3. Сохраняется ли нужное поведение? Это задача требований, сценариев и проверки состояния.
4. Можно ли принять и выпустить результат? Это задача качества проверок, совместимости перехода и наблюдения.

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

Мой рабочий вывод: начинать с недостающего доказательства. Если неясно, где функция, нужна навигация. Если теряются последствия, нужна карта связей. Если переносится старая логика, нужен эталон поведения. Каждый добавленный слой закрывает конкретный пропуск. Пятая группа проблем относится не к правке, а к самой работе агента: сессии, команда, ревью и восстановление после сбоя; о ней отдельный раздел.

1. Где реализовано поведение

Контекст — информация, доступная модели в текущей работе. Его полезность зависит от выбора файлов и сохранённых решений, а не от объёма: всё дерево репозитория не объясняет, какие связи существенны для задачи.

Самый дешёвый слой контекста — курируемые проектом документы: файл инструкций агенту в корне репозитория (AGENTS.md, CLAUDE.md), записи архитектурных решений (ADR) и описание модулей. Именно там живёт «история решений», которую агент не восстановит из кода. Если таких документов нет, их стоит завести до первого крупного поручения: короткая карта компонентов, правила проекта, команды сборки и проверок.

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

У средств навигации разные границы. Aider repository map сжимает сведения о символах и выбирает релевантные части в пределах бюджета. Протокол языкового сервера (LSP) задаёт запросы ссылок и входящих/исходящих вызовов; конкретный сервер должен их поддерживать. codespaces от diskd-ai — структурный поиск по коду, не облачная среда GitHub с похожим именем; его документация сама перечисляет ограничения для динамических связей. Для любого анализатора нужно проверить поддержку языка и то, как он видит вызовы через плагины, конфигурацию и внешние сервисы.

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

Контрольная проверка: добавьте новый файл и измените схему без изменения существующего кода. Анализ должен учесть их либо явно сообщить о неполноте. Для направлений связей возьмите маленький пример с заранее известными вызывающими и вызываемыми функциями: синтаксически правильный запрос может отвечать на другой вопрос.

2. Что затронет изменение

Задача одна во всех стеках: найти потребителей изменения и проверить, что их поведение сохранится. Два учебных примера показывают, чем отличается способ проверки.

• TypeScript, монорепозиторий: агент меняет общий тип ответа сервера. Проверка типов внутри репозитория найдёт пакеты, которые его используют. Отдельно выпускаемый клиент она не увидит; его совместимость проверяется сценарием на границе обмена.
• Python или Ruby, приложение с плагинами: агент удаляет функцию, которую текстовый поиск не нашёл среди вызовов. Перед удалением нужно проверить регистрацию плагинов, динамическую загрузку и наблюдаемое выполнение. Отсутствие вызова в логах за короткий период не доказывает, что функция не нужна.

Поэтому единица анализа — проблема и требуемое свидетельство. Язык определяет парсер, правила и способ запуска проверки; в смешанной системе добавляются границы между языками, конфигурацией, запросами и внешними интерфейсами.

В монорепозитории самый дешёвый ответ на вопрос «что затронуто» дают инструменты сборки: расчёт затронутых пакетов (affected) в Nx, Turborepo или Bazel показывает, какие проекты и тесты зависят от изменённого файла. Список владельцев кода (CODEOWNERS) добавляет, кого спросить о затронутом модуле. Оба списка неполны для динамических связей и внешних потребителей, но закрывают большую часть прямых зависимостей бесплатно.

Для точных вопросов нужен граф. Граф свойств кода (CPG) соединяет синтаксис, управление и зависимости данных, и запросы к нему точнее текстового поиска. Для динамической системы граф дополняют фактами загруженного приложения: маршрутами, моделями, реальными схемами и наблюдением выполнения. При этом «связь существует», «путь выполнялся» и «путь больше не нужен» остаются тремя разными утверждениями.

Для данных вопрос тот же: откуда взялась колонка и какие отчёты затронет её изменение. Его решают каталоги происхождения данных (OpenLineage / Marquez, DataHub, OpenMetadata) и инструменты преобразований с собственной картой зависимостей (dbt, SQLMesh, Dataform). Карту кода приложения и карту данных нужно связать через проверяемые границы; ни один из этих инструментов не делает этого сам.

Когда связи известны, их закрепляют как исполняемые ограничения: запрет зависимости между слоями, циклов или конкретного обращения. Для этого есть ArchUnit для Java, Import Linter для Python и dependency-cruiser для JavaScript/TypeScript. ArchUnit импортирует байткод и проверяет правила; после правки агента он покажет новую зависимость между слоями или цикл, но не правильность расчёта скидки.

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

Отдельная ловушка — перепутать проверку описания правила с его исполнением. CodeGraph Михаила Савина описывает контроль архитектуры по графу кода и различает эти операции: принятый YAML-файл ещё не означает, что исходники проанализированы, а результат применён при приёмке.

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

3. Сохраняется ли нужное поведение

Старая система, или legacy, содержит поведение, которое нигде не описано целиком. «Упростить» расчёт скидки можно вместе с редким, но нужным исключением. Для переноса подходит дифференциальное тестирование: старая и новая реализации выполняются на одинаковых входах, результаты сравниваются. Сравнение должно включать ошибки и изменения состояния: два одинаковых ответа ещё не означают одинаковых записей в базе. Версии старой программы и среды входят в эталон; запуск на другом интерпретаторе сдвигает точку сравнения.

Для последовательностей действий полезны проверки свойств и модели состояний. Hypothesis для Python генерирует действия и значения, но ожидаемые свойства задаёт автор теста.

Мутационное тестирование проверяет сами тесты: в программу намеренно вносится изменение, которое они должны заметить. Stryker делает это для JavaScript/TypeScript, C# и Scala; для другого языка нужен свой инструмент. Высокая доля пойманных мутаций говорит о чувствительности тестов, а не о полноте требований.

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

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

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

4. Можно ли принять и выпустить результат

Локальные тесты проходят, а приложение в другом репозитории ломается. Нужно перечислить потребителей и проверить их ожидания. Pact поддерживает контракты потребителя и поставщика для HTTP и сообщений; проверенные примеры известных клиентов не покрывают неизвестные интеграции.

Для несовместимого изменения интерфейса или схемы подходит фазовый переход: расширить поддержку, перенести потребителей и данные, затем удалить старый вариант. Parallel Change называет эти фазы expand, migrate и contract. Поддержка двух вариантов имеет цену, поэтому переход нужно завершить.

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

Работоспособность включает скорость и ресурсы: правильный ответ может стать слишком дорогим из-за повторных запросов к базе. Grafana k6 задаёт пороги по метрикам нагрузки и завершает проверку неуспешно при их нарушении. Сценарий, данные и пороги должны быть своими; пример из документации не является эксплуатационным бюджетом проекта.

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

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

Контрольная проверка: запустите старого клиента против нового поставщика. Прервите перенос данных на копии и запустите его снова. Внесите известное замедление и убедитесь, что порог нагрузки срабатывает.

Работа агента: сессии, команда, ревью и сбои

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

Несколько агентов добавляют координацию. Каждому нужны область работы, вход, ожидаемый артефакт, зависимости и условие завершения; итог проверяется после объединения результатов. Дополнительная рабочая директория Git (worktree) разделяет изменения файлов, но база данных, порты и внешние сервисы остаются общими. Совместное дерево тоже возможно, если процесс интеграции это допускает.

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

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

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

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

Реестр 29 проблем

Это рабочая классификация для выбора проверки, не отраслевой стандарт и не оценка частоты инцидентов. Группы повторяют разделы выше. Средства в строках — примеры кандидатов; часть решений требует процесса и теста, а не нового продукта.

Где реализовано поведение

Что затронет изменение

Сохраняется ли нужное поведение

Можно ли принять и выпустить результат

Работа агента

С чего начать на своём проекте

Выберите 5–10 фиксированных задач: найти реализацию, предсказать последствия правки, сохранить старое поведение, обнаружить запрещённую зависимость и показать неполное основание. Включите известный контрольный дефект. До запуска закрепите ожидаемое качество и лимиты работы.

Сравните три режима с одинаковой моделью, требованиями и задачами:

• текстовый поиск и чтение исходников;
• то же с архитектурной картой;
• то же с выбранными слоями схем и выполнения.

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

В эксперименте METR начала 2025 года опытные разработчики открытых проектов тратили с AI на 19% больше времени. В обновлении февраля 2026 авторы объяснили, почему новые оценки ненадёжны: отбор участников и задач изменился, а время параллельной агентной работы сложно измерять. Для меня это основание измерять эффект на своём процессе вместе с качеством приёмки.

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

Границы исследования

Это карта, а не обзор рынка и не доказанная методология. Инструменты описаны по документации; ни один не испытан сравнительно на одном проекте. Частота проблем не измерена, отдельные пункты — исследовательские риски. Поддержка конкретного стека и эффективность инструментов требуют проверки на месте. Безопасность цепочки зависимостей, лицензии, воспроизводимость сборок, конкурентные операции и отказоустойчивость остались за рамками. Следующий этап — сравнительный пилот на кодовых базах с разными языками и способами связывания компонентов.

Термины

• LSP — протокол взаимодействия с языковым сервером, в том числе для поиска ссылок и вызовов.
• CPG — граф свойств кода, соединяющий структурные представления программы.
• Legacy — существующая система с накопленным поведением и историей решений.
• Дифференциальный тест — сравнение старой и новой реализации на одинаковых входах.
• Мутация — намеренное изменение программы для проверки чувствительности тестов.
• Flaky — нестабильная проверка, исход которой меняется между запусками.
• Потребитель / поставщик — стороны взаимодействия приложений: одна обращается к интерфейсу другой.
• Worktree — дополнительная рабочая директория, подключённая к тому же Git-репозиторию.
• Идемпотентность — свойство операции не создавать дополнительный эффект при повторе.
• Контрольная точка — сохранённое состояние, от которого можно продолжить выполнение.

Инструменты и методики

Кандидаты для пилота по вопросам статьи. Это не рейтинг и не список установленных программ; поддержка языка и версии проверяются на месте.

Методики: направленный поиск контекста; сценарии поведения и BDD; архитектурные тесты; дифференциальные проверки; проверки свойств; мутационное тестирование; совместимое изменение интерфейса через расширение, перенос и удаление; контрольные точки и протокол повтора операций. Их выбор определяется недостающим свидетельством, а не числом подключённых средств.

Источники

Актуальность документального среза — 7 октября 2026 года. Ссылки в тексте указывают, какое утверждение они поддерживают; обобщения и контрольные сценарии — мой синтез, а не результаты испытаний продуктов.

• Созвон «ИЫшницы», 30 сентября 2026: анонс встречи, транскрипт. Ссылки ведут в закрытый Telegram-чат и открываются только его участникам; частные сообщения в статью не перенесены.
• CodeGraph Михаила Савина: руководство по контролю архитектуры.
• xref Ника Гребнева: оригинал xref-guide.md, предоставленный автором и опубликованный без правок. Руководство описывает связывание кода, данных и наблюдаемого выполнения; публичный репозиторий или пакет я не нашёл, реализацию не испытывал.
• Документация инструментов: Aider repo map, LSP: references и call hierarchy, codespaces, CPG, ArchUnit, Import Linter, dependency-cruiser, Prism, pg_query, Hypothesis, Stryker, Playwright, CodeQL, Pact, Parallel Change, k6, Git worktree, LangGraph persistence и checkpointers, OWASP, OpenLineage, DataHub, OpenMetadata, dbt, SQLMesh, Dataform.
• Исследования: RepoCoder, 2023 — итеративный поиск контекста для дополнения кода, не полный цикл изменения приложения; Lost in the Middle, 2023/2024 — использование длинного контекста в задачах по документам, не эксперимент с coding-агентами; SWE-bench, ICLR 2024 — оценка исправлений по реальным задачам Python-репозиториев; LINEAGEX, ICDE Demo 2025 — извлечение происхождения колонок из SQL; METR 2025 и обновление 2026 — измерение эффекта AI на собственных задачах. У SWE-bench и LINEAGEX прочитаны аннотации, полный текст и данные ещё не разобраны.

Статус: статья ещё в работе и доступна по прямой ссылке. Следующий этап исследования — проверка методов на реальном проекте.

Автор: Данил Письменный · Дата: 7 октября 2026