Theory of Code Space: Do Code Agents Understand Software Architecture?

Зацепила тут одна тема, не удержался и дошёл до статьи. Она ещё сильно work in progress.

Статья: https://arxiv.org/abs/2603.00601
Код: https://github.com/che-shr-cat/tocs
Большой пост: https://gonzoml.substack.com/p/do-code-agents-actually-understand

Понимают ли код-агенты код, с которым работают?

Не в смысле "могут ли написать функцию" — это уже давно решённая задача. Я про другое: когда агент ковыряется в кодовой базе из 30 модулей, строит ли он в “голове” какую-то модель архитектуры? Понимает ли, какие модули от каких зависят, как текут данные, какие есть архитектурные ограничения? Или просто локально матчит паттерны и надеется на лучшее?

Идея в том, что всё целиком запихивать в контекст неспортивно. Во-первых, не каждая реальная кодовая база влезет, во-вторых, даже если влезет технически, то не факт, что от этого будет много пользы. Агент, как и человек, должен исследовать структуру кода, чтобы понять, что происходит. И в процессе должен (в идеале) как-то строить и обновлять свою “ментальную карту”.

Все существующие бенчмарки кода меряют выход — скомпилировался ли патч, прошёл ли тест. Никто не меряет, что агент понимает о системе в процессе работы с ней. Ну либо я не нашёл.

Всё началось с того, что я прочитал Theory of Space (https://arxiv.org/abs/2602.07055, авто-обзор тут https://t.me/gonzo_ML/4807) — классную работу про то, как мультимодальные модели строят "когнитивные карты" при исследовании частично наблюдаемых сред. Там два ключевых феномена: Active-Passive Gap (модели хуже работают, когда сами исследуют среду, vs когда им дают всё сразу) и Belief Inertia (не могут обновить свои представления, когда среда меняется).

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

Собственно, я взял и сделал бенчмарк. Theory of Code Space (ToCS) — берём агента, сажаем в процедурно сгенерированную кодовую базу (ground truth известен), даём бюджет в 20 действий (открыть файл, поискать, инспектировать символ), и каждые 3 действия просим выдать своё текущее понимание архитектуры в виде структурированного JSON. Получается не финальный снапшот, а временной ряд — как понимание развивается по мере исследования.

Что за кодовые базы? Генератор делает Pipeline-архитектуру средней сложности — 27-30 Python-файлов, 5 подпакетов, 70-84 ребра зависимостей и 15-16 архитектурных инвариантов. Есть этапы пайплайна, наследующие общий абстрактный базовый класс (ABC, StageBase), адаптеры поверх них, middleware (логирование, retry), утилиты, и — что важно — distractor-модули (legacy/, compat.py), которые ни к чему не подключены, но выглядят правдоподобно. Нейминг нейтральный: mod_a.py, mod_b.py, а не extract.py → transform.py → load.py — чтобы модель не могла угадать архитектуру по именам файлов.

Четыре типа рёбер, от простых к сложным:

* IMPORTS (~67%): обычные Python-импорты, видны через AST. Любой парсер найдёт.
* CALLS_API (~17%): рантаймовые вызовы функций между модулями. Нужно читать тела функций, хотя докстринги могут подсказать ("delegates to module X", “wraps module X” и т.п.).
* REGISTRY_WIRES (~9%): динамическая загрузка через config. Реестр читает pipeline_config.json и загружает стейджи через importlib — никакого import statement в коде нет. Нужно прочитать и конфиг, и логику загрузки.
* DATA_FLOWS_TO (~7%): данные одного модуля идут на вход другому. Нужно понять логику оркестрации в runner.py — multi-hop reasoning, откуда что берётся и куда уходит.

Суть в том, что примерно треть рёбер невидима для import-following. Это и создаёт осмысленный разрыв между синтаксическим анализом и семантическим пониманием.