SavePearlHarbor

Почему AI-агент ищет по коду неправильно, и как это чинит cocoindex-code за две команды

—

от автора

admin

Большинство харнессов ищут grep’ом по ключевым словам, а не по смыслу. Поставил AST-based семантический поиск на свой проект, разобрался с устройством и сравнил с CodeGraph и SocratiCode

Если вы работаете с Claude Code, Cursor или Codex на большом проекте, то знаете типичную боль: просишь агента «найди, где у нас обрабатывается авторизация», а он начинает гонять grep по ключевым словам. Если функция называется validateUserSession, а вы спросили про «авторизацию» — grep её не найдёт, потому что он ищет совпадение строк, а не смысл. Агент бегает по файлам, жжёт токены, и через десяток вызовов либо находит, либо сдаётся.

Это фундаментальное ограничение текстового поиска. И его решает семантический поиск — когда запрос и код сопоставляются по смыслу через эмбеддинги, а не по буквальному совпадению. Я уже разбирал на Хабре два инструмента из этой ниши — CodeGraph (граф символов через tree-sitter) и SocratiCode (векторный поиск на Qdrant). Недавно мне попался третий — cocoindex-code, и он зацепил меня тем, что ставится буквально в две команды и работает без настройки баз данных. Поставил, прогнал на своём проекте, разобрался с устройством. Рассказываю.

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

Что это и в чём идея

cocoindex-code (CLI-команда ccc) — это легковесный инструмент семантического поиска по кодовой базе. Apache-2.0, 1.7k звёзд на GitHub, построен поверх движка CocoIndex — это Rust-движок для трансформации данных от тех же авторов.

Ключевая идея — дать coding-агенту инструмент, который ищет по смыслу, а не по тексту. Вместо grep агент делает запрос «find how user sessions are managed», и получает релевантные куски кода, даже если слова «session» в них нет.

Главное отличие от аналогов, которое меня и заинтересовало — zero config. Не нужно поднимать Qdrant в Docker (как у SocratiCode), не нужно настраивать векторную БД, не нужен API-ключ для эмбеддингов. Всё работает локально из коробки. Установка реально в две команды, и я это проверил.

Заявленная экономия — 70% токенов для coding-агента. Цифра из README, и она правдоподобна: вместо того чтобы агент читал десятки файлов целиком, он получает несколько точечных релевантных чанков.

Установка: реально две команды

Тут без подвоха. Ставится через pipx:

pipx install 'cocoindex-code[full]'

Флаг [full] важен — он тянет sentence-transformers для локальных эмбеддингов, чтобы всё работало без API-ключа. По умолчанию используется модель Snowflake/snowflake-arctic-embed-xs — маленькая и быстрая. Есть и slim-вариант (cocoindex-code без [full]), но он требует облачного провайдера эмбеддингов и API-ключ — берите его, только если не хотите тянуть ~1 ГБ torch + transformers.

Дальше подключаем скилл для агента:

npx skills add cocoindex-io/cocoindex-code

И всё. После этого, как обещает README, агент сам научится запускать демон, инициализировать индекс, следить за кодовой базой и использовать семантический поиск, когда это полезно. Не нужно вручную делать ccc init или ccc index — скилл учит агента делать это самостоятельно.

У меня на проекте среднего размера (Python-бэкенд, около 400 файлов) первичная индексация заняла пару минут. Дальше watcher досинхронизирует только изменения, так что переиндексации каждый раз нет.

Если хочется ручного контроля, есть прямой CLI:

ccc init                              # инициализация проектаccc index                             # построить индексccc search "authentication logic"     # искать

Фоновый демон стартует автоматически при первом обращении. Мелочь, а приятно — не нужно отдельно его запускать.

Как устроен AST-чанкинг — главное техническое решение

Вот тут самое интересное с инженерной точки зрения, и тут cocoindex делает правильную вещь.

Наивный подход к индексации кода — порезать файлы на куски фиксированного размера (например, по 50 строк) и посчитать эмбеддинг каждого куска. Проблема в том, что такая нарезка рвёт код посреди функции: половина функции попадает в один чанк, половина в другой, и эмбеддинг каждого получается «полудохлым» — он не описывает законченную смысловую единицу.

cocoindex чанкует по границам AST. Исходник парсится через Tree-sitter в синтаксическое дерево, и нарезка идёт строго по границам функций, классов, методов. Каждый чанк — это законченная смысловая единица: целая функция, целый класс. Эмбеддинг такого чанка осмысленный, потому что описывает цельный кусок логики.

Это критично для качества поиска. Когда вы спрашиваете «где обрабатываются платежи», вектор запроса сопоставляется с векторами цельных функций, и матч получается точным. Если бы чанки были рваными, половина релевантной функции просто не нашлась бы.

Tree-sitter тут — та же библиотека, что использует GitHub для навигации по коду и подсветки. Проверенный инструмент, поддерживает десятки языков. Это, кстати, ровно тот же подход, что я видел в CodeGraph — оба строят свою работу на Tree-sitter AST. Разница в том, что CodeGraph строит из AST граф связей (кто кого вызывает), а cocoindex использует AST для нарезки на чанки под эмбеддинги. Об этом различии подробнее ниже.

Локальные эмбеддинги: приватность и отсутствие API-ключей

Второе, что мне понравилось — эмбеддинги считаются локально, на вашей машине, через sentence-transformers. Это даёт три преимущества.

Первое — приватность. Ваш код не уходит ни в какое облако для построения индекса. Для корпоративной разработки, где код нельзя светить наружу, это часто решающий фактор. SocratiCode тоже умеет локально (через Ollama), но cocoindex делает это дефолтом без всякой настройки.

Второе — нет затрат на API. Облачные эмбеддинги (OpenAI text-embedding и аналоги) стоят денег за каждый чанк. На большой кодовой базе с тысячами функций первичная индексация может вылиться в ощутимую сумму. Локальная модель — бесплатно.

Третье — работает оффлайн. Нет зависимости от внешнего сервиса, индексация и поиск работают без интернета.

Цена за это — нужно скачать модель (около 1 ГБ зависимостей с torch) и потратить чуть больше CPU/памяти на инференс эмбеддингов. Для дефолтной snowflake-arctic-embed-xs это немного, модель маленькая. Если хочется качество получше — можно подключить модель покрупнее, но для большинства задач xs хватает.

Watcher: пересчитываются только изменённые чанки

Третий технический момент, который стоит отметить — умная инкрементальная синхронизация.

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

Это та же философия инкрементальности, что в самом движке CocoIndex (он позиционируется как incremental data transformation engine). Для разработки это важно: индекс остаётся свежим по мере того, как вы пишете код, без заметных тормозов и без ручного запуска переиндексации.

На практике у меня это работало незаметно — правишь код, через секунду-другую индекс уже актуален, и агент ищет по свежей версии.

Два способа подключения: Skill и MCP

cocoindex поддерживает два способа интеграции с агентом, и стоит понимать разницу.

Skill (рекомендованный). Это npx skills add cocoindex-io/cocoindex-code. Скилл — это набор инструкций, который учит агента, когда и как использовать семантический поиск. Агент сам решает, что вот сейчас полезно поискать по смыслу, и сам вызывает ccc. Работает с Claude Code и другими skill-совместимыми агентами.

MCP Server. Альтернатива — запустить cocoindex как MCP-сервер:

claude mcp add cocoindex-code -- ccc mcp

Тогда агент получает MCP-инструмент search с параметрами: запрос, лимит результатов, фильтры по языку и путям. Это более стандартный путь интеграции, работает с Claude Code, Codex, OpenCode — любым MCP-совместимым хостом.

Инструмент search возвращает матчащие куски кода с путём к файлу, языком, содержимым, номерами строк и score похожести. То есть агент получает не «вот файл, читай весь», а точечные релевантные фрагменты с координатами.

Разница между Skill и MCP примерно такая: Skill — это «научи агента пользоваться инструментом по своему усмотрению», MCP — «дай агенту инструмент как часть протокола». Для Claude Code оба варианта рабочие, я бы начинал со Skill как с более простого.

Чем отличается от CodeGraph и SocratiCode

Раз уж я разбирал оба, проведу прямое сравнение — это три инструмента одной ниши с разными подходами.

SocratiCode — векторный поиск на Qdrant + Ollama, гибридный (семантика + BM25 через RRF). Сильная сторона — мощный гибридный поиск. Слабая — требует Docker для Qdrant и Ollama, тяжелее в развёртывании.

CodeGraph — структурный граф символов через Tree-sitter + SQLite. Сильная сторона — детерминированная трассировка вызовов (кто кого вызывает, impact-анализ). Слабая — не умеет в семантику, ищет по именам и связям.

cocoindex-code — векторный семантический поиск с AST-чанкингом, локальные эмбеддинги, zero config. Сильная сторона — простота установки (две команды, без Docker и БД) и приватность (всё локально). Слабая — это чистый семантический поиск, без графа связей; не покажет «кто вызывает эту функцию».

Если упрощать выбор:

  • Нужен простой семантический поиск без возни с инфраструктурой → cocoindex. Самый легковесный из трёх.

  • Нужна трассировка вызовов и impact-анализ → CodeGraph (граф детерминирован).

  • Нужен максимально мощный гибридный поиск и не пугает Docker → SocratiCode. По сути cocoindex и SocratiCode решают похожую задачу (семантический поиск через вектора), но cocoindex жертвует частью мощности ради простоты. CodeGraph стоит особняком — это про структуру, а не про смысл.

Идеальный сетап, наверное — поставить cocoindex для семантики (он лёгкий) плюс CodeGraph для трассировки, и пусть агент использует оба под разные типы вопросов: «найди код про X» → cocoindex, «что сломается, если поменяю Y» → CodeGraph.

Где это реально помогает

После того как поставил и погонял, сформулирую сценарии, где cocoindex даёт ощутимую пользу.

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

Большой проект, где grep тонет. На монорепе с тысячами файлов grep по общему слову («handler», «process», «manager») вернёт сотни совпадений. Семантический поиск отранжирует по смыслу и даст релевантное сверху.

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

Концептуальный поиск. «Найди код, который делает что-то похожее на rate limiting» — семантика поймает реализацию, даже если она называется throttleRequests и слова rate limiting там нет. grep тут бессилен.

Ограничения, о которых стоит знать

Чтобы не выглядело рекламно — где у инструмента границы.

Только семантический поиск, без графа. cocoindex найдёт релевантный код по смыслу, но не скажет «эту функцию вызывают вот отсюда и отсюда». Для трассировки нужен граф (CodeGraph). Это разные задачи.

Качество зависит от модели эмбеддингов. Дефолтная snowflake-arctic-embed-xs маленькая и быстрая, но не топовая по качеству. На сложных концептуальных запросах она может промахиваться. Можно подключить модель покрупнее, но это компромисс скорость/качество.

Первичная индексация на большом проекте не мгновенная. «Разбираемся в коде за секунды» из заголовков промо — преувеличение. Индексация большой базы — это минуты, а не секунды. Поиск после индексации — да, быстрый, но первый проход требует времени.

~1 ГБ зависимостей для локального режима. torch + transformers весят прилично. Если у вас ограничен диск или хочется минимализма — это заметный довесок. Slim-вариант легче, но требует облачных эмбеддингов.

Молодой проект. 1.7k звёзд, 191 коммит, 19 открытых issue. Активно развивается, но это не зрелый энтерпрайз-инструмент. Для критичных процессов учитывайте.

Что я вынес

Несколько мыслей по итогам.

AST-чанкинг — это правильный дефолт для индексации кода. Резать по границам функций, а не по фиксированному размеру строк — кажется очевидным, но многие инструменты этого не делают. cocoindex делает, и это заметно по качеству поиска.

Zero config — недооценённая фича. Я уважаю SocratiCode за мощность, но необходимость поднимать Qdrant в Docker — барьер. cocoindex ставится в две команды и работает. Для адопшена это решает: чем ниже порог входа, тем выше шанс, что инструментом реально будут пользоваться.

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

Семантика и структура — разные оси, и это снова подтверждается. Третий инструмент в нише, и снова видно: вектора (cocoindex, SocratiCode) ловят смысл, граф (CodeGraph) ловит связи. Это не конкуренты, а взаимодополняющие подходы.

Резюме

cocoindex-code — это лёгкий, быстрый в установке инструмент семантического поиска по коду для AI-агентов. Главные козыри — установка в две команды без Docker и баз данных, AST-чанкинг по границам функций для осмысленных эмбеддингов, локальные эмбеддинги без API-ключей и приватности ради, и умный watcher с пересчётом только изменённого.

Телеграм-пост, что редкость, не наврал — все ключевые заявления подтверждаются README и моим опытом. Единственное преувеличение — «разбираемся в коде за секунды»: индексация это минуты, а не секунды, но поиск после неё действительно быстрый.

Если у вас большой проект и AI-агент, который тонет в grep — попробуйте, порог входа минимальный (две команды, всё локально, Apache-2.0). Если нужна трассировка вызовов — добавьте к нему CodeGraph. А если хотите максимум мощности гибридного поиска и не боитесь Docker — смотрите в сторону SocratiCode. Все три — про то, чтобы агент перестал жечь токены на слепой grep и начал искать по смыслу.

Полезные ссылки:

ссылка на оригинал статьи https://habr.com/ru/articles/1049814/