Den Einstieg wählen

Ein Archyl-Projekt enthält ein C4-Modell Ihrer Software: Systeme, Container, Komponenten und Code sowie die Beziehungen zwischen ihnen. Es gibt vier Wege, es zu füllen. Sie lassen sich kombinieren, und keiner bindet Sie fest.

Unabhängig von Ihrer Wahl sind die nächsten Schritte dieselben: Ihre Coding-Agenten verbinden (siehe „Dann damit arbeiten“ weiter unten) und das Modell mit dem Code im Gleichschritt halten.

In der App zeichnen

Erstellen Sie ein Projekt im Dashboard und fügen Sie dann auf dem Canvas Systeme, Container und Beziehungen hinzu. Der Schnellstart-Leitfaden führt Sie Schritt für Schritt durch.

Zeichnen ist der richtige Start für ein System, das noch nicht existiert, oder um den Kontext vor dem ersten Code zu skizzieren. Sie können später zu Code wechseln: archyl dsl pull schreibt das Gezeichnete in archyl.yaml.

Mit KI entdecken

Die KI-Entdeckung liest ein verbundenes Repository und schlägt Systeme, Container, Komponenten, Beziehungen und Technologien vor. Nichts landet im Modell, bevor Sie es freigeben.

In der App: Verbinden Sie das Repository unter Projekteinstellungen › Git-Integration (siehe Git-Integration), starten Sie eine Entdeckung und prüfen Sie dann, was sie gefunden hat.

Im Terminal, im Wurzelverzeichnis des Repositorys:

archyl login
archyl init --new

init --new erstellt das Projekt, verbindet das Repository über sein Git-Remote, führt die Entdeckung vor Ihren Augen aus, öffnet das Review, zeichnet das Ergebnis und bietet an, Ihre Coding-Agenten zu verbinden. Nützliche Flags: --name, --team, --branch, --provider für ein selbst gehostetes Remote (github_enterprise, gitlab_private, gitea) und --yes, um alle Standardwerte zu übernehmen. Siehe den CLI-Leitfaden.

Die Entdeckung kommt mit Monorepos zurecht: Sie erkennt apps/, packages/, services/ und libs/ und ordnet jeden Service einem Container zu.

Als Code schreiben

Beschreiben Sie die Architektur in einer archyl.yaml im Wurzelverzeichnis des Repositorys und pushen Sie sie. Das Dateiformat steht unter Architektur als Code.

archyl login
archyl init --new --no-discover   # create the project and link this repository, no AI
$EDITOR archyl.yaml               # describe the architecture
archyl dsl diff                   # what a push would create or change
archyl dsl push                   # import it
archyl diagram                    # look at the result

Eine minimale Datei:

version: "1.0"
systems:
  - name: Shop
    containers:
      - name: Storefront
        type: web_app
        technologies: [React]
      - name: Orders API
        type: api
        technologies: [Go]
      - name: Orders DB
        type: database
        technologies: [PostgreSQL]
  - name: Stripe
    external: true
relationships:
  - from: Storefront
    to: Orders API
    label: Places orders
    type: calls
  - from: Orders API
    to: Orders DB
    type: reads_from
  - from: Orders API
    to: Stripe
    label: Charges cards
    type: calls

Elemente werden über ihren Namen zugeordnet. Ein Push legt Neues an, aktualisiert Geändertes und löscht nie: Ein Element, das nur Archyl hat, bleibt bestehen, und archyl dsl diff führt es als „only in Archyl“ auf.

Ihr Coding-Agent kann die erste Version schreiben: Führen Sie archyl setup aus und bitten Sie ihn dann, das Repository gemäß dem Schema in archyl.yaml zu beschreiben. Prüfen müssen Sie die Datei trotzdem selbst.

Um Datei und Modell im Gleichschritt zu halten, committen Sie archyl.yaml und pushen sie entweder aus der CI mit der GitHub Action oder nutzen Jetzt synchronisieren unter Projekteinstellungen › Architektur als Code. archyl dsl diff --exit-code lässt einen CI-Job fehlschlagen, wenn beide voneinander abweichen.

Aus einem anderen Tool importieren

Klicken Sie in der Projektliste auf Projekt importieren und wählen Sie das Format: Archyl YAML, Structurizr DSL, LikeC4, IcePanel JSON oder Backstage JSON. Ein Structurizr-Workspace, der über !include-Dateien verteilt ist, lässt sich als Zip hochladen. Details, und wo jedes Format den Projektnamen ablegt, stehen unter Projekte importieren.

Monorepo-Durchgang

Dies ist der Code-Weg von Anfang bis Ende für ein Monorepo, ohne KI-Entdeckung:

shop/
├── apps/
│   ├── storefront/
│   └── admin/
├── services/
│   ├── orders/
│   └── payments/
└── packages/
    └── ui/

1. Projekt erstellen und Repository verknüpfen. Im Wurzelverzeichnis des Monorepos:

archyl init --new --no-discover --name "Shop" --team platform

Das schreibt .archyl.json, das das Repository mit dem Projekt verknüpft. Committen Sie die Datei: Sie enthält keine Geheimnisse.

2. Ein System mit einem Container pro deploybarer Einheit modellieren. Apps und Services werden zu Containern. Ein geteiltes Paket wie packages/ui ist meist kein eigener Container: Beschreiben Sie es als Komponente der Container, die es nutzen, oder lassen Sie es weg.

3. Jeden Container nach seinem Ordner benennen. So können archyl brief, where, check, impact und der Guard-Hook erkennen, zu welchem Element eine geänderte Datei gehört: Eine Datei gehört zu einem Element, wenn einer der Ordner in ihrem Pfad den Namen des Elements trägt. Der Vergleich ignoriert Groß- und Kleinschreibung, Leerzeichen und Satzzeichen sowie ein abschließendes Wort wie API, Service oder Worker, sodass Orders Service zu services/orders/… passt und Payments API zu services/payments/….

4. Eine oder mehrere Dateien wählen. Eine einzelne archyl.yaml im Wurzelverzeichnis ist am einfachsten. Geben Sie in einem großen Monorepo jedem Service eine eigene Datei neben seinem Code und binden Sie diese aus dem Wurzelverzeichnis ein, sodass jedes Team seinen Teil bearbeitet:

# archyl.yaml
version: "1.0"
include:
  - apps/storefront/archyl.yaml
  - services/orders/archyl.yaml
  - services/payments/archyl.yaml
systems:
  - name: Shop
    description: The online shop
  - name: Stripe
    external: true

# services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Shop
    type: api
    technologies: [Go]
relationships:
  - from: Payments API
    to: Stripe
    label: Charges cards
    type: calls

Include-Pfade sind relativ zur Datei, die sie deklariert, und Beziehungen können auf Elemente in jeder der Dateien zeigen. Die Regeln stehen unter Include.

5. Pushen und prüfen.

archyl dsl diff
archyl dsl push
archyl where services/payments/internal/charge.go   # should name Payments API
archyl diagram "Payments API"                       # the container and its neighbours

Meldet where eine Datei als nicht zugeordnet, benennen Sie den Container nach seinem Ordner um und pushen Sie erneut.

6. Aktuell halten. Committen Sie archyl.yaml und die eingebundenen Dateien. Pushen Sie bei Änderungen aus der CI oder nutzen Sie Jetzt synchronisieren, das auch die eingebundenen Dateien aus dem Repository holt.

Dann damit arbeiten

Sobald das Modell existiert:

• Verbinden Sie Ihre Coding-Agenten mit archyl setup (Claude Code, Cursor, VS Code, Codex) oder im Dashboard. Sie rufen dann plan, brief und den Harness auf, bevor sie Code ändern.
• Prüfen Sie Änderungen dagegen mit archyl check und archyl review in der CI. Siehe den CLI-Leitfaden.
• Führen Sie Menschen und Agenten ein mit archyl tour: ein geführter Rundgang durch die Teile, die man zuerst kennen sollte, mit den zu lesenden Dateien. archyl tour --markdown > ONBOARDING.md hält ihn schriftlich fest.
• Erkunden Sie es mit archyl map, archyl diagram <element> oder dem Canvas in der App.

Wege kombinieren

• Entdecken, dann als Code verwalten: Führen Sie eine Entdeckung aus, geben Sie sie frei, führen Sie dann archyl dsl pull aus und committen Sie ab da archyl.yaml.
• Als Code schreiben, dann entdecken: Eine Entdeckung schlägt nur vor, was das Modell noch nicht hat, und kann so Komponenten unter den von Ihnen geschriebenen Containern ergänzen. Prüfen Sie sie wie jede andere Entdeckung.
• In der App zeichnen und aus dem Code pushen: Beides bearbeitet dasselbe Modell. Ein Push aktualisiert, was die Datei beschreibt, und lässt den Rest unberührt.