Dieses Tool repariert fehlerhafte KI-Diagramme

KI-Agenten lügen oft, wenn sie Ihre Codebasis abbilden. Wenn Sie einen Coding-Agenten bitten, ein Repo zu diagrammieren, sehen Sie möglicherweise Kafka, Redis oder ein API-Gateway, das gar nicht existiert. Diese Diagramme sehen oft plausibel aus, aber sie halluzinieren Komponenten, was die gesamte Visualisierung für die reale Entwicklung unzuverlässig und nutzlos macht. Sie können sich nicht auf Visualisierungen verlassen, die aus Fiktion entstanden sind.

Archify geht dieses Problem direkt an. Sein KI-Agent zeichnet nichts; stattdessen beschreibt er das System als strukturiertes, typed JSON. Dieser grundlegende Wandel trennt die präzise Beschreibung des Systems von seiner visuellen Darstellung. Archify validiert dieses JSON dann rigoros, bevor überhaupt ein Diagramm erscheint, und stellt so Genauigkeit von Grund auf sicher.

Stellen Sie sich Archify wie LLVM für Systemkarten vor. Der KI-Coding-Agent fungiert als Frontend und generiert die anfängliche Systembeschreibung. Diese Beschreibung wird zu einer validierten JSON Intermediate Representation (IR), die sich an strikte Schemata halten muss. Erst nach Bestehen dieser Prüfungen wandelt ein lokaler Compiler die IR in das endgültige, interaktive HTML um, was eine mehrstufige, überprüfbare Ausgabe anstelle von Raten garantiert.

Archify lässt eine KI nicht einfach ein Diagramm „zeichnen“. Stattdessen verlangt es vom KI-Agenten die Ausgabe einer strukturierten, typisierten JSON Intermediate Representation (IR). Diese IR durchläuft dann eine rigorose, deterministische Validierungspipeline. Archify prüft sie gegen strikte Schemata und atomare Gates auf Integrität, um sicherzustellen, dass die Systembeschreibung Bestand hat.

Entscheidend ist, dass schlechtes JSON nicht auf magische Weise zu einem fehlerhaften Diagramm wird. Wenn der Graph ungültig ist, bricht Archify den Prozess ab und liefert klare Diagnosen und Regelcodes. Das bedeutet, Sie erhalten Fehlermeldungen, auf die Sie reagieren können, anstatt einer visuellen Darstellung zu vertrauen, die stillschweigend falsch ist. Dieser „Fail-Closed“-Ansatz schafft grundlegende Zuverlässigkeit.

Als Nächstes fügt Archify mit seiner Repo Evidence-Funktion eine leistungsstarke Ebene überprüfbarer Beweise hinzu. Knoten in einem Diagramm können ein „SRC“-Abzeichen anzeigen. Klicken Sie darauf, und Sie springen direkt zum spezifischen Code, Commit und sogar zum exakten Zeilenbereich innerhalb Ihres Repositorys, der die Existenz der Komponente beweist. Die Architektur ist daher nachweislich wahr und nicht nur plausibel.

Betrachten Sie Tools wie Mermaid: Sie können syntaktisch korrektes Diagramm-Code schreiben, aber es könnte dennoch ein Diagramm generieren, das logisch fehlerhaft ist oder Komponenten enthält, die in Ihrer tatsächlichen Codebasis nicht vorhanden sind. Archifys umfassende Validierungsebene, gepaart mit seinen direkten Code-Verknüpfungsbeweisen, fügt eine entscheidende Dimension von semantic trust hinzu, die anderen Tools einfach fehlt.

Nachdem der Compiler von Archify das JSON validiert hat, erstellt er eine self-contained HTML file. Dies ist kein statisches Bild; es ist eine interaktive Systemkarte, die echten Nutzen bietet. Sie können nach jedem Dienst suchen und sofort dessen Upstream- und Downstream-Abhängigkeiten aufdecken. Verfolgen Sie dann interaktiv komplexe Abläufe, wie zum Beispiel einen „Cache-Miss“-Pfad durch Ihr gesamtes System, Schritt für Schritt, anstatt nur auf ein statisches Diagramm zu starren.

Für Pull Requests bietet die architecture diffing-Funktion einen entscheidenden Vorteil. Archify vergleicht zwei validierte Snapshots Ihres Systems und generiert einen visuellen „Vorher, Delta, Nachher“-Vergleich. Dies hebt jede architektonische Änderung klar hervor: welche Komponenten hinzugefügt, entfernt oder umgeleitet wurden, was Code-Reviews wesentlich robuster macht und unbeabsichtigte Verschiebungen verhindert.

Während die interaktive HTML-Datei das primäre Artefakt und das stärkste Feature von Archify ist, bietet es auch robuste Exportfunktionen. Sie können problemlos statische Bilder in Formaten wie PNG, JPEG, WebP, SVG und WebM generieren. Es erstellt zudem praktische 1200x630 Share-Cards für die schnelle Kommunikation. Bitte beachten Sie jedoch, dass diese Exporte zweitrangig sind; der wahre Wert liegt im dynamischen, erkundbaren HTML. Für einen tieferen Einblick in die Funktionen von Archify besuchen Sie das GitHub-Repository: 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 glänzt, wenn Sie spezifische, begrenzte Fragen stellen. Vermeiden Sie vage Anweisungen wie „dieses Repo abbilden“; das führt meist zu unbrauchbaren Ergebnissen. Stellen Sie stattdessen eine präzise Frage, wie zum Beispiel: „Erstelle ein Diagramm des Benutzerauthentifizierungs-Flows bei einem Cache-Miss“, und beschränken Sie es für mehr Klarheit und Fokus auf 8-12 Knoten. Dieser zielgerichtete Ansatz stellt sicher, dass Sie aussagekräftige, validierte Ergebnisse erhalten.

Archify ist jedoch keine Universallösung. Es ist nicht ideal für einfache Diagramme, die direkt in GitHub-READMEs eingebettet werden sollen, da GitHub seine interaktive HTML-Ausgabe nicht rendert. Das Tool erfordert zudem einen bestehenden AI agent workflow unter Verwendung von Plattformen wie Claude Code oder Cursor und lässt sich eher als Agent-Skill denn als eigenständige App integrieren.

In kritischen Situationen glänzt Archify besonders. Seine validierte, interaktive Ausgabe schafft verifizierbare Artefakte für entscheidende Entwicklungsphasen. Dazu gehören:

• Das Generieren von Architekturdiagrammen für PR-Reviews, die ein klares Delta der Änderungen bieten.
• Das Entwerfen neuer Funktionen innerhalb von Designdokumenten.
• Die Etablierung einer zuverlässigen, commit-bereiten Source of Truth für Systemkomponenten in Ihrem Repository.

Dieser Ansatz verwandelt Diagramme von statischen Bildern in vertrauenswürdige, bearbeitbare Systemkarten und macht sie zu einem unverzichtbaren Bestandteil Ihres Engineering-Prozesses.

Was ist Archify?

Archify ist ein Open-Source-Agent-Skill, der es KI-Coding-Agenten wie Claude ermöglicht, verifizierbare, interaktive Architekturdiagramme zu generieren. Es funktioniert, indem der Agent eine strukturierte JSON-Repräsentation eines Systems erstellt, die Archify anschließend validiert und in eine in sich geschlossene HTML-Datei kompiliert.

Wie verhindert Archify ungenaue Diagramme?

Anstatt die KI ein Bild „zeichnen“ zu lassen, erzwingt Archify eine strikte Validierungspipeline. Die KI muss einen typisierten JSON-Graphen ausgeben, der einem Schema entspricht. Wenn das JSON ungültig ist oder einen unmöglichen Zustand beschreibt, schlägt der Prozess mit einer klaren Diagnose fehl, wodurch die Erstellung irreführender Diagramme verhindert wird.

Welche KI-Agenten funktionieren mit Archify?

Archify ist als Agent-Skill konzipiert und lässt sich in verschiedene beliebte Coding-Assistenten integrieren, darunter Claude Code, Cursor, Codex CLI, OpenCode und DeepSeek Harness.

Ist Archify ein Ersatz für Mermaid?

Für KI-generierte, interaktive und verifizierbare Diagramme, die in PRs oder Design-Reviews verwendet werden, bietet Archify überlegene Funktionen. Für einfache Diagramme, die direkt in ein GitHub-README eingebettet werden, ist Mermaid jedoch oft die unkompliziertere Wahl, da dessen Ausgabe nativ von GitHub gerendert wird.