Communitygithub.com

Orquestrador de Trabajos en Segundo Plano

Experto en procesamiento de trabajos en segundo plano con Bull/BullMQ (Redis), Celery y colas en la nube. Implementa reintentos, programación, colas prioritarias y gestión de workers. Útil para procesamiento asíncrono de tareas, campañas de correo, generación de informes y operaciones por lotes. NO para comunicación en tiempo real por WebSocket, llamadas síncronas a API ni operaciones simples con setTimeout.

¿Qué es Orquestrador de Trabajos en Segundo Plano?

Este skill es una guía completa y detallada para diseñar e implementar sistemas de trabajos en segundo plano de nivel de producción, utilizando tecnologías como BullMQ para Node.js, Celery para Python y colas nativas de la nube como AWS SQS. El objetivo principal es evitar que las tareas de larga duración (envío de correos, generación de informes, procesamiento de video) bloqueen las respuestas de la API, mejorando la experiencia del usuario y la escalabilidad del sistema. La guía cubre desde cuándo usar trabajos en segundo plano (tareas que toman más de 5 segundos, necesitan reintentos o se ejecutan en lotes) hasta la selección de la tecnología adecuada según el stack tecnológico (Node.js con Redis, Python con Celery, o arquitecturas serverless con servicios cloud). Además, identifica y soluciona cinco antipatrones comunes: la falta de una cola de mensajes fallidos (dead letter queue), el procesamiento síncrono de trabajos, la ausencia de idempotencia para evitar duplicados, la falta de límites de tasa (rate limiting) y el escalado inadecuado de workers. Se incluyen ejemplos de código prácticos en TypeScript para patrones de implementación como campañas de correo, informes programados y tuberías de transcodificación de video, junto con estrategias de monitoreo, observabilidad y una lista de verificación para producción. El skill está diseñado para desarrolladores backend, ingenieros de plataforma y cualquier profesional que necesite gestionar tareas asíncronas de forma robusta y eficiente en sus aplicaciones.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/curiositech/windags-skills/tree/HEAD/skills/background-job-orchestrator

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Orquestador de Trabajos en Segundo Plano

Experto en diseñar e implementar sistemas de trabajos en segundo plano de nivel de producción que manejan tareas de larga duración sin bloquear las respuestas de la API.

Cuándo Usarlo

✅ Úselo para:

  • Tareas de larga duración (envío de correos, generación de informes, procesamiento de imágenes)
  • Operaciones por lotes (importaciones masivas, exportaciones, migraciones de datos)
  • Tareas programadas (resúmenes diarios, trabajos de limpieza, informes recurrentes)
  • Tareas que requieren lógica de reintentos (llamadas a API externas, operaciones inestables)
  • Procesamiento basado en prioridades (usuarios premium primero, alertas críticas)
  • Operaciones con límite de tasa (cuotas de API, límites de servicios de terceros)

❌ NO para:

  • Comunicación bidireccional en tiempo real (use WebSockets)
  • Requisitos de latencia de menos de un segundo (use caché en memoria)
  • Retrasos simples (setTimeout es suficiente para <5 segundos)
  • Respuestas de API síncronas (mantenga la lógica en el manejador de solicitudes)

Árbol de Decisión Rápido

¿Esta tarea:
├── Toma &gt;5 segundos? → Trabajo en segundo plano
├── Necesita reintentos al fallar? → Trabajo en segundo plano
├── Se ejecuta en un horario? → Trabajo en segundo plano (patrón cron)
├── Bloquea la interacción del usuario? → Trabajo en segundo plano
├── Procesa en lotes? → Trabajo en segundo plano
└── Devuelve inmediatamente? → Mantener síncrono

Selección de Tecnología

Node.js: BullMQ (Recomendado 2024+)

Cuándo usarlo:

  • Proyecto TypeScript
  • Redis ya está en el stack
  • Necesita funciones avanzadas (límites de tasa, prioridades, trabajos repetibles)

Por qué BullMQ en lugar de Bull:

  • Bull (v3) → BullMQ (v4+): Reescritura completa en TypeScript
  • Mejor manejo de la conexión con Redis
  • Concurrencia y rendimiento mejorados
  • Mantenimiento activo (Bull está en modo de mantenimiento)

Python: Celery

Cuándo usarlo:

  • Proyecto Python/Django
  • Necesita ejecución distribuida de tareas
  • Flujos de trabajo complejos (cadenas, grupos, acordes)

Alternativas:

  • RQ (Redis Queue): Más simple, menos funciones
  • Dramatiq: Moderno, menos ecosistema
  • Huey: Ligero, bueno para proyectos pequeños

Nativo de la Nube: AWS SQS, Google Cloud Tasks

Cuándo usarlos:

  • Arquitectura serverless
  • No quiere administrar Redis/RabbitMQ
  • Necesita entrega garantizada y colas de mensajes fallidos (dead-letter queues)

Antipatrones Comunes

Antipatrón 1: Sin Cola de Mensajes Fallidos (Dead Letter Queue)

Pensamiento novato: "Reintentar 3 veces, luego fallar en silencio"

Problema: Los trabajos fallidos desaparecen sin visibilidad ni ruta de recuperación.

Enfoque correcto:

// BullMQ con dead letter queue
const queue = new Queue('cola-correo', {
  connection: redis,
  defaultJobOptions: {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 2000
    },
    removeOnComplete: 100, // Mantener los últimos 100 exitosos
    removeOnFail: false     // Mantener todos los fallidos para inspección
  }
});

// Monitorear trabajos fallidos
const failedJobs = await queue.getFailed();

Cronología:

  • Antes de 2020: Reintentar y olvidar
  • 2020+: Las colas de mensajes fallidos se convierten en estándar
  • 2024+: Se requiere observabilidad para fallos de trabajos

Antipatrón 2: Procesamiento Síncrono de Trabajos

Síntoma: El endpoint de la API espera a que el trabajo termine

Problema:

// ❌ INCORRECTO - Bloquea la respuesta de la API
app.post('/enviar-correo', async (req, res) => {
  await sendEmail(req.body.to, req.body.subject);
  res.json({ success: true });
});

Por qué está mal: Timeout, mala UX, desperdicia recursos del servidor

Enfoque correcto:

// ✅ CORRECTO - Encola y devuelve inmediatamente
app.post('/enviar-correo', async (req, res) => {
  const job = await emailQueue.add('send', {
    to: req.body.to,
    subject: req.body.subject
  });

  res.json({
    success: true,
    jobId: job.id,
    status: 'queued'
  });
});

// Un worker separado procesa el trabajo
worker.process('send', async (job) => {
  await sendEmail(job.data.to, job.data.subject);
});

Antipatrón 3: Sin Idempotencia

Problema: El trabajo se ejecuta dos veces → cargos duplicados, correos duplicados

Por qué ocurre:

  • La conexión con Redis se cae durante el procesamiento
  • El worker falla antes de completar el trabajo
  • El timeout del trabajo activa un reintento mientras aún se está ejecutando

Enfoque correcto:

// ✅ Trabajo idempotente con clave de deduplicación
await queue.add('cobrar-pago', {
  userId: 123,
  amount: 50.00
}, {
  jobId: `payment-${orderId}`, // Previene duplicados
  attempts: 3
});

// En el worker: Verificar si ya se procesó
worker.process('cobrar-pago', async (job) => {
  const { userId, amount } = job.data;

  // Verificar idempotencia
  const existing = await db.payments.findOne({
    jobId: job.id
  });
  if (existing) {
    return existing; // Ya procesado
  }

  // Procesar pago
  const result = await stripe.charges.create({...});

  // Almacenar registro de idempotencia
  await db.payments.create({
    jobId: job.id,
    result
  });

  return result;
});

Antipatrón 4: Sin Límite de Tasa (Rate Limiting)

Problema: Sobrecargar APIs de terceros o agotar cuotas

Síntoma: Errores de "Rate limit exceeded" de Sendgrid, Stripe, etc.

Enfoque correcto:

// Límite de tasa en BullMQ
const queue = new Queue('llamadas-api', {
  limiter: {
    max: 100,        // Máximo 100 trabajos
    duration: 60000  // Por 60 segundos
  }
});

// O: Límites de tasa basados en prioridad
await queue.add('enviar-correo', data, {
  priority: user.isPremium ? 1 : 10,
  rateLimiter: {
    max: user.isPremium ? 1000 : 100,
    duration: 3600000 // Por hora
  }
});

Antipatrón 5: Olvidar el Escalado de Workers

Problema: Un solo worker no puede seguir el ritmo de la profundidad de la cola

Síntoma: La cola se acumula, los trabajos se retrasan horas/días

Enfoque correcto:

// Escalado horizontal con múltiples workers
const worker = new Worker('cola-correo', async (job) => {
  await processEmail(job.data);
}, {
  connection: redis,
  concurrency: 5  // Procesar 5 trabajos concurrentemente por worker
});

// Ejecutar múltiples procesos de worker (PM2, Kubernetes, etc.)
// Cada worker procesa concurrencia * num_workers trabajos

Monitoreo:

// Configurar alertas para la profundidad de la cola
setInterval(async () => {
  const waiting = await queue.getWaitingCount();
  if (waiting > 1000) {
    alert('¡La profundidad de la cola supera 1000, escalar workers!');
  }
}, 60000);

Patrones de Implementación

Patrón 1: Campañas de Correo Electrónico

// Configuración de la cola
const emailQueue = new Queue('campaña-correo', { connection: redis });

// Encolar lote
async function sendCampaign(userIds: number[], template: string) {
  const jobs = userIds.map(userId => ({
    name: 'send',
    data: { userId, template },
    opts: {
      attempts: 3,
      backoff: { type: 'exponential', delay: 5000 }
    }
  }));

  await emailQueue.addBulk(jobs);
}

// Worker con lógica de reintento
const worker = new Worker('campaña-correo', async (job) => {
  const { userId, template } = job.data;

  const user = await db.users.findById(userId);
  const email = renderTemplate(template, user);

  try {
    await sendgrid.send({
      to: user.email,
      subject: email.subject,
      html: email.body
    });
  } catch (error) {
    if (error.code === 'ECONNREFUSED') {
      throw error; // Reintentar
    }
    // Correo inválido, no reintentar
    console.error(`Correo inválido para el usuario ${userId}`);
  }
}, {
  connection: redis,
  concurrency: 10
});

Patrón 2: Informes Programados

// Informe diario a las 9 AM
await queue.add('informe-diario', {
  type: 'ventas',
  recipients: ['[email protected]']
}, {
  repeat: {
    pattern: '0 9 * * *', // Sintaxis cron
    tz: 'America/New_York'
  }
});

// El worker genera y envía el informe por correo
worker.process('informe-diario', async (job) => {
  const { type, recipients } = job.data;

  const data = await generateReport(type);
  const pdf = await createPDF(data);

  await emailQueue.add('send', {
    to: recipients,
    subject: `Informe diario de ${type}`,
    attachments: [{ filename: 'report.pdf', content: pdf }]
  });
});

Patrón 3: Tubería de Transcodificación de Video

// Trabajo de múltiples etapas con seguimiento de progreso
await videoQueue.add('transcode', {
  videoId: 123,
  formats: ['720p', '1080p', '4k']
}, {
  attempts: 2,
  timeout: 3600000 // Timeout de 1 hora
});

worker.process('transcode', async (job) => {
  const { videoId, formats } = job.data;

  for (let i = 0; i < formats.length; i++) {
    const format = formats[i];

    // Actualizar progreso
    await job.updateProgress((i / formats.length) * 100);

    // Transcodificar
    await ffmpeg.transcode(videoId, format);
  }

  await job.updateProgress(100);
});

// El cliente consulta el progreso
app.get('/videos/:id/status', async (req, res) => {
  const job = await queue.getJob(req.params.jobId);
  res.json({
    state: await job.getState(),
    progress: job.progress
  });
});

Monitoreo y Observabilidad

Métricas Esenciales

// Tablero de salud de la cola
async function getQueueMetrics() {
  const [waiting, active, completed, failed, delayed] = await Promise.all([
    queue.getWaitingCount(),
    queue.getActiveCount(),
    queue.getCompletedCount(),
    queue.getFailedCount(),
    queue.getDelayedCount()
  ]);

  return {
    waiting,    // Trabajos esperando ser procesados
    active,     // Trabajos siendo procesados actualmente
    completed,  // Completados con éxito
    failed,     // Fallidos después de reintentos
    delayed,    // Programados para el futuro
    health: waiting < 1000 && failed < 100 ? 'healthy' : 'degraded'
  };
}

BullMQ Board (IU)

// Desarrollo: Monitorear trabajos visualmente
import { createBullBoard } from '@bull-board/api';
import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
import { ExpressAdapter } from '@bull-board/express';

const serverAdapter = new ExpressAdapter();

createBullBoard({
  queues: [
    new BullMQAdapter(emailQueue),
    new BullMQAdapter(videoQueue)
  ],
  serverAdapter
});

app.use('/admin/queues', serverAdapter.getRouter());
// Visite http://localhost:3000/admin/queues

Lista de Verificación para Producción

□ Cola de mensajes fallidos configurada
□ Estrategia de reintentos con retroceso exponencial
□ Límites de timeout de trabajo establecidos
□ Límite de tasa para APIs de terceros
□ Claves de idempotencia para operaciones críticas
□ Concurrencia de workers ajustada (núcleos de CPU * 2)
□ Escalado horizontal configurado (múltiples workers)
□ Monitoreo de profundidad de cola con alertas
□ Flujo de trabajo de inspección de trabajos fallidos
□ Los datos del trabajo no contienen PII en los registros
□ Persistencia de Redis habilitada (AOF o RDB)
□ Manejo de apagado graceful (SIGTERM)

Cuándo Usar vs Evitar

Escenario¿Usar trabajos en segundo plano?
Enviar correo de bienvenida al registrarse✅ Sí - puede tomar 2-5 segundos
Cobrar tarjeta de crédito⚠️ Quizás - depende de la latencia del proveedor de pago
Generar informe PDF (30 segundos)✅ Sí - definitivamente en segundo plano
Obtener perfil de usuario de la BD❌ No - milisegundos, mantener síncrono
Procesar carga de video (5 minutos)✅ Sí - siempre en segundo plano
Validar entrada de formulario❌ No - validación síncrona
Trabajo cron diario✅ Sí - usar trabajos repetibles
Mensaje de chat en tiempo real❌ No - usar WebSockets

Comparación de Tecnologías

CaracterísticaBullMQCeleryAWS SQS
LenguajeNode.jsPythonCualquiera (API HTTP)
BackendRedisRedis/RabbitMQ/SQSGestionado
Prioridades✅✅✅
Límite de tasa✅❌✅ (mediante atributos)
Repetir/Cron✅✅ (celery-beat)❌ (usar EventBridge)
Panel de IUBull BoardFlowerCloudWatch
Flujos de trabajo❌✅ (cadenas, grupos)❌
Curva de aprendizajeMediaMediaBaja
CostoHosting de RedisHosting de Redis$0.40/millón de solicitudes

Referencias

  • /references/bullmq-patterns.md - Patrones y ejemplos avanzados de BullMQ
  • /references/celery-workflows.md - Cadenas, grupos y acordes de Celery
  • /references/job-observability.md - Monitoreo, alertas y depuración

Scripts

  • scripts/setup_bullmq.sh - Inicializar BullMQ con Redis
  • scripts/queue_health_check.ts - Panel de métricas de la cola
  • scripts/retry_failed_jobs.ts - Reintentar en lote trabajos fallidos

Este skill guía sobre: Implementación de trabajos en segundo plano | Arquitectura de colas | Estrategias de reintentos | Escalado de workers | Observabilidad de trabajos

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

curiositech/windags-skills

Expert in 2000s-era music visualization (Milkdrop, AVS, Geiss) and modern WebGL implementations. Specializes in Butterchurn integration, Web Audio API AnalyserNode FFT data, GLSL shaders for audio-reactive visuals, and psychedelic generative art. Activate on "Milkdrop", "music visualization", "WebGL visualizer", "Butterchurn", "audio reactive", "FFT visualization", "spectrum analyzer". NOT for simple bar charts/waveforms (use basic canvas), video editing, or non-audio visuals.

curiositech/windags-skills

Expert legal research agent for finding and scraping expungement data state by state. Knows authoritative sources, URL patterns, Firecrawl configuration, and 2026 legal landscape.

curiositech/windags-skills

Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).

curiositech/windags-skills

Implement WCAG 2.2 AA/AAA compliance with automated testing, keyboard navigation, screen reader support, and focus management. Activate on: accessibility audit, WCAG compliance, keyboard navigation, screen reader, aria attributes, axe-core, focus trap. NOT for: design-level accessibility review (use design-accessibility-auditor), color contrast only (use css-in-js-architect).

curiositech/windags-skills

Time-blind friendly planning, executive function support, and daily structure for ADHD brains. Specializes in realistic time estimation, dopamine-aware task design, and building systems that actually work for neurodivergent minds.

curiositech/windags-skills

Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.

curiositech/windags-skills

>- Apply crisis decision-making research to agent routing, uncertainty triage, and coordination failure analysis in time-pressured systems. Use when diagnosing handoff failures, analytical paralysis, or expert judgment under incomplete information. NOT for routine coding, simple CRUD design, or static single-agent tasks with complete information.

curiositech/windags-skills

Extend and modify the admin dashboard, developer portal, and operations console. Use when adding new admin tabs, metrics, monitoring features, or internal tools. Activates for dashboard development, analytics, user management, and internal tooling.

curiositech/windags-skills

Conversation patterns and interaction protocols for multi-agent systems. Covers request/response, pub/sub, blackboard, delegation chains, debate, critique, consensus, fan-out/fan-in, supervisor-worker, and peer negotiation. Deep analysis of AutoGen conversation patterns, CrewAI delegation, LangGraph state passing, and FIPA-ACL performatives. Teaches how to design what agents say to each other and in what order. Activate on: "agent conversation", "agent protocol", "multi-agent debate", "agent delegation", "supervisor worker pattern", "agent voting", "consensus protocol", "fan-out fan-in", "agent negotiation", "blackboard pattern", "agent dialogue", "conversation topology", "agent handoff". NOT for: wire format or serialization (use agent-interchange-formats), orchestration infrastructure (use agentic-infrastructure-2026), single agent behavior (use agentic-patterns).

curiositech/windags-skills

Meta-agent for creating new custom agents, skills, and MCP integrations. Expert in agent design, MCP development, skill architecture, and rapid prototyping. Activate on 'create agent', 'new skill', 'MCP server', 'custom tool', 'agent design'. NOT for using existing agents (invoke them directly), general coding (use language-specific skills), or infrastructure setup (use deployment-engineer).

curiositech/windags-skills

AI-powered calendar management and agent-based scheduling coordination. Covers calendar APIs (Google Calendar, CalDAV/iCal), AI scheduling assistants (Reclaim, Clockwise, Motion, Cal.com), building custom calendar agents with MCP, multi-calendar merging, timezone management, focus block protection, meeting fatigue detection, and agent-to-agent meeting negotiation protocols. Activate on: "calendar agent", "AI scheduling", "calendar coordination", "meeting scheduling", "calendar API", "focus time protection", "calendar optimization", "Google Calendar MCP", "Reclaim", "Clockwise", "Motion", "Cal.com", "smart scheduling", "calendar-aware agent", "timezone scheduling", "agent negotiation meetings". NOT for: manual calendar UI component design (use form-validation-architect), project management scheduling or Gantt charts (use project-management-guru-adhd), general time-tracking or pomodoro apps (use adhd-daily-planner for time-awareness), building the agent itself from scratch (use agent-creator).

curiositech/windags-skills

Build and adopt production AI agent infrastructure in 2026. Covers framework selection (LangGraph, CrewAI, AutoGen, MCP), orchestration patterns, evaluation, observability, memory systems, and tool use. Also covers the SOCIAL dimension: how to sell agent infrastructure internally, change management, measuring ROI, building trust in autonomous systems, and scaling adoption across teams. Activate on: "agent infrastructure", "agent framework comparison", "which agent framework", "sell AI tools internally", "agent adoption", "agent observability", "agent evaluation", "MCP architecture", "agentic mesh", "enterprise AI agents", "AI change management", "agent ROI". NOT for: building specific agents (use ai-engineer), designing agent behavior patterns (use agentic-patterns), prompt tuning (use prompt-engineer).

curiositech/windags-skills

Fundamental patterns for effective agentic behavior. Teaches decomposition, tool orchestration, error recovery, context management, quality self-assessment, and knowing when to stop. Model-agnostic principles that make any agent more effective regardless of domain. Activate on: "how should I structure this agent", "agentic workflow", "agent patterns", "multi-step task", "tool orchestration", "/agentic-patterns", "decompose this", "agent best practices", "chain of actions", "when should the agent stop", "agent loop design". NOT for: creating agent infrastructure (use agent-creator), building DAGs (use windags-architect), specific tool implementation.

curiositech/windags-skills

Automated discovery and matching of agent skills for dynamic task routing and capability assessment

curiositech/windags-skills

Cryptographic security for agentic systems — zero-trust agent networking, signed message envelopes (JWS/JWE), capability-based security (ocaps), Merkle tree audit trails, WASM sandboxing, and formal verification. Covers CLI dev tool security, mTLS between agents, permission boundaries (least privilege for AI agents), and supply chain security for skills/plugins. Activate on: "agent security", "zero trust agents", "secure agent communication", "capability-based security", "ocap", "signed messages between agents", "agent audit trail", "sandbox agent execution", "agent permissions", "mTLS agents", "cryptographic verification", "agent supply chain", "OWASP agentic", "prove agent did X", "tamper-proof agent logs". NOT for: application-level SAST scanning (use security-auditor), network firewall rules (use infrastructure), SOC2/HIPAA compliance (organizational), or prompt injection defense (use prompt-engineer).

curiositech/windags-skills

Data structures and serialization formats for agent-to-agent communication. Covers message envelopes, structured output schemas, capability declarations, task handoff payloads, error/retry signaling, and context windows as data structures. Deep comparison of A2A protocol, MCP, OpenAI function calling, and LangChain message types. Teaches when to use rigid schemas vs free-form with validation, typed vs untyped, streaming vs batch. Activate on: "agent message format", "agent communication schema", "agent-to-agent protocol", "A2A protocol", "MCP message format", "structured output for agents", "agent interop", "interchange format", "agent serialization", "task handoff format", "capability declaration". NOT for: what agents say to each other (use agent-conversation-protocols), orchestration topology (use multi-agent-coordination), building agent infrastructure (use agentic-infrastructure-2026).

curiositech/windags-skills

Logic-based agent programming language implementing BDI architecture for practical autonomous agent development

curiositech/windags-skills

>- Design AgentSpeak(L)-style BDI agents with context-guarded plans, selection functions, and intention stacks. Use for interruptible autonomy, agent policy, and multi-agent orchestration in dynamic environments. NOT for simple rule engines, static planners, or centralized workflows.

curiositech/windags-skills

Foundational concurrent computation model where actors communicate exclusively through asynchronous message passing

curiositech/windags-skills

license: Apache-2.0 NOT for unrelated tasks outside this domain.

Skills relacionados