Claude Code & Temporal: Zuverlässige Workflows und Long-Running Tasks

Celery bricht unter Last zusammen. SQS-Queues verlieren den Zustand bei einem Worker-Neustart. Selbst geschriebene Retry-Logik enthält Sonderfälle, die man erst nach dem ersten Production-Incident entdeckt. Temporal löst diese Probleme grundlegend — nicht durch bessere Konfiguration, sondern durch ein anderes Modell: Workflows als Code, Zustand als Invariante, Fehler als normale Kontrollstruktur.

Dieser Artikel zeigt, was Temporal ist, wann es den Unterschied macht und wie Claude Code die Temporal-Entwicklung konkret beschleunigt — von der ersten Activity bis zum produktionsreifen Child-Workflow.

1. Was ist Temporal?

Temporal ist eine Open-Source-Workflow-Engine, die aus dem Cadence-Projekt bei Uber entstanden ist. Das Kernversprechen: Workflows werden als normaler Programmcode geschrieben, aber Temporal garantiert deren zuverlässige Ausführung — über Neustarts, Crashes und Netzwerkfehler hinweg.

Das funktioniert über Event-Sourcing: Temporal persistiert jeden Schritt eines Workflows in einem unveränderlichen Log. Bricht der Worker ab, wird der Workflow beim nächsten Start exakt an der letzten sicheren Position fortgesetzt — ohne dass der Entwickler dafür manuellen Checkpoint-Code schreiben muss.

2. Temporal vs. Celery vs. SQS

Die Wahl zwischen Celery, SQS und Temporal hängt von der Anforderung ab. Für einfache, kurzlebige Background-Jobs reicht Celery vollkommen aus. Sobald aber Zustand über mehrere Schritte hinweg erhalten bleiben muss, wird der Unterschied kritisch:

• Celery verliert den Zustand bei einem Worker-Absturz. Retries starten von vorne. Für mehrstufige Prozesse braucht man externe Zustandsspeicherung, die man selbst bauen und warten muss.
• SQS garantiert Delivery, nicht Ordnung oder Zustand. Bei Visibility-Timeout-Problemen entstehen Doppelverarbeitungen, die man mit Idempotenz-Schlüsseln absichern muss — ebenfalls selbst gebaut.
• Temporal macht Zustand zur Kernfunktion des Systems. Jeder Workflow-Schritt ist persistent. Retries, Timeouts und Compensation sind eingebaut — ohne zusätzliche Infrastruktur.

Temporal hat eine höhere Einstiegshürde als Celery, weil es ein eigenes Denkmodell mitbringt. Der Aufwand zahlt sich aus, sobald Workflows länger als wenige Sekunden laufen oder mehr als einen externen Aufruf machen.

3. Workflows und Activities im Python SDK

Das Temporal Python SDK trennt Workflows und Activities durch Dekoratoren. Ein Workflow definiert die Orchestrierung, eine Activity die tatsächliche Arbeit:

import asyncio
from temporalio import activity, workflow
from temporalio.client import Client
from temporalio.worker import Worker

@activity.defn
async def fetch_user_data(user_id: str) -> dict:
    # Echter HTTP-Call, Datenbankzugriff, etc.
    response = await http_client.get(f"/users/{user_id}")
    return response.json()

@activity.defn
async def send_welcome_email(user: dict) -> None:
    await email_service.send(
        to=user["email"],
        template="welcome"
    )

@workflow.defn
class OnboardingWorkflow:
    @workflow.run
    async def run(self, user_id: str) -> str:
        user = await workflow.execute_activity(
            fetch_user_data,
            user_id,
            start_to_close_timeout=timedelta(seconds=10),
        )
        await workflow.execute_activity(
            send_welcome_email,
            user,
            start_to_close_timeout=timedelta(seconds=30),
        )

Der Workflow selbst macht keine I/O. Er ruft Activities auf und wartet auf deren Ergebnis. Das ist der Schlüssel zur Determiniertheit: Temporal kann den Workflow jederzeit unterbrechen und fortsetzen, weil der Workflow-Code selbst keinen Seiteneffekt hat.

4. Retries und Timeouts

Temporal unterscheidet zwischen zwei Arten von Timeouts, die häufig verwechselt werden:

• schedule_to_close_timeout: Die maximale Gesamtdauer einer Activity inklusive aller Retries. Ist diese Zeit abgelaufen, schlägt die Activity endgültig fehl.
• start_to_close_timeout: Wie lange ein einzelner Versuch dauern darf. Bei einem Timeout wird die Activity erneut gestartet.

from temporalio.common import RetryPolicy

retry_policy = RetryPolicy(
    initial_interval=timedelta(seconds=1),
    backoff_coefficient=2.0,
    maximum_interval=timedelta(minutes=5),
    maximum_attempts=10,
    non_retryable_error_types=["InvalidUserError"],
)

result = await workflow.execute_activity(
    fetch_user_data,
    user_id,
    start_to_close_timeout=timedelta(seconds=30),
    schedule_to_close_timeout=timedelta(minutes=10),
    retry_policy=retry_policy,
)

5. Child Workflows

Wenn ein Workflow selbst zu groß oder zu lang wird, sind Child Workflows die richtige Abstraktion. Ein Parent-Workflow startet Kind-Workflows, die vollständig unabhängig laufen und ihren eigenen Zustand halten:

@workflow.defn
class BatchProcessingWorkflow:
    @workflow.run
    async def run(self, user_ids: list[str]) -> None:
        # Child Workflows parallel starten
        handles = [
            await workflow.start_child_workflow(
                OnboardingWorkflow.run,
                user_id,
                id=f"onboarding-{user_id}",
            )
            for user_id in user_ids
        ]
        # Auf alle warten
        await asyncio.gather(*[h.result() for h in handles])

Child Workflows sind nicht nur eine Strukturierungshilfe — sie lösen das Limit für die maximale Event-History eines einzelnen Workflows. Lange laufende Batch-Jobs, die Tausende von Schritten umfassen, sollten immer über Child Workflows aufgeteilt werden.

6. Signale und Queries

Temporal ermöglicht es, von außen mit laufenden Workflows zu kommunizieren. Signale senden Daten an einen Workflow (Fire-and-Forget), Queries lesen den aktuellen Zustand aus:

@workflow.defn
class ApprovalWorkflow:
    def __init__(self) -> None:
        self._approved: bool | None = None

    @workflow.signal
    async def approve(self) -> None:
        self._approved = True

    @workflow.signal
    async def reject(self, reason: str) -> None:
        self._approved = False

    @workflow.query
    def status(self) -> str:
        if self._approved is None:
            return "pending"
        return "approved" if self._approved else "rejected"

    @workflow.run
    async def run(self, request_id: str) -> bool:
        # Warten bis Signal kommt (oder Timeout)
        await workflow.wait_condition(
            lambda: self._approved is not None,
            timeout=timedelta(days=7),
        )
        return self._approved

Dieses Muster macht menschliche Genehmigungsschritte in automatisierten Pipelines einfach implementierbar — der Workflow pausiert deterministisch und setzt fort, sobald das Signal kommt.

7. Claude Code-Tipps für Temporal-Entwicklung

Claude Code beschleunigt Temporal-Projekte an mehreren Stellen konkret:

Workflow-Struktur generieren: Beschreibe den Prozess in natürlicher Sprache, Claude Code erstellt das Gerüst mit korrekten Dekoratoren, Timeout-Angaben und Retry-Policies. Die häufigsten Anfängerfehler — I/O im Workflow statt in Activities, fehlende Timeouts — werden dabei direkt vermieden.

claude "Erstelle einen Temporal Workflow für einen dreistufigen
Bestellprozess: Zahlung prüfen, Lager reservieren, Versand beauftragen.
Jeder Schritt soll im Fehlerfall bis zu 3x wiederholt werden."

Determiniertheit prüfen lassen: Claude Code liest bestehende Workflow-Definitionen und identifiziert nicht-deterministische Operationen — datetime.now(), random(), direkte HTTP-Calls — die in Activities ausgelagert werden müssen.

Lokale Entwicklungsumgebung aufsetzen: Temporal Server läuft lokal via Docker. Claude Code schreibt die docker-compose.yml, das Worker-Start-Skript und die Verbindungskonfiguration aus einer einzigen Beschreibung.

"Temporal's Lernkurve liegt nicht im Code, sondern im Konzept. Wenn das Modell sitzt — Workflow orchestriert, Activity führt aus — schreibt sich der Code fast von selbst."

Tests für Workflows: Das Temporal Python SDK hat ein eingebautes Test-Framework. Claude Code schreibt Unit-Tests, die den Workflow ohne echten Temporal-Server ausführen, Activities mocken und Signale simulieren — inklusive der korrekten Verwendung von temporalio.testing.WorkflowEnvironment.