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 を収集し、後で集約する非同期呼び出しパターンを使用します。

ワーカー固有のアクティビティキュー

機能、ローカリティ、セキュリティ、またはレート制御が必要な場合に使用します。

スケジュールとタイマー

ワークフロー内の相対的な遅延にはタイマーを使用します。

カレンダーベースまたは定期的な起動にはスケジュールを使用します。

レビュアーの対応方針

このスキルを使用する際は、次の点に従ってください。

• 具体的かつ実践的に、保守的な判断をしてください
• 詳細が不足している場合に、安全だと決めつけないでください
• ブロッキングとなる問題と、妥当なトレードオフを区別してください
• 曖昧な助言ではなく、具体的な是正方法を示してください
• 根拠、リスク、推奨事項を明確に分けてください
• 情報が不足している箇所は推測せず、inconclusive としてください

アンチパターン一覧

該当する場合は、次の項目を明示的に指摘してください。

重大なアンチパターン

• 非決定的なワークフローロジック
• 変化する外部状態に直接依存するワークフローロジック
• 大きなデータの塊をワークフロー履歴に渡すこと
• 冪等性のないアクティビティの副作用
• 単一のワークフローに対するシグナルの集中送信
• ビジネス状態の保存先として検索属性を使用すること
• 一時的なアクティビティの失敗を補うためにワークフローのリトライポリシーを使用すること

高リスクのアンチパターン

• コードの整理だけを目的として子ワークフローを使用すること
• 時間がかかる処理や失敗しやすい処理にローカルアクティビティを使用すること
• 必要がないのに、一度限りの遅延開始にスケジュールを使用すること
• スケジュールを使うべき場面で cron を使用すること
• 大量または長時間実行されるワークフローに Continue-As-New の戦略がないこと
• リプレイまたはバージョン管理の戦略がないこと

中リスクのアンチパターン

• すべてのアクティビティに同一のタイムアウトポリシーを適用すること
• アクティビティを過剰に細分化して、イベント履歴を肥大化させること
• メモまたは可視性データが強い一貫性を持つと想定すること
• 根拠なくタスクキューを分割すること

メンテナー向けの注意

このスキルは、次の点を維持してください。

• エージェントが繰り返し使用できるだけの安定性
• 人間が読みやすいこと
• Temporal の機能の進化に合わせて拡張できること
• 本番環境の安全性を重視した方針

更新時には、次の項目を維持してください。

• 明示的なルール
• デフォルトの推奨事項
• アンチパターンの検出
• 構造化された出力に関する要件
• 実践的なレビューの質問