🎯 О чём этот конспект: Практическое руководство по исследованию и визуализации архитектуры AI-сгенерированных приложений с помощью двух специализированных инструментов: плагина Understand Anything для Claude Code и архитектурного фреймворка Groma на базе C4-модели. Разбирается, как превратить сотни сгенерированных ИИ файлов в понятную интерактивную карту системы.

👤 Кому будет полезно: Вайбкодерам, разработчикам и фаундерам, которые создают продукты с помощью AI-агентов (Claude Code, Cursor, Windsurf) и хотят быстро ориентироваться в структуре проекта, понимать взаимосвязи компонентов и безопасно вносить изменения.

✨ Что получите: Пошаговые инструкции по установке, сканированию и визуализации кодовой базы, готовые CLI-команды, методы генерации бизнес-туров и сравнительные метрики затрат времени и токенов.

1. Автоматический онбординг в проект через Understand Anything для Claude Code

Контекст: Когда приложение создаётся итеративно через ИИ-агентов (например, гибридный стек из Python-бэкенда и SwiftUI-клиента), разработчик часто теряет общее представление о структуре модулей. Текстовые объяснения в чате не дают целостной картины навигации по проекту. Плагин Understand Anything разворачивается прямо внутри CLI-агента Claude Code, анализирует кодовую базу через подчинённых агентов и строит веб-дашборд с разделением на функциональные слои и пошаговым маршрутом чтения кода.

Тайминг: ▶ 00:42▶ 01:12

Выгода: Полный интерактивный тур по 170+ файлам проекта без необходимости вручную читать каждый модуль; экономия 2–3 часов при первом знакомстве с AI-кодом.

Как применить:

• Шаг 1: Установка плагина — Claude Code CLI] — Добавьте маркетплейс и установите плагин Understand Anything в окружение Claude Code:

claude plugin marketplace add understand-anything
claude plugin install understand-anything

• Шаг 2: Запуск сканирования проекта — Claude Code CLI] — Перейдите в корень репозитория и запустите базовое сканирование:

understand

• Шаг 3: Настройка фильтрации файлов — Интерактивный CLI] — При запросе исключений выберите рекомендуемые правила (skip experimental/temp files), чтобы не расходовать контекст на временные файлы и кэш.
• Шаг 4: Исследование веб-дашборда — Web Browser] — Откройте сгенерированный локальный дашборд. Пройдите по слоям (UI, Engine, Rendering, Export, Tests) и запустите режим Project Tour, который выстроит логический порядок чтения ключевых файлов с автоописанием функций.

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

2. Глубокий анализ бизнес-логики и влияния изменений через скиллы Understand Anything

Контекст: Знания структуры файлов недостаточно для понимания того, как реализованы бизнес-процессы (например, захват видео, матчинг дублей со сценарием, экспорт таймлайна). Кроме того, при внесении правок вайбкодеру нужно знать, какие модули сломаются. В Understand Anything встроены специализированные навыки (skills) для объяснения конкретных файлов, построения предметной (доменной) карты и проверки Git-диффов.

Тайминг: ▶ 02:33▶ 03:17

Выгода: Мгновенный ответ на вопрос «что делает этот файл и с чем он связан» без перегрузки контекста всей кодовой базой; автоматический аудит влияния правок перед коммитом.

Как применить:

• Шаг 1: Анализ конкретного файла — Claude Code CLI] — Вызовите команду детального разбора для интересующего файла (например, Swift-контроллера):

understand explain path/to/AI.swift

• Шаг 2: Построение карты доменной области — Claude Code CLI] — Запустите дополнительный агентский прогон для анализа бизнес-сценариев:

understand domain

• Шаг 3: Запросы к кодовой базе на естественном языке — Claude Code CLI] — Задавайте вопросы Claude Code, используя сохранённую карту проекта вместо чтения сырых файлов:

claude "Используя сохранённую карту understand, объясни, как устроен пайплайн рендеринга видео"

• Шаг 4: Проверка влияния изменений перед коммитом — Claude Code CLI] — Запустите Git-анализ изменений для выявления затронутых компонентов:

understand git-change

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

3. Архитектурное моделирование системы по C4-методологии через Groma

Контекст: Большие системы требуют строгой иерархии: Система → Контейнеры (отдельные приложения/сервисы) → Компоненты → Код. Инструмент Groma (groma.md) использует модель C4 и собственные статические сканеры (для Python, Swift и других языков), которые строят первичную архитектурную схему без затрат токенов LLM.

Тайминг: ▶ 03:30▶ 04:24

Выгода: Нулевые затраты токенов на первичное сканирование; структурирование архитектуры по международному стандарту C4.

Как применить:

• Шаг 1: Установка Groma CLI — Terminal / npm] — Установите пакет глобально через Node Package Manager:

npm install -g groma

• Шаг 2: Запуск веб-интерфейса — Terminal] — Выполните команду инициализации веб-сервера в директории проекта:

groma web

• Шаг 3: Автоматическое статическое сканирование — Groma Web] — Выберите встроенные сканеры под ваш стек (например, Python Scanner + Swift Scanner) для формирования первичного графа зависимостей.

Результат: Развернутый локальный сервер Groma с базовой C4-картой системы, содержащей распознанные модули и файлы.

4. Очистка и группировка C4-карты Groma с помощью Claude

Контекст: Автоматические статические парсеры часто создают «кашу» из несвязанных приложений, дробя проект на десятки мелких несвязанных блоков вместо логических контейнеров (например, Python Engine и macOS SwiftUI App). Groma предоставляет структурированные инструкции и промпты, которые передаются в Claude для перегруппировки компонентов, описания их назначения и выстраивания связей.

Тайминг: ▶ 04:32▶ 05:40

Выгода: Получение архитектурной схемы с точной иерархией контейнеров и компонентов за 5 минут работы ИИ-агента вместо ручной отрисовки в Figma/Miro.

Как применить:

• Шаг 1: Экспорт инструкций реорганизации — Groma Web] — Скопируйте системный промпт и спецификацию карты из интерфейса Groma.
• Шаг 2: Запуск задачи рефакторинга карты в Claude — Claude Code / Claude Desktop] — Передайте промпт с запросом на агрегацию разрозненных модулей в логические контейнеры:

Follow Groma's C4 reorganization rules. Group the scanned components into two primary containers:
1. Python Engine (video processing, cut pipeline, export)
2. macOS SwiftUI App (UI state, screen routers, user interactions)
Generate clear descriptions for each component, specify technologies used, and document data flows between them.

• Шаг 3: Применение обновлений — Groma Web] — Наблюдайте за перерисовкой графа в реальном времени по мере сохранения файлов разметки агентом.

Результат: Чистая двухуровневая архитектура с понятным разделением ответственности, описанием технологий и ссылками на исходный код.

5. Интерактивная 2D-навигация, подсветка синтаксиса и именованные потоки данных

Контекст: На этапе отладки важно видеть не только статические блоки, но и динамику: как данные перетекают из интерфейса в обработчик и на выгрузку. Groma поддерживает именованные сквозные потоки (Named Flows), переключение уровней детализации C4 (от общего System Context до Component), 2D/3D режимы и встроенный просмотрщик с полноценной подсветкой синтаксиса.

Тайминг: ▶ 05:25▶ 06:35

Выгода: Наглядное отслеживание сквозных пользовательских путей (User Flows) и проверка исходного кода в одном окне без переключения в IDE.

Как применить:

• Шаг 1: Переключение на 2D-режим — Groma UI] — Выберите 2D View вместо наклонного 3D-режима (Angled View) для максимальной читаемости текста и связей.
• Шаг 2: Управление уровнями C4 — Панель слоев] — Скройте детальные компоненты для демонстрации общей картины стейкхолдерам, затем раскройте уровень Container → Component для погружения в логику конкретного модуля.
• Шаг 3: Трассировка сквозного потока (Named Flow) — Groma UI] — Активируйте сценарий (например, Editing and Review -> Timeline Export to Premiere Pro), чтобы подсветить цепочку вызовов от UI-экрана через Python-пайплайн до финального экспорта файла.
• Шаг 4: Инспекция кода — Встроенный редактор] — Кликните по компоненту и откройте файл: код отобразится с нативной подсветкой синтаксиса (Swift, Python и др.).

Результат: Полное понимание пути движения данных внутри проекта с возможностью быстрой валидации реализации в коде.

6. Сравнение эффективности: Время выполнения и расход токенов

Контекст: Использование ИИ-агентов для анализа больших репозиториев влечет прямые затраты времени и контекстных токенов. Понимание метрик обоих инструментов позволяет выбрать оптимальный подход в зависимости от бюджета и сложности задачи.

Тайминг: ▶ 07:54▶ 08:28

Выгода: Оптимизация расходов на API Claude; выбор инструмента под конкретную задачу (быстрый визуальный скелет vs глубокий агентский аудит).

Сравнительная таблица метрик (на проекте из 178 файлов):

Результат: Четкие критерии выбора: Understand Anything — для управляемого онбординга и вопросов в CLI; Groma — для быстрой архитектурной схемы C4 и визуализации связей.

FAQ

В: Можно ли использовать Groma без плагина Backlog.md?

О: Да. Groma работает полностью автономно как инструмент визуализации архитектуры. Backlog.md требуется только в том случае, если вы хотите привязать задачи и бэклог проекта прямо к узлам архитектурной карты.

В: Почему первичное сканирование Groma выглядит хаотично?

О: Статический сканер опирается исключительно на файловую структуру и директории без понимания семантики. Чтобы объединить разрозненные файлы в логические сервисы (контейнеры C4), требуется запустить очистку через Claude по встроенным правилам Groma.

В: Поддерживает ли Understand Anything просмотр кода с подсветкой синтаксиса?

О: На текущий момент в веб-интерфейсе Understand Anything код открывается простым текстом без синтаксической подсветки. В Groma встроен полноценный просмотрщик с корректной подсветкой для Swift, Python и других языков.

В: Зачем использовать команду understand domain, если уже есть базовый скан?

О: Базовый скан группирует систему по техническим слоям (UI, Rendering, Tests). Команда understand domain перестраивает карту с точки зрения бизнес-логики (импорт материала, сопоставление дублей, авторедактирование), что помогает быстрее понять предметную суть продукта.

В: Учитывают ли метрики расхода токенов кэширование контекста?

О: Да, озвученные цифры (11.5M и 4M токенов) отражают общий трафик с учетом повторного чтения кэшированного контекста (Prompt Caching) при многоагентных прогонах в Claude.

В: Как CLI-агент Claude Code использует сохраненную карту Understand Anything?

О: После сканирования плагин сохраняет структурированную карту проекта локально. При последующих вопросах Claude читает компактную карту вместо повторного сканирования сотен файлов, что экономит токены и ускоряет ответы.

Ресурсы и ссылки

• Understand Anything — плагин для Claude Code для автоматического создания интерактивных карт кодовой базы и онбординга — упомянут в видео.
• Groma (groma.md) — архитектурный инструмент визуализации кодовых баз на основе модели C4 (автор: Alex) — упомянут в видео.
• Backlog.md — инструмент интеграции задач и бэклога в архитектурную карту Groma — упомянут в видео.
• The Gray Cut — гибридное приложение автора (Python engine + SwiftUI macOS app), использованное в качестве тестовой кодовой базы (178 файлов) — упомянуто в видео.

Конспект создан на основе видео «How to visualize your codebase (Understand Anything and Groma)» канала Alex Finn / Vibe Coding. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=9DT8y0dnga8