Agentic Engineering: как управлять ИИ-агентами в масштабе

«Никто больше не может читать AI-код: не потому, что он плохой, а потому, что его слишком много и он пишется слишком быстро». Чтобы не утонуть в море сгенерированных строк, инженеры переходят к Agentic Engineering — методологии управления автономными системами, где разработка превращается в итеративный цикл Spec-Build-Check, а сложные зависимости визуализируются в интерактивные карты.

🗺️ Проблема «нечитаемого» AI-кода и концепция Cardograph 0:00

Современная разработка столкнулась с парадоксом: AI пишет код настолько быстро и в таких объемах, что человек физически перестает его читать . Проблема не в качестве генерации, а в «усталости» человеческого восприятия перед лицом бесконечного потока файлов. В ситуации, когда один измененный файл может потянуть за собой цепочку из 11 зависимостей, обычное дерево папок в IDE перестает давать реальное представление о структуре проекта . Никто в команде, включая автора промпта, зачастую не знает, что именно сломается при внесении правок .

Решением этой проблемы становится Cardograph — инструмент, превращающий репозиторий GitHub в интерактивную карту . Основные возможности концепции:

• Визуализация зависимостей: превращение папок в боксы, а импортов — в линии связей между ними .
• Анализ Blast Radius: при выборе файла система подсвечивает все узлы, которые могут «сломаться» при его изменении на два уровня вглубь .
• Верифицируемость: в отличие от обычных чат-ботов, Cardograph строит карту на основе парсинга реального кода, а не догадок нейросети .

Главное правило проекта: AI разрешено объяснять только то, что уже доказано парсером . Карта, которая верна на 90%, хуже, чем отсутствие карты вовсе, так как пользователь не может определить, какие именно 10% являются ложью или галлюцинацией . Ранее в разговоре автор упоминал, что для реализации этого подхода используется связка Next.js, TypeScript и инструментов визуализации.

Разница между простым AI-запросом и полноценным агентом 3:34

В индустрии происходит подмена понятий: многие называют «агентом» обычный API-вызов . Однако отправка текста и получение ответа в 15 строках кода — это не агент, а просто «телефонный звонок» к модели, ограниченный её внутренними знаниями .

Настоящий агент определяется наличием цикла (loop) . Модель сама по себе не может открыть файл, запустить команду или выполнить поиск — она лишь генерирует текст . В агентской схеме:

1. Модель пишет: «Мне нужно увидеть этот файл» .
2. Внешняя система (оркестратор) читает этот запрос, достает файл и подает его обратно на вход модели .
3. Модель анализирует новые данные и решает, какой шаг будет следующим .

Этот процесс медленнее и дороже обычного запроса, но он необходим для задач, которые невозможно решить за один проход, например: «Что сломается, если я изменю этот файл?» . Особенность Cardograph в том, что агент не работает внутри самого приложения — он развернут отдельно и обращается к системе за нужными данными по мере необходимости . При этом критически важно переходить от «ощущений» к цифрам: использование инструментов вроде Langsmith позволяет записывать каждый вызов и оценивать точность агента по заранее известным ответам, полученным из парсера кода .

Методология Spec-Build-Check и настройка Claude.md 9:02

В эпоху AI-инжиниринга написание синтаксиса становится дешевым, а ценность разработчика смещается в сторону принятия архитектурных решений и контроля галлюцинаций модели . Процесс разработки в проекте строится по циклу Spec-Build-Check :

1. Spec (Спецификация): создание короткого файла на простом английском языке с описанием того, что нужно сделать, что запрещено и как проверить результат .
2. Build (Сборка): агент превращает спецификацию в код.
3. Check (Проверка): верификация результата. Если агент ошибся, код удаляется, спецификация правится, и цикл запускается заново .

Для управления поведением агента используются два ключевых файла контекста. Первый — project-doc.md, описывающий идею продукта, целевую аудиторию и список того, что намеренно оставлено за рамками проекта (out of scope) . Второй — claude.md (или agents.md), содержащий жесткие правила игры .

В claude.md фиксируются критические ограничения: например, запрет на «угадывание» связей между файлами на основе их названий . Если парсер не подтвердил импорт, агент не имеет права рисовать линию на графе, даже если это кажется «логичным» . Также файл диктует манеру общения: агент должен предлагать конкретные варианты (А или Б) с обоснованием, вместо того чтобы задавать открытые вопросы, останавливающие сборку . Такая структура позволяет избежать накопления технического долга, который возникает, когда разработчик пытается «допромптить» уже работающий, но непонятный AI-код . Для настройки окружения на начальном этапе автор использует стандартные команды Next.js и интеграцию с Clerk для аутентификации .

🛡️ Безопасная B2B архитектура: Интеграция Clerk и Supabase 25:04

Настройка современной B2B платформы требует не просто разделения прав доступа, а создания системы, где безопасность гарантирована на уровне инфраструктуры. Основная проблема традиционного подхода заключается в том, что логика доступа часто «размазана» по коду приложения: если разработчик забудет добавить один фильтр в запрос, данные одной компании могут утечь другой . Чтобы избежать этого в Cardograph, используется стратегия переноса ответственности за безопасность непосредственно в базу данных с помощью Row Level Security (RLS) .

Настройка мультиарендности через RLS и Clerk 25:18

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

Процесс интеграции начинается с настройки окружения Next.js, где устанавливаются пакеты @supabase/supabase-js и @supabase/ssr . Однако ключевой момент здесь — «знакомство» системы аутентификации (Clerk) с системой хранения данных (Supabase). По умолчанию они ничего не знают друг о друге: Clerk понимает, кто вы, а Supabase хранит что вы можете трогать . Чтобы связать их, в панели Clerk активируется интеграция с Supabase, где указывается домен Clerk в настройках сторонних провайдеров (Third-party Auth) внутри Supabase .

После этой связки Supabase начинает доверять токенам, подписанным Clerk. Это позволяет реализовать концепцию, где:

• Идентификация пользователя происходит через JWT-токен .
• Токен несет в себе «клейм» (claim) организации .
• База данных считывает этот токен напрямую, решая, какие строки (rows) вернуть пользователю .

Такой подход избавляет от необходимости делать лишние запросы к провайдеру аутентификации во время выполнения (runtime), так как вся необходимая информация для проверки прав уже содержится в сессии .

Использование MCP-серверов для управления базой 27:02

Для ускорения разработки и интеграции AI-агентов в рабочий процесс используется протокол MCP (Model Context Protocol). MCP-сервер для Supabase позволяет AI-инструментам напрямую взаимодействовать с базой данных без необходимости заходить в графический дашборд . Это критически важно для этапа «Agentic Engineering»: агент может самостоятельно проверить, добавились ли нужные колонки или применились ли миграции, просто «спросив» об этом сервер .

Установка MCP-сервера выполняется через терминал командой npx skills add supabase , после чего агент получает возможность:

1. Инспектировать структуру таблиц .
2. Применять SQL-миграции в автоматическом режиме .
3. Проверять статус выполнения команд через Bash-скрипты .

При первоначальной сборке фазы 01 агент Claude может столкнуться с тем, что Clerk не создает организации «молча» из-за настроек безопасности . В таких случаях процесс разделяется: сервер через Backend API Clerk создает команду, а клиентский шаг активирует её для пользователя .

Валидация прав доступа на уровне БД 39:08

Когда мы переходим к созданию рабочих пространств (Workspaces), архитектура базы данных должна отражать структуру B2B-организаций. В рамках второй фазы разработки создаются 8 ключевых таблиц (проекты, анализы, файлы, зависимости и др.), каждая из которых владеет своими строками через внешний ключ к ID организации .

Важнейшее ограничение (Constraint) этого этапа: «Авторизация — это свойство базы данных, а не проверка, которую приложение должно не забыть выполнить» . Это означает:

• Ни одна таблица не доступна для чтения без явной политики RLS .
• Проверка прав происходит на уровне SQL-движка .
• Если данные другой команды когда-либо вернутся в ответе, это считается ошибкой политики базы данных, а не фронтенда .

Для тестирования этой системы AI-агент использует MCP для автоматического «засева» (seeding) данных . Проверка работоспособности выглядит так: создается одна организация (например, «Adrian's Team») с пятью записями и вторая («JS Mastery Demo») с двумя . Если пользователь первой организации не видит записи второй, значит, RLS-фильтры работают корректно . Это подтверждает, что мультиарендность изолирована на самом глубоком уровне, что позволяет безопасно масштабировать Cardograph как корпоративный инструмент .

Ранее в разговоре авторы упоминали методологию Spec-Build-Check, которая здесь применяется для автоматизации создания миграций и проверки соответствия кода спецификациям.

🧠 Архитектура анализа: от сырого кода к графу зависимостей 50:05

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

Ядро системы на базе TS Morph 50:34

Разработка парсера началась с четкого определения контрактов данных. Клод предложил использовать библиотеку TS Morph, так как она является единственным полноценным инструментом, способным корректно обрабатывать типизацию и сложные связи в TypeScript-проектах .

В процессе создания ядра были решены ключевые архитектурные задачи:

• Определение модулей: Файловый модуль приравнивается к папке, в которой он находится .
• Фильтрация нод: Каждая единица кода (.ts, .tsx, .js, .jsx) становится узлом графа, за исключением содержимого папки node_modules .
• Резолвинг путей: Система использует встроенный резолвер TypeScript, учитывая ближайшие файлы tsconfig.json. Это критически важно для корректной обработки алиасов путей (path aliases), расширений (extends) и индексных файлов .
• Типизация связей: Был создан файл types.ts, описывающий структуру «ребер» (edges) графа и классификацию файлов, что позволяет отличать обычные импорты от динамических или реэкспортов .

Для проверки надежности парсер был протестирован на крупных Open Source проектах. В репозитории tRPC система успешно обнаружила и разрешила более 250 папок с реэкспортами, выдав всего один неразрешенный импорт с указанием конкретной причины . Ранее в разговоре авторы касались методологии Spec-Build-Check, и именно здесь она показала свою эффективность: парсер сам предоставил отчет об «акцептансе» (Files found / Files parsed / Files skipped), подтвердив свою готовность к работе с реальным кодом .

Визуализация и логика «схлопывания» в React Flow 55:00

Когда данные получены, встает вопрос их отображения. Для отрисовки карты используется React Flow в связке с алгоритмом детерминированной послойной компоновки . Главная проблема визуализации больших репозиториев — избыточность: невозможно выбросить сотни файлов на экран одновременно и сохранить читаемость.

Для решения этой проблемы была внедрена логика Folding (схлопывания) папок :

1. Каждая директория изначально рассматривается как отдельный узел.
2. Алгоритм обходит структуру от самых глубоких папок к родительским.
3. Если папка содержит меньше критического количества файлов, она «мерджится» (сливается) с родительской директорией .
4. При клике на такой «свернутый» узел открывается панель, показывающая список файлов внутри, что позволяет сохранять масштаб графа управляемым .

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

Интерактивность и анализ связей (Fan-in/Fan-out) 58:35

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

Цветовая кодировка помогает мгновенно считать контекст:

• Зеленые линии: Входящие зависимости (кто импортирует этот файл) .
• Янтарные (amber) линии: Исходящие зависимости (что импортирует этот файл) .

Разработчики столкнулись с багом, когда React Flow блокировал клики по кастомным компонентам внутри нод, но это было исправлено добавлением корректных обработчиков событий указателя . Также была реализована поддержка скроллинга внутри развернутых папок: теперь при прокрутке списка из 120+ файлов связи динамически перерисовываются только для тех элементов, которые видны в модальном окне .

Панель деталей и сводка репозитория 1:09:22

Финальным штрихом главы стала реализация правой панели, которая работает по принципу «нулевой задержки» (zero network requests) . Все данные уже находятся в браузере после первичного парсинга, поэтому переключение между файлами происходит мгновенно.

Если ничего не выбрано, панель показывает Repository Summary:

• Название проекта и детектированный фреймворк .
• Общее количество файлов и импортов (например, 687 файлов и 3554 импорта для Excalidraw) .
• Список самых зависимых файлов («Most dependent on») и точки входа — файлы, которые никто не импортирует, с которых стоит начинать чтение кода .

При выборе файла панель отображает его тип, количество строк и детальный список зависимостей . Это создает фундамент для следующего этапа — внедрения AI-агентов, которые будут объяснять логику этих связей, о чем пойдет речь в следующих частях статьи.

🧭 Динамический анализ: Blast Radius и реальные данные 1:15:25

На текущем этапе разработки Cardograph переходит от статической визуализации к инструменту, который помогает принимать решения при рефакторинге. После того как агент успешно перенес изменения в новую ветку GitHub и открыл PR , фокус смещается на глубокий анализ связей и автоматизацию проверки качества кода. Инструмент начинает «понимать», как изменения в одном модуле резонируют по всей системе.

Автоматизированное ревью с Code Rabbit 1:16:43

Когда PR содержит 48 измененных файлов и десятки тысяч строк кода , ручная проверка становится узким местом. Для решения этой проблемы в пайплайн интегрируется Code Rabbit — AI-ассистент, специализирующийся на анализе pull-запросов .

Процесс интеграции включает несколько шагов:

• Аутентификация через GitHub и выбор конкретного репозитория (в данном случае Cardograph) .
• Автоматическая генерация резюме (walkthrough), которое описывает добавленные уровни: контракты парсера, обход репозитория и интерактивные превью .
• Создание диаграмм последовательности (sequence diagrams), визуализирующих взаимодействие между компонентами, такими как AnalysisView и DetailPane .

Code Rabbit не просто описывает изменения, но и ищет уязвимости и несоответствия. В ходе демонстрации инструмент обнаружил ошибку в обработке категорий файлов без расширений: UI ошибочно добавлял лишнюю точку к значению none . Исправление таких мелочей через AI-чат позволяет поддерживать чистоту кодовой базы, не отвлекаясь на сотни мелких комментариев вручную . Ранее в разговоре авторы упоминали важность концепции Cardograph для чтения AI-кода, и Code Rabbit становится практическим воплощением этой идеи на уровне PR.

Анализ Blast Radius и Dependency Chain 1:20:05

Шестая фаза разработки делает граф «по-настоящему полезным» . Вводятся две ключевые функции:

1. Blast Radius (Радиус поражения): показывает, на что повлияет изменение конкретного файла .
2. Dependency Chain (Цепочка зависимостей): демонстрирует, от чего зависит выбранный файл .

С технической точки зрения обе функции представляют собой один и тот же алгоритм обхода графа (transitive walk) по списку ребер, где меняется только направление движения и задается лимит глубины . По умолчанию установлена глубина в два уровня . Это критическое ограничение: если идти глубже, инструмент вернет половину репозитория, что лишает анализ смысла .

Интерфейс также становится «умнее»: при выборе категории на боковой панели (rail) остальные файлы не исчезают, а затемняются (dimming), позволяя видеть контекст всей системы . Дополнительно вводятся «инсайты» — автоматическое обнаружение циклических импортов, «осиротевших» файлов (которые никто не импортирует) и аномально больших модулей . При этом учитывается специфика фреймворков: например, файлы маршрутов Next.js могут иметь ноль импортов, но не быть при этом лишними, так как их вызывает сам фреймворк .

Пайплайн анализа репозиториев в реальном времени 1:26:20

Финальный этап главы — замена статических данных на полноценный поток обработки GitHub-URL . Пайплайн состоит из четырех стадий: Fetch, Select, Parse и Store .

Ключевые особенности реализации:

• Загрузка архивов: репозитории скачиваются как .tar.gz, что избавляет от необходимости хранить токены GitHub и управлять правами доступа для публичных проектов .
• Superbase Realtime: прогресс анализа транслируется в браузер через механизм подписок базы данных, а не через постоянные опросы (polling) . Канал реального времени защищен политиками безопасности: одна организация не может просматривать прогресс анализа другой .
• Обработка сбоев: если процесс «умирает» без явной ошибки, система через некоторое время помечает его как «stale» (устаревший), чтобы пользователь не ждал бесконечно .

Для работы серверной части используется секретный ключ Superbase, так как сессионный токен пользователя (Clerk) живет всего 60 секунд, чего недостаточно для парсинга крупного проекта . При тестировании на библиотеке Shadcn UI система успешно обработала почти 10,000 связей за 18 секунд . После завершения записи данных в БД происходит автоматический редирект с интерактивной страницы прогресса на итоговую карту проекта .

🧩 Адаптеры фреймворков и расширение парсера 1:40:30

На текущем этапе Cardograph превращается из простого визуализатора связей в инструмент глубокого понимания контекста приложения . Основная задача этой фазы — научить систему распознавать «роли» файлов, основываясь на соглашениях популярных фреймворков, таких как Next.js, Nest.js и Express . Это позволяет пользователю не просто видеть граф, но и фильтровать его по функциональным категориям: серверные действия (Server Actions), роуты API, макеты (Layouts) или конфигурационные файлы .

Поддержка CommonJS и Express-адаптер 1:43:39

Ранее в разговоре упоминалось, что парсер успешно обрабатывал современные import выражения, однако огромное количество Node.js проектов всё еще полагаются на require . Без поддержки CommonJS анализ таких репозиториев приводил к созданию «пустых» графов, где файлы практически не имели связей, даже если формальный показатель покрытия кода достигал 100% .

Ключевые изменения в логике парсера:

• Детекция require: Теперь вызовы с литеральными путями разрешаются так же, как и обычные импорты .
• Обработка module.exports: Это позволяет файлам полноценно участвовать в цепочке зависимостей графа .
• Смешанный режим: Система корректно обрабатывает файлы, в которых одновременно используются оба стандарта экспорта/импорта .

Для Express-проектов был добавлен специализированный адаптер, который определяет роли файлов на основе конвенций именования папок . Если файл находится в директориях routes, controllers или services (включая единственное число), Cardograph автоматически присваивает ему соответствующую метку . Важное ограничение: из-за сложности статического анализа динамических роутеров в Express (переменные, middleware), разработчики решили пока не извлекать таблицу маршрутов для этого фреймворка, чтобы избежать неточностей .

Валидация через сравнение Edge List 1:45:08

Поскольку изменения затрагивали само ядро парсера (Parser Core), критически важным условием было сохранение работоспособности для уже поддерживаемых фреймворков . Методология проверки заключалась в следующем: запуск новой версии парсера на старых проектах должен генерировать список связей (Edge List), на 100% идентичный предыдущим результатам .

В качестве примера успешного внедрения приводится анализ node-express-boilerplate: если до обновлений система видела 0 связей, то после внедрения поддержки CommonJS и Express-адаптера количество обнаруженных ребер графа выросло до 107 . Это подтверждает, что Cardograph теперь способен эффективно «читать» классические Node.js приложения, визуализируя модели данных (например, User Model) и их влияние на остальную кодовую базу .

📊 Трассировка AI-вызовов через Langsmith 1:56:31

Переход к функции «AI-объяснений» требует не просто отправки запросов в OpenAI, но и создания надежной инфраструктуры для мониторинга . Интеграция Langsmith становится фундаментом для отладки, контроля качества и оптимизации затрат . Трассировка позволяет фиксировать четыре ключевых параметра каждого вызова: входные данные, полученный ответ, длительность выполнения и стоимость в токенах .

Настройка и локальная разработка агентов 1:58:04

Процесс интеграции начинается с настройки Langsmith, где Cardograph регистрируется как проект для «агентской» разработки . Несмотря на наличие облачных решений (Managed Deep Agents), команда начинает с локальной настройки, чтобы агент работал как отдельный сервис, независимый от основного Next.js приложения . Это обеспечивает гибкость: локальный код позже можно будет перенести в управляемую среду без переписывания под другой рантайм .

Настройка включает:

1. Установку OpenAI SDK и инструментария Langsmith .
2. Создание API-ключей и настройку переменных окружения (.env.local), включая включение флага трассировки (tracing=true) .
3. Использование Claude для генерации базового кода агента-исследователя, который будет использовать модель GPT от OpenAI .

Интеллектуальное кэширование и прозрачность трасс 2:01:51

Одной из центральных задач при внедрении объяснений (Phase 10) стала система кэширования . Чтобы не тратить токены при каждом клике на один и тот же файл, объяснения сохраняются в базе данных (через миграции Supabase) . Ключом кэша выступает контент самого файла: если код не изменился, пользователь мгновенно получает старое объяснение; если же в файл были внесены правки — генерируется новый запрос .

Особенность реализации в том, что даже попадание в кэш должно отображаться в Langsmith . Трассировка фиксирует запрос, но помечает его как «Cache Hit» с нулевым расходом токенов и отсутствием реального вызова модели . Это позволяет разработчикам в реальном времени проверять эффективность логики кэширования и видеть полную картину взаимодействия пользователя с AI-функциями приложения .

🛡️ Оценка качества AI-ответов (Evaluations) 2:12:22

Когда AI становится частью продукта, критически важно перевести обсуждение качества его ответов из плоскости субъективных мнений в плоскость конкретных цифр . Для этого в Cardograph была внедрена система эвалуаций (Evaluations) — методология, позволяющая количественно оценить точность работы агента. В отличие от стандартных тестов, здесь используется три типа оценщиков, так как разные аспекты качества требуют разных подходов к проверке .

Основная цель фазы тестирования — убедиться, что AI не «галлюцинирует» и не выдумывает данные, которых не было в предоставленном контексте . Это особенно важно при анализе структуры проекта, где модель может ссылаться на несуществующие пути к файлам. Для решения этой задачи используются как детерминированные алгоритмы, так и другие LLM в роли судей (LLM-as-a-judge).

Детерминированная проверка путей (Invented Path Check) 2:13:02

Самая строгая проверка касается целостности данных: если AI упоминает в объяснении путь к файлу, этот путь обязан присутствовать в контексте, который был передан модели . Здесь не требуется другая нейросеть для оценки — достаточно простого программного сравнения списков (set membership) .

• Механика проверки: Система сравнивает каждый путь, упомянутый в ответе, с точным набором путей, переданных в промпте . Если путь не совпадает — он считается выдуманным (invented).
• Реализация: Проверка запускается непосредственно внутри приложения при каждой генерации объяснения (даже если оно берется из кэша) . Результат проверки в виде числового скора (score) сразу записывается в Langsmith .
• Тестирование тестов: Чтобы убедиться в работоспособности самого оценщика, используется метод «сплайсинга» (splice). Разработчики намеренно вставляют ложный путь в 11 корректных объяснений, и если скрипт pmpm eval paths отлавливает все 11 ошибок, значит, система мониторинга работает исправно . В реальных условиях Cardograph показал точность около 90–96% по этому показателю .

Классификация ролей и точность Ground Truth 2:13:20

Вторая категория тестов направлена на проверку того, насколько правильно AI определяет роль файла (например, является ли файл сервисом, моделью или утилитой) . Ранее в проекте уже были определены соглашения об именовании (conventions), такие как *.service.ts в Nest.js .

Процесс оценки строится на сравнении ответа модели с «эталонной правдой» (ground truth) :

1. Из метаданных файла скрывается его реальная роль.
2. AI просят классифицировать файл на основе его содержимого и связей.
3. Ответ сравнивается с исходным значением из конвенции фреймворка.

В ходе тестов была выявлена точность на уровне 91% . Интересный инсайт: чаще всего ошибки возникали при попытке отличить React Hook от Component, тогда как сервисы и конфигурационные файлы AI распознает практически безошибочно .

Эксперименты с промптами: V0 против V1 2:23:33

Одной из самых мощных возможностей системы оценки является сравнение версий промптов side-by-side . Это позволяет количественно измерить, как изменение инструкций влияет на результат. В Cardograph сравнили старую версию (V0 retired), которая была максимально лаконичной и запрещала форматирование, с новой версией (V1 current), содержащей инструкции о «честности» и анализе соседей .

Результаты эксперимента в Langsmith показали неожиданные данные:

• Новый, более подробный промпт оказался чуть менее точным в плане выдуманных путей (95% против 100% у V0) .
• При этом стоимость (token usage) у новой версии оказалась ниже, несмотря на большую точность в некоторых специфических сценариях .

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

🤖 Автономные агенты и безопасность данных 2:30:41

На финальных этапах разработки Cardograph фокус смещается с написания базового кода на его валидацию и создание интеллектуальной надстройки. В современной разработке, где Claude Code может генерировать сотни строк за раз, «узкое горлышко» перемещается из процесса написания кода в процесс его проверки . Ранее в разговоре упоминалась трассировка вызовов через Langsmith, и теперь эти инструменты становятся основой для полноценного автономного агента, способного не просто «болтать», а эффективно оперировать графом зависимостей всей кодовой базы.

Исправление критических багов через Triage в Code Rabbit 2:30:41

Процесс код-ревью с использованием Code Rabbit демонстрирует, как AI-инструменты находят ошибки, которые практически невозможно заметить при обычном просмотре диффов. В ходе демонстрации Code Rabbit обнаружил две критические логические дыры в самом «детекторе галлюцинаций» приложения .

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

Особого внимания заслуживает случай с файлом roles.ts, который импортировал сам себя . Из-за этой циклической зависимости в тестах (evals) модель получала вопрос, в котором уже содержался ответ, что приводило к ложноположительным результатам и искажению метрик точности . Разработчик подчеркивает, что такие комментарии ревьюера — это не приказы, а входные данные . AI-агент (Claude Code) проверяет каждое замечание Code Rabbit и может отклонить исправление, если оно не подходит проекту, как это случилось с предложением по изменению переменных окружения .

Создание автономного агента (Manage Deep Agents) 2:34:48

Разработка переходит к созданию Cardograph Agent — отдельного сервиса, который живет вне основного приложения и работает на базе фреймворка Manage Deep Agents . В отличие от простого вызова API, это полноценный агент с четким набором инструментов (tools), которые используют ту же логику графа, что и визуальный интерфейс .

Агент получает шесть ключевых инструментов для исследования кода :

1. Summary: краткий обзор всего анализа.
2. Search: поиск файлов по части пути.
3. Files by role: листинг файлов по их ролям в архитектуре.
4. Neighbors: поиск прямых связей конкретного файла.
5. Walk: транзитивный обход графа в обоих направлениях (поиск цепочек зависимостей).
6. Routes: доступ к таблице маршрутизации приложения.

Агент настраивается через файл instructions.mmd, где прописаны правила «отказа» (refusal behavior) . Например, агент никогда не должен строить догадки о связях, если их нет в графе (правило "never infer"), и не должен обсуждать свои внутренние механизмы . Это гарантирует, что ответы будут базироваться на жестких данных парсера, а не на галлюцинациях LLM.

Безопасность и JWT-учетные данные 2:42:31

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

Реализация защиты строится на следующих принципах:

• Short-lived signed credentials: Информация о доступе живет в кратковременном подписанном токене, привязанном к конкретной организации и ID анализа .
• Изоляция токенов: У агента нет «мастер-ключа», способного прочитать всё; его инструменты ограничены областью действия (scope) текущей беседы .
• Интеграция с Supabase: Для проверки полномочий используется импорт приватного ключа с алгоритмом ES256 в настройки JWT Supabase .

Тестирование через команду pnpm agent check подтверждает, что любая попытка использовать поддельный или «испорченный» токен (garbage token) приводит к отказу в доступе, гарантируя безопасность данных в B2B-среде .

🏁 Финал проекта: Переход к парадигме Agentic Engineering 2:55:29

Завершение работы над Cardograph знаменует собой не просто окончание разработки очередного приложения, а смену фундаментального подхода к созданию программного обеспечения . Весь пройденный путь — от проектирования архитектуры до настройки глубоких агентов — демонстрирует, что современный разработчик перестает быть просто «писателем кода» и превращается в дирижера сложных интеллектуальных систем . Проект Cardograph стал практическим воплощением того, как интеграция передовых инструментов позволяет одному инженеру управлять кодовой базой, объем и сложность которой раньше требовали усилий целой команды .

🧠 От коллекции промптов к управлению процессами 2:55:41

Ключевой вывод проекта заключается в том, что реальная ценность ИИ в разработке лежит далеко за пределами простых чат-интерфейсов и разрозненных подсказок . Методология, продемонстрированная в ходе создания Cardograph, направлена на то, чтобы сделать инженера способным направлять автономных агентов через весь жизненный цикл разработки . Это подразумевает:

• Способность запускать масштабные проекты с абсолютного нуля, делегируя рутинную сборку агентам .
• Эффективное вхождение в огромные, уже существующие кодовые базы, которые разработчик не писал лично, с помощью инструментов визуализации и анализа .
• Переход от написания отдельных функций к проектированию рабочих процессов (workflows), где ИИ берет на себя роль исполнителя инженерных задач .

Автор подчеркивает, что хотя сам рабочий процесс Cardograph доступен в open-source формате и может быть установлен бесплатно , критически важным является понимание логики и «мышления», стоящего за этими инструментами . Именно этот концепт — «Agentic Engineering» — становится главной темой для профессионального роста в эпоху доминирования больших языковых моделей .

🛠️ Итоговая синергия технологического стека 2:56:08

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

В итоговом обзоре выделяются следующие компоненты системы:

1. Clerk: Решил вопросы безопасности, сделав аутентификацию пользователей и управление организациями в B2B-сегменте невероятно простыми в реализации .
2. Supabase: Стал надежным «фундаментом» всей системы, обеспечив хранение данных и эффективное взаимодействие с базой .
3. LangSmith: Обеспечил «зрение» для ИИ-компонентов, взяв на себя управление агентами, функционал поиска и, что наиболее важно, оценку качества (evaluations) ответов ИИ-моделей .
4. Code Rabbit: Гарантировал жизнеспособность проекта в долгосрочной перспективе, контролируя масштабируемость кода и предотвращая его деградацию после десятков pull-реквестов .

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