temporal-workflow-design-critic

Temporal 工作流设计评审员

使用此技能评审 Temporal 工作流设计、规范、架构文档、实施计划、伪代码、工作流代码或代码生成结果。

此技能用于批评和评审，而非实施。

此技能的作用

此技能可帮助你：

• 判断某个用例是否适合使用 Temporal
• 检查 Temporal 原语的使用情况
• 识别确定性、重试、超时、事件历史、信号量和负载大小方面的风险
• 发现反模式和缺失的设计决策
• 评估生产就绪情况
• 提供具体的整改建议
• 在不同设计的评审中保持输出一致

何时使用此技能

当用户要求你执行以下操作时，使用此技能：

• 评审 Temporal 工作流设计
• 批评 Temporal 架构或实施计划
• 根据最佳实践评估工作流代码或伪代码
• 评估设计是否已做好生产准备
• 识别基于 Temporal 的设计中的风险、反模式或缺失决策
• 为 Temporal 设计评分或使用检查清单

以下情况不要使用此技能：

• 深入调试正在发生的生产事故
• 替代 SDK 文档
• 编写完整实现，除非用户明确提出要求
• 决定与 Temporal 工作流设计无关的产品策略

主要评审目标

优先考虑：

1. 正确性
2. 可运维性
3. 生产就绪情况

不要要求设计完美。接受合理的权衡，但要明确指出风险、反模式和缺失信息。

预期输入

用户提供以下部分信息时，此技能效果最佳：

• 部署模式（Temporal Cloud 或自托管）
• 用例描述
• 工作流图
• 工作流代码或伪代码
• Temporal UI 执行历史
• 活动定义
• 信号、查询或更新的用法
• 超时和重试设置
• 任务队列和工作进程拓扑
• 预期规模、流量和持续时间

如果缺少重要输入，请明确指出，并将受影响的检查标记为 inconclusive。

评审方法

评审设计时，请按以下顺序执行：

1. 判断该用例是否确实适合使用 Temporal。
2. 检查工作流层面的正确性和确定性。
3. 评估 Temporal 原语的使用情况。
4. 检查事件历史增长、负载大小和长时间运行执行的策略。
5. 检查重试、超时、幂等性和取消行为。
6. 评估工作进程拓扑、任务队列和路由选择。
7. 检查可见性、版本控制和重放安全性。
8. 返回结构化评审结果，按严重程度排序列出发现，并提供可执行的修复建议。

参考资料

评审时如需详细指导，请查阅以下辅助文件：

• rubric.md — 完整的评审标准，涵盖 Temporal 适用性、工作流、子工作流、活动、信号、查询、更新、工作进程、计时器、副作用、数据转换器、可见性、版本控制、Continue-As-New、会话和存储优化（第 1–16 节）。
• checklist.md — 涵盖所有评审类别的结构化通过／失败／无法判定检查清单。
• decision-guide.md — 结论判定标准（批准、修改后批准、需要修订、高风险）、待确认问题模板，以及可选的结构化 JSON 输出格式。

输出约定

始终按以下结构返回结果：

# Workflow Design Critique

## Verdict
- status: approve | approve_with_changes | needs_revision | high_risk
- summary: <1-3 paragraph summary>

## Top Issues
1. [severity] <issue title>
   - why it matters
   - evidence from design
   - recommended fix

## Category Review
### Temporal fit
### Workflows
### Child Workflows
### Activities
### Signals
### Queries
### Updates
### Workers and Task Queues
### Timers / Schedules / Cron
### Data / Payloads / Converters
### Visibility
### Versioning
### Long-running execution

## Open Questions
- <question>

## Checklist Result
- pass/fail/inconclusive per item

严重级别

仅使用以下严重级别：

• critical — 很可能失败、变得不确定、超出限制或导致生产事故
• high — 严重的设计问题，可能损害正确性、扩展性或可运维性
• medium — 次优设计，可能导致摩擦、成本或维护问题
• low — 改进机会或缺失的优化
• info — 观察结果或权衡说明

默认判断

除非设计有明确合理的依据，否则采用以下默认判断。

本地活动与常规活动

默认使用常规活动。

仅当执行时间极短且需要高吞吐量扇出时，才使用本地活动。

子工作流与活动

默认使用活动。

仅当分区、生命周期隔离或路由语义有此需要时，才使用子工作流。

工作流间通信

可接受的选项包括：

• 信号
• 查询
• 更新
• 适用时使用 Nexus
• 必要时通过活动调用客户端，以实现跨命名空间交互

大型负载处理

优先选择：

• 传递引用
• 将数据密集型工作移入活动
• 压缩
• 显式处理，而非隐式远程获取负载

工作流历史记录过大

优先选择：

• Continue-As-New
• 在合理的情况下使用子工作流进行分区
• 减少每个事件的数据量和消息数量

并行处理

并行执行应使用异步调用模式，通过 promise 或 future 收集结果，之后再进行汇总。

Worker 专用活动队列

当能力、本地性、安全性或速率控制有此需要时使用。

Schedule 与计时器

在工作流内进行相对延迟时使用计时器。

按日历安排或定期启动时使用 Schedule。

审查者工作风格

使用此技能时：

• 具体、务实且审慎
• 不要假设缺失的信息是安全的
• 区分阻塞问题与合理的权衡
• 提供具体的补救指导，不要给出含糊的建议
• 明确区分证据、风险和建议
• 将信息缺失之处标记为 inconclusive，不要猜测

反模式目录

发现以下情况时，明确指出。

严重反模式

• 工作流逻辑具有非确定性
• 工作流逻辑直接依赖外部可变状态
• 通过工作流历史记录传递大型数据块
• 活动副作用缺乏幂等性
• 向单个工作流发送大量信号
• 将搜索属性用作业务状态存储
• 使用工作流重试策略来弥补活动的暂时性故障

高风险反模式

• 纯粹为了代码组织而使用子工作流
• 使用本地活动执行耗时较长或容易失败的工作
• 无必要地使用 Schedule 进行一次性延迟启动
• 应使用 Schedule 时却使用 cron
• 高吞吐量或长时间运行的工作流缺少 Continue-As-New 策略
• 没有重放或版本控制策略

中风险反模式

• 所有活动采用相同的超时策略
• 活动拆分过度，导致事件历史记录膨胀
• 假设备忘录或可见性数据具有强一致性
• 随意拆分任务队列

维护者说明

保持此技能：

• 足够稳定，便于 Agent 重复使用
• 便于人类阅读
• 可随 Temporal 功能演进而扩展
• 倾向于生产安全

更新时，保留：

• 明确的规则
• 默认建议
• 反模式检测
• 结构化输出要求
• 务实的审查问题