AgentSkillsCN

nexus-decision-guide

用于评估 Temporal Nexus 是否适合您的用例的架构决策框架。当用户询问“我应该使用 Nexus 吗？”、“Nexus 与子工作流的对比”、“Nexus 与活动的对比”、“何时使用 Nexus”、“跨命名空间模式”、“多命名空间架构”、“Nexus 的权衡与优势”时，可使用此技能。该框架涵盖权衡分析、复杂度评分以及迁移路径。请勿将其用于 Nexus 的实现细节或代码示例——有关 Nexus 的具体实现，应使用 nexus-operations 技能。

SKILL.md
--- frontmatter
name: nexus-decision-guide
description: Architecture decision framework for evaluating whether Temporal Nexus is right for your use case. Use when user asks "should I use nexus", "nexus vs child workflows", "nexus vs activities", "when to use nexus", "cross-namespace pattern", "multi-namespace architecture", "nexus tradeoffs", or "nexus benefits". Covers tradeoff analysis, complexity scoring, and migration paths. Do NOT use for Nexus implementation details or code examples — use nexus-operations instead.
version: 1.0.0

Nexus Decision Guide

Guidance for deciding whether Temporal Nexus is the right communication pattern for your architecture.

Decision Framework

Step 1: Do You Need Cross-Namespace Communication?

If all your workflows run in a single namespace, stop here — you don't need Nexus.

  • •Same-namespace decomposition → Child Workflows
  • •Same-namespace messaging → Signals, Queries, or Updates
  • •Same-namespace external calls → Activities

Step 2: What Drives the Namespace Separation?

ReasonNexus Fit
Team ownership boundariesStrong — Nexus provides clean service contracts
Security/compliance isolationStrong — namespaces + Nexus maintain isolation
Independent scalingStrong — separate workers, separate scaling
Environment separation (dev/staging/prod)Not applicable — use same namespace structure per env
Just organizational preferenceWeak — consider if the operational overhead is worth it

Step 3: What Are the Communication Requirements?

NeedBest Pattern
Fire-and-forget notificationSignals (if same NS) or Activities calling Signal API
Quick data lookup (< 10s)Nexus sync operation
Long-running cross-team processNexus async (workflow-backed) operation
Cross-namespace, no durability neededActivity with Temporal client (simpler, less durable)
Cross-namespace with full durabilityNexus (the primary use case)

Step 4: Evaluate the Tradeoffs

Nexus adds:

  • •Nexus Endpoints (cluster-level routing resources to create and manage)
  • •Handler workers (separate workers for Nexus service registration)
  • •Service contracts (typed interfaces to define and maintain)
  • •Cross-namespace debugging complexity (tracing across caller + handler)

Nexus provides:

  • •At-least-once execution with automatic retries and circuit breaking
  • •Clean API boundaries between teams
  • •Independent deployment and scaling per namespace
  • •Full durable execution across namespace boundaries

The question: Does the isolation and durability benefit outweigh the operational complexity for your case?

Architecture Patterns

Pattern: Service Mesh via Nexus

Multiple teams each owning a namespace, connected via Nexus endpoints:

code
┌──────────────┐   Nexus: payments-ep   ┌──────────────┐
│  orders-ns   │──────────────────────>│ payments-ns  │
│  (Team A)    │                        │ (Team B)     │
│              │   Nexus: inventory-ep  ┌──────────────┐
│              │──────────────────────>│ inventory-ns │
└──────────────┘                       │ (Team C)     │
                                       └──────────────┘

Good when: Teams need independence, clear ownership, separate deployment cycles.

Pattern: Shared Platform Service

Common platform service (e.g., notifications, payments) exposed via Nexus to all consuming namespaces:

code
┌────────────┐
│ service-a  │──┐
└────────────┘  │   Nexus: notify-ep   ┌────────────────┐
                ├────────────────────>│ notifications  │
┌────────────┐  │                     │ (platform team)│
│ service-b  │──┘                     └────────────────┘
└────────────┘

Good when: A central capability is consumed by many teams.

Anti-Pattern: Nexus Within Single Namespace

Don't use Nexus if caller and handler are in the same namespace. Child workflows give you the same decomposition with less overhead.

Anti-Pattern: Nexus for Simple External Calls

If you just need to call an HTTP API and don't need cross-namespace durability, use a regular Activity. Nexus is for Temporal-to-Temporal communication.

Complexity Assessment

Rate your scenario:

FactorLow (1)Medium (2)High (3)
Number of consuming namespaces12-34+
Handler operation complexitySimple syncMix of sync/asyncComplex chains
Team independence requirementNice to haveImportantCritical
Existing namespace topologySingle NSFew NS, ad-hocMulti-NS established

Score 4-6: Consider if simpler patterns (child workflows, activities) suffice. Score 7-9: Nexus is likely a good fit. Score 10-12: Nexus is strongly recommended.

Migration Path

If you're currently using ad-hoc cross-namespace communication (activities calling Temporal client, etc.):

  1. •Define Nexus service contracts for existing cross-namespace calls
  2. •Create Nexus endpoints pointing to handler namespaces
  3. •Implement handler services wrapping existing workflows
  4. •Migrate callers one at a time to use NexusClient
  5. •Remove old activity-based cross-namespace glue code

Additional Resources

  • •nexus-operations skill — detailed implementation guidance
  • •namespace-management skill — namespace setup and Nexus endpoint management