DEV Community

Cover image for Claude Workflows automatisieren: So laufen sie von selbst
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Claude Workflows automatisieren: So laufen sie von selbst

Es gibt einen Leitsatz für agentenbasiertes Programmieren: Das Ziel ist nicht der bessere Prompt, sondern ein Workflow, der ohne permanente Überwachung läuft. Claude als Chatfenster zu nutzen funktioniert, skaliert aber nur so weit wie Ihre Aufmerksamkeit. Der größere Nutzen entsteht, wenn Claude per Zeitplan oder Trigger startet, Aufgaben abarbeitet, Ergebnisse deterministisch prüft und Menschen nur dann einbezieht, wenn eine Entscheidung nötig ist.

Apidog noch heute ausprobieren

TL;DR

Ein unbeaufsichtigter Claude-Workflow braucht fünf Bausteine:

  1. eine präzise schriftliche Spezifikation
  2. Headless-Ausführung, z. B. claude -p
  3. eine deterministische Verifikationsschranke
  4. harte Leitplanken wie Tool-Allowlists, Iterationslimits, Kostenlimits und Notschalter
  5. eine saubere Übergabe an Menschen bei Erfolg oder Fehler

Der Agent selbst ist nicht der riskante Teil. Riskant ist ein Agent ohne Schranke, ohne Grenzen und ohne Beobachtbarkeit. Bauen Sie zuerst diese Infrastruktur, dann automatisieren Sie.

Warum „läuft ohne Sie“ das eigentliche Ziel ist

Überwachter Chat hat einen klaren Engpass: Sie. Claude generiert schnell, wartet danach aber auf Ihre nächste Eingabe. Jede Iteration hängt davon ab, dass ein Mensch liest, entscheidet und erneut promptet.

Unbeaufsichtigte Workflows verschieben diese Grenze. Der Agent arbeitet, ein Skript prüft das Ergebnis, Fehler werden automatisch zurückgeführt, und Sie greifen nur an den Übergabepunkten ein. Der Vorteil ist nicht nur Geschwindigkeit, sondern Parallelität: Sie skalieren, indem Sie weitere Workflows hinzufügen, nicht indem Sie schneller tippen.

Dieses Muster haben wir bereits bei Claude Code dynamische Workflows behandelt: Eine Sitzung wird in mehrere parallele Agenten oder Aufgaben aufgeteilt.

Der Preis dafür: Ein unbeaufsichtigter Agent kann Fehler weitertragen, wenn keine Schranke existiert. Bei einem Chat merken Sie einen schlechten Diff beim Lesen. Bei einem autonomen Workflow kann der Agent committen, den nächsten Schritt ausführen und weiterlaufen. Deshalb verschiebt sich die Arbeit vom Prompt-Crafting zum Systemdesign.

Anthropic beschreibt denselben Punkt im Artikel zum Aufbau effektiver Agenten: Der Hebel liegt nicht in einer einzelnen cleveren Nachricht, sondern in der Umgebung rund um das Modell.

Die fünf Bausteine eines unbeaufsichtigten Workflows

Wenn einer dieser Punkte fehlt, macht der Workflow entweder selbstbewusst das Falsche oder hört nie auf.

1. Präzise Spezifikation

Der Agent braucht zu Beginn jedes Laufs ein klares Ziel.

Schlecht:

Repariere die API.
Enter fullscreen mode Exit fullscreen mode

Besser:

Implementiere POST /orders.

Akzeptanzkriterien:
- Gibt bei gültigem Body HTTP 201 zurück.
- Validiert den Request Body gegen das OpenAPI-Schema.
- Lehnt fehlende Pflichtfelder mit HTTP 422 ab.
- Gibt eine JSON-Antwort mit id, customer_id, total und status zurück.
Enter fullscreen mode Exit fullscreen mode

Eine gute Spezifikation ist gleichzeitig Prompt, Dokumentation und Prüfbasis.

2. Headless-Ausführung

Claude muss ohne interaktive Eingabe laufen. Dafür verwenden Sie nicht die Chat-Oberfläche, sondern einen nicht-interaktiven Modus wie claude -p.

3. Deterministische Verifikationsschranke

Der Workflow braucht eine externe Prüfung, die eindeutig pass oder fail liefert:

  • Unit-Tests
  • Integrationstests
  • Typecheck
  • Linter
  • OpenAPI-Vertragstest
  • JSON-Schema-Validierung
  • API-Test-Szenario

Wichtig: Die Schranke entscheidet, nicht das Modell.

4. Leitplanken

Ein unbeaufsichtigter Lauf braucht harte Grenzen:

  • erlaubte Tools
  • maximale Iterationen
  • Kostenlimit
  • isolierter Workspace
  • Logging
  • Notschalter

5. Übergabe

Ein Workflow darf nicht still enden. Er muss am Ende entweder:

  • einen PR-Entwurf öffnen
  • eine Benachrichtigung senden
  • einen Fehlerbericht erstellen
  • eskalieren

Stille ist kein Erfolg.

Die Claude-Bausteine

Headless-Modus mit claude -p

Der Print-Modus von Claude Code führt einen Prompt nicht-interaktiv aus und beendet sich danach. Das ist die Grundlage für geplante oder getriggerte Workflows.

claude -p "Implement the orders endpoint per spec.md, then run the test suite" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1
Enter fullscreen mode Exit fullscreen mode

Das wichtigste Flag ist hier --allowedTools.

Im Chat genehmigen Sie Aktionen manuell. Im Headless-Modus gibt es diese Kontrolle nicht. Die Tool-Allowlist ist daher Ihre primäre Sicherheitsgrenze.

Starten Sie eng:

--allowedTools "Edit,Write"
Enter fullscreen mode Exit fullscreen mode

Erweitern Sie nur, wenn der Workflow es wirklich braucht:

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Die vollständigen Optionen finden Sie in den Claude Code-Dokumenten.

Claude Agent SDK für eigene Kontrolllogik

Wenn ein Shell-Befehl nicht ausreicht, können Sie mit dem Claude Agent SDK eine eigene Schleife bauen.

Damit steuern Sie programmatisch:

  • welche Aufgabe Claude bekommt
  • welche Tools erlaubt sind
  • wie viele Iterationen laufen
  • welche Fehler zurückgeführt werden
  • wann der Workflow stoppt

Beispiel in TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

const MAX_ITERATIONS = 8;

let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `${task}

Previous failures:
${feedback}`,
    options: {
      allowedTools: ["Edit", "Write", "Bash"],
    },
  })) {
    // Nachrichten streamen und protokollieren
    console.log(msg);
  }

  const gate = runVerification();

  if (gate.passed) {
    console.log("Verification passed");
    break;
  }

  feedback = gate.failures;
}
Enter fullscreen mode Exit fullscreen mode

Die Struktur ist entscheidend:

  1. Claude arbeitet.
  2. Eine externe Schranke prüft.
  3. Fehler werden als strukturierter Kontext zurückgegeben.
  4. Die Schleife läuft erneut.
  5. Bei Erfolg oder Iterationslimit wird gestoppt.

Wenn Sie zwischen einer selbstgebauten Schleife und einer gehosteten Lösung entscheiden, hilft der Vergleich verwaltete Agenten vs. Agent SDK.

Hooks für deterministische Leitplanken

Hooks führen eigene Befehle an festen Punkten im Claude-Lebenszyklus aus. Der Unterschied zum Agenten: Hooks sind deterministisch. Claude kann sie nicht „wegargumentieren“.

Beispiel: Nach jeder Dateiänderung wird die Testsuite ausgeführt.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test --silent"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Das ist für unbeaufsichtigte Läufe wichtig. Wenn ein Agent Code ändert, läuft die Prüfung automatisch. Nicht optional. Nicht abhängig von Modellvertrauen.

Praktische Hook-Ideen:

npm test --silent
npm run typecheck
npm run lint
npm run test:contract
Enter fullscreen mode Exit fullscreen mode

Für API-Projekte ist besonders nützlich:

npm run test:openapi
Enter fullscreen mode Exit fullscreen mode

oder ein Skript, das Requests gegen die laufende API ausführt und Antworten gegen das Schema validiert.

Scheduler: Workflows automatisch starten

Ein Workflow, der ohne Sie laufen soll, braucht einen Auslöser.

Auf Servern ist das meist cron. Auf macOS kann es launchd sein. In CI/CD können es GitHub Actions, GitLab CI oder ähnliche Systeme sein.

Beispiel mit cron:

# Jeden Werktag um 7 Uhr: Wartungsworkflow ausführen und protokollieren
0 7 * * 1-5 cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" \
  >> logs/run-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

Das Grundmuster:

  1. Scheduler startet den Lauf.
  2. Claude liest die Spezifikation.
  3. Claude bearbeitet den Code.
  4. Hooks und Tests prüfen deterministisch.
  5. Logs erfassen jeden Schritt.
  6. Bei Erfolg oder Fehler erfolgt eine Übergabe.

Entwerfen Sie die Schleife, nicht den Prompt

Die bessere Frage lautet nicht:

Was soll ich Claude sagen?
Enter fullscreen mode Exit fullscreen mode

Sondern:

Welche Schleife bringt Claude dazu, sich selbst mit den richtigen Fehlern zu korrigieren?
Enter fullscreen mode Exit fullscreen mode

Ein Agent ist ein schneller Generator. Er hat aber kein verlässliches Gefühl dafür, ob das Ergebnis korrekt ist. Die Schleife liefert dieses Signal über Tests, Schemata und Vertragstests.

Dieses Prinzip haben wir in Hören Sie auf, Ihren Code-Agenten zu prompten, bauen Sie stattdessen die Schleife ausführlicher beschrieben.

Eine gute Schleife sieht so aus:

Spezifikation lesen
→ Änderung generieren
→ Tests ausführen
→ Fehler extrahieren
→ Fehler an Agent zurückgeben
→ wiederholen bis grün oder Limit erreicht
Enter fullscreen mode Exit fullscreen mode

Die Zuversicht des Modells ist dabei irrelevant. Nur das Urteil der Schranke zählt.

Deshalb ist auch eine stabile Datei wie design.md, AGENTS.md oder spec.md so wertvoll. Sie hält Ziel, Einschränkungen und Definition von „fertig“ fest. Mehr dazu im Artikel zu design.md- oder AGENTS.md-Dateien.

Beispiel: unbeaufsichtigte API-Wartung

Angenommen, Sie möchten jeden Morgen prüfen, ob Ihre API-Implementierung noch zur OpenAPI-Spezifikation passt. Claude soll Abweichungen beheben, aber niemals ungeprüften Code ausliefern.

1. Spezifikation definieren

Der Vertrag liegt in einer OpenAPI-Datei.

Beispiel:

paths:
  /orders:
    post:
      requestBody:
        required: true
      responses:
        "201":
          description: Order created
        "422":
          description: Validation error
Enter fullscreen mode Exit fullscreen mode

Zusätzlich gibt es Testfälle für das erwartete Verhalten.

2. Aufgabe formulieren

tasks/nightly-api-maintenance.md:

Synchronisiere die API-Implementierung mit der OpenAPI-Spezifikation.

Regeln:
- Ändere keine OpenAPI-Spezifikation.
- Ändere keine Testdateien.
- Bearbeite nur Dateien unter src/.
- Führe nach Änderungen die API-Tests aus.
- Stoppe, wenn die Tests grün sind oder keine sichere Änderung möglich ist.

Ziel:
- Alle Endpunkte erfüllen den OpenAPI-Vertrag.
- Fehlende Pflichtfelder liefern HTTP 422.
- Erfolgreiche POST-Requests liefern HTTP 201.
Enter fullscreen mode Exit fullscreen mode

3. Headless ausführen 

claude -p "$(cat tasks/nightly-api-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> logs/api-maintenance.log 2>&1
Enter fullscreen mode Exit fullscreen mode

4. Verifikationsschranke ausführen

Die Schranke sollte konkrete Fehler zurückgeben:

FAIL POST /orders
Expected: HTTP 422 when customer_id is missing
Actual: HTTP 500

FAIL POST /orders
Field total expected number
Actual: string
Enter fullscreen mode Exit fullscreen mode

Diese Fehler eignen sich als nächster Prompt-Kontext. Claude muss nicht raten, was falsch ist.

5. Schleife oder Eskalation

Pseudocode:

const MAX_ATTEMPTS = 5;

for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
  await runClaude({
    task: maintenanceTask,
    feedback: lastFailures,
  });

  const result = await runApiContractTests();

  if (result.passed) {
    await openPullRequest();
    await notify("API maintenance passed. PR created.");
    break;
  }

  lastFailures = result.failures;

  if (attempt === MAX_ATTEMPTS) {
    await notify(`API maintenance failed after ${MAX_ATTEMPTS} attempts:\n${lastFailures}`);
  }
}
Enter fullscreen mode Exit fullscreen mode

6. Übergabe

Der Workflow sollte nie direkt still auf main schreiben.

Besser:

  • Branch erstellen
  • Änderungen committen
  • PR-Entwurf öffnen
  • Testergebnisse anhängen
  • Menschen benachrichtigen

Wo Apidog in diesen Workflow passt

Für API-Workflows ist die Schranke der wichtigste Teil. Genau hier passt Apidog in die Architektur: API-Design, Schema, Mock-Server und automatisierte Tests liegen in einem Arbeitsbereich.

Damit können Sie:

  • API-Verträge zentral pflegen
  • Antworten gegen Schemata validieren
  • Mock-Server für nicht verfügbare Abhängigkeiten nutzen
  • automatisierte Tests als Pass/Fail-Signal verwenden
  • dem Agenten strukturierte Fehler zurückgeben

Der praktische Nutzen: Der Agent bekommt nicht nur „fehlgeschlagen“, sondern konkrete, schema-validierte Fehler. Beispiel:

POST /orders failed
Expected response.status: 201
Actual response.status: 500

Schema mismatch:
response.total expected number, received string
Enter fullscreen mode Exit fullscreen mode

Das ist genau die Art Feedback, die eine Agentenschleife braucht.

Teams, die den Endpunktzugriff über den Apidog AI Agent Debugger verdrahten, können Agenten Endpunkte testen und inspizieren lassen, ähnlich wie ein menschlicher Tester. Wenn Sie die Schranke visuell statt manuell implementieren möchten, können Sie Apidog herunterladen.

API-Workflow in Apidog

Leitplanken für sichere unbeaufsichtigte Läufe

Ein unbeaufsichtigter Agent braucht Grenzen, keine guten Absichten.

Enge Tool-Allowlist

Geben Sie nur frei, was die Aufgabe benötigt.

Für reine Codeänderungen:

--allowedTools "Edit,Write"
Enter fullscreen mode Exit fullscreen mode

Wenn Tests ausgeführt werden müssen:

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Vermeiden Sie uneingeschränkte Shell-Nutzung ohne Sandbox.

Iterationen begrenzen

Ein Lauf, der nach mehreren Versuchen nicht grün wird, sollte stoppen.

const MAX_ITERATIONS = 5;
Enter fullscreen mode Exit fullscreen mode

Nicht:

Versuche weiter, bis es funktioniert.
Enter fullscreen mode Exit fullscreen mode

Autonome Endlosschleifen sind teuer und gefährlich.

Kostenobergrenze setzen

Unbeaufsichtigte Schleifen können Token verbrauchen, ohne dass es jemand merkt. Protokollieren Sie deshalb:

  • Startzeit
  • Endzeit
  • Anzahl Iterationen
  • geschätzte Token
  • Kosten pro Lauf
  • Grund für Abbruch

Weitere praktische Hinweise stehen im Artikel zum Reduzieren der Agenten-Token-Kosten.

Schranke schützen

Der Agent darf die Schranke nicht verändern.

Schützen Sie daher:

  • Testdateien
  • OpenAPI-Spezifikation
  • Validierungsskripte
  • CI-Konfiguration
  • Snapshot-Baselines

Wenn der Agent Tests anpassen darf, um sie zu bestehen, automatisieren Sie keinen Fortschritt, sondern Selbsttäuschung.

In Sandbox arbeiten

Führen Sie unbeaufsichtigte Läufe nicht direkt auf main aus.

Besser:

git checkout -b agent/nightly-api-maintenance
Enter fullscreen mode Exit fullscreen mode

Oder:

git worktree add ../agent-run agent/nightly-api-maintenance
Enter fullscreen mode Exit fullscreen mode

Noch besser für riskantere Läufe: Container oder temporäre Arbeitsbereiche.

Logging aktivieren

Jeder Lauf sollte nachvollziehbar sein.

Mindestens erfassen:

run_id
timestamp
task
allowed_tools
changed_files
test_result
failures
iterations
final_status
Enter fullscreen mode Exit fullscreen mode

Ein unbeaufsichtigter Workflow ohne Logs ist später kaum debugbar.

Notschalter einbauen

Beispiel:

if [ -f /tmp/stop-claude-workflows ]; then
  echo "Kill switch active. Exiting."
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Oder über eine Umgebungsvariable:

if [ "$DISABLE_AGENT_WORKFLOWS" = "true" ]; then
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Menschliche Freigabe an den Rändern

„Ohne Sie“ heißt nicht „ohne Kontrolle“.

Sinnvolle Übergabepunkte:

  • vor dem Start: Aufgabe freigeben
  • nach Erfolg: PR prüfen
  • bei Fehler: Alarm mit Kontext
  • bei Grenzwertüberschreitung: Eskalation

Diese Muster überschneiden sich mit der agentenbasierten Workflow-Tool-Verdrahtung.

Häufige Fehler

Keine externe Schranke

Wenn die einzige Prüfung lautet:

Claude, bist du fertig?
Enter fullscreen mode Exit fullscreen mode

dann haben Sie keinen Workflow. Sie haben einen unbeaufsichtigten Chatbot.

Die Schranke muss außerhalb des Agenten liegen.

Zu große Aufgaben

Schlecht:

Warte den gesamten Service.
Enter fullscreen mode Exit fullscreen mode

Besser:

Synchronisiere POST /orders mit der OpenAPI-Spezifikation.
Enter fullscreen mode Exit fullscreen mode

Kleine Aufgaben konvergieren. Große Aufgaben bleiben hängen oder erzeugen unübersichtliche Diffs.

Zu viele Berechtigungen

Alles freizugeben ist bequem, aber gefährlich.

Schlecht:

--allowedTools "Edit,Write,Bash,Read,WebFetch"
Enter fullscreen mode Exit fullscreen mode

Besser:

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Und die Shell nur in einer Sandbox.

Stiller Erfolg

Ein Workflow, der Änderungen erzeugt, aber niemanden informiert, ist unbrauchbar.

Mindestens:

  • PR-Link senden
  • Testergebnis anhängen
  • geänderte Dateien auflisten

Stiller Fehler

Ein Workflow, der abbricht und niemand merkt es, ist schlimmer als kein Workflow.

Bei Fehlern senden:

Workflow: nightly-api-maintenance
Status: failed
Attempts: 5
Last failure:
POST /orders expected 422, received 500
Log: logs/run-2026-06-08.log
Enter fullscreen mode Exit fullscreen mode

Dem Selbstbericht des Modells vertrauen

Claude wird oft schreiben, dass die Aufgabe erledigt ist. Das ist kein Beweis.

Der Beweis ist:

Tests passed.
Schema validation passed.
Contract tests passed.
PR created.
Enter fullscreen mode Exit fullscreen mode

Wenn Sie die Architektur größer denken möchten, behandelt Agent Harness Design, wie diese Teile skalierbar zusammenpassen.

Minimales Setup zum Starten

Wenn Sie klein anfangen möchten, bauen Sie diesen Workflow:

1. spec.md schreiben
2. claude -p gegen diese Spezifikation ausführen
3. Tests nach jeder Änderung laufen lassen
4. maximal 5 Iterationen erlauben
5. in einem separaten Branch arbeiten
6. bei Erfolg PR erstellen
7. bei Fehler Nachricht senden
Enter fullscreen mode Exit fullscreen mode

Beispielskript:

#!/usr/bin/env bash
set -euo pipefail

TASK_FILE="tasks/nightly-api-maintenance.md"
LOG_FILE="logs/run-$(date +%F-%H%M%S).log"
MAX_ATTEMPTS=5

mkdir -p logs

for attempt in $(seq 1 "$MAX_ATTEMPTS"); do
  echo "Attempt $attempt" | tee -a "$LOG_FILE"

  claude -p "$(cat "$TASK_FILE")" \
    --allowedTools "Edit,Write,Bash" \
    --output-format json \
    >> "$LOG_FILE" 2>&1

  if npm run test:api >> "$LOG_FILE" 2>&1; then
    echo "Verification passed" | tee -a "$LOG_FILE"
    exit 0
  fi

  echo "Verification failed" | tee -a "$LOG_FILE"
done

echo "Workflow failed after $MAX_ATTEMPTS attempts" | tee -a "$LOG_FILE"
exit 1
Enter fullscreen mode Exit fullscreen mode

Das ist nicht perfekt, aber es enthält die entscheidenden Bausteine: Headless-Ausführung, Schranke, Iterationslimit und Logging.

Fazit

Claude-Workflows, die ohne Sie laufen, sind weniger ein Prompting-Problem als ein Systemdesign-Problem.

Die fünf entscheidenden Bausteine sind:

  1. präzise Spezifikation
  2. Headless-Ausführung
  3. deterministische Verifikationsschranke
  4. harte Leitplanken
  5. saubere Übergabe

Wenn diese Teile stehen, wird Claude zu einem schnellen Arbeiter in einem begrenzten, beobachtbaren und prüfbaren System.

Starten Sie mit einem einzigen Workflow. Schreiben Sie eine klare Spezifikation, führen Sie Claude headless aus, validieren Sie mit Tests, begrenzen Sie die Iterationen, isolieren Sie den Workspace und lassen Sie sich bei Erfolg oder Fehler benachrichtigen.

Für API-Projekte ist die Testsuite Ihre wichtigste Schranke. Apidog bündelt API-Design, Mocking und automatisierte Tests in einem Arbeitsbereich, sodass Sie Spezifikation und Verifikation zusammenhalten können. Laden Sie Apidog herunter, verdrahten Sie die Schranke und lassen Sie den Workflow laufen, während Sie an etwas anderem arbeiten.

Top comments (0)