Почему AI-агент не понимает бизнес-логику проекта

Структуру системы увидеть проще, чем причины её существования

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

Такие графы помогают ответить на вопросы:

• какие части проекта зависят друг от друга;

• какие библиотеки используются в конкретном модуле;

• какие изменения могут повлиять на другие части системы;

• какие компоненты являются центральными для архитектуры.

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

Но граф зависимостей описывает структуру системы, а не причины её появления.

Он показывает, что связь существует, но не объясняет, зачем она была создана.

Для разработчика эта разница может быть критичной.

Архитектурное решение не всегда видно в коде

Представим два сервиса, между которыми отсутствует прямая зависимость.

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

Исследование неоднократно подчёркивает, что многие архитектурные решения существуют вне самого кода.

По этой причине даже хорошо построенная карта репозитория не гарантирует понимания системы.

Источники, посвящённые архитектурному анализу, отдельно отмечают необходимость связывать структуру кода с более высокими уровнями описания системы. В академических работах для этого предлагаются специальные графовые представления, которые объединяют низкоуровневую структуру проекта с архитектурными описаниями и объяснениями.

Само появление таких подходов показывает, что одной информации о зависимостях недостаточно.

Почему успешный результат не всегда означает понимание проекта

В исследовании встречается ещё одна важная мысль. Агент способен решить задачу и при этом не понимать систему целиком.

Он может:

• найти правильный файл;

• внести корректное изменение;

• пройти тесты;

• получить положительный результат в бенчмарке.

Но при этом причина успеха может заключаться не в понимании архитектуры, а в удачном поиске похожего паттерна.

Именно поэтому в исследованиях 2025–2026 годов появляется интерес к отдельной оценке способности агента исследовать репозиторий. Исследователи пытаются отделить навигацию по проекту от качества итогового патча.

За этим подходом стоит простая идея: способность найти правильное место в системе и способность понять её устройство — не обязательно одно и то же.

Что именно недоступно агенту

Исследование не утверждает, что современные агенты полностью лишены понимания бизнес-контекста. Однако несколько источников указывают на ограничение другого рода.

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

Это различие особенно заметно в областях, где важную роль играют:

• бизнес-правила;

• архитектурные компромиссы;

• исторические решения команды;

• причины появления ограничений;

• договорённости между подразделениями;

• требования предметной области.

Часть этой информации может существовать в документации, обсуждениях, архитектурных решениях и внутренних правилах, но отсутствовать в самом коде.

Поэтому даже подробный анализ репозитория не гарантирует доступ к полному контексту принятия решений.

Почему появляются файлы памяти и архитектурные инструкции

Одной из реакций на эту проблему стало распространение файлов вроде AGENTS.md и CLAUDE.md.

Их задача заключается не только в объяснении структуры проекта. Они также позволяют зафиксировать знания, которые невозможно надёжно извлечь из исходного кода.

Такие файлы могут содержать:

• архитектурные ограничения;

• правила работы с модулями;

• требования к изменениям;

• особенности предметной области;

• принятые проектные соглашения.

Фактически они становятся способом передать агенту часть контекста, который отсутствует в графах зависимостей и картах репозитория.

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

Почему проблема остаётся открытой

Несмотря на развитие карт репозиториев, графов зависимостей и механизмов поиска, исследование не показывает существования общепринятого решения проблемы архитектурного понимания.

Напротив, часть источников рассматривает её как одно из ключевых ограничений современных агентных систем.

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

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

Вывод

Исследование показывает, что современные AI-агенты научились достаточно эффективно работать со структурой программных систем. Они способны строить карты репозитория, анализировать зависимости между компонентами и находить релевантные участки кода.

Однако архитектурное понимание не сводится к анализу структуры.

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

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