Atomic Tasks (Descomposición Atómica de Tareas)

1. Visión general del concepto y problema sistémico

En el desarrollo clásico, las tareas difusas ("Hacer la autorización", "Reescribir el módulo de búsqueda") son la principal fuente de retrasos y retrabajos. En la era del desarrollo con agentes de IA, el costo de una mala descomposición ha aumentado exponencialmente.

Cuando un ingeniero da a un agente una instrucción difusa de alto nivel, el agente hace suposiciones sobre decenas de detalles indefinidos. Como resultado, se genera un diff monolítico de 40 archivos, donde se mezclan el diseño, los esquemas de base de datos y las reglas de negocio. Verificar tal diff es prácticamente imposible: el ingeniero siente sobrecarga cognitiva, presiona "Aceptar" y, una semana después, se enfrenta a conflictos irresolubles.

Atomic Tasks (Tareas Atómicas) es una disciplina de ingeniería que estructura el trabajo bajo el principio de indivisibilidad:

• Cada subtarea se enfoca en un solo cambio de comportamiento o estructura.
• Tiene parámetros de entrada claramente definidos y invariantes de salida esperados.
• Puede ser completamente implementada, probada y comprometida por separado del resto del sistema.

Monolito caótico (Fallo del agente):
[Requisito: "Hazme una tienda en línea"] ---> [LLM genera un lío de 30 archivos con marcadores]

Descomposición atómica (Éxito controlado):
[Requisito: "Proceso de pedido"]
   |
   +---> Tarea 1: Crear esquema Drizzle para la tabla Order + migración (Verificación: db:push)
   |
   +---> Tarea 2: Escribir función pura calculateTotal(items, discount) (Verificación: 5 pruebas unitarias)
   |
   +---> Tarea 3: Implementar POST /api/orders con validación Zod (Verificación: curl / prueba API)
   |
   +---> Tarea 4: Crear formulario UI para el proceso de pedido (Verificación: componente en el navegador)

2. Taxonomía arquitectónica y modelo mental

Gradación de niveles de granularidad de tareas (Task Granularity Spectrum):

1. Nivel Macro (System Feature / Epic):
   • Meta de negocio (por ejemplo, "Soporte para la multilingüidad del sitio"). No se puede alimentar directamente al chat del agente como un solo comando.
2. Módulo Atómico (Feature Slice / Component):
   • Corte vertical de funcionalidad (por ejemplo, "Enrutamiento de locales a través de middleware").
3. Acción Atómica (Atomic Micro-Task):
   • Paso específico de modificación de una capa: "Crear un diccionario de traducciones para la página 404 en formato JSON y agregar tipos estrictos a las claves."
   • Tiempo de ejecución: 2–5 minutos.
   • Número de líneas modificadas: hasta 50–100 líneas.

3. Pipeline técnico y mecánica interna

Plantilla de tarea atómica de ingeniería (TASK_SPEC.md)

### Tarea: Creación de un repositorio para almacenar tokens de sesión

**Contexto de archivos:**
- Archivo objetivo: `src/lib/auth/session-store.ts`
- Archivo de prueba: `src/lib/auth/__tests__/session-store.test.ts`
- Contrato de referencia: `src/lib/auth/types.ts`

**Requisitos:**
1. Implementar la clase `RedisSessionStore`, que implemente la interfaz `SessionStore`.
2. El método `saveSession(token, data, ttlSeconds)` debe establecer una clave con TTL usando el comando Redis `SETEX`.
3. El método `getSession(token)` debe devolver un objeto deserializado o `null` si la clave no existe.

**Criterio de finalización (Definition of Done):**
- El comando `npx vitest run src/lib/auth/__tests__/session-store.test.ts` devuelve un 100% de pruebas exitosas.
- No hay errores de tipado: `npx tsc --noEmit` pasa con 0 errores.

Pipeline de ejecución de un paso atómico:

1. El ingeniero formula TASK_SPEC con contexto y prueba claros.
2. El agente lee SOLAMENTE los 2-3 archivos indicados (ventana de contexto limpia, cero alucinaciones).
3. El agente escribe la implementación.
4. Ejecución de prueba automática -> luz verde.
5. El ingeniero revisa el diff compacto (20 líneas) en 15 segundos.
6. Git commit: `git commit -m "feat(auth): implement redis session store"`

4. Escenarios prácticos de ingeniería en producción

01. Migración segura de base de datos de 10 millones de filas

En lugar de una migración compleja, el equipo descompone la tarea en 4 tareas atómicas: 1) Agregar una nueva columna como nullable; 2) Escribir un script de fondo de sincronización por lotes de 1000 filas; 3) Cambiar la escritura a la nueva columna; 4) Agregar la restricción NOT NULL y eliminar el campo antiguo. Cada etapa se verifica y despliega por separado, eliminando el riesgo de bloqueo de la tabla.

02. Salida de un estado de bloqueo creativo durante el debugging

El ingeniero no entiende por qué un algoritmo complejo de cálculo de rutas devuelve un resultado incorrecto. En lugar de revisar infructuosamente todo el archivo de 1000 líneas, descompone el algoritmo en 5 subfunciones limpias y escribe una prueba separada para cada una. En la tercera subfunción se encuentra un error de redondeo, y el bug se corrige en 3 minutos.

03. Dirigible paralelo de subagentes (Parallel Subagents)

Gracias a la atomicidad, el arquitecto puede ejecutar 3 sesiones diferentes del modelo simultáneamente: un agente escribe un parser XML, otro un generador de informes PDF, y otro un esquema de base de datos. Dado que sus contratos son atómicos y no se superponen en archivos compartidos, no hay conflictos de fusión (Merge Conflicts).

5. Errores comunes, trampas y seguridad

1. Parálisis por fragmentación (Micro-Task Hell): La descomposición excesiva de una tarea en 50 pequeños pasos de 30 segundos cada uno crea fricción burocrática: el tiempo para formular el prompt y esperar la respuesta comienza a superar el tiempo de escritura de código. Mantenga una escala saludable: 1 tarea atómica debe contener un paso significativo para resolver el problema.
2. Pérdida del invariante global (Local Optimum Trap): Cada tarea atómica puede ejecutarse perfectamente a su nivel, pero en conjunto los módulos pueden no encajar si no se ha establecido un contrato de interfaz común desde el principio (Contract-First Design).
3. Acumulación de basura no comprometida: Si después de completar cada tarea atómica no se realiza un git commit, después de 5 iteraciones el árbol de trabajo se convierte en un caos de cientos de cambios incomprensibles, y las ventajas de la atomicidad se pierden por completo.