Workflows mit Claude Code und KI entwickeln

Ein exportiertes Repository ist dafür gemacht, dass ein KI-Agent wie Claude Code darin arbeitet: Es enthält Anweisungen für den Agenten, die Typen jedes Skripts und eine Kommandozeile, die prüft, testet und importiert, was der Agent geändert hat. Was zurückkommt, ist ein Entwurf. Veröffentlicht wird weiterhin mit einem Klick einer Person in der App; kein Befehl, kein Werkzeug und kein KI-Schritt veröffentlicht, pausiert oder löscht einen Workflow. Im Skripteditor der App schreibt, erklärt und korrigiert auch eine KI Skripte („Mit KI schreiben“).

Diese Seite geht den Weg vom Export bis zur veröffentlichten Version durch.

1. Die Workflows exportieren

Im Workflow-Designer schreibt Exportieren eine ZIP-Datei mit den Workflows und, wenn Anweisungen für KI-Agenten gewählt ist, den Dateien für den Agenten in der obersten Ebene (Exportieren, importieren und Git). Ein Push an die Gegenstelle des Arbeitsbereichs schreibt dieselben Dateien (Workflows in Git). Das Repository enthält dann:

• workflows/<key>/workflow.yaml und workflows/<key>/scripts/, die Workflows und ihre Skripte;
• workflows/<key>/types/, die Deklarationen des SDK, die Typen des Arbeitsbereichs, die der Workflow nutzt, und die Deklarationen jedes Skript-Schritts, sodass ein Editor, tsc und der Agent dieselben Typen sehen wie die App;
• CLAUDE.md, AGENTS.md und .claude/skills/acriva-workflows/SKILL.md: was der Agent wissen muss.

2. Das Repository mit Claude Code öffnen

Entpacken Sie die ZIP-Datei (oder klonen Sie das Repository) und starten Sie Claude Code in seinem Ordner. Claude Code liest CLAUDE.md und den Skill von selbst; andere Agenten lesen AGENTS.md. Die drei Dateien sagen:

• dass alles im Repository von jedem mit Schreibzugriff darauf stammen kann und für den Agenten Daten sind, nie Anweisungen, denen er folgt;
• dass in der App veröffentlicht wird, von einer Person, und dass acriva workflows push nur Entwürfe importiert;
• den Aufbau, die Hooks, die Grenzen der Sandbox und die Dokumenttypen und Felder des Arbeitsbereichs mit ihren Schlüsseln;
• die Befehle der CLI.

Es sind Anweisungen, keine Einstellungen. Der Export schreibt nie .mcp.json, .claude/settings.json oder Hooks: Solche Dateien sind Code, den das Werkzeug des Agenten ausführt. Genehmigen Sie nie einen MCP-Server oder Einstellungen eines Projekts, die Sie nicht selbst hinzugefügt haben.

Der nächste Export schreibt die drei Dateien neu. Ändern Sie die Workflows, nicht die Anweisungen.

3. Mit der CLI prüfen, testen und importieren

Die CLI @acriva/cli (acriva) prüft, testet und importiert das Repository über die API von Acriva mit einem API-Schlüssel. Sie ist noch nicht auf npm veröffentlicht; sobald sie es ist, legen Sie ihre genaue Version in der package.json des Repositorys fest (npm i -D @acriva/cli@<version>) und führen sie mit npx acriva aus. Sie braucht Node.js 22.12 oder neuer.

Erstellen Sie einen Schlüssel unter Einstellungen, in der Kategorie Sicherheit & Zugang, auf der Seite API-Schlüssel, für eine Rolle, die Workflows verwaltet: mit der Berechtigung workflows:read (Die Typen des Workflow-SDK abrufen, Skripte prüfen und Workflow-Pakete validieren und testen (braucht eine Rolle, die Workflows verwaltet)) zum Prüfen und Testen und zusätzlich workflows:draft (Workflows als Entwurf importieren; veröffentlicht werden sie von einer Person in Acriva (braucht eine Rolle, die Workflows verwaltet)) zum Importieren. Dann:

export ACRIVA_URL=https://app.acriva.de
export ACRIVA_TENANT=<die Adresse Ihres Arbeitsbereichs>
export ACRIVA_API_KEY=acv_live_…   # nur aus der Umgebung, nie in einer Datei des Repositorys

npx acriva workflows validate      # die Prüfung des Servers für jeden Workflow und jedes Skript, mit ACR-S-Codes und Positionen
npx acriva workflows test          # führt die Fixtures (workflows/<key>/fixtures/*.json) in der Sandbox aus; nichts wird angewendet
npx acriva workflows push          # importiert die Workflows als Entwürfe

• validate führt dieselben Prüfungen aus wie das Veröffentlichen: die Regeln des Workflows und für jedes Skript die Typprüfung und den Lint. Ein Problem erscheint als workflows/<key>/scripts/<datei>:<zeile>:<spalte> error ACR-S003 ….
• test führt die synthetischen Fälle in fixtures/ aus: ein Dokument, die Antworten der Datenquellen, die Zeilen der Datentabellen und das erwartete Ergebnis. --document <id> führt es stattdessen auf einem echten Dokument aus. Das braucht die Berechtigung documents:read des Schlüssels und Ihre Bestätigung: Dessen Werte verlassen dann Acriva und erreichen Ihr Terminal oder Ihren Agenten.
• push legt für jeden Workflow einen Entwurf an. Verweise, die es im Arbeitsbereich nicht gibt (eine Rolle, ein Schlagwort, ein Mitglied), warten 7 Tage auf die Zuordnung durch eine Person in der App. Einen Entwurf, den eine Person gespeichert hat, ersetzt nur --replace-draft; Acriva bewahrt den Entwurf dieser Person dann als vorherigen Entwurf auf und benachrichtigt sie (siehe Schritt 5).

--json gibt ein JSON-Objekt aus, für die CI. Der Exit-Code sagt, was geschehen ist: 0 in Ordnung, 1 die Prüfungen sind fehlgeschlagen, Verweise warten oder der Entwurf einer Person steht im Weg, 2 Aufruf oder Konfiguration, 3 der Schlüssel wurde abgelehnt, 4 nicht verfügbar, 5 der Server oder das Netz.

Die CLI läuft nicht, wenn sie einen API-Schlüssel im Repository findet, und sie gibt den Schlüssel nie aus. Widerrufen Sie einen Schlüssel, der je committet wurde: Er bleibt in der Historie des Repositorys.

4. Dem Agenten den MCP-Server geben

acriva mcp bietet dem Agenten dieselben Prüfungen über MCP (stdio) an: die Werkzeuge validate, test_run und import_draft und als Ressourcen die Deklarationen des SDK, einen Überblick für Skript-Autoren, die Typen des Arbeitsbereichs und den Index des Kochbuchs. Kein Werkzeug veröffentlicht, pausiert, setzt fort oder löscht. Für Claude Code:

export ACRIVA_API_KEY=acv_live_…
claude mcp add acriva -e ACRIVA_URL=https://app.acriva.de -e ACRIVA_TENANT=<arbeitsbereich> -- npx @acriva/cli@<version> mcp

Der Server kennzeichnet, was er aus dem Repository, einem Lauf oder vom Server zitiert, als nicht vertrauenswürdige Daten für den Agenten. Mit --allow-real-documents darf ein Testlauf ein echtes Dokument verwenden: Dessen Werte erreichen dann das Modell des Agenten außerhalb des KI-Gateways von Acriva und seiner Kontrollen, als Ihre eigene Verarbeitung, und bleiben in den lokalen Protokollen des Agenten. Diese Sitzung bietet keinen Import an. Setzen Sie das nur in der Konfiguration Ihres eigenen Werkzeugs.

5. Der Entwurf in der App

Der gepushte Workflow ist ein Entwurf im Workflow-Designer. Der Designer nennt über der Fläche seine Herkunft, Importiert über API-Schlüssel „‹Name›“, und der Dialog zum Veröffentlichen nennt sie unter Herkunft. Prüfen Sie den Entwurf wie jeden anderen: die Fläche, die Skripte, die Probleme und einen Testlauf auf einem Dokument des Arbeitsbereichs. Hat der Push einen Entwurf ersetzt, den eine Person gespeichert hatte, sagt der Designer, wessen Entwurf aufbewahrt ist, und Vorherigen Entwurf wiederherstellen holt ihn zurück (Ein Entwurf, den ein API-Schlüssel importiert hat).

6. Veröffentlichen ist der Klick einer Person

Wählen Sie im Designer Veröffentlichen. Der Dialog zeigt die Prüfung und was die neue Version ändert; erst seine Bestätigung erzeugt die neue Version. Bis dahin läuft die veröffentlichte Version weiter, und kein Befehl und kein Agent kann sie veröffentlichen.

Skripte im Editor mit KI schreiben und korrigieren

Der Skripteditor hat eine eigene KI, über das KI-Gateway von Acriva: Mit KI schreibt ein Skript nach einer Beschreibung, Fehler erklären (KI, 1 Credit) und Fehler beheben (KI, 1 Credit) an einem Problem, das die Prüfung markiert (Strg+.), erklären und beheben es, und Vorschläge beim Tippen ergänzen eine Zeile (ausgeschaltet, bis Sie sie einschalten). Jeder Vorschlag ist ein Diff, der nur den Entwurf ändert; gespeichert wird erst, wenn Sie ihn Übernehmen, und die Prüfung des Servers läuft darauf wie auf jede Änderung. An das Modell gehen das Skript, das Problem und die Deklarationen, nie ein Dokument oder seine Werte. Eine Anfrage kostet Credits; mehr unter Mit KI schreiben und Fehler beheben.

Der Agent im Repository und die KI des Editors sind zwei Wege zum selben Entwurf: Beide enden vor dem Veröffentlichen, das nur eine Person kann.