Этот инструмент исправляет ошибочные AI-диаграммы

AI-агенты часто лгут при отображении вашей кодовой базы. Попросите агента по программированию составить диаграмму репозитория, и вы можете увидеть Kafka, Redis или API-шлюз, которых на самом деле не существует. Эти диаграммы часто выглядят правдоподобно, но они галлюцинируют компоненты, делая всё изображение ненадежным и бесполезным для реальной разработки. Вы не можете полагаться на визуальные эффекты, рожденные вымыслом.

Archify решает эту проблему напрямую. Его AI-агент ничего не рисует; вместо этого он описывает систему в виде структурированного, типизированного JSON. Этот фундаментальный сдвиг отделяет точное описание системы от ее визуального представления. Затем Archify тщательно проверяет этот JSON перед появлением любой диаграммы, обеспечивая точность с самого начала.

Представьте Archify как LLVM для системных карт. AI-агент по программированию выступает в роли фронтенда, генерируя первоначальное описание системы. Это описание становится проверенным JSON Intermediate Representation (IR), который должен соответствовать строгим схемам. Только после прохождения этих проверок локальный компилятор превращает IR в финальный интерактивный HTML, гарантируя многоэтапный, проверяемый результат вместо догадок.

Archify не просто позволяет AI «рисовать» диаграмму. Вместо этого он требует, чтобы AI-агент выдавал структурированное, типизированное JSON Intermediate Representation (IR). Этот IR затем попадает в строгий, детерминированный конвейер проверки. Archify проверяет его на соответствие строгим схемам и атомарным шлюзам для обеспечения целостности, гарантируя, что описание системы является верным.

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

Далее, Archify добавляет мощный уровень проверяемых доказательств с помощью функции Repo Evidence. Узлы на диаграмме могут отображать значок «SRC». Нажмите на него, и вы перейдете непосредственно к конкретному коду, коммиту и даже точному диапазону строк в вашем репозитории, которые доказывают существование компонента. Таким образом, архитектура является доказуемо истинной, а не просто правдоподобной.

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

После того как компилятор Archify проверяет JSON, он создает автономный HTML-файл. Это не статичное изображение; это интерактивная системная карта, которая предлагает реальную пользу. Вы можете найти любой сервис, мгновенно обнаружив его восходящие и нисходящие зависимости. Затем интерактивно отслеживайте сложные потоки, например, следуя пути «cache miss» через всю вашу систему, шаг за шагом, вместо того чтобы просто смотреть на статичную диаграмму.

Для pull-запросов функция architecture diffing дает решающее преимущество. Archify сравнивает два проверенных снимка вашей системы, создавая визуальное сравнение «До, Дельта, После». Это четко выделяет каждое архитектурное изменение: какие компоненты были добавлены, удалены или перенаправлены, что делает проверку кода более надежной и предотвращает непреднамеренные сдвиги.

Хотя интерактивный HTML-файл является основным артефактом и самой сильной стороной Archify, он также предлагает надежные возможности экспорта. Вы можете легко создавать статические изображения в форматах PNG, JPEG, WebP, SVG и WebM. Он также создает удобные карточки для публикации размером 1200x630 для быстрого обмена информацией. Но важно понимать, что эти экспортируемые файлы вторичны; истинная ценность заключается в динамичном, интерактивном HTML. Чтобы глубже изучить возможности Archify, посетите его репозиторий на GitHub: tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. - GitHub.

Archify лучше всего работает, когда вы задаете ему конкретные, ограниченные вопросы. Избегайте расплывчатых инструкций вроде «составь карту этого репозитория»; это обычно приводит к получению большого объема бесполезных данных. Вместо этого задайте точный вопрос, например: «Нарисуй диаграмму потока аутентификации пользователя при промахе кэша», возможно, ограничив ее 8-12 узлами для ясности и фокусировки. Такой целенаправленный подход обеспечивает значимый и проверенный результат.

Однако Archify не является универсальным решением. Он не идеален для простых диаграмм, встроенных непосредственно в README на GitHub, так как GitHub не отображает его интерактивный HTML-вывод. Инструмент также требует наличия существующего рабочего процесса AI-агента с использованием таких платформ, как Claude Code или Cursor, интегрируясь как навык агента, а не как отдельное приложение.

В ответственных ситуациях Archify действительно проявляет себя лучше всего. Его проверенный, интерактивный вывод создает верифицируемые артефакты для критических этапов разработки. К ним относятся:

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

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

Что такое Archify?

Archify — это open-source навык агента, который позволяет AI-агентам для кодинга, таким как Claude, создавать верифицируемые, интерактивные архитектурные диаграммы. Он работает за счет того, что агент создает структурированное JSON-представление системы, которое Archify затем проверяет и компилирует в автономный HTML-файл.

Как Archify предотвращает появление неточных диаграмм?

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

Какие AI-агенты работают с Archify?

Archify разработан как навык агента и интегрируется с несколькими популярными помощниками по кодингу, включая Claude Code, Cursor, Codex CLI, OpenCode и DeepSeek Harness.

Является ли Archify заменой Mermaid?

Для созданных AI, интерактивных и верифицируемых диаграмм, используемых в PR или при обзоре дизайна, Archify предлагает превосходные функции. Однако для простых диаграмм, встроенных непосредственно в README на GitHub, Mermaid часто является более простым выбором, так как его вывод нативно отображается на GitHub.