Что такое Codebase Intelligence и зачем он нужен AI-агенту
Codebase Intelligence описывает локальный слой, который превращает репозиторий в структурированные данные, пригодные для AI-агента. Каждый фрагмент кода получает описание: что он делает, с чем связан и как менялся во времени. Агент обращается к слою как к инструменту и получает готовое досье по нужной точке кодовой базы, а не поток сырых строк.
Такой слой реализован в открытом проекте TeaRAGs. Это локальный MCP-сервер: он объединяет семантический поиск, граф вызовов и метрики git-истории и отдаёт агенту результат по запросу. Аббревиатура MCP расшифровывается как Model Context Protocol, стандарт подключения инструментов к агентным клиентам, поэтому переписывать сам агент не приходится.
Смысл слоя в одном: сократить путь от вопроса разработчика до релевантного кода. Выигрыш заметен там, где репозиторий перестаёт помещаться в контекст, и именно с этим сталкиваются команды на крупных монолитах.
Чем Codebase Intelligence отличается от обычного поиска по коду
Поиск по файлам, будь то grep или поиск в IDE, возвращает совпадения строк. Он отвечает на вопрос «где встречается это слово» и молчит о смысле найденного. Агент, получивший десяток файлов с совпадениями, тратит контекст на чтение и сам решает, какой из них относится к задаче.
Слой понимания отдаёт контекст: назначение фрагмента, его связи и историю изменений. Вместо одного файла агент видит точку входа, связанные вызовы и метрики по этому участку кода. Для правки логики оформления заказа этого достаточно, чтобы сразу перейти к делу и не тянуть в контекст половину репозитория.
Почему агенту недостаточно контекстного окна
Автор TeaRAGs работает с Rails-монолитом размером 3,5M+ строк. Такой объём не помещается в контекстное окно, и рост окна проблему не снимает: длинный контекст дороже обрабатывать, а внимание модели на нём размывается.
Значит, нужен внешний слой, который сам находит релевантное и отдаёт его порциями. Границы порции задаёт ранжирование внутри индекса, а не ручной выбор файлов. Именно на монолите в 3,5M+ строк TeaRAGs и тестируется. О том, как агенты теряют целостность кода при работе с крупными репозиториями, читайте в разборе про когнитивную ловушку агентной разработки.
Почему агентные инструменты ломаются на больших монолитах
Рынок инструментов для агентной разработки переполнен. Одни обещают сохранять контекст между сессиями, другие берутся понимать всю кодовую базу целиком, третьи продают память, планирование и автономность в одном флаконе. Часть таких проектов на поверку оказывается README-проектами, часть честно работает на демо-репозитории и падает с OOM при первой встрече с реальным энтерпрайз-проектом. Это авторская оценка человека, который искал рабочий инструмент под свой монолит, и он изложил её в публикации о собственном проекте.
Разрыв словарей: почему агент не находит нужную логику
Разработчик пишет «оформление заказа», а в коде живут checkout, fulfillment и order_placement. Семантический поиск сглаживает часть расхождений, но не все: доменный жаргон команды часто не совпадает с именами сущностей в репозитории. Без слоя понимания агент либо не находит фрагмент, либо приносит нерелевантный и строит правку на нём. Как агент при этом теряет ранее заданные требования, разобрано в материале про intent continuity для кодинг-агентов.
Индексация часами и облачные эмбеддинги
Альтернативы, которые автор пробовал на монолите в 3,5M+ строк, распадались на три категории. Одни индексировались часами. Другие требовали отдать код в облако и платить за эмбеддинги. Третьи поддерживали Ruby лишь номинально. Для команды с проприетарным кодом первые два пункта часто неприемлемы: часы ожидания при переиндексации ломают рабочий цикл, а выгрузка исходников на сторонний API противоречит политике безопасности.
Ruby и DSL: почему поддержка «номинальная»
Ruby с его предметно-ориентированными языками плохо поддаётся наивному парсингу. В Rails многое описано декларативно: ассоциации, скоупы, валидации, колбэки. Инструмент, который режет файл по строкам, теряет эти связи и выдаёт куски кода без контекста. TeaRAGs задуман с учётом этой проблемы и заявляет нативный AST-чанкинг для девяти языков. Точный список языков в доступном фрагменте источника не раскрыт, поэтому конкретики по Ruby добавить нечем.
Как устроен TeaRAGs: три представления кода и единое «досье»
Архитектура TeaRAGs держится на трёх представлениях одного кода: что он делает, как связан и как жил во времени. Каждое отвечает на свой вопрос, вместе они дают агенту контекст, который до этого приходилось собирать вручную по нескольким инструментам.
Проект начался как форк простого движка семантического поиска на Ollama + Qdrant. Из форка вырос полностью локальный инструмент, на который у автора ушло больше полугода, по его собственному описанию.
Семантический поиск: что код делает
Первый слой ищет фрагменты по смыслу, а не по точному совпадению строк. В основе лежат эмбеддинги: код разбивается на чанки, каждый превращается в вектор и складывается в векторную базу Qdrant. Модель для построения эмбеддингов запускается локально через Ollama, то есть наружу ничего не уходит. Запрос агента проходит ту же процедуру и находит ближайшие по смыслу чанки, даже если формулировка не совпадает с именами в коде.
Граф вызовов: как код связан
Второй слой отвечает на вопрос о связях. Граф показывает, кто вызывает найденный фрагмент и что вызывает он сам. Для агента это защита от правок, которые ломают неочевидные зависимости: меняя метод, полезно видеть всех его потребителей. Похожую задачу решает граф влияния кодовой базы, о котором рассказано в разборе CodeSlicer и невидимых для агента зависимостей.
Git-история: как код жил во времени
Третий слой читает историю коммитов и превращает её в метрики. Автор называет среди них churn (частота изменений), долю багфиксов и владение кодом. Эти метрики участвуют в ранжировании: участок, который часто меняется и часто правится вместе с багфиксами, для агента может оказаться важнее, чем стабильный и редко трогаемый код. Конкретные веса и формулы в доступном фрагменте источника не раскрыты, так что оценить силу влияния этих метрик на выдачу по публичным данным нельзя.
Локальность и приватность: что именно не покидает вашу машину
TeaRAGs полностью локальный инструмент: ни код, ни его производные (индекс, эмбеддинги, граф вызовов) не покидают локальную среду. Это ключевое свойство проекта, а не дополнительная опция.
Ollama и Qdrant: локальный стек
За локальность отвечают два компонента. Ollama запускает модель, которая считает эмбеддинги на вашей машине. Qdrant хранит векторы и отвечает за поиск ближайших соседей. Связка Ollama + Qdrant была основой того самого движка семантического поиска, форк которого стал отправной точкой TeaRAGs. Сверх этого работает локальный MCP-сервер, через который агент и обращается к индексу.
Почему это важно для команд с закрытым кодом
Облачные эмбеддинги стоят денег и создают риск утечки. Каждый запрос к внешнему API отправляет фрагменты исходников наружу, а при индексации монолита речь идёт о больших объёмах. Для команд с проприетарным кодом это часто красная линия: политика безопасности запрещает выгружать исходники на сторонние сервисы, и локальный слой позволяет использовать агентов без обхода этих правил. Сертификацию или независимый аудит автор не заявлял, так что подтверждения безопасности со стороны у проекта нет.
Производительность и поддержка языков: что известно на сегодня
Заявленные ориентиры такие: индекс монолита на 3,5M+ строк строится за минуты, а нативный AST-чанкинг поддерживает девять языков. Обе цифры взяты из заголовка и описания темы, в доступном фрагменте источника они развёрнуто не подтверждены. Это важно держать в голове: «за минуты» без указания железа, размера индекса и числа потоков остаётся формулировкой без независимой проверки.
AST-чанкинг: зачем разбивать код по структуре, а не по строкам
Наивное разбиение по строкам или по фиксированному числу символов рвёт логические блоки: метод распадается на два чанка, класс теряет связь с методами. AST-чанкинг режет код по синтаксическим узлам, поэтому в один чанк попадает цельная функция или класс. Для семантического поиска это заметно улучшает качество: эмбеддинг цельного метода описывает его назначение точнее, чем вектор случайного фрагмента.
Что с Ruby и Rails
TeaRAGs задуман под проблему Ruby и тестируется на Rails-монолите, что косвенно говорит о внимании автора к этому языку. Публичных деталей о качестве поддержки Ruby в доступном фрагменте источника нет: ни списка обрабатываемых конструкций DSL, ни сравнения с другими языками. Проверить это можно только на своём репозитории.
Чем TeaRAGs отличается от типичных инструментов и что у него общего с ними
TeaRAGs не заменяет агента. Claude Code, RooCode или любой другой клиент продолжает вести диалог, планировать и писать код. TeaRAGs добавляет к нему локальный слой понимания кодовой базы, который агент вызывает как инструмент.
Почему автор не нашёл готовой замены
История проекта начинается с рабочей связки Claude + RooCode + семантический поиск на Ollama. Связка была основным инструментом автора, пока не перестала работать. После этого он полностью пересел на Claude Code и начал искать замену семантическому индексу. Требования оказались жёсткими: работать локально, индексировать монолит в 3,5M+ строк за разумное время и нормально поддерживать Ruby. Ни одно из найденных решений не закрывало все три пункта, поэтому появился собственный проект.
Место TeaRAGs в пайплайне агентной разработки
Логика встраивания простая: агент по ходу решения задачи вызывает MCP-инструменты TeaRAGs, получает ранжированные фрагменты вместе с их связями и историей, и уже на этом основании планирует правку. Слой не принимает решений за агента и не пишет код. Он отвечает за то, чтобы в контекст попало нужное, а не случайное. Пошаговой инструкции по установке в доступном фрагменте источника нет, поэтому конкретные команды здесь приводить не буду.
Ограничения и риски: что важно учитывать
У подхода есть слабые места, и часть из них видна уже по публичным данным.
Субъективность авторских оценок
Единственный доступный источник, публикация о TeaRAGs, это рассказ автора о собственном проекте. Критика альтернатив в нём пристрастна по определению: человек описывает проблемы, с которыми столкнулся сам, на своём стеке и своём монолите. Из этого не следует, что те же инструменты не справятся на другом проекте. Проверять инструменты стоит на своей кодовой базе и своих задачах.
Что осталось за кадром публичных данных
Ряд заявленных деталей в доступном фрагменте не раскрыт:
- точные метрики ранжирования: churn, доля багфиксов и владение кодом упомянуты, но формулы и веса не приведены;
- список девяти языков с нативным AST-чанкингом не назван;
- бенчмарки не опубликованы: ни сравнения с альтернативами на одном наборе задач, ни замеров на разном железе.
К этому добавляется общая зависимость от качества индекса. Если чанкинг ошибается или граф вызовов неполон, агент получит уверенно выглядящий, но неточный контекст. Локальность эту проблему не решает.
Кому подходит TeaRAGs и с чего начать
Инструмент рассчитан на разработчиков, которые используют локальные LLM и AI-агентов и работают с крупными монолитами. Особенно там, где в стеке есть Ruby и Rails: именно на таком проекте TeaRAGs проверяется. Проект открытый, что позволяет изучить устройство до того, как ставить его в рабочий процесс.
Кому инструмент, скорее всего, не подойдёт
Если репозиторий целиком помещается в контекст, отдельный слой понимания добавляет сложность без заметной отдачи: агенту хватает прямой загрузки файлов. Нет смысла менять стек и тем командам, которых устраивают облачные решения и чьи политики безопасности разрешают отправлять код на сторонние API. Копировать чужой выбор под свой проект без замеров тоже не стоит.
Как оценить пользу на своём проекте
Разумный порядок такой. Начните с тестового репозитория и замерьте время построения индекса. Затем прогоните 10-15 типовых для вашей команды запросов и посмотрите, попадают ли в выдачу те файлы, которые вы сами считаете релевантными. После этого подключите слой к агенту и сравните, как меняется качество ответов на реальных задачах: меньше ли ошибок в правках, реже ли агент уходит не туда. Критерии общие, гарантированных цифр за ними не стоит, а решение стоит принимать по своим замерам.