Designing Event-Driven Architecture with Claude: Schema, Idempotency, Versioning

1. Why event-driven design produces different failure classes

In synchronous request-response systems, a failure is usually visible right away: the call fails, and the client gets an error. Event-driven systems decouple the timing and ordering of processing, so failures often only surface hours later, for example when a consumer processes an event twice or can no longer parse an outdated schema version. This temporal decoupling makes up-front design considerably more important than for classic APIs.

Claude is well suited to systematically playing through these failure classes before the first event type is even produced. Instead of asking Claude for a generic event architecture, it pays off to give it concrete scenarios, such as what happens when a consumer restarts and re-reads old events, or when a producer publishes an event with a new required field that older consumers do not know about.

2. Event schema design: event sourcing vs. simple domain events

A foundational design decision is whether events are merely notifications about a business fact that already happened, so-called domain events like OrderShipped, or whether the complete state of an entity is reconstructed exclusively from a sequence of events, as event sourcing prescribes. Both approaches have very different consequences for storage, traceability, and complexity, and Claude can help play those consequences out concretely for the specific use case instead of evaluating them abstractly.

For most teams, event sourcing is a substantially bigger investment because it requires snapshotting, projections, and careful version management of the event stream. A useful prompting approach is giving Claude the concrete business requirements, such as whether a complete audit history is required by regulation, and letting it derive whether simple domain events with a separate audit log suffice or event sourcing is genuinely justified.

// Example: domain event vs. event-sourcing event compared
// Domain event (notification about a completed business fact)
{
  "event_type": "OrderShipped",
  "event_id": "evt_8f21a9",
  "occurred_at": "2026-08-08T09:14:22Z",
  "order_id": "ord_5521",
  "tracking_number": "DHL-8823741"
}

// Event-sourcing event (part of the full state history)
{
  "event_type": "OrderItemAdded",
  "aggregate_id": "ord_5521",
  "aggregate_version": 4,
  "event_id": "evt_71c30d",
  "payload": {"sku": "ABC-123", "quantity": 2, "price_cents": 4990}
}

3. Thinking through choreography vs. orchestration with Claude

When several services need to react to an event, two fundamental coordination patterns are available. Choreography lets each service react to events independently and emit new events itself, without central control, which favors loose coupling but makes the overall flow hard to follow once more than three or four services are involved. Orchestration, by contrast, centralizes the flow in a process coordinator that explicitly controls when each service gets called, which makes the flow more visible but introduces a new form of coupling to the orchestrator.

Claude can help weigh this trade-off when given the number of involved services, the expected error-handling logic, and the traceability requirements. As a rule of thumb, choreography fits few, stable event chains well, while orchestration makes error handling considerably clearer for complex sagas with many compensation steps, such as a multi-stage order cancellation.

# Prompt for Claude Code: weighing choreography vs. orchestration
claude "We have 5 services that need to react to an order cancellation
(order, payment, inventory, shipping, notification). The cancellation
needs compensation logic if a step fails. Compare choreography and
orchestration for this specific case:
- How visible does the overall flow stay under failure conditions?
- Where does new coupling get introduced?
- Which pattern fits sagas with compensation steps better?
Give a reasoned recommendation, not just a plain list of pros and cons.

4. Idempotency: the most common pitfall in review

At-least-once delivery is the rule in most messaging systems, not the exception, meaning every consumer must expect to receive an event more than once, for example after a network error or a consumer restart before acknowledgment. Without idempotency, a duplicated PaymentReceived event can, in the worst case, lead to a duplicate credit. Claude can check consumer code specifically for missing idempotency safeguards, such as a unique event key with deduplication before the actual processing happens.

A typical review pattern is presenting Claude with the consumer code alongside the question of what happens on receiving the same event twice. This frequently reveals that the business logic itself is correct, but no check for already-processed event IDs exists, a pattern that is easy to miss in code reviews without a specific focus on idempotency, since the code works flawlessly in the normal case of single delivery.

5. Event versioning: schema evolution without breaking consumers

Events are often read over years by different consumers deployed at different points in time, which is why schema changes must stay backward compatible. A new optional field is usually uncritical, while renaming or removing an existing field breaks older consumers immediately. Claude can specifically check a planned schema change during review for whether it stays additive or represents a breaking change requiring a new event version with parallel delivery.

In practice it pays off to present Claude with both the old and the new schema and explicitly ask it to flag breaking changes, rather than relying on an informal team assessment. It is also worth adopting a fixed convention, such as a schema_version field on every event, so consumers can tell during parsing which version they are currently processing and how to handle unknown new fields.

# Prompt for Claude Code: detecting a breaking change in an event schema
claude "Compare the old event schema (schema_v1.json) with the new draft
(schema_v2_draft.json) for OrderCreated. Check:
- Is an existing field renamed, removed, or its type changed?
- Are new required fields introduced without a default?
- Could a consumer that only knows v1 misinterpret the new event?
Mark every change explicitly as 'additive' or 'breaking'.

6. Persistence layer: event store, broker, and retention

An often-overlooked design aspect is how long events stay available at all and who is responsible for their persistence. A plain message broker with short retention works fine for fire-and-forget notifications, but not as a reliable source of truth once a new consumer later needs to read historical events. A dedicated event store with long or unlimited retention, by contrast, becomes necessary once event sourcing or an audit trail is part of the architecture.

Claude can help with this decision when given the actual traceability requirements, replay capability needed for future consumers, and regulatory retention periods. What matters is not asking Claude for the technically most elegant solution, but for the solution that fits the team's actual operational cost and existing infrastructure, since a full event store means substantially more operational effort than a simple broker.

7. Dead letter queues: what happens to unprocessable events

Not every event can be processed successfully, for example when the payload is malformed, a referenced entity was already deleted, or a consumer repeatedly fails with a transient error. Without a dead letter queue, such an event either disappears silently or blocks the entire queue, because the system keeps redelivering the same bad entry over and over before it can move on to the next event. Claude can specifically ask, when reviewing consumer code, where an event gets moved to after a defined number of failed processing attempts.

Just as important as merely having a dead letter queue is a defined process for handling it: who gets notified when events land there, how are they replayed after a fix, and how long do they stay retained. Claude can help sketch out this operational process alongside the technical implementation, so a dead letter queue does not turn into a silent data graveyard that nobody checks regularly.

8. A reusable review prompt for event designs

Similar to microservices boundaries, a fixed checklist reused as a prompt basis for every new event type pays off: is the event idempotently processable, does a unique event key exist, is processing order actually relevant from a business standpoint or not, is the schema additively extensible, and is there clear ownership assigned for the event schema. These criteria can be saved as a fixed prompt template and applied consistently to every new event.

An additional point often missing in practice is explicitly asking about ordering guarantees: many messaging systems guarantee order only within a partition or topic, not globally. Claude can help during review detect whether business logic wrongly assumes a global ordering guarantee the underlying system does not actually provide, a mistake that often only shows up under load.

9. Limits: Claude does not know the real message rate

As helpful as Claude is at thinking through schema and communication patterns, it knows neither the actual message rate in production nor the real latency distribution between producer and consumer nor the concrete behavior of the chosen message broker under load. Design decisions that look good on paper, such as choreography with six involved services, can run into problems at real message volume that only show up in monitoring.

Every draft worked out with Claude should therefore be verified through load tests and real monitoring in a staging environment before going to production. Claude delivers the conceptual groundwork and surfaces pitfalls such as missing idempotency, but final verification against real system characteristics remains the team's job, backed by actual operational metrics.

10. Summary

11. FAQ: Event-Driven Architecture with Claude: Key Questions