Tag: Context Engineering

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

• Claude / Anthropic docs
• Cursor
• n8n (orquestación de workflows)
• LangChain (RAG & retrievers)
• Prisma
• OpenAPI Spec
• Vercel AI SDK

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?
• ¿Cuándo debo usar CLAUDE.md?
• ¿Para qué sirve AGENTS.md?
• ¿Qué contienen los memory files y quién los actualiza?
• ¿Por qué usar sub-agentes en lugar de un mega-agente?
• ¿Qué es RAG y por qué es relevante aquí?
• ¿Cómo auditar ejecuciones de sub-agentes?

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:

• ast-grep (análisis AST recomendado)
• LangSmith (observabilidad de prompts/contextos)
• Weights & Biases (tracking de experimentos)

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

• Resumen rápido (lectores con prisa)
• Context Engineering: qué es y por qué importa
• Principios técnicos fundamentales
• Ejemplo 1 — Refactorización en un monorepo TypeScript
  • Enfoque ingenuo
  • Enfoque Context Engineering (profesional)
• Ejemplo 2 — Agente L2 en n8n que realmente resuelve incidencias
  • Enfoque ingenuo
  • Enfoque Context Engineering
• Guía práctica: checklist para construir pipelines de contexto
• Riesgos y consideraciones operativas
• Conclusión técnica
• FAQ

FAQ

• ¿Qué diferencia a prompt engineering de context engineering?
• ¿Cuándo debo priorizar construir pipelines de contexto?
• ¿Qué es chunking semántico y por qué es importante?
• ¿Cómo se integra RAG híbrido en un flujo de trabajo existente?
• ¿Qué métricas debo instrumentar para auditar el contexto?
• ¿Cómo mitigo riesgos de privacidad al inyectar contexto?

Tiempo estimado de lectura: 5 min