За пределами корректности: архитектурное понимание в кодовых LLM

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

Пайплайн включает двух судей: Architecture Complexity Judge (судья архитектурной сложности, ACJ), который оценивает, насколько архитектурное понимание конкретной кодовой базы требуется для задачи, и Architecture Quality Judge (судья архитектурного качества, AQJ), который оценивает соответствие патча архитектурным конвенциям конкретного репозитория по правилам, опирающимся на исходный код.

Дообучение Qwen3-8B/14B/32B на 3 360 отобранных примерах даёт resolved rate (долю решённых задач) до 27,2% на SWE-bench Verified - до 540% выше базовой модели и до 256% выше, чем при неотфильтрованном дообучении на полном датасете. Кроме того, обученные модели демонстрируют сильную кросс-языковую генерализацию и устойчивое улучшение архитектурной корректности патчей.

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

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

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

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

Чтобы решить эту проблему, авторы предлагают агентный пайплайн оценки, который использует сильную LLM как масштабируемую замену экспертной архитектурной оценке. Он автоматически строит качественные данные для supervised fine-tuning (контролируемого дообучения, SFT), ориентированные на архитектурное рассуждение.

Код и данные доступны в открытых источниках: датасет на Hugging Face и README пайплайна оценки.

Понимание архитектуры ПО

Помимо функциональной корректности, сопровождение ПО требует рассуждений об архитектуре системы: границах модулей, ограничениях уровней и межкомпонентных зависимостях. Предыдущие работы изучали архитектурное качество через статические метрики анализа: coupling (связанность), cohesion (сцепление) и complexity (сложность).

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

LLM-as-a-Judge и оценка по рубрикам

Недавние работы исследуют LLM-as-a-Judge (использование LLM как судьи) для субъективных или трудно проверяемых задач: качества суммаризации, корректности рассуждений и preference judgment (оценки предпочтений). Важным направлением стала rubric-guided evaluation (оценка по рубрике), где LLM генерируют или применяют структурированные критерии оценивания.

Однако существующие подходы по рубрикам обычно работают на уровне задачи и используют фиксированную схему оценки. Это плохо подходит для software engineering (инженерии ПО), где архитектурные ограничения специфичны для репозитория и меняются между проектами.

Авторы стремятся строить данные для supervised fine-tuning (контролируемого дообучения, SFT), которые улучшают архитектурное рассуждение в LLM за пределами локальной функциональной корректности. Для каждого примера учитываются описание проблемы, репозиторий, кандидатный патч и траектория рассуждения.

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

Пайплайн оценки состоит из двух компонентов. Architecture Complexity Judge (судья архитектурной сложности, ACJ) оценивает, насколько глубокое понимание репозитория требуется для задачи. Architecture Quality Judge (судья архитектурного качества, AQJ) сначала генерирует архитектурную рубрику для конкретного репозитория и issue (задачи), а затем оценивает кандидатный патч по этой рубрике.

3.1. Судья архитектурной сложности

ACJ измеряет архитектурную сложность задачи: насколько глубокое понимание codebase (кодовой базы) нужно инженеру, чтобы прийти к патчу. Это отличается от общей сложности программирования. Навыки работы с внешними API, доменные знания или алгоритмическая сложность учитываются только тогда, когда они зависят от архитектуры репозитория.

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

На третьем этапе судья моделирует исследование репозитория, которое потребовалось бы инженеру, начинающему с нуля. Начиная с изменённых файлов, он отслеживает вызывающие и вызываемые функции, интерфейсы, data-flow (потоки данных), общее состояние, sibling implementations (соседние реализации) и архитектурные границы.

Затем сложность декомпозируется на пять независимых осей: Scope of Context (объём контекста), Dependency Chain Depth (глубина цепочки зависимостей), Implicit Knowledge (неявное знание), Coordination Complexity (сложность координации) и Insight Density (плотность инсайта). После оценки по осям ACJ агрегирует результат в одну из пяти меток: Trivial, Low, Moderate, High или Expert.

3.2. Судья архитектурного качества

AQJ оценивает, насколько патч уважает архитектуру целевого репозитория: паттерны, границы и структурные конвенции. Универсальной архитектурной рубрики не существует: слоёная архитектура, event-driven system (событийно-ориентированная система) и плагинный фреймворк требуют разных критериев соответствия.

Сначала AQJ генерирует рубрику из codebase (кодовой базы), а не применяет фиксированный набор универсальных осей. Рубрика выводит, какие архитектурные свойства важны в конкретном репозитории и конкретной задаче, а затем фиксирует эти свойства до оценки патча.

Генерация рубрики включает четыре шага: разбор issue (задачи), доказательное исследование архитектуры, вывод осей с приоритетами и генерацию текстовых «якорей» качества. Такие якоря описывают, как выглядит идеальное соответствие и какие структурные проблемы характерны для плохого патча.

Затем оценщик патча выдаёт вердикт архитектурного соответствия: High, High_with_concerns, Acceptable или Low. Для каждой primary-axis (основной оси) анализируются эффекты за пределами изменённых файлов, например подклассы, вызывающие методы и модули, импортирующие изменённые символы.

3.3. Порог фильтрации и обучение

Для обучения выбираются примеры, которые проходят заданные пороги по ACJ и AQJ. На отфильтрованном датасете оптимизируется masked next-token cross-entropy loss (маскированная кросс-энтропийная ошибка предсказания следующего токена): в лосс включаются только токены траектории ассистента, а сообщения пользователя и наблюдения среды маскируются.

Авторы проверяют подход на открытых моделях Qwen3-8B, Qwen3-14B и Qwen3-32B. Исходные обучающие данные получены из датасета на уровне репозиториев, построенного на реальных GitHub-проектах с помощью пайплайна RepoForge.

Исходный датасет состоит из 5 000 качественных Python-траекторий, сгенерированных моделью MiniMax-M2.5 и отобранных через teacher pass-rate filtering (фильтрацию по прохождению задач учительской моделью). После фильтрации ACJ и AQJ авторы получают 3 360 архитектурно отобранных примеров.

Оценка проводится на SWE-bench Verified и SWE-bench Multilingual. Второй бенчмарк используется для проверки кросс-языковой генерализации после обучения только на Python-данных. Во всех экспериментах используется OpenHands как execution scaffold (среда выполнения и взаимодействия с репозиторием), максимум 300 шагов на задачу и метрика Pass@1.

Сравнение проводится с тремя вариантами: Original (базовая модель без дообучения), FullData (модель, дообученная на полном датасете) и Ours (модель, дообученная на архитектурно отобранном подмножестве).

5.1. Эффективность выбранных данных

Подход авторов стабильно превосходит бейзлайны для всех размеров модели на SWE-bench Verified. По сравнению с базовой моделью resolved rate (доля решённых задач) растёт с 3,2% до 17,4% для Qwen3-8B, с 4,6% до 17,8% для Qwen3-14B и с 9,0% до 27,2% для Qwen3-32B.

По сравнению с обучением на полном датасете архитектурно отобранные данные также дают лучший результат: рост с 6,8% до 17,4% для Qwen3-8B, с 9,4% до 17,8% для Qwen3-14B и с 15,6% до 27,2% для Qwen3-32B. Это показывает, что меньший, но архитектурно значимый набор данных эффективнее, чем обучение на всех доступных данных без фильтрации.

Распределение по качеству AQJ показывает, что fine-tuning (дообучение) на архитектурно отобранных данных не только повышает resolved rate, но и смещает модель к генерации патчей, лучше соблюдающих структурные конвенции целевого репозитория.

Для Qwen3-8B суммарная доля High и High_with_concerns растёт с 60,9% до 83,6%; для Qwen3-14B - с 64,0% до 87,1%; для Qwen3-32B - с 72,1% до 93,5%.

5.2. Кросс-языковая генерализация

Подход авторов обобщается на другие языки программирования, несмотря на обучение исключительно на Python-примерах. При оценке на SWE-bench Multilingual, который покрывает 9 языков помимо Python, подход улучшает результаты относительно Original (базовой модели без дообучения) на 286-420% для всех моделей.

Аналогично, подход стабильно превосходит FullData (модель, дообученную на полном датасете) для всех размеров модели. Эти устойчивые улучшения показывают, что паттерны архитектурного рассуждения, выученные на Python-данных, эффективно переносятся на другие языки. Это указывает, что архитектурное понимание в значительной степени языконезависимо: оно опирается на границы модулей, направления зависимостей и паттерны абстракции, а не на синтаксис конкретного языка.

5.3. Связь со статическими метриками

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

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

Агентные оценки ACJ и AQJ не удаётся воспроизвести с помощью отдельных статических метрик качества и сложности кода. Для AQJ ни одна статическая метрика не показывает сильной корреляции с оценками судьи; наиболее высокоранговые признаки фактически являются метриками размера изменения, например дельтой размера файлов или LoC (числа строк кода), с максимальной корреляцией около 0,24 по модулю.

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

Авторы также проверяют, можно ли воссоздать агентный pipeline (пайплайн) фильтрации только по статическим метрикам. Фильтрация по метрикам повышает resolved rate (долю решённых задач) на SWE-bench Verified, но ухудшает результат на SWE-bench Multilingual. Это говорит о слабой переносимости порогов по метрикам между разными сценариями оценки. Агентный подход устойчиво превосходит оба бейзлайна на обоих бенчмарках и показывает более надёжный выбор данных.

6.1. Можно ли предсказать оценки ACJ/AQJ статическими метриками?

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

Чтобы изучить это подробнее, авторы используют все 157 метрик как признаки для обучения моделей random forest (случайного леса, RF), предсказывающих мультиклассовые оценки ACJ/AQJ. Модель для AQJ показывает заметно более сильный результат, что указывает на совместную нелинейную информацию в статических метриках. Для ACJ такой перенос работает хуже.

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

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

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

Fine-tuning (дообучение) на отобранном датасете стабильно превосходит как необученные, так и полностью дообученные базовые модели разных размеров, демонстрируя сильную кросс-языковую генерализацию. Подход также улучшает архитектурное соответствие патчей одновременно с ростом доли решённых задач.

Эти результаты показывают, что архитектурное рассуждение - обучаемая и переносимая способность, если обучающие данные отбираются с использованием явных структурных критериев качества.

В работе стратегия фильтрации оценивалась на трёх open-source models (моделях с открытыми весами) и двух широко используемых бенчмарках. Результаты могут не обобщаться на другие модели, поэтому авторы призывают будущие исследования измерить эффективность подхода на более широком наборе моделей.

A.1. Детали реализации навыков

В приложении приведён prompt (промпт) для Evidence-Based Architecture Exploration (доказательного исследования архитектуры) в ACJ. Его цель - оценить, какое количество архитектурного понимания codebase (кодовой базы) требуется, чтобы решить конкретную проблему. Судья не оценивает качество решения; он оценивает, насколько хорошо инженер должен понимать архитектуру системы, чтобы прийти к корректному исправлению.

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

Промпты для Rubric Generation (генерации рубрики) и Single-Axis Assessment (оценки по одной оси) в AQJ аналогично описывают формат YAML, поля axis_name, priority, ideal_conformance, poor_conformance и evidence (доказательства). Смысл в том, что AQJ генерирует рубрику, строго привязанную к конкретной кодовой базе, а затем отдельные субагенты по каждой оси выдают текстовую оценку и список доказательств.

A.2. Пример патчей разного качества

В этом разделе приводятся два diff-фрагмента для одного issue (задачи) в MONAI. Патч с высоким AQJ-баллом добавляет явную проверку tuple (кортежа) в convert_to_contiguous, чтобы не изменять тип контейнера и устранить корень проблемы. Патч с низким AQJ-баллом меняет downstream-function (нижестоящую функцию) collate_meta_tensor, пытаясь восстанавливать тип контейнера через type(elem_0)(...), что лишь частично скрывает проблему и добавляет хрупкость.

Текстовое объяснение в (рис.2) сводится к тому, что качественный патч чинит причину, а низкокачественный - симптом.

A.3. Изученные метрики качества архитектуры ПО

Приложение перечисляет метрики и пороги для ACJ-стиля и AQJ-стиля, ссылки на источники метрик, графики корреляций между статическими метриками и оценками ACJ/AQJ, а также подробные описания реализованных групп метрик: complexity (сложность), size (размер), unused code (неиспользуемый код), cohesion (сцепление), dependency graph (граф зависимостей), OO-метрики (объектно-ориентированные метрики), composite/evolution metrics (составные и эволюционные метрики) и patch-specific metrics (метрики патча).

Отдельно описываются пять осей ACJ: Scope of Context (объём контекста), Dependency Chain Depth (глубина цепочки зависимостей), Implicit Knowledge (неявное знание), Coordination Complexity (сложность координации) и Insight Density (плотность инсайта).