Back to Details

event-driven-architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Event-Driven Architect

事件驱动架构

Design asynchronous systems built around durable events, explicit contracts, and operationally safe consumers.
Scope: Event-driven application architecture and reliability patterns. NOT for synchronous API design (api-designer) or batch ETL pipeline design (data-pipeline-architect).
设计围绕持久化事件、明确契约和操作安全的消费者构建的异步系统。
适用范围： 事件驱动应用架构与可靠性模式。不适用于同步API设计（api-designer）或批量ETL管道设计（data-pipeline-architect）。

Canonical Vocabulary

标准术语表

TermDefinition
eventImmutable record of something that happened
commandRequest to perform an action, not a fact
topicNamed stream or channel carrying related events
partition keyValue used to preserve order for a subset of events
consumer groupIndependent set of workers processing the same topic
idempotency keyStable identity used to make repeated processing safe
dead-letter queueHolding area for messages that exceeded normal retries
outboxTransactional pattern for publishing events from database changes
sagaMulti-step workflow coordinated through events and compensations
contract versionCompatibility marker for event schema evolution
TermDefinition
event已发生事件的不可变记录
command执行操作的请求，而非事实
topic承载相关事件的命名流或通道
partition key用于保留事件子集顺序的值
consumer group处理同一主题的独立工作者集合
idempotency key确保重复处理安全的稳定标识
dead-letter queue存放超出正常重试次数消息的区域
outbox从数据库变更发布事件的事务性模式
saga通过事件和补偿操作协调的多步骤工作流
contract version事件 schema 演进的兼容性标记

Dispatch

调度模式

$ARGUMENTSMode
design <domain or workflow>
Design an event-driven architecture
review <architecture or code path>
Audit an existing event flow
contract <event>
Define or evolve an event contract
reliability <flow>
Design retries, ordering, and recovery
migration <change>
Plan adoption or replacement of an event flow
Natural language about queues, brokers, or async workflowsAuto-detect the closest mode
EmptyShow the mode menu with examples
$ARGUMENTS模式
design <domain or workflow>
设计事件驱动架构
review <architecture or code path>
审计现有事件流
contract <event>
定义或演进事件契约
reliability <flow>
设计重试、排序与恢复机制
migration <change>
规划事件流的采用或替换方案
关于队列、消息代理或异步工作流的自然语言描述自动检测最匹配的模式
空输入显示带示例的模式菜单

Mode Menu

模式菜单

#ModeExample
1Design
design order fulfillment across payments, inventory, and shipping
2Review
review event flow for user-created -> email sync
3Contract
contract invoice.paid
4Reliability
reliability retry strategy for webhook ingestion
5Migration
migration move monolith side effects to events
#模式Example
1设计
design order fulfillment across payments, inventory, and shipping
2评审
review event flow for user-created -> email sync
3契约定义
contract invoice.paid
4可靠性设计
reliability retry strategy for webhook ingestion
5迁移规划
migration move monolith side effects to events

When to Use

适用场景

  • Designing async workflows across services or bounded contexts
  • Choosing event contracts, partition keys, or consumer responsibilities
  • Introducing outbox, retry, replay, or dead-letter handling
  • Reviewing whether an event system is resilient or over-coupled
  • Planning migration from synchronous side effects to durable events
  • 跨服务或限界上下文设计异步工作流
  • 选择事件契约、分区键或消费者职责
  • 引入outbox、重试、重放或死信处理机制
  • 评审事件系统是否具备弹性或存在过度耦合
  • 规划从同步副作用到持久化事件的迁移

Classification Logic

分类逻辑

Classification Gate
  1. If the task is synchronous API design, request-response contracts, or CRUD endpoint shape, use api-designer.
  2. If the task is batch ETL, warehouse movement, or analytics-oriented transformation, use data-pipeline-architect.
  3. If the task is broker installation, vendor-specific setup, or platform operations, use the relevant platform or devops skill.
  4. If the workflow is ambiguous, first classify whether the system is centered on durable facts, asynchronous coordination, and replay-safe consumers. Only stay in this skill when the answer is yes.
分类判定规则
  1. 如果任务是同步API设计、请求-响应契约或CRUD端点设计，使用api-designer技能。
  2. 如果任务是批量ETL、数据仓库迁移或面向分析的转换，使用data-pipeline-architect技能。
  3. 如果任务是消息代理安装、特定供应商配置或平台运维，使用相关的平台或DevOps技能。
  4. 如果工作流不明确，首先判断系统是否以持久化事实、异步协调和可重放安全消费者为核心。只有当答案为是时，才使用本技能。

Progressive Disclosure

渐进式信息披露

  • Keep 
    SKILL.md
    focused on routing, operator steps, and non-negotiable constraints.
  • Read reference files as indicated instead of loading everything at once.
  • Load 
    references/event-vs-command.md
    when the main question is whether something should be an event, command, or synchronous call.
  • Load 
    references/failure-modes.md
    when the task involves retries, replay, ordering, poison messages, or dead-letter handling.
  • Load 
    references/saga-comparison.md
    when choosing choreography, orchestration, or compensating workflows.
  • Load 
    references/output-templates.md
    when formatting architecture, contract, reliability, or migration outputs.
  • 保持
    SKILL.md
    聚焦于路由、操作步骤和不可协商的约束。
  • 按需读取参考文件，而非一次性加载所有内容。
  • 当核心问题是应使用事件、命令还是同步调用时，读取
    references/event-vs-command.md
    。
  • 当任务涉及重试、重放、排序、毒消息或死信处理时，读取
    references/failure-modes.md
    。
  • 当选择编排、编舞或补偿工作流时，读取
    references/saga-comparison.md
    。
  • 当格式化架构、契约、可靠性或迁移输出时，读取
    references/output-templates.md
    。

Instructions

操作指南

Mode: Design

模式：设计

  1. Identify the business facts that should become events. Name them in past tense.
  2. Separate facts from commands and queries.
  3. Read 
    references/event-vs-command.md
    if the fact-vs-command boundary is unclear.
  4. Define the producer, topic, partition key, consumers, and contract for each event.
  5. Specify ordering requirements and where ordering does not matter.
  6. Read 
    references/saga-comparison.md
    when the workflow spans multiple services or compensating actions.
  7. Produce an architecture with failure handling, replay, and observability using 
    references/output-templates.md
    as needed.
  1. 识别应转化为事件的业务事实，使用过去式命名。
  2. 区分事实与命令、查询。
  3. 如果事实与命令的边界不清晰，读取
    references/event-vs-command.md
    。
  4. 为每个事件定义生产者、主题、分区键、消费者和契约。
  5. 指定排序要求以及无需排序的场景。
  6. 当工作流跨多个服务或涉及补偿操作时，读取
    references/saga-comparison.md
    。
  7. 按需使用
    references/output-templates.md
    生成包含故障处理、重放和可观测性的架构方案。

Mode: Review

模式：评审

  1. Read the event catalog, code path, or architecture diagram.
  2. Check for hidden synchronous coupling, missing idempotency, weak contract ownership, or undefined replay behavior.
  3. Flag places where an event stream is being misused for request-response semantics.
  4. Read 
    references/failure-modes.md
    when the review touches ordering, replay, retries, or consumer safety.
  5. Present findings by severity.
  1. 读取事件目录、代码路径或架构图。
  2. 检查是否存在隐藏的同步耦合、缺失的幂等性、薄弱的契约所有权或未定义的重放行为。
  3. 标记事件流被错误用于请求-响应语义的场景。
  4. 当评审涉及排序、重放、重试或消费者安全时，读取
    references/failure-modes.md
    。
  5. 按严重程度呈现评审结果。

Mode: Contract

模式：契约定义

  1. Define required fields, producer, ownership, ordering expectations, and versioning strategy.
  2. State which fields are identifiers, business facts, and metadata.
  3. Prefer additive evolution; document deprecation windows for consumers.
  4. Read 
    references/event-vs-command.md
    if the proposed contract still looks like a command or query.
  1. 定义必填字段、生产者、所有权、排序预期和版本化策略。
  2. 说明哪些字段是标识符、业务事实和元数据。
  3. 优先采用增量演进方式；为消费者文档化弃用窗口期。
  4. 如果拟议的契约仍类似命令或查询，读取
    references/event-vs-command.md
    。

Mode: Reliability

模式：可靠性设计

  1. Read 
    references/failure-modes.md
    .
  2. Design retry policy, backoff, poison-message handling, and dead-letter routing.
  3. Specify idempotency strategy for consumers and handlers.
  4. Define replay safety and operator controls.
  1. 读取
    references/failure-modes.md
    。
  2. 设计重试策略、退避机制、毒消息处理和死信路由规则。
  3. 指定消费者和处理程序的幂等性策略。
  4. 定义重放安全性和操作员控制机制。

Mode: Migration

模式：迁移规划

  1. Map the current synchronous side effect or legacy event flow.
  2. Introduce the new event path behind explicit checkpoints.
  3. Read 
    references/output-templates.md
    for migration checkpoints and cutover framing.
  4. Keep rollback simple by preserving the old path until the new path proves stable.
  1. 映射当前的同步副作用或遗留事件流。
  2. 在明确的检查点后引入新的事件路径。
  3. 读取
    references/output-templates.md
    获取迁移检查点和切换框架。
  4. 通过保留旧路径直至新路径稳定，简化回滚操作。

Output Requirements

输出要求

  • Every design must identify producer, topic, partition key, consumers, and failure strategy.
  • Every contract must state ownership and versioning rules.
  • Every reliability plan must include idempotency and dead-letter handling.
  • 每个设计方案必须明确生产者、主题、分区键、消费者和故障策略。
  • 每个契约必须声明所有权和版本化规则。
  • 每个可靠性计划必须包含幂等性和死信处理机制。

Reference File Index

参考文件索引

FileRead When
references/event-vs-command.md
The main design question is whether to emit an event, issue a command, or keep a synchronous call
references/failure-modes.md
The task involves retries, ordering, replay, poison messages, dead-letter queues, or consumer recovery
references/saga-comparison.md
Choosing choreography, orchestration, or compensating saga structure across services
references/output-templates.md
Formatting architecture, contract, reliability, review, or migration outputs
File读取时机
references/event-vs-command.md
核心设计问题是选择事件、命令还是同步调用时
references/failure-modes.md
任务涉及重试、排序、重放、毒消息、死信队列或消费者恢复时
references/saga-comparison.md
跨服务选择编舞、编排或补偿Saga结构时
references/output-templates.md
格式化架构、契约、可靠性、评审或迁移输出时

Critical Rules

核心规则

  1. Model business events as facts in past tense, not commands.
  2. Consumers must be idempotent whenever retries or replay are possible.
  3. Use the outbox pattern when publishing events from transactional database changes.
  4. Do not use an event bus for low-latency request-response requirements that need immediate consistency.
  5. Event contracts should evolve additively whenever possible.
  1. 将业务事件建模为过去式的事实，而非命令。
  2. 只要存在重试或重放可能，消费者必须具备幂等性。
  3. 从事务性数据库变更发布事件时，使用outbox模式。
  4. 对于需要即时一致性的低延迟请求-响应需求，不要使用事件总线。
  5. 事件契约应尽可能采用增量演进方式。

Scaling Strategy

扩展策略

  • small: Keep the design narrow. Define the minimum event set, one ownership boundary, and one reliability strategy before expanding.
  • medium: Add explicit contract ownership, partition strategy, replay rules, and a clear saga choice for multi-service or mixed batch-plus-event workflows. Avoid hiding synchronous dependencies behind event terminology.
  • large: Sequence cross-domain programs and migrations by bounded context. Start with one proven event path, then expand consumer batches and downstream automation only after replay, dead-letter handling, and observability are operator-safe.
  • 小型场景：保持设计范围狭窄。在扩展前，定义最小事件集、一个所有权边界和一种可靠性策略。
  • 中型场景：添加明确的契约所有权、分区策略、重放规则，并为多服务或混合批量+事件工作流明确Saga选择。避免用事件术语掩盖同步依赖。
  • 大型场景：按限界上下文排序跨领域方案和迁移。从一条经过验证的事件路径开始，仅在重放、死信处理和可观测性达到操作员安全标准后，再扩展消费者批次和下游自动化。

Scope Boundaries

范围边界

IS for: event contracts, topics, sagas, retries, replay, outbox, consumer design.
NOT for: synchronous REST or GraphQL API design, batch analytics pipelines, or broker installation details.
适用： 事件契约、主题、Saga、重试、重放、outbox、消费者设计。
不适用： 同步REST或GraphQL API设计、批量分析管道、消息代理安装细节。