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

Источник: https://www.youtube.com/watch?v=-AkIj8TG3Uc
Канал: JavaScript Mastery
Опубликовано: 02.10.2026

---

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

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

[[JUMP:00:00]]

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

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

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

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

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

[[JUMP:03:34]]

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

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

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

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

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

[[JUMP:09:02]]

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

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

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

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

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

[[JUMP:25:04]]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[JUMP:1:15:25]]

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

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

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

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

*   Аутентификация через GitHub и выбор конкретного репозитория (в данном случае Cardograph) [1:16:55].
*   Автоматическая генерация резюме (walkthrough), которое описывает добавленные уровни: контракты парсера, обход репозитория и интерактивные превью [1:17:50].
*   Создание диаграмм последовательности (sequence diagrams), визуализирующих взаимодействие между компонентами, такими как `AnalysisView` и `DetailPane` [1:18:30].

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

### Анализ Blast Radius и Dependency Chain
[[JUMP:1:20:05]]

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

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

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

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

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

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

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

*   **Загрузка архивов:** репозитории скачиваются как `.tar.gz`, что избавляет от необходимости хранить токены GitHub и управлять правами доступа для публичных проектов [1:26:34].
*   **Superbase Realtime:** прогресс анализа транслируется в браузер через механизм подписок базы данных, а не через постоянные опросы (polling) [1:27:14]. Канал реального времени защищен политиками безопасности: одна организация не может просматривать прогресс анализа другой [1:27:55].
*   **Обработка сбоев:** если процесс «умирает» без явной ошибки, система через некоторое время помечает его как «stale» (устаревший), чтобы пользователь не ждал бесконечно [1:28:21].

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 🤖 Автономные агенты и безопасность данных

[[JUMP:2:30:41]]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*   Способность запускать масштабные проекты с абсолютного нуля, делегируя рутинную сборку агентам [2:55:50].
*   Эффективное вхождение в огромные, уже существующие кодовые базы, которые разработчик не писал лично, с помощью инструментов визуализации и анализа [2:55:55].
*   Переход от написания отдельных функций к проектированию рабочих процессов (workflows), где ИИ берет на себя роль исполнителя инженерных задач [2:56:00].

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

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

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

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

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

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