Event-Driven Architecture Rules

event-drivenmessagingarchitecturebackend

Conventions for designing and implementing event-driven systems

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

Name events in past tense to reflect what happened: UserCreated, OrderShipped, PaymentFailed. Include event ID, timestamp, source, version, and correlation ID in every event envelope. Version event schemas; use schema registry to enforce compatibility (backward or full). Never modify an existing event schema in a breaking way; create a new version instead. Make all event consumers idempotent; processing the same event twice must be safe. Store events in an append-only event store; never update or delete past events. Use dead-letter queues for events that fail processing after ${max_retries} retries. Implement the outbox pattern for transactional event publishing to avoid dual writes. Log event processing start, success, and failure with the event ID and correlation ID. Test event handlers with realistic payloads including edge cases and older schema versions. Monitor consumer lag metrics; alert when lag exceeds ${lag_threshold} messages. Document event contracts in an event catalog accessible to all teams. Use compacted topics for events that represent the latest state of an entity. Avoid large payloads in events; reference entity IDs and let consumers fetch if needed.