DOMINICODE

Tag: AI

  • Cómo gestionar la memoria en agentes entre sesiones de forma eficiente

    Cómo gestionar la memoria en agentes entre sesiones de forma eficiente

    Context Engineering — el arte de gestionar el contexto del agente entre sesiones

    Tiempo estimado de lectura: 5 min

    • Context Engineering es disciplina operativa para mantener la memoria de agentes entre sesiones y evitar que “arranquen desde cero”.
    • Tres archivos clave (CLAUDE.md, AGENTS.md, memory files) convierten reglas, roles y memoria en infraestructura reutilizable.
    • Arquitectura de sub-agentes (orquestador, especialistas, QA) minimiza ruido y mejora precisión, latencia y coste.
    • Prácticas concretas: cierre de sesión obligatorio, outputs estructurados (JSON/Zod), RAG con caché semántico y auditoría por ejecución.

    Context Engineering es la práctica de diseñar y mantener la memoria operativa de agentes entre sesiones. Si aplicas GSD a equipos humanos, Context Engineering aplica GSD a agentes: dividir tareas, documentar decisiones y asegurar que la próxima sesión no sea una pizarra en blanco. Sin esta disciplina, los agentes alucinan, revierten decisiones y se vuelven caras e ineficaces.

    Resumen rápido (lectores con prisa)

    Context Engineering diseña la memoria y reglas permanentes de agentes para mantener continuidad entre sesiones. Úsalo cuando un sistema de agentes necesita precisión, trazabilidad y bajo coste operativo. Importa porque evita alucinaciones, pérdida de progreso y decisiones reversibles. Funciona con tres capas: reglas estáticas, memoria dinámica y sub-agentes especializados.

    El problema

    El problema es elegante y directo: los LLMs razonan bien, pero olvidan. El historial de chat como única memoria funciona en demos; colapsa en repositorios reales. Más tokens en el prompt solo añaden ruido. La solución práctica es convertir el repositorio en la memoria del agente mediante tres capas: reglas estáticas, memoria dinámica y sub-agentes especializados.

    Tres archivos que cambian el juego: CLAUDE.md, AGENTS.md y memory files

    CLAUDE.md (o .cursorrules) — la “constitución” del proyecto

    Propósito: reglas inmutables que el agente debe respetar.

    Contenido práctico: stack exacto (Node 20, React 18), políticas de seguridad, restricciones arquitectónicas y decisiones no negociables.

    Ejemplo (resumen):

    • Stack: Node 20, TypeScript 5.x, Next.js 14.
    • Convenciones: ESLint + Prettier; tests en Vitest.
    • Restricciones: “Nunca acceder a Supabase desde cliente; usar Server Actions”.

    CLAUDE.md es lo primero que un agente debe leer al comenzar.

    AGENTS.md — el organigrama legible por máquinas

    Propósito: definir quién hace qué en un sistema multi-agente.

    Contenido práctico: routing de tareas, roles (FrontendWorker, DBOptimizer, QAReviewer), permisos para commits.

    Resultado: orquestador capaz de delegar la tarea correcta al sub-agente correcto sin mandar TODO el repo como contexto.

    Memory files — la memoria viva (.context/ o .ai/)

    – active_task.md: la tarea actual, objetivo y criterios de éxito.

    – changelog_ai.md: decisiones y porqués (no sólo el qué).

    – lessons_learned.md: problemas recurrentes y soluciones definitivas.

    Rutina obligatoria: al cerrar sesión el agente actualiza estos archivos. Al abrir sesión, los lee y retoma.

    Sub-agentes: aislar contexto, reducir ruido, mejorar precisión

    Arquitectura propuesta:

    Arquitectura propuesta

    • Agente Orquestador (Router): lee AGENTS.md, empaqueta contexto mínimo y llama al especialista.
    • Agente Especialista (Worker): recibe solo lo necesario (e.g., esquema DB + active_task.md) para reducir ruido.
    • Agente Revisor (QA): valida output contra CLAUDE.md y tests antes de aplicar cambios.

    Ventaja: un sub-agente con 10k tokens relevantes produce mejores resultados que un mega-agente con 100k tokens llenos de ruido. También reduce costos y latencia.

    Prácticas operativas (lo que realmente marca la diferencia)

    • Obliga a un “cierre de sesión”: el prompt final del día debe ser “Actualiza active_task.md, changelog_ai.md y sugiere el siguiente paso”.
    • Usa esquemas para outputs: fuerza JSON/Zod para evitar outputs malformados.
    • RAG + caché semántico: externaliza historial pesado en una vector DB y recupera solo lo necesario por tarea. (Ver LangChain)
    • Streaming y UX: implementa streaming token a token para evitar bloqueos de UI. (Vercel AI SDK: Vercel AI SDK)
    • Auditoría y permisos: registra cada ejecución de sub-agente y limita quién puede hacer merges automáticos.

    Estructura mínima recomendada del repo

    /project-root
  /src
  /.ai
    CLAUDE.md
    AGENTS.md
    active_task.md
    changelog_ai.md
    lessons_learned.md
  /.ai/logs
  /docs

    Herramientas y lecturas útiles

    Criterio final para equipos técnicos

    Context Engineering no es documentación bonita. Es infraestructura operativa que convierte agentes en miembros persistentes del equipo. Si inviertes en reglas estáticas (CLAUDE.md), memoria dinámica (memory files) y una red de sub-agentes bien definida (AGENTS.md + orquestador), ganarás precisión, velocidad y trazabilidad. Sin esto, los agentes seguirán siendo costosos “showrooms” en lugar de fuerza productiva real.

    Aplica GSD a tus agentes: trocea, documenta, cierra sesiones. Si lo haces bien, el agente no volverá a arrancar desde cero.

    Dominicode Labs

    Si te interesa profundizar en automatización, agentes y workflows aplicados a equipos técnicos, puedes continuar explorando recursos y experimentos en Dominicode Labs. Es una continuación lógica para poner en práctica patrones de Context Engineering mencionados aquí.

    FAQ

    ¿Qué es Context Engineering?

    Context Engineering es la práctica de diseñar y mantener la memoria operativa y reglas de agentes entre sesiones para mantener continuidad, reducir alucinaciones y preservar decisiones previas.

    ¿Cuándo debo usar CLAUDE.md?

    Usa CLAUDE.md al empezar cualquier sesión de agente: contiene reglas inmutables, stack, convenciones y restricciones que el agente debe respetar. Es el primer archivo que el agente debe leer.

    ¿Para qué sirve AGENTS.md?

    AGENTS.md define roles, routing de tareas y permisos en sistemas multi-agente, permitiendo al orquestador delegar correctamente sin enviar el repo entero como contexto.

    ¿Qué contienen los memory files y quién los actualiza?

    Contain archivos como active_task.md, changelog_ai.md y lessons_learned.md. El agente en sesión debe actualizarlos al cerrar sesión; el próximo agente los lee al abrir sesión.

    ¿Por qué usar sub-agentes en lugar de un mega-agente?

    Porque un sub-agente centrado con contexto relevante (p. ej. 10k tokens) produce resultados más precisos y eficientes que un mega-agente con 100k tokens de ruido. Reduce costos, latencia y errores.

    ¿Qué es RAG y por qué es relevante aquí?

    RAG (Retrieval-Augmented Generation) externaliza historial pesado en una vector DB y recupera solo lo necesario por tarea. Es relevante para evitar enviar todo el historial en cada prompt y mantener precisión.

    ¿Cómo auditar ejecuciones de sub-agentes?

    Registra cada ejecución en logs estructurados (.ai/logs), incluye metadatos (input mínimo, decision hashes) y limita permisos para merges automáticos. La auditoría debe permitir reproducir la decisión y revisar cumplimiento con CLAUDE.md.

  • Cómo especificar un agente SDD antes de su implementación

    Cómo especificar un agente SDD antes de su implementación

    SDD + Agentes: cómo especificar un agente antes de construirlo

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Especificar antes de construir: define flujos de decisión, límites de herramientas y condiciones de parada antes de programar.
    • SDD para agentes ≠ SDD tradicional: los agentes requieren specs que formalicen libertad, herramientas y puntos de escalado humano.
    • Tres bloques críticos: topología de decisión, contratos de herramienta con schemas y guardrails cuantificables.
    • La spec debe ser ejecutable: tests automatizados, simuladores de fallo y verificación en CI/CD.

     

    Introducción

    SDD + Agentes: cómo especificar un agente antes de construirlo — dilo antes de teclear. Si no documentas la caja de arena cognitiva del LLM, lo que construyas será frágil, caro y peligroso. La especificación no es burocracia: es la diferencia entre un experimento que explota y un servicio que vive en producción.

    En las primeras líneas: especificar un agente significa definir flujos de decisión, límites de herramientas y condiciones de parada antes de escribir una sola línea de código. Hazlo así y reduces bucles infinitos, facturas de API descontroladas y escrituras destructivas en tus bases.

    Resumen rápido (lectores con prisa)

    Qué es: Una spec agéntica formaliza topología de decisión, contratos de herramientas y condiciones de parada.

    Cuándo usarla: Antes de implementar agentes que razonan o que pueden tocar recursos críticos.

    Por qué importa: Evita comportamientos estocásticos dañinos, costes inesperados y fallos de integridad de datos.

    Cómo se aplica: Define un patrón operativo único, schemas de entrada/salida para cada tool, y guardrails cuantificables con telemetría y pruebas.

    Por qué SDD para agentes no es lo mismo que SDD tradicional

    En apps CRUD, spec = modelos de datos + endpoints + contratos. Un 404 es un fallo leve. Un agente sin spec puede intentar cien variaciones de la misma consulta SQL, escribir datos corruptos o invocar herramientas fuera de scope. Aquí falla la arquitectura, no el prompt.

    Los agentes razonan de forma estocástica. Por eso la spec debe formalizar:

    • Qué libertad tiene el agente en cada punto.
    • Qué herramientas puede tocar y cómo.
    • Cuándo debe pararse y llamar a un humano.

    Anthropic recomienda priorizar flujos orquestados sobre autonomía total para casos críticos (ver: Anthropic — Building effective agents). Toma nota: la industria no apuesta por “agentes libres” en producción sin guardrails.

    Tres bloques que debe cubrir tu spec agéntica

    1) Flujos de decisión: topología y patrón operativo

    Decide uno (y solo uno) de estos patrones por caso de uso:

    • Enrutamiento semántico: el LLM clasifica intenciones y delega a código determinista.
    • Máquina de estados orquestada: el LLM elige transiciones entre nodos predefinidos (n8n, LangGraph, XState).
    • Bucle ReAct autónomo: pensamiento-observación-acción libre (solo para experimentos controlados).

    No mezcles sin regla. Define explícitamente qué patrón rige cada intent/endpoint y por qué.

    2) Límites de herramientas (Tool Boundaries)

    Una herramienta para un agente no es un endpoint cualquiera. Tu spec de herramienta debe incluir, al menos:

    • Contrato de datos (Zod o JSON Schema). No aceptes “any”.
    • Descripciones semánticas por campo: guía al LLM sobre qué producir exactamente.
    • Precondiciones de uso: cuándo está permitido invocar la tool.
    • Protocolo de fallo: ¿autocorrección (con el error serializado), retry con backoff, usar valor por defecto o abortar y escalar?

    Ejemplo mínimo (JSON Schema + fallback):

    {
  "name": "createUser",
  "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] },
  "description": "Crea un usuario. email debe ser un correo válido. No inferir dominios.",
  "precondition": "email provisto por usuario",
  "onError": { "strategy": "abort_and_escalate", "max_retries": 0 }
}

    Si dejas el onError en blanco, el agente decidirá por su cuenta —y lo hará mal.

    3) Guardrails y condiciones de parada

    Los guardrails no son sugerencias; son límites numéricos y verificables:

    • Max Steps: 5–10 iteraciones razonables por sesión antes de forzar cierre.
    • Retries por herramienta: típicamente 1–3, con backoff y registro.
    • Presupuesto operativo: tokens máximos por ejecución y tiempo máximo (p. ej. 30s wall clock).
    • Reglas de escalado humano: por ejemplo, tres fallos consecutivos de la misma tool o confianza del modelo < 0.6 → escalar.

    Documenta esos números en la spec. Implanta telemetría que lo verifique en tiempo real.

    Ingeniería práctica: plantilla rápida para tu spec agéntica

    Un documento mínimo y accionable debe contener:

    1. Directiva principal (system prompt base, objetivo inmutable).
    2. Fronteras negativas (anti-prompts: qué nunca debe hacer el agente).
    3. Contrato de memoria (qué guarda la memoria episódica y qué va a la semántica, p. ej. pgvector).
    4. Matriz de herramientas (schema, descripciones, precondiciones, fallback).
    5. Criterios de interrupción y política de escalado humano.
    6. Tests de comportamiento (simulaciones de fallo: error DB, timeout API, input malicioso).

    Incluye URLs en la spec para APIs críticas, contratos de datos y documentación de seguridad. Un equipo debe poder reproducir el flujo completo sin leer código.

    Trade‑offs y decisiones reales

    – Ventana de contexto gigante vs memoria estructurada: ventajas teóricas hay, pero en producción la memoria estructurada gana por latencia, coste y precisión (ver problema “lost in the middle”: arXiv:2307.03172).

    – Autonomía vs auditabilidad: cuanto más autónomo, menos auditable. Para negocios, prioriza auditabilidad.

    – Retry agresivo vs abort + humano: lo primero puede romper tu DB; lo segundo ralentiza workflows pero salva integridad.

    Cierre operativo: de la spec al CI/CD

    La spec no es un PDF muerto. Debe formar parte del pipeline:

    • Tests automatizados que validen precondiciones y fallbacks.
    • Simuladores que reproduzcan errores de herramientas.
    • Guardrails chequeados en staging y alertas de telemetría en producción.

    Si tu spec no se puede testear automáticamente, no es spec: es promesa. Y las promesas no pagan facturas.

    Define la caja de arena antes de soltar los músculos del agente. Es la única manera de que tus agentes actúen con intención, no con catástrofe.

    Dominicode Labs

    Para equipos que implementan pipelines y simuladores de fallo como parte de la spec, una referencia práctica y recursos complementarios están disponibles en Dominicode Labs. Considéralo como un recurso adicional para integrar tests y telemetría en tu CI/CD.

     

    FAQ

    ¿Por qué no vale con un buen prompt para controlar un agente?

    Un prompt no formaliza contratos ni límites verificables. Los agentes razonan de forma estocástica; sin schemas, precondiciones y guardrails numéricos, el prompt será frágil frente a inputs inesperados.

    ¿Qué es un contrato de herramienta y por qué usar JSON Schema?

    Un contrato de herramienta define tipos, formatos y campos requeridos. JSON Schema o Zod son formalismos que permiten validar entradas/salidas de forma determinista y evitar “any” que produzca comportamiento impredecible.

    ¿Cuántas iteraciones (Max Steps) son razonables?

    La guía práctica sugiere entre 5 y 10 iteraciones por sesión antes de forzar cierre. Ese rango reduce bucles infinitos y consumo excesivo de recursos.

    ¿Cómo debo manejar fallos recurrentes de una herramienta?

    Define un protocolo de fallo en la spec: retries limitados con backoff, registro y una estrategia de escalado (por ejemplo, abort_and_escalate tras N retries). No dejes el comportamiento en blanco.

    ¿Qué pruebas automatizadas son mínimas para una spec agéntica?

    Al menos: validación de precondiciones, simuladores de fallo de tools (DB error, timeout), y tests que verifiquen que los guardrails se activan (Max Steps, budget, retries).

    ¿Dónde documentar la política de escalado humano?

    La política de escalado debe estar en la spec principal, con reglas verificables (ej. tres fallos consecutivos de la misma tool o confianza < 0.6 → escalado) y enlaces a contactos/runbooks en tu repositorio de operaciones.

  • Cómo manejar errores en agentes de IA usando TypeScript

    Cómo manejar errores en agentes de IA usando TypeScript

    Error handling en agentes de IA: TypeScript te obliga a hacerlo bien

    Tiempo estimado de lectura: 3 min

    Ideas clave

    • Evita try/catch genéricos: ocultan la causa raíz y llevan a reintentos inútiles o a falsos positivos.
    • Usa Result<T, E>: convierte errores en valores tipados que el orquestador y el LLM pueden razonar.
    • Forzar exhaustividad con never: el compilador impide desplegar manejadores incompletos.
    • Persistir errores en memoria: guarda fallos estructurados en la memoria episódica para decisiones posteriores.
    • Instrumenta y prueba: telemetría, tests y SLAs para garantizar conducta operativa.

    Tabla de contenidos

    Introducción

    Error handling en agentes de IA: TypeScript te obliga a hacerlo bien. Dilo alto. Si tu agente llama herramientas, escribe datos o encadena flujos, el modo en que tratas los fallos decide si tendrás un sistema autocorrectivo o un monstruo que consume tokens y rompe tablas.

    Los try/catch genéricos son la forma más rápida de cegar a un agente. TypeScript, usado con disciplina, no te da magia: te da garantías. Garantías que convierten excepciones impredecibles en valores tipados que el agente puede razonar, registrar y recuperar.

    Resumen rápido (lectores con prisa)

    Qué: Trata errores como valores con Result<T,E> en lugar de throw.

    Cuándo: Siempre que tu agente llame herramientas, escriba en DB o coordine flujos.

    Por qué importa: Evita reintentos ciegos, reduce tokens gastados y hace al agente reparable.

    Cómo funciona: Devuelve {ok: true|false} con error tipado y usa checks exhaustivos con never para obligar a manejar nuevos casos.

    Por qué los try/catch genéricos matan tus agentes

    Un humano reintenta después de un HTTP 500. Un agente no. Cuando un LLM recibe solo “Error executing tool”, pierde la causa raíz. ¿Duplicado en la DB? ¿Timeout? ¿Bad payload? Sin esa información, el agente hará una de dos cosas útiles para nadie: reintentar la misma acción hasta agotar tu presupuesto o “alucinar” que la acción fue exitosa para seguir el flujo.

    En sistemas agénticos cada fallo es una señal. Ocultarla con un mensaje opaco equivale a apagar los sensores del coche mientras conduces rápido.

    Result<T, E>: convertir errores en datos con contrato

    La respuesta práctica es sencilla: deja de tirar (throw) y empieza a devolver. El patrón Result<T, E> transforma errores en valores discriminados que obligan al consumidor a lidiar con ellos.

    type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

    Ejemplo de herramienta:

    async function createUser(email: string): Promise<Result<User, 'DUPLICATE_EMAIL' | 'DB_TIMEOUT' | 'INVALID_SCHEMA'>> {
  // nunca throw; siempre retorna ok: true | ok: false
}

    ¿Qué cambia? Ahora el orquestador recibe información accionable. Si ok: false y error === ‘DUPLICATE_EMAIL’, inyectas esa razón en la memoria episódica y el LLM pregunta por otro email en vez de repetir la misma INSERT. Transformas ruido en contexto.

    Documentación útil sobre Result (concepto inspirado en Rust): Documentación útil sobre Result (concepto inspirado en Rust)

    never y exhaustive checks: el compilador como guardarraíl

    Pasa esto en equipos: alguien añade un nuevo error y olvida manejarlo. Resultado: el agente se comporta de forma impredecible en producción. Aquí entra el patrón de comprobación exhaustiva con never.

    Define tus errores como unión discriminada:

    type AgentError =
  | { type: 'DatabaseError'; code: number }
  | { type: 'AuthError'; reason: string }
  | { type: 'ValidationError'; issues: string[] };

    Y formatea para el LLM con un switch que fuerza exhaustividad:

    function formatErrorForLLM(error: AgentError): string {
  switch (error.type) {
    case 'DatabaseError': return `DB failure (${error.code}). No retry.`;
    case 'AuthError': return `Auth failed: ${error.reason}. Re-auth required.`;
    case 'ValidationError': return `Invalid: ${error.issues.join(', ')}. Fix and retry.`;
    default:
      const _exhaustive: never = error;
      return _exhaustive;
  }
}

    Si alguien añade { type: 'RateLimit' } a AgentError y no actualiza este switch, TypeScript fallará en compilación. Lee sobre exhaustiveness checks: Lee sobre exhaustiveness checks

    Eso no es paranoia: es disciplina. Tu CI/CD no permitirá desplegar un agente que no explica cada fallo.

    Integración práctica con memoria y orquestación

    Errores tipados deben viajar junto con resultados hacia la memoria episódica. Diseño minimalista:

    • La tool retorna Result.
    • El orquestador persiste tanto éxitos como fallos en la memoria episódica (Redis) y semántica (vector DB si aplica).
    • El prompt incluye el fallo estructurado antes de la siguiente llamada al LLM.
    • El LLM decide la acción (retry con modificación, pedir datos al usuario, escalar).

    Además: valida entradas con Zod/JSON Schema antes de llamar a la tool. Un buen schema reduce la superficie de errores y hace que los fallos restantes sean reales y manejables.

    Operacional: telemetría, tests y SLAs

    No sirve con tipos si no lo verificas. Tienes que medir:

    • Retries por tipo de error (P50/P95).
    • Frecuencia de errores no mapeados (build-breakers).
    • Tokens gastados en reintentos.
    • Casos escalados a humano.

    Incluye tests que simulen fallos de DB, timeouts y errores de validación. Tu pipeline debe romper si un nuevo error llega a producción sin un handler en el switch exhaustivo.

    Cierre operativo

    El try/catch genérico es cómodo. También es la razón por la que tu agente se convierte en una caja negra con facturas altas y datos rotos. Convertir errores en valores tipados (Result<T,E>) y forzar comprobaciones exhaustivas con never no es estilo: es seguridad operativa.

    Aplica esto ya, instrumenta telemetría y haz que tu build falle si alguien olvida un caso de error. En el próximo artículo mostraremos cómo serializar esos errores en memoria episódica y usar feedback estructurado para que el agente aprenda a autocorregirse sin intervención humana.

    Dominicode Labs

    Para equipos que diseñan agentes y pipelines de orquestación, es útil contar con recursos y experimentos que muestren patrones de integración entre memoria episódica y errores tipados. Continúa explorando técnicas y prototipos en Dominicode Labs para ver implementaciones prácticas y ejemplos aplicados a agentes y workflows.

    FAQ

    ¿Por qué no debo usar try/catch genéricos en agentes?

    Porque ocultan la causa raíz y priven al agente de información accionable. Un mensaje opaco lleva a reintentos inútiles o a continuar el flujo como si la acción hubiera tenido éxito.

    ¿Qué es Result<T,E> y cómo cambia la arquitectura?

    Es un patrón que devuelve un valor tipado indicando éxito o fallo ({ok: true; value} | {ok: false; error}). Obliga al consumidor a tratar explícitamente los errores y permite que orquestadores y LLMs actúen sobre causas concretas.

    ¿Cómo obliga TypeScript a manejar nuevos errores?

    Mediante comprobaciones exhaustivas usando never en un switch sobre una unión discriminada. Si se añade un nuevo caso y no se maneja, el compilador falla.

    ¿Dónde guardo los errores para que el agente los use?

    Persiste fallos en la memoria episódica (ej. Redis) y en la memoria semántica si aplica (vector DB). El orquestador debe guardar tanto éxitos como fallos para proporcionar contexto al LLM.

    ¿Qué métricas debo instrumentar primero?

    Retries por tipo de error (P50/P95), frecuencia de errores no mapeados, tokens gastados en reintentos y casos escalados a humano.

    ¿Cómo debo testear los manejadores de error?

    Incluye tests que simulen fallos de DB, timeouts y errores de validación; el pipeline debe fallar si un nuevo error llega a producción sin handler.

    ¿Qué herramientas de validación recomiendan antes de llamar a una tool?

    Valida entradas con Zod o JSON Schema para reducir la superficie de errores y asegurar que los fallos restantes sean reales y manejables.

  • Implementación del RALPH Loop en agentes LLM para evitar fallos

    Implementación del RALPH Loop en agentes LLM para evitar fallos

    ¿Qué es RALPH Loop? Guía técnica para arquitectos de agentes

    Si buscas “que es ralph loop?” necesitas algo más que una definición: necesitas un mapa práctico para diseñar agentes que no se vuelvan peligrosos o caros en producción. El RALPH Loop es un patrón de control iterativo para agentes basados en LLM que añade aprendizaje y gobernanza explícita al ciclo de razonamiento-actuación. Aplicado bien, evita bucles infinitos, ahorra tokens y protege datos críticos. Aplicado mal, convierte tu agente en un script que consume presupuesto y arriesga integridad operacional.

    Resumen rápido (lectores con prisa)

    RALPH Loop organiza cada iteración del agente en cinco fases: Retrieve, Analyze/Act, Learn, Plan y Halt. Funciona combinando LLMs con memoria temporal y reglas deterministas para evitar bucles, reducir coste por tokens y proteger acciones destructivas. Se aplica cuando el agente tiene permisos de escritura, sesiones largas o herramientas múltiples; si no, ReAct o pipelines simples bastan.

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Cinco fases: Retrieve, Analyze/Act, Learn, Plan, Halt.
    • Halt crítico: combinación LLM + heurísticas deterministas (MaxSteps, token budget, detección de loops).
    • Aprendizaje en ejecución: registrar resultados para no repetir errores en la misma sesión.
    • Stacks recomendados: LangGraph/LangChain, n8n o implementación personalizada en Python.
    • Checklist: sandboxing, trazas JSONL, límites y escalado humano.

    Tabla de contenidos

    ¿Qué es RALPH Loop? Definición y motivación

    El RALPH Loop es un marco que organiza cada iteración del agente en cinco fases: Retrieve, Analyze/Act, Learn, Plan y Halt. Nace como evolución práctica de ReAct (Reason + Act) al responder a dos carencias claras en entornos reales: la incapacidad de aprender de acciones previas en la misma ejecución y la falta de una condición de parada robusta.

    ReAct es un punto de partida académico útil (ver artículo de ReAct). RALPH toma esa base y la convierte en arquitectura productiva: trae memoria temporal, reglas deterministas y heurísticas de seguridad para que el agente no provoque incidentes.

    Las cinco fases del RALPH Loop (implementables)

    R: Retrieve (Recuperar)

    – Recupera sólo el contexto necesario: historial relevante, resultados previos, vectores RAG. Evita saturar la ventana de contexto con ruido. Para RAG y vectores, mira prácticas comunes en Retrieval-Augmented Generation.

    A: Analyze & Act (Analizar y Actuar)

    – El LLM decide la herramienta y emite una llamada estructurada (function calling). Aquí la salida debe ser accionable (API call, ejecución de script, query SQL mockeada en pruebas).

    L: Learn (Aprender)

    – Registra el resultado (success/failure, códigos de error, latencia). Actualiza la memoria de trabajo para no repetir la misma acción inútil. Esta es la diferencia operativa: evita repetir fallos y detectar patrones de error.

    P: Plan (Planificar)

    – Ajusta la estrategia: intentar alternativa, degradar la acción, o solicitar más datos. Mantén un plan explícito serializable (lista de pasos pendientes, prioridad, contexto).

    H: Halt (Detener/Escalar)

    – Evaluación final: ¿objetivo cumplido? ¿sin progreso real? Si no, escalar a humano. La fase Halt combina la opinión del LLM con reglas duras (max steps, token budget, detección de loops).

    Por qué la fase Halt es la más crítica

    Los LLM son probabilísticos. No puedes confiar en que “sabran” cuando deben parar. En producción, la fase Halt se implementa como combinación LLM + heurísticas deterministas:

    • Límite de iteraciones (MaxSteps = 5–15 según complejidad).
    • Timeout absoluto por ejecución.
    • Presupuesto de tokens/coste por ejecución.
    • Detección de bucles semánticos (similitud coseno > 0.95 entre planes consecutivos).
    • Reglas de seguridad para acciones destructivas (p. ej. bloqueo de delete sin aprobación humana).

    Estas reglas son guardrails; no sustituyen la auditoría humana, pero evitan incendios evitables.

    Implementación práctica: stacks y patrones

    LangGraph / LangChain

    – Modela cada fase como nodo del grafo. Usa aristas condicionales en Halt que consulten métricas deterministas y el veredicto del LLM. Documentación útil para orquestación: Documentación de LangChain.

    n8n

    – Construye workflows cíclicos en lugar de un nodo monolítico de agente. Nodifica Retrieve, Analyze, Learn, Plan y un nodo Switch que implemente Halt. n8n facilita observabilidad y reintentos: n8n.

    Implementación personalizada (Python)

    – Clase AgentState serializable: historial, iteraciones, token_cost, last_action. Métodos: retrieve(), act(), learn(), plan(), halt_check(). Esto da máximo control y testabilidad.

    Ejemplo concreto (simplificado)

    Objetivo: “Optimizar consultas lentas”.

    Iteración 1: Retrieve → identifica consulta y plan de índices.

    Act: propone CREATE INDEX (mockeado en harness).

    Learn: índice ya existe → error “duplicate”.

    Plan: intenta analizar plan de ejecución alternativo.

    Halt: si tras 5 intentos sigue sin progreso, escalar a humano.

    Si CREATE INDEX hubiera sido ejecutado en prod sin harness, el agente podría seguir intentando acciones que dañan datos. RALPH previene eso.

    Cuándo aplicar RALPH Loop

    Usa RALPH cuando el agente:

    • Tiene permisos de escritura o acciones con efectos irreversibles.
    • Opera en sesiones largas con múltiples herramientas.
    • Interactúa con APIs externas inestables o con datos sensibles.

    Si tu caso es un simple extractor de texto o clasificación puntual, ReAct o un pipeline lineal bastan.

    Checklist mínimo antes de desplegar

    • Sandboxing y mocks para pruebas.
    • Registro estructurado de trazas (JSONL).
    • MaxSteps y token budget configurados.
    • Mecanismo de escalado humano probado.
    • Métricas: iteraciones por tarea, token cost, tasa de escalation.

    El RALPH Loop no es magia; es disciplina de ingeniería. Si quieres agentes operables, dales memoria, reglas y límites. Sin eso, tendrás un asistente caro y peligroso. Con eso, tendrás una pieza automatizada que escala capacidad sin quemar infraestructura ni reputación.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows y quieres explorar patrones de producción y orquestación, consulta los recursos y experimentos disponibles en Dominicode Labs. Es una continuación lógica para equipos que buscan implementar guardrails y observabilidad en pipelines de agentes.

    FAQ

    ¿Qué problemas resuelve RALPH Loop?

    Evita bucles infinitos, reduce coste por tokens y protege la integridad operacional al añadir memoria temporal, aprendizaje en ejecución y reglas deterministas de parada.

    ¿En qué se diferencia de ReAct?

    ReAct combina razonamiento y acción, pero no incorpora aprendizaje en la misma ejecución ni condiciones de parada robustas. RALPH añade fases de Learn y Halt para cubrir esas carencias.

    ¿Cuántas iteraciones debo permitir (MaxSteps)?

    Depende de la complejidad: típicamente entre 5 y 15. Ajusta según riesgo, coste de tokens y criticidad de la acción.

    ¿Cómo se detectan bucles semánticos?

    Usando métricas de similitud (por ejemplo, similitud coseno > 0.95 entre planes consecutivos) y comparando estados serializados del plan de acción.

    ¿Qué métricas debo registrar?

    Iteraciones por tarea, token cost, latencia por acción, códigos de error, y tasa de escalado a humano.

    ¿Es necesario usar un stack específico?

    No. LangGraph/LangChain y n8n son prácticas comunes por observabilidad y orquestación, pero una implementación personalizada en Python ofrece máximo control y testabilidad.

    ¿Cómo pruebo acciones destructivas en desarrollo?

    Usa sandboxing y mocks, ejecuta acciones en harness controlado y registra resultados estructurados antes de permitir ejecuciones en producción.

  • Cuatro herramientas de IA esenciales para emprendedores técnicos

    Cuatro herramientas de IA esenciales para emprendedores técnicos

    IA para emprendedores: las 4 herramientas que uso todos los días

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Un stack de cuatro herramientas (Perplexity, Cursor, n8n y v0) cubre investigación, código, orquestación y UI para MVPs productivos.
    • Cada plataforma resuelve un problema concreto y se integra sin fricción con las demás.
    • Usa Perplexity para evidencia, Cursor para código con contexto, n8n para automatización controlada y v0 para prototipado UI rápido.
    • Este enfoque prioriza velocidad sin sacrificar calidad; no es para scripts one‑off ni entornos regulados sin políticas claras.

    Tabla de contenidos

    Introducción

    IA para emprendedores: las 4 herramientas que uso todos los días. Si eres fundador técnico y estás cansado de probar aplicaciones brillantes que no escalan, este artículo te dice exactamente qué usar —y por qué— para convertir IA en multiplicador de fuerza real.

    No es una lista de modas. Es el stack operativo que cubre investigación, desarrollo, orquestación y prototipado. Cada herramienta la uso a diario porque resuelve un problema concreto en mi flujo de trabajo y se integra con las demás sin fricción.

    Resumen rápido (lectores con prisa)

    Perplexity: evidencia y referencias para decisiones técnicas. Cursor: generación y refactorización con visibilidad del repo. n8n: automatizaciones autoalojables y controladas. v0: scaffolding UI React + Tailwind para MVPs.

    IA para emprendedores: las 4 herramientas que uso todos los días

    Estas cuatro plataformas no son intercambiables. Juntas forman un sistema: Perplexity para la evidencia, Cursor para el código con contexto, n8n para la automatización con control y v0 para llevar la interfaz del MVP al campo de batalla.

    1) Perplexity Pro — investigación técnica fundamentada

    Perplexity

    Usos concretos

    • Auditar una dependencia antes de añadirla: pedir benchmarks y CVEs documentados.
    • Extraer endpoints relevantes de una API y generar esquemas TypeScript a partir de la doc.
    • Diagnóstico de errores raros con enlaces a issues de GitHub y soluciones reales.

    Cuando buscas decisiones arquitectónicas, Google devuelve ruido SEO; necesitas hechos y referencias. Perplexity actúa como motor de respuestas fundamentadas: cita fuentes, enlaza documentación y evita alucinaciones sobre versiones o APIs recientes.

    Por qué lo tengo abierto antes de empezar un pull request: reduce el riesgo de elegir la solución “popular” en vez de la adecuada.

    2) Cursor — desarrollo asistido por contexto de repositorio

    Cursor

    Cómo lo uso

    • Flujo Spec-First: escribo interfaces y tipos, pido a Cursor los tests (TDD) y luego la implementación.
    • Refactorizaciones cross-módulo sin romper imports ni tipos.
    • Integración con modelos Anthropic (Claude) para tareas de razonamiento complejas.

    Cursor deja de ser un autocompletador para convertirse en un IDE con memoria de todo el repo. Eso cambia la conversación: cuando pides una refactorización o que genere tests, el modelo ve las interfaces, dependencias y convenciones reales del proyecto.

    Resultado: menos correcciones manuales, menos “import not found” y código que encaja de verdad con la base existente.

    3) n8n — orquestación y automatización controlada

    n8n

    Casos de uso diarios

    • Triaje automático de soporte: correo → clasificación LLM → crear ticket en Jira/Slack.
    • Pipelines ETL: extraer Stripe → transformar con JS → cargar en PostgreSQL.
    • Backend de herramientas para asistentes GPT: el agente razona, n8n ejecuta los permisos y las acciones.

    Zapier sirve al marketing; n8n sirve a ingeniería. Autoalojable, nodos de código y soporte para agentes/LLMs lo convierten en el backbone cuando necesitas ejecutar lógica real sobre tus datos, mantener privacidad y controlar errores.

    Si la automatización toca datos sensibles o requiere lógica personalizada, n8n es la única opción que no te dejará con dudas de cumplimiento.

    4) v0 (Vercel) — prototipado UI rápido y utilizable

    v0

    Qué me ahorra

    • Scaffolding de dashboards y formularios validados.
    • Código que respeta patterns de Next.js y facilita integración con Server Components.
    • Iteraciones de diseño que van directamente al repo, no a un diseñador externo.

    v0 genera componentes React + Tailwind listos para producción desde descripciones en lenguaje natural. No es magia estética; es velocidad para convertir hipótesis en interfaces conectables a tu backend.

    Para MVPs que necesitan verse y funcionar rápido, v0 reduce semanas de trabajo a horas.

    Cómo encajan estas piezas en un flujo real

    1. Decisión arquitectónica: Perplexity te da la evidencia y los enlaces (docs, issues).
    2. Diseño del contrato: escribes tipos/interfaces y casos límite.
    3. Implementación y pruebas: Cursor genera tests y código con visión de repo.
    4. Orquestación y producto: n8n automatiza flujos operativos; v0 entrega la UI del MVP.

    URLs de referencia rápidas

    Cuándo usar este stack y cuándo no

    Úsalo si quieres velocidad sin sacrificar calidad: MVPs productivos, equipos pequeños, founders técnicos que necesitan iterar rápido. No lo uses para scripts one-off sin mantenimiento o en entornos regulados donde las políticas corporativas prohíban modelos generativos.

    La diferencia es sencilla: las herramientas ejecutan; tú decides. Quien domine el “qué” y el “por qué” seguirá teniendo ventaja competitiva. Estas cuatro plataformas reducen la fricción operativa, no sustituyen el criterio técnico.

    Empieza mañana

    Define dos tipos, genera los tests con Cursor, monta un flujo simple en n8n y pide a v0 el scaffold del dashboard. Verás que el tiempo que ahorras no es solo horas: es autocontrol técnico. Esto no acaba aquí; el próximo paso es convertir esa prueba en una rutina reproducible para todo tu equipo.

    Dominicode Labs

    Si trabajas en automatización, agentes o workflows y quieres ejemplos reproducibles que integren investigación, código, orquestación y UI, revisa Dominicode Labs. Encontrarás plantillas y guías prácticas para aplicar este stack en proyectos reales.

    FAQ

    ¿Para qué sirve Perplexity en un flujo técnico?

    Perplexity sirve para obtener evidencia, referencias y enlaces a documentación o issues que apoyen decisiones arquitectónicas. Reduce riesgo al proveer fuentes verificables en lugar de resultados orientados a SEO.

    ¿Cómo mejora Cursor el desarrollo en equipo?

    Cursor aporta contexto del repo al proceso de generación de código: permite generar tests, refactorizaciones y código que respeta interfaces y convenciones ya existentes, reduciendo errores de integración.

    ¿Por qué elegir n8n sobre Zapier?

    n8n es autoalojable, soporta nodos de código y ofrece control de datos y errores, por lo que es más adecuado para ingeniería y workflows que manejan información sensible o lógica personalizada.

    ¿v0 reemplaza a un diseñador?

    No reemplaza a un diseñador en todos los casos. v0 acelera el scaffolding y genera componentes listos para producción, especialmente útil en MVPs donde velocidad e integración con el backend son prioritarias.

    ¿Este stack es adecuado para entornos regulados?

    No se recomienda sin revisar las políticas corporativas y de cumplimiento. En entornos regulados hay que validar uso de modelos generativos y requisitos de privacidad antes de adoptar el stack.

    ¿Qué pruebas recomendar para integrar este flujo?

    Recomiendo pruebas unitarias y de integración generadas desde el contrato (types/interfaces), pipelines ETL validados en n8n y pruebas end-to-end del UI scaffolded por v0. Vitest es una referencia recomendada para tests.

  • Cómo construir un subagente en Claude Code para revisión de PRs

    Cómo construir un subagente en Claude Code para revisión de PRs

    Cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests

    Tiempo estimado de lectura: 4 min

    • Patrón práctico: contexto acotado + reglas estrictas + output accionable para integrar IA en pipelines.
    • Dos casos: revisor de PRs (diff) y generador de tests (por archivo).
    • Implementación: scripts CLI que usan Claude Code, prompts versionados y hooks/CI para automatizar.
    • Precauciones: controlar tokens, contexto parcial y mantener revisión humana para decisiones críticas.
    Entender cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests, es el salto práctico entre usar IA como chat y convertirla en un componente automatizado de tu pipeline de desarrollo. Aquí tienes un tutorial accionable, sin humo: código, prompts y reglas para que funcione de verdad.

    Resumen rápido (lectores con prisa)

    Un subagente es un script que envía contexto limitado (diff o archivo) a Claude Code con un prompt versionado. Úsalo cuando la tarea sea repetitiva y pueda expresarse con reglas claras. La clave: reducir contexto, reglas estrictas y automatizar en hooks/CI.

    Cómo construir tu primer subagente en Claude Code — paso a paso

    Requisitos mínimos

    • Node.js y npm.
    • Cuenta y credenciales de Anthropic (Claude Code).
    • Repositorio Git con cambios en una rama distinta a main.

    Instalación rápida

    Instala la CLI de Claude Code y autentica:

    npm install -g @anthropic-ai/claude-code
claude auth

    (Referencia: npm package @anthropic-ai/claude-code)

    1. Define el System Prompt (qué puede y qué no puede hacer)

    El System Prompt es la barrera entre ruido y valor. Guarda uno en la raíz: .claude-reviewer-prompt.md.

    Contenido recomendado:

    Eres un Staff Engineer realizando una revisión de código.
Recibirás un `git diff`. Tu objetivo es identificar problemas críticos.

Reglas:
1. Ignora formato y estilo (linters ya hacen eso).
2. Busca: vulnerabilidades, condiciones de carrera, mutaciones de estado no controladas y complejidad innecesaria.
3. Si hay nueva lógica sin tests, marca "Missing Tests" como error crítico.
4. Responde en Markdown. Si todo está correcto, responde solo: "✅ Código limpio. Listo para PR."

    Sé explícito: lo que no está en las reglas, está fuera del subagente.

    2. Script que orquesta el subagente (claude-pr-review.sh)

    Extrae el diff y pásalo al modelo. Crea /scripts/claude-pr-review.sh:

    #!/bin/bash
DIFF=$(git diff main...HEAD -- ':!**/package-lock.json' ':!**/dist/**')

if [ -z "$DIFF" ]; then
  echo "No hay cambios para revisar."
  exit 0
fi

PROMPT=$(cat .claude-reviewer-prompt.md)

claude --print --prompt "$PROMPT

Aquí tienes el diff:
\`\`\`diff
$DIFF
\`\`\`"

    Notas:

    • Excluye archivos generados para ahorrar tokens (-- ':!path').
    • claude --print muestra la respuesta en terminal; puedes redirigirla a un archivo.

    3. Variante: generador de tests por archivo

    Mismo patrón, distinto input. Crea /scripts/claude-gen-tests.sh:

    #!/bin/bash
FILE_PATH=$1
if [ ! -f "$FILE_PATH" ]; then
  echo "Archivo no encontrado: $FILE_PATH"
  exit 1
fi

claude --print --prompt "Actúa como SDET especializado en TypeScript.
Genera tests unitarios con Jest para el siguiente archivo. Usa mocking donde aplique. Devuelve solo el código del test.

Archivo:
$(cat $FILE_PATH)" > "${FILE_PATH%.*}.test.ts"

    El resultado es un punto de partida. No lo aceptes ciegamente: revisa los mocks y aserciones.

    4. Integración práctica: Hooks y CI

    Un script manual se olvida. Integra el revisor en un hook pre-push (Husky) o como job en CI.

    Ejemplo Husky (.husky/pre-push):

    #!/bin/sh
./scripts/claude-pr-review.sh || exit 1

    Si detecta un problema crítico, el script puede devolver exit 1 y bloquear el push.

    En CI, ejecuta el script y falla el job si el output contiene palabras clave (ej. “Missing Tests” o “Error crítico”).

    5. Limitaciones y buenas prácticas

    • Coste de tokens: pasar un diff enorme puede ser caro. Filtra archivos irrelevantes. Regla práctica: apunta a menos de ~20k tokens por invocación.
    • Contexto parcial: el subagente solo ve lo que le das (diff o archivo). Los falsos positivos aparecen cuando la lógica depende de archivos no incluidos.
    • No es reemplazo de humanos: automatiza lo repetitivo; deja decisiones arquitectónicas a desarrolladores senior.
    • Versiona prompts y scripts: audítalos como cualquier herramienta crítica.

    6. Decisión rápida: cuándo usar un subagente local

    Usa subagentes locales si:

    • La tarea es repetitiva y repite reglas claras (seguridad simple, checklists de arquitectura).
    • Tienes un disparador claro (push, PR, commit).
    • Puedes limitar el contexto para controlar coste y precisión.

    Evítalos cuando:

    • Requieres análisis de arquitectura completa de un monorepo.
    • Necesitas pruebas end-to-end dependientes de infra externa.

    Conclusión (y lo que sigue)

    El patrón es simple y poderoso: reduce ruido dando contexto acotado y reglas firmes. Implementa el revisor y el generador de tests como base, obsérvalos un par de semanas, afina el prompt y automatiza su ejecución en hooks o CI. Esto no acaba aquí: un subagente bien definido se convierte en una pieza de infraestructura que reduce fricción y libera criterio humano para lo que realmente importa.

    Dominicode Labs

    Para equipos que investigan automatización y agentes en pipelines, puede ser útil explorar recursos y experimentos adicionales en Dominicode Labs. Considera esto como una continuación lógica para prototipar y versionar subagentes en un entorno experimental controlado.

    FAQ

    ¿Qué es un subagente en este contexto?

    Un subagente es un componente automatizado que envía contexto específico (por ejemplo, un git diff o el contenido de un archivo) a un modelo (Claude Code) junto con un prompt versionado y reglas, para producir output accionable usado en pipelines de desarrollo.

    ¿Cómo protejo credenciales y datos sensibles?

    Almacena credenciales en entornos seguros (secrets en CI, variables de entorno en el sistema) y evita pasar archivos que contengan secretos en los diffs enviados al modelo. Versiona prompts pero no incluyas secretos en ellos.

    ¿Cuándo el subagente debe fallar un push?

    Haz que falle cuando detecte errores críticos claramente definidos en el prompt (por ejemplo, “Missing Tests” o “Error crítico”). Mantén una lista pequeña y precisa de condiciones que realmente justifiquen bloquear un push.

    ¿Cómo controlo el coste de tokens?

    Filtra archivos irrelevantes, limita el tamaño del diff y prioriza invocaciones por carpeta o por cambios significativos. Regla práctica: apunta a menos de ~20k tokens por invocación.

    ¿Puedo usar otros modelos o proveedores?

    Sí. El patrón (contexto acotado + reglas estrictas + output accionable) es agnóstico al proveedor. Ajusta comandos y prompts según la API/CLI del proveedor seleccionado.

    ¿Cómo versiono y audito prompts?

    Guarda prompts en el repositorio (por ejemplo, .claude-reviewer-prompt.md) y trata los cambios como código: revisiones, PRs y registro de cambios. Audítalos como cualquier herramienta crítica operativa.

  • Cómo Crear una Especificación Técnica Efectiva para Claude

    Cómo Crear una Especificación Técnica Efectiva para Claude

    ¿Quieres convertir una idea brillante en un plan técnico que no se desmorone en la primera integración?

    Tiempo estimado de lectura: 6 min

    • Empieza por el porqué: describir el valor antes de pedir diseño técnico.
    • Documenta y estructura: volcado de contexto organizado en secciones claras.
    • Limita y pide artefactos: define stack, restricciones y solicita outputs machine-readable.
    • Itera con pruebas: divide en fases, genera tests y checklist de aceptación desde el inicio.

    Introducción

    Poca gente habla de esto en voz alta: usar a Claude sin método es como dar un GPS a alguien que no sabe leer mapas. Te lleva rápido. Te deja en medio de la nada.

    Descubrí algo curioso trabajando con equipos: los proyectos con mejor documentación no son los más lentos. Son los que sobreviven. Y con IA, la supervivencia depende de tu habilidad para traducir intuiciones en contratos técnicos claros. Claude puede ser el mejor compañero para eso —si sabes cómo pedirle las cosas.

    Esto no es un manual académico. Es un plan para usar Claude y salir del “hacer que funcione” hacia “hacer que dure”.

    Resumen rápido (lectores con prisa)

    Qué es: método para convertir intuiciones en especificaciones técnicas usando Claude.

    Cuándo usarlo: cuando las decisiones afectan contratos, seguridad o arquitectura.

    Por qué importa: reduce ambigüedad, acelera integración y baja la deuda técnica.

    Cómo funciona: estructura el prompt, define stack y límites, pide artefactos machine-readable y tests en fases.

    Guía paso a paso

    1) Empieza por el porqué, no por el cómo

    No le sueltes al modelo: “Hazme el CRUD.” Suéltale: “Esto existe porque…”

    Explica el negocio en 3–5 frases. Quién usa el producto. Qué métricas importan. Qué es un éxito y qué es un fallo. Claude necesita entender el valor antes de diseñar la estructura. Si no sabe el porqué, propondrá soluciones bonitas que no resuelven nada real.

    2) Brain dump: vacía la cabeza en orden

    Haz un volcado de contexto. Todo. Usuarios, roles, integraciones, datos sensibles, presupuestos, deadlines. Todo en bruto. Luego organízalo en secciones:

    • Objetivo del producto.
    • Requisitos no negociables.
    • Integraciones externas.
    • Restricciones de coste o tiempo.

    Si no lo pones por escrito, la IA lo “olvidará” cuando la conversación crezca. La ventana de contexto es grande, pero limitada. La spec fija el rumbo.

    3) Define límites claros: el terreno de juego

    Un LLM sin límites propone arquitectura épica. Kubernetes para un formulario. Event Sourcing para un blog. Fija el stack y las reglas: Next.js o Angular, Postgres o Mongo, monolito o microservicios. Di lo que está permitido y lo que está prohibido.

    Esto no es control por control. Es evitar decisiones peligrosas. Cuanto más concreto seas, más útiles serán las propuestas de Claude.

    4) Usa a Claude como auditor: Red Teaming

    Hazle preguntas desagradables. Pídele que rompa el diseño.

    “Si la base de datos recibe 10k req/s, ¿qué falla?”

    “¿Qué pasa si el OAuth provider devuelve 500 por 30 segundos?”

    “Describe tres formas en que esto puede ser explotado.”

    Pedir a Claude que actúe como Staff Engineer es oro. Suele encontrar cuellos de botella y escenarios que no ves en la primera pasada.

    5) Pide un Plan Técnico Estructurado (no un ensayo)

    No le pidas “un diseño”. Pide un plan accionable y dividido en entregables. Que incluya:

    • Arquitectura general (componentes y responsabilidades).
    • Modelos de datos (tablas o colecciones, relaciones).
    • Contratos de API (endpoints, métodos, payloads).
    • Reglas de seguridad y manejo de secretos.
    • Estrategia de testing y despliegue.
    • Checklist de aceptación.

    Exige formatos concretos: interfaces TypeScript, OpenAPI, diagramas Mermaid. Claude los produce con disciplina si se lo pides.

    6) Prompt maestro: estructura rígida para resultados deterministas

    Empaqueta la solicitud final con bloques semánticos. Ejemplo sencillo que Claude entiende bien:

    <contexto_negocio>
    Resumen del problema en 3–5 frases.
    </contexto_negocio>

    <stack_requerido>
    Frontend: Next.js 14. Backend: Node 20. DB: PostgreSQL 15.
    </stack_requerido>

    <restricciones>
    Monolito. No sugerir microservicios. Cumplir GDPR.
    </restricciones>

    <output_esperado>
    Markdown con: arquitectura, modelos TypeScript, OpenAPI y Mermaid.
    </output_esperado>

    Sí: usa algo parecido. Claude procesa estructura. Evita “hazme algo bueno” y usa “hazme esto exacto”.

    7) Itera en pequeños pasos: divide para conquistar

    No le pidas “termina todo en un prompt”. Divide el plan en fases:

    • Fase 1: Modelo de datos y contratos.
    • Fase 2: Endpoints principales + seguridad.
    • Fase 3: Estrategia de despliegue y observabilidad.

    Aprueba cada fase antes de avanzar. Así mantienes coherencia y controlas la complejidad.

    8) Genera pruebas desde el principio

    Pide a Claude que escriba tests de aceptación junto al contrato. Un endpoint sin test es un contrato sin firma.

    Solicita ejemplos de payloads válidos e inválidos. Solicita tests automáticos que fallen si no cumples las reglas. Así la implementación se vuelve una verificación automática del plan.

    9) Convierte la spec en artefactos machine-readable

    No dejes todo en texto. Pide:

    • OpenAPI / Swagger.
    • Esquema DB (SQL o Prisma).
    • Interfaces TypeScript.
    • Mermaid para diagramas.

    Estos artefactos alimentan la fase de implementación y reducen la ambigüedad cuando uses Copilot o agentes de coding.

    10) Añade reglas de guardia: políticas y anti-patrones

    Incluye en la spec lo que NO se debe hacer. Ejemplos útiles:

    • No exponer tokens en el frontend.
    • No usar dependencias sin CVE review.
    • Todas las APIs deben ser idempotentes.
    • Tiempo máximo de respuesta: 500ms en endpoints críticos.

    La IA responde bien a instrucciones negativas si las formulas claras.

    11) Implantación práctica: .cursorrules y SPEC.md

    Pon la spec en el repo. No escondas nada en Google Docs. Dos archivos mínimos:

    • SPEC.md: objetivo, reglas, contratos, checklist de aceptación.
    • .cursorrules (o el archivo que tu herramienta use): reglas automáticas consumibles por agentes.

    Que la spec sea la primera lectura del modelo cada vez que se genere código.

    12) Checklist de revisión para PRs generados por IA

    No es lo mismo revisar un PR humano que uno generado por IA. Usa una checklist específica:

    • ¿Respeta la spec? (sí/no)
    • ¿Hay tests que cubren casos límite?
    • ¿Se siguen convenciones de seguridad?
    • ¿Hay duplicación innecesaria de lógica?
    • ¿Los nombres reflejan la intención del dominio?

    Si falla cualquiera, rechaza y pide reescritura a la IA con referencia a la sección exacta de SPEC.md.

    13) Historias reales (sin fantasías)

    Equipo A: arrancó sin spec. 10 librerías distintas, 3 sistemas de auth, un pico y nada funcionó. Reescritura completa en 3 semanas.

    Equipo B: escribió spec en 2 días, usó Claude para generar contratos y tests. Demo en 48 horas. Integración estable en producción. ¿Qué prefieres?

    14) Cuándo no usar Claude para esto

    Claude es excelente en diseño. No lo necesitas para:

    • Tiny fixes en funciones locales.
    • Tests unitarios triviales.
    • Autocompletado en IDE (usa Copilot si quieres velocidad inline).

    Usa Claude cuando la decisión impacte contratos, seguridad o arquitectura.

    15) Plantilla mínima de SPEC.md (pégala ya)

    Pon esto en la raíz del repo. No la copies palabra por palabra sin adaptar. Pero hazlo.

    – Título y objetivo en una frase.

    – Stack aprobado (y versiones).

    – Reglas arquitectónicas innegociables (3).

    – Interfaces/contratos principales.

    – Criterios de aceptación (tests que deben pasar).

    – Política de secretos.

    – Responsables y permisos de cambio.

    Hazlo ahora. No mañana.

    16) Metáfora que pega y no falla

    La spec es la brújula. Claude es el marinero diestro. Sin brújula, el marinero navega. Rápido. Pero a la deriva. Con la brújula, llega al puerto. A salvo.

    17) Urgencia real: la deuda técnica no perdona

    Cada PR aceptado sin spec es una deuda invisible. Se acumula. Multiplica el coste de cada iteración futura. Actuar ahora es barato. Reescribir después es caro.

    CTA: hazlo en 60 minutos

    Abre el repo. Crea SPEC.md con las seis secciones mínimas que te di.

    Si quieres, te doy la plantilla lista para pegar. Respóndeme con “Quiero la plantilla” y te la envío ahora mismo.

    Esto no acaba aquí. Si quieres, te enseño:

    • Un prompt maestro listo para Claude.
    • Un SPEC.md completo para un proyecto típico (Next.js + PostgreSQL).
    • Un .cursorrules ejemplo para que la spec sea leída por agentes.

    Dime cuál quieres y te lo mando. Tus commits lo agradecerán. Y dentro de seis meses, tu equipo también.

    Si quieres recursos y experimentos prácticos sobre automatización, agentes y workflows, revisa Dominicode Labs. Es una continuación lógica para quienes aplican estas prácticas en repos reales y pipelines de integración continua.

    FAQ

    Respuesta

    Debe resumir en una frase el problema que se resuelve, los usuarios principales, y las métricas que determinan éxito o fallo. Manténlo en 2–3 líneas claras.

    Respuesta

    Usa bloques semánticos: contexto negocio, stack requerido, restricciones y output esperado. Entrega ejemplos concretos y formatos de salida (TypeScript, OpenAPI, Mermaid).

    Respuesta

    Prioriza OpenAPI, esquema de BD (SQL/Prisma) e interfaces TypeScript. Estos permiten plug-and-play con herramientas de generación y tests automáticos.

    Respuesta

    Usa Copilot para autocompletado y fixes locales. Usa Claude para diseño, contratos, análisis de riesgos y generación de artefactos estructurados que guían implementaciones.

    Respuesta

    Incluye verificación de spec, cobertura de tests (casos límite), cumplimiento de reglas de seguridad y ausencia de duplicación. Si falla cualquiera, rechaza el PR.

    Respuesta

    Añádelo al repo raíz y configura el pipeline para validar que la spec se carga antes de generar artefactos. Automatiza checks que garanticen que los agents leen .cursorrules en cada run.

  • Mejorando rendimiento y SEO al migrar de Angular a Next.js 16

    Mejorando rendimiento y SEO al migrar de Angular a Next.js 16

    De Angular a Next.js 16: lo que aprendí migrando un proyecto real

    Tiempo estimado de lectura: 4 min

    • Rendimiento y SEO fueron el motor: migramos por Core Web Vitals malos, TTFB lento y bundle que penalizaba conversión móvil.
    • Server-first cambia la mentalidad: Next.js 16 y React Server Components mueven carga y lógica al servidor, reduciendo JavaScript en cliente.
    • Menos boilerplate para mutaciones: Server Actions permiten llamar funciones server-side desde formularios sin endpoints REST intermedios.
    • Fricciones reales: cache, alcance de “use client” y observabilidad requieren disciplina adicional en producción.

    De Angular a Next.js 16: lo que aprendí migrando un proyecto real empezó como un problema de negocio: Core Web Vitals malos, TTFB lento y un bundle que penalizaba conversión móvil. La migración no fue una moda técnica; fue una necesidad para reducir fricción de usuario y mejorar SEO técnico. Esto marcó cada decisión técnica que tomamos.

    Resumen rápido (lectores con prisa)

    Qué es: Next.js 16 (App Router) usa React Server Components para renderizar HTML en servidor y enviar JavaScript mínimo al cliente.

    Cuándo usarlo: cuando SEO, Core Web Vitals o TTFB afectan métricas de negocio y necesitas ejecutar lógica sensible en servidor.

    Por qué importa: reduce bundle inicial, mejora TTFB y simplifica flujos de datos server-side.

    Cómo funciona (resumen): renderizado server-side con funciones asíncronas para fetch/ORM, Server Actions para llamadas server desde forms y control explícito de caché y revalidación.

    De Angular a Next.js 16: por qué no es solo “aprender otra sintaxis”

    Angular es un framework opinado para SPAs: inyección de dependencias, RxJS y templates declarativos. Next.js 16 (App Router) invierte ese paradigma con React Server Components (RSC): renderizado en servidor, HTML entregado al cliente y JavaScript mínimo para interactividad. Documentación oficial Next.js.

    La diferencia no es menor: pasas de pensar “qué corre en el cliente” a “qué debe correr en el servidor”. Ese cambio impacta performance, seguridad y la forma en que estructuras estado y dependencias.

    Tres lecciones técnicas que cambiaron nuestro código

    1) RxJS se queda fuera del camino principal

    En Angular, RxJS orquesta peticiones, eventos y sincronizaciones. Eso ofrece control fino (cancelaciones, operadores), pero añade complejidad de mantenimiento (unsubscribe, memory leaks).

    En Next.js 16, Server Components son funciones async: await fetch() o llamadas al ORM desde el servidor. La simplicidad reduce boilerplate y evita parpadeos de carga en el cliente. Ejemplo real: reemplazar múltiples subscriptions por una única llamada asíncrona en el server simplificó la lógica y redujo errores de sincronización.

    Nota práctica: para cancelaciones del lado del cliente hay que usar explícitamente AbortController; la ergonomía de RxJS no existe por defecto.

    2) La inyección de dependencias se reimagina

    El contenedor DI de Angular es una comodidad arquitectónica (services providedIn: 'root'). React/Next no tienen un DI integrado. Las alternativas que adoptamos:

    • Instancias únicas exportadas desde módulos ES6 (clientes DB, SDKs).
    • React Context solo para estado UI que vive en cliente (tema, sesión).
    • Props/Composición para inyección explícita en componentes que dependen de servicios.

    Resultado: más explicitud y trazabilidad, pero más disciplina para no propagar dependencias globales por accidente.

    3) Server Actions: menos endpoints, menos boilerplate

    Migrar formularios del flujo Angular (form → HttpClient → endpoint REST → backend) a Server Actions colapsó la cadena. En Next.js 16 puedes llamar funciones en el servidor directamente desde el form:

    export async function updateUser(formData: FormData) {
  'use server';
  const name = formData.get('name') as string;
  await db.user.update({ where: { id: session.userId }, data: { name } });
  revalidatePath('/profile');
}

    El beneficio es claro: menos endpoints internos y menos código repetitivo. El riesgo: mezclar lógica de negocio en componentes si no separamos responsabilidades adecuadamente. Docs de Server Actions

    Fricciones reales que te van a doler en producción

    • Cache y freshness: Next.js App Router tiene capas de caché (memoization, data cache, route cache). Sin revalidate o cache: 'no-store' puedes servir datos obsoletos. Leer.
    • “use client” propagate cost: marcar un componente como cliente arrastra su subárbol y puede romper los beneficios del SSR si importas librerías pesadas.
    • Observabilidad de comportamiento: la frontera servidor/cliente exige testing más exhaustivo (end-to-end + integración server actions) y pipelines de CI que validen rendimiento.
    • Seguridad y surface area: Server Actions facilitan lógica server-side, pero exigen revisar permisos y sanitización con más rigor.

    Criterio práctico para Tech Leads: ¿vale la pena migrar?

    No migres por moda. Migra si:

    • Tu producto es público y SEO o Core Web Vitals impactan conversiones (ver métricas en web.dev/vitals).
    • El bundle inicial y TTFB están bloqueando métricas de negocio.
    • Necesitas ejecutar lógica sensible en servidor para reducir exposición o proteger IP.

    Mantén Angular si:

    • Es un dashboard interno con poca necesidad SEO.
    • El equipo domina RxJS y la arquitectura actual es sostenible.
    • El coste de migración supera el beneficio económico esperado.

    Conclusión

    La migración De Angular a Next.js 16: lo que aprendí migrando un proyecto real fue menos una reescritura técnica y más una reorganización de responsabilidades: qué corre en el servidor, cómo se inyectan dependencias y cómo se gestionan mutaciones. Next.js 16 ofrece ganancias reales en rendimiento y simplicidad operativa, pero exige disciplina (caché, límites use client, separación de responsabilidades). Si tu negocio lo justifica, la inversión devuelve rendimiento y una arquitectura más alineada con un futuro server-first. Si no, Angular sigue siendo una opción sólida y productiva.

    FAQ

    Respuesta: Migramos porque Core Web Vitals malos, TTFB lento y un bundle grande estaban afectando conversión móvil y SEO. La migración fue una decisión de negocio para reducir fricción de usuario y mejorar SEO técnico.

    Respuesta: No hay un reemplazo directo. En Next.js 16 se usa programación asíncrona en Server Components (await fetch(), llamadas al ORM) y, para cancelaciones cliente, AbortController. La lógica de orquestación que RxJS ofrecía suele simplificarse en el servidor o con patrones de composición en cliente.

    Respuesta: Server Actions son funciones que se ejecutan en el servidor y se pueden invocar desde formularios en el cliente. Reducen la necesidad de endpoints REST intermedios. Requieren separar responsabilidades para no mezclar lógica de negocio en componentes. Más detalles.

    Respuesta: Los riesgos principales son caché y freshness (servir datos obsoletos sin revalidate), el coste de marcar componentes como cliente que arrastran subárboles pesados y la necesidad de mayor observabilidad y testing para la frontera servidor/cliente.

    Respuesta: No conviene migrar si el proyecto es un dashboard interno con poca necesidad SEO, si el equipo domina la arquitectura actual o si el coste de migración supera el beneficio económico esperado.

    Respuesta: Usar instancias únicas exportadas desde módulos ES6 (clientes DB, SDKs), React Context para estado UI cliente y props/composición para inyección explícita en componentes. Esto aporta trazabilidad a costa de disciplina para evitar dependencias globales indeseadas.

  • Cómo crear un MCP Server para integrar LLMs con seguridad

    Cómo crear un MCP Server para integrar LLMs con seguridad

    MCP servers explicados: qué son, para qué sirven y cómo crear el tuyo

    Entender los MCP servers explicados: qué son, para qué sirven y cómo crear el tuyo es importante si quieres conectar un LLM con datos y acciones de tu infraestructura sin abrir una caja negra insegura. El Model Context Protocol (MCP) busca estandarizar esa capa: separa el razonamiento del modelo de la ejecución real que hace tu código.

    Documentación y recursos oficiales:

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Un MCP Server expone Resources (solo lectura), Tools (acciones ejecutables) y Prompts (templates) para clientes LLM.
    • La comunicación puede ser por stdio (local) o SSE/HTTP (remoto) manteniendo credenciales en el servidor.
    • Empieza con capacidades de solo lectura; exige confirmación humana para escrituras peligrosas.
    • Implementa autenticación, rate limiting y auditoría con trace IDs para producción.

    Introducción

    Un MCP Server es un proceso ligero (local o remoto) que expone al cliente de IA tres tipos de capacidades bien definidas: Resources (solo lectura), Tools (acciones ejecutables) y Prompts (templates). El cliente (por ejemplo Claude Desktop, Cursor, Windsurf, o un agente en n8n) descubre esas capacidades y decide cuándo invocarlas. La comunicación suele usar stdio para ejecuciones locales o SSE/HTTP para conexiones remotas. Crucial: las credenciales y el acceso real permanecen en tu servidor; el LLM no las recibe.

    Resumen rápido (lectores con prisa)

    MCP es un protocolo para separar razonamiento (LLM) de ejecución (tu infra).

    Expone Resources (lectura), Tools (acciones) y Prompts (templates) para clientes LLM.

    Transporte: stdio local o SSE/HTTP remoto; credenciales se quedan en el servidor.

    Útil para integrar múltiples clientes LLM con una capa única, segura y versionable.

    Qué es un MCP Server

    Un MCP Server publica capacidades que los clientes LLM pueden descubrir y usar en tiempo de ejecución. Las capacidades son:

    • Resources: datos de solo lectura (esquemas, logs resumidos, métricas).
    • Tools: acciones ejecutables con entradas definidas por esquema.
    • Prompts: plantillas que combinan contextos y recursos relevantes.

    Por qué usar MCP en vez de una API ad-hoc

    • Estándar único: el mismo servidor puede trabajar con múltiples clientes LLM sin reescribir integraciones.
    • Seguridad mejorada: las credenciales no viajan en prompts.
    • Descubrimiento dinámico: el cliente lista herramientas y recursos disponibles en tiempo de ejecución.

    Arquitectura mínima de un MCP Server

    • Transporte: stdio (local) o SSE/HTTP (remoto).
    • Registro de capabilities: lista de tools/resources que el servidor publica.
    • Handlers: funciones que ejecutan las herramientas y devuelven contenido estructurado.
    • Logging/auditoría: registros de llamadas, inputs y outputs con firma/trace-id.

    Ejemplo práctico (Node.js + TypeScript)

    Instalación y preparación

    mkdir mi-mcp-server && cd mi-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node
npx tsc --init

    Ejemplo mínimo: src/index.ts

    import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import os from "os";

const server = new Server({name:"mi-mcp", version:"0.1.0"}, {capabilities:{tools:{}}});

server.setRequestHandler(ListToolsRequestSchema, async ()=>({
  tools: [{ name: "get_system_info", description: "Info SO y memoria", inputSchema: { type: "object", properties: {}, required: [] } }]
}));

server.setRequestHandler(CallToolRequestSchema, async (req)=>{
  if (req.params.name === "get_system_info") {
    return { content: [{ type:"text", text: JSON.stringify({ platform: os.platform(), totalMemory: os.totalmem() }, null, 2) }] };
  }
  throw new Error("tool-not-found");
});

await server.connect(new StdioServerTransport());
console.error("MCP server listo");

    Compila con npx tsc y ejecuta node dist/index.js. Para clientes como Claude Desktop registra el comando en su config (paths en macOS/Windows según documentación del cliente).

    Qué exponer (y qué no)

    Empieza por recursos de solo lectura y herramientas inofensivas:

    • Recursos: esquemas de DB, logs resumidos, métricas con paginación.
    • Tools (lectura): consultas parametrizadas que devuelven resultados limitados.
    • Prompts: plantillas que pre-cargan recursos relevantes.

    Evita al principio: comandos de escritura (DROP, DELETE), accesos de shell indiscriminados, o cualquier endpoint que pueda cambiar estado sin confirmación humana. Implementa siempre un flujo de validación humana para acciones críticas.

    Producción: seguridad y operativa

    • Autenticación y autorización: el servidor debe gestionar credenciales y validar cada petición con roles.
    • Rate limiting y cuotas: evita que un prompt malicioso dispare herramientas repetidamente.
    • Auditoría inmutable: registra request/response con trace IDs, timestamps y hashes del prompt.
    • Testing: mocks para tools y tests end-to-end con clientes (stdio y SSE).
    • Paginación y resumido: no envíes logs enteros; ofrece ventanas y resúmenes para preservar tokens.

    Casos de uso reales y prácticas recomendadas

    • Integración con n8n: usa el MCP Server como puente para disparar workflows desde lenguaje natural sin exponer credenciales a la interfaz.
    • Revisión de PRs automatizada: expón diffs y reglas como recursos; la tool devuelve checklist y reportes en Markdown.
    • Soporte operador: diagnóstico de infra mediante logs resumidos y herramientas read-only que recogen métricas.

    Registra y versiona tus prompts y esquemas del MCP en el repo; trátalos como código crítico.

    Conclusión

    Los MCP servers explicados aquí son la pieza que convierte LLMs en componentes confiables dentro de una plataforma técnica. No es magia: es disciplina. Empieza pequeño (solo lectura), instrumenta todo, exige confirmación humana para escrituras y versiona los prompts. Si lo haces bien, tendrás agentes que razonan con seguridad y una única capa mantenible que conecta IA con tus sistemas.

    Mención: Dominicode Labs

    Para equipos que exploran automatización y agentes como parte de su plataforma técnica, puede ser útil revisar trabajos y prototipos en Dominicode Labs. Es una referencia contextual para enfoques de integración y experimentación práctica.

    FAQ

    ¿Qué diferencia a un MCP Server de una API tradicional?

    Un MCP Server define un estándar para que clientes LLM descubran y llamen capacidades (Resources, Tools, Prompts). Mantiene credenciales y lógica de ejecución en el servidor, evitando que se incrusten en prompts como suele pasar con APIs ad-hoc.

    ¿Cómo se comunican el cliente LLM y el MCP Server?

    La comunicación común es por stdio para ejecuciones locales o mediante SSE/HTTP para conexiones remotas. El cliente consulta las capabilities y llama handlers definidos por el servidor.

    ¿Qué precauciones de seguridad debo implementar?

    Implementa autenticación y autorización por roles, rate limiting, auditoría inmutable con trace IDs y validation humana para acciones que modifican estado.

    ¿Puedo exponer herramientas de escritura si las requisito?

    Sí, pero siempre detrás de controles estrictos: confirmación humana, autorización granular, pruebas y registros completos. Evita exponer inicialmente comandos destructivos.

    ¿Cómo se versionan prompts y esquemas?

    Registra y versiona prompts y esquemas en el repositorio del proyecto como parte del código crítico; aplica revisiones, pruebas y despliegues controlados.

    ¿Qué formatos de respuesta soportan las tools?

    Las tools devuelven contenido estructurado (por ejemplo objetos JSON con bloques de tipo texto o markdown). El SDK y el spec del MCP describen los schemas esperados.

    ¿Cuál es el transporte recomendado para producción?

    Para local, stdio es simple y seguro. Para entornos distribuidos, SSE/HTTP ofrece mayor flexibilidad; la elección depende de latencia, despliegue y requisitos de auditoría.

  • Cómo Context Engineering Mejora el Uso de IA en Proyectos Técnicos

    Cómo Context Engineering Mejora el Uso de IA en Proyectos Técnicos

    Context Engineering: el skill que separa a quien usa IA de quien la domina — Diferenciar prompt engineering de context engineering, con ejemplos prácticos en proyectos reales

    Context Engineering: el skill que separa a quien usa IA de quien la domina — Diferenciar prompt engineering de context engineering, con ejemplos prácticos en proyectos reales aparece en la primera línea porque esto no es semántica fina: si quieres resultados reproducibles con LLMs, primero dominas el contexto que les das.

    Resumen rápido (lectores con prisa)

    Qué es: Context engineering diseña pipelines que recuperan, filtran, reordenan y entregan exactamente la información que un LLM necesita. Cuándo usarlo: cuando buscas respuestas reproducibles y verificables de modelos. Por qué importa: reduce ruido y evita que el modelo «adivine». Cómo funciona (resumen): chunking semántico, RAG híbrido, re-ranking y trazabilidad del contexto.

    Los modelos no fallan por malos prompts. Fallan porque les lanzas una montaña de información sin estructura y esperan sentido. El paper “Lost in the Middle” documenta por qué contextos enormes con baja señal degradan la precisión: https://arxiv.org/abs/2307.03172.

    Context Engineering: qué es y por qué importa

    Prompt engineering modela la instrucción: rol, formato, few-shot. Es importante, pero es la punta del iceberg.

    Context engineering diseña pipelines que recuperan, filtran, reordenan y entregan exactamente la información que el modelo necesita. Es infraestructura. Es código. Es la diferencia entre un agente que improvisa y uno que actúa con datos verificables.

    Herramientas y lecturas útiles:

    Principios técnicos fundamentales

    • Chunking semántico: corta por límites lógicos (funciones, clases, secciones), no por número de caracteres. Un fragmento coherente = menos ambigüedad.
    • Recuperación híbrida (RAG avanzado): combina búsqueda vectorial con BM25 y filtrado por metadatos. Cada técnica cubre puntos ciegos de la otra.
    • Re-ranking con Cross-Encoders: recupera amplio, reordena preciso. El orden que lee el LLM importa.
    • Grafos de dependencia: extrae import graph para entregar solo archivos que dependen directamente del cambio que quieres hacer.
    • Instrumentación del contexto: registra qué se inyectó, tokens consumidos y rank scores para auditar decisiones.

    Ejemplo 1 — Refactorización en un monorepo TypeScript

    Problema frecuente: cambias la firma de un endpoint y esperas que el asistente actualice todo el frontend y backend.

    Enfoque ingenuo (solo prompt)

    Copias controladores y componentes al chat. Resultado: el modelo inventa imports, omite tipos compartidos y el build falla.

    Enfoque Context Engineering (profesional)

    1) Ejecuta análisis estático con ast-grep para localizar los nodos AST que llaman al endpoint.

    2) Genera un paquete de contexto pequeño: OpenAPI actualizado, la interfaz TypeScript compartida y los snippets AST afectados.

    3) Re-ranquea los fragmentos por relevancia y adjunta tests unitarios mínimos.

    Resultado: PR atómico, compilable y con pruebas que pasan. El LLM actúa sobre lo esencial, no sobre ruido.

    Ejemplo 2 — Agente L2 en n8n que realmente resuelve incidencias

    Problema: un bot en Slack contesta “reinicia” porque carece del estado real del sistema.

    Enfoque ingenuo

    Enviar error text y prompt extenso. Respuestas genéricas.

    Enfoque Context Engineering

    Antes de llamar al LLM, el workflow hace:

    • Query a Datadog/Grafana para obtener los últimos N logs (filtrados por servicio y correlación)
    • Query SQL read-only para validar estado de cuenta/recursos del usuario
    • Búsqueda semántica en documentación interna y re-ranking para extraer la resolución exacta

    El LLM recibe un JSON estructurado con logs, estado y docs. No adivina; redacta una intervención operativa reproducible. En n8n esto se modela como nodos previos que transforman y sanitizan el contexto.

    Guía práctica: checklist para construir pipelines de contexto

    • Define señal mínima: ¿qué datos hacen que la respuesta deje de ser una suposición?
    • Implementa chunking por semántica, no por longitud.
    • Usa RAG híbrido: vector search + BM25 + metadatos.
    • Añade re-ranking con Cross-Encoders para ordenar resultados.
    • Instrumenta: guarda el contexto inyectado (hashes), tokens consumidos y scores.
    • Limita permisos y sanitiza PII antes de inyectar datos sensibles.
    • Versiona specs y pipelines; trátalos como código crítico.

    Riesgos y consideraciones operativas

    • Costo de tokens y latencia: curar contexto reduce tokens inútiles, pero re-ranking y cross-encoders añaden coste computacional.
    • Seguridad y privacidad: nunca inyectes credenciales ni expongas PII sin enmascaramiento. Diseña roles y auditable human-in-the-loop para acciones críticas.
    • Overfitting de contexto: si tu re-ranker prioriza siempre el mismo fragmento, podrías ignorar cambios recientes. Mantén ventanas temporales y freshness rules.

    Conclusión técnica

    Context Engineering no es un nicety; es la capa que convierte IA probabilística en un componente reproducible de tu stack. Los equipos que ganan no son los que escriben mejores prompts; son los que construyen pipelines que entregan al modelo exactamente la señal que necesita, en el formato correcto y con trazabilidad. Eso es lo que separa a quien usa IA de quien la domina.

    Para equipos que trabajan con automatización, agentes, n8n o workflows, explorar prácticas y experimentos adicionales puede acelerar la adopción segura y reproducible. Más recursos y pruebas de concepto están disponibles en Dominicode Labs.

    Tabla de contenidos

    FAQ

    ¿Qué diferencia a prompt engineering de context engineering?

    Prompt engineering diseña la instrucción y el formato de la interacción. Context engineering construye la infraestructura y pipelines que entregan al modelo la información relevante, limpia y ordenada para que esa instrucción produzca resultados reproducibles.

    ¿Cuándo debo priorizar construir pipelines de contexto?

    Cuando las respuestas del modelo necesitan ser verificables, reproducibles o accionables en producción—por ejemplo, cambios de código a gran escala, acciones operativas automatizadas o workflows de soporte.

    ¿Qué es chunking semántico y por qué es importante?

    Es dividir el contenido por límites lógicos (funciones, clases, secciones) en lugar de por caracteres. Reduce ambigüedad y mejora la relevancia de la información entregada al modelo.

    ¿Cómo se integra RAG híbrido en un flujo de trabajo existente?

    Combina búsqueda vectorial para semántica con BM25 para coincidencias léxicas y aplica filtros por metadatos. Recupera amplio, luego re-ranquea con Cross-Encoders para entregar la mejor señal al LLM.

    ¿Qué métricas debo instrumentar para auditar el contexto?

    Guarda hashes del contexto inyectado, tokens consumidos por llamada, scores de recuperación y re-ranking, y un registro de versiones de specs y pipelines.

    ¿Cómo mitigo riesgos de privacidad al inyectar contexto?

    Sanitiza y enmascara PII, limita permisos para queries y usa pipelines read-only para datos sensibles. Diseña revisiones humanas para acciones críticas.

    Tiempo estimado de lectura: 5 min