KI-gestützte Entdeckung

Connect a repository from the project settings to enable AI discovery

Die KI-Entdeckungsfunktion von Archyl analysiert Ihre Codebasis, um Ihre Softwarearchitektur automatisch zu entdecken und zu dokumentieren. Dies spart Stunden manueller Dokumentationsarbeit und stellt sicher, dass Ihre Architekturdokumentation mit Ihrem tatsächlichen Code synchron bleibt.

So funktioniert es

1. Verbinden Sie Ihr Repository

Verbinden Sie zunächst Ihr Git-Repository mit Archyl:

  1. Gehen Sie zu Ihren Projekteinstellungen
  2. Klicken Sie auf "Repository verbinden"
  3. Wählen Sie Ihren Git-Anbieter (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea oder selbst gehostete Instanzen)
  4. Autorisieren Sie Archyl für den Zugriff auf Ihr Repository

2. Starten Sie die Entdeckung

Nach der Verbindung starten Sie die KI-Entdeckung:

  1. Klicken Sie in Ihrem Projekt auf "Entdeckung starten"
  2. Wählen Sie den zu analysierenden Branch
  3. Klicken Sie auf "Entdeckung ausführen"

3. KI-Analyse

Die KI analysiert Ihre Codebasis in mehreren Phasen:

  1. Strukturanalyse — Ermittelt den Systemnamen, die Container und externe Abhängigkeiten
  2. Detaillierte Entdeckung — Analysiert Quelldateien in parallelen Blöcken, um Komponenten, Code-Elemente und Beziehungen zu finden
  3. Beziehungsverfeinerung — Gleicht Container miteinander ab, um Abhängigkeiten zwischen Services zu finden
  4. Parallele Nachanalyse — Entdeckt ADRs, Dokumentation, API-Verträge und Paketabhängigkeiten

Zu den entdeckten Elementen gehören:

  • Systeme: Übergeordnete Softwaresysteme und externe Abhängigkeiten
  • Container: Services, APIs, Datenbanken, Webanwendungen, Worker
  • Komponenten: Module, Pakete, Handler, Repositories, Services
  • Code-Elemente: Klassen, Interfaces, Funktionen mit Dateipfaden
  • Beziehungen: Wie Elemente kommunizieren (nutzt, ruft auf, sendet an, liest von)

4. Überprüfen & Genehmigen

Entdeckungen werden zur Überprüfung in den Status Ausstehend versetzt:

  1. Überprüfen Sie jedes entdeckte Element
  2. Bearbeiten Sie Namen, Beschreibungen oder Beziehungen
  3. Genehmigen Sie zutreffende Entdeckungen
  4. Lehnen Sie fehlerhafte ab oder ändern Sie sie

Bei neuen Projekten (ohne bestehende C4-Elemente) werden Entdeckungen automatisch genehmigt, damit Sie schnell loslegen können.

Inkrementelle Entdeckung

Die inkrementelle Entdeckung hält Ihr C4-Modell aktuell, indem sie nur die geänderten Dateien analysiert — nicht das gesamte Repository. Das ist schneller, kostengünstiger und kann automatisch bei jedem Push ausgeführt werden.

Funktionsweise der inkrementellen Entdeckung

  1. Code wird auf den Default-Branch gepusht
  2. Archyl empfängt das Push-Event (über Webhook oder GitHub Action)
  3. Geänderte Dateien werden aus den Push-Commits extrahiert
  4. Nur Quelldateien werden analysiert (gelöschte Dateien werden übersprungen)
  5. Die KI wird auf der kleineren Dateimenge ausgeführt
  6. Neue Elemente werden als ausstehende Entdeckungen zur Überprüfung erstellt
  7. Bestehende Elemente werden automatisch dedupliziert — keine Duplikate

Inkrementelle Entdeckung aktivieren

Es gibt zwei Möglichkeiten, die inkrementelle Entdeckung zu aktivieren:

Option A: GitHub Webhook (ohne Konfiguration)

  1. Öffnen Sie die Einstellungen Webhook-Konfiguration Ihres Projekts
  2. Aktivieren Sie Discovery on Push
  3. Kopieren Sie die Webhook-URL und fügen Sie sie in den Einstellungen Ihres GitHub-Repositorys hinzu
  4. Wählen Sie das Event push

Jeder Push auf den Default-Branch löst dann automatisch eine inkrementelle Entdeckung aus.

Option B: GitHub Action (CI/CD)

Fügen Sie die Archyl Incremental Discovery Action zu Ihrem Workflow hinzu. Eine vollständige Anleitung finden Sie unter GitHub Actions Integration.

name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Vollständige vs. inkrementelle Entdeckung

Vollständige Entdeckung Inkrementelle Entdeckung
Umfang Gesamtes Repository Nur geänderte Dateien
Auslöser Manuell (UI/API) Automatisch (Push-Webhook oder GitHub Action)
Geschwindigkeit Minuten (abhängig von der Repository-Größe) Sekunden bis Minuten
KI-Kosten Höher (analysiert alle Dateien) Niedriger (analysiert nur den Diff)
Anwendungsfall Ersteinrichtung, größere Refactorings Tägliche Codeänderungen
Deduplizierung Vollständige Deduplizierung gegen das bestehende Modell Gleiche Deduplizierung — keine Duplikate

Vollständige und inkrementelle Entdeckung kombinieren

Der empfohlene Ablauf:

  1. Führen Sie eine vollständige Entdeckung aus, wenn Sie ein Repository zum ersten Mal verbinden
  2. Aktivieren Sie die inkrementelle Entdeckung, um das Modell aktuell zu halten
  3. Führen Sie die vollständige Entdeckung erneut aus nach größeren Refactorings oder Migrationen

Die inkrementelle Entdeckung erstellt ausstehende Elemente genau wie die vollständige Entdeckung — Sie prüfen Änderungen immer, bevor sie auf Ihr C4-Modell angewendet werden.

Unterstützte Technologien

Die KI-Entdeckung funktioniert mit über 15 Sprachen und Frameworks:

Sprachen

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, Scala

Build-Systeme & Paketmanager

npm, Go modules, pip/Poetry, Maven, Gradle, Cargo, Composer, RubyGems, NuGet, CMake (find_package, FetchContent, CPM), Conan, vcpkg

Frameworks

React, Next.js, Vue, Angular, Express, Fastify, NestJS, Django, Flask, FastAPI, Spring Boot, ASP.NET Core, Ruby on Rails, Gin, Fiber

Infrastruktur

Docker, Kubernetes, Terraform, Helm, Ansible, GitHub Actions, AWS CDK, Pulumi

Monorepo-Unterstützung

Archyl erkennt Monorepo-Strukturen automatisch:

  • Verzeichnisse apps/, packages/, services/, libs/
  • Proportionale Dateiauswahl über alle Services hinweg
  • Jeder Service wird im C4-Modell einem eigenen Container zugeordnet
  • Beziehungen zwischen Services werden erkannt

Best Practices

Klein anfangen

Für große Codebasen:

  1. Beginnen Sie mit einem einzelnen Service oder Modul
  2. Überprüfen und verfeinern Sie die Ergebnisse
  3. Erweitern Sie schrittweise auf andere Bereiche

Regelmäßige Aktualisierungen

Halten Sie Ihre Dokumentation aktuell:

  1. Aktivieren Sie die inkrementelle Entdeckung für automatische Aktualisierungen
  2. Überprüfen Sie ausstehende Entdeckungen regelmäßig
  3. Führen Sie nach größeren Refactorings eine vollständige Entdeckung aus

Mit manueller Arbeit kombinieren

KI-Entdeckung ist ein Ausgangspunkt:

  1. Nutzen Sie KI für die Hauptarbeit
  2. Fügen Sie Geschäftskontext manuell hinzu (Beschreibungen, ADRs)
  3. Verfeinern Sie Beziehungen und Beschreibungen

REST-API

POST   /api/v1/discovery/start                            # Start full discovery
GET    /api/v1/discovery/jobs/:jobId                       # Get job status
POST   /api/v1/projects/:id/discovery/incremental          # Trigger incremental discovery

Fehlerbehebung

Entdeckung dauert zu lange

  • Reduzieren Sie die Anzahl der analysierten Dateien (passen Sie die maximale Dateianzahl in der Konfiguration an)
  • Nutzen Sie die inkrementelle Entdeckung für regelmäßige Aktualisierungen
  • Konzentrieren Sie sich auf bestimmte Branches

Ungenaue Ergebnisse

  • Überprüfen und korrigieren Sie laufend — mit dem Ausstehend-Status können Sie jedes Element einzeln genehmigen oder ablehnen
  • Besser strukturierter Code liefert bessere Ergebnisse
  • Ergänzen Sie genehmigte Elemente um Beschreibungen, um den Kontext für künftige Entdeckungen zu verbessern

Keine Dateien analysiert

  • Prüfen Sie, ob Ihr Repository verbunden ist und der Branch existiert
  • Stellen Sie sicher, dass Quelldateien erkannte Dateiendungen haben (.go, .ts, .py, .java usw.)
  • Vergewissern Sie sich, dass das Zugriffstoken Leseberechtigungen für das Repository hat