Guía de especificación

Un complemento práctico a los Estándares de Ejecución. Los estándares definen las capas y primitivas. Esta guía muestra cómo usarlas.

¿Cuándo necesitas una spec?

No toda interacción con IA requiere una especificación formal. Usa este árbol de decisión:

Usa un prompt cuando:

La tarea es un solo paso con criterios de éxito obvios
Evaluarás el resultado inmediatamente
El fallo no cuesta nada (puedes simplemente volver a hacer el prompt)

Usa un prompt + archivo de contexto cuando:

La tarea requiere conocimiento del dominio (terminología, voz de marca, restricciones técnicas)
Ya has hecho este tipo de tarea antes y la calidad importa
El resultado será usado por otros

Usa una especificación completa cuando:

La tarea tiene múltiples pasos o dependencias
Múltiples personas o agentes trabajarán en partes de ella
El fallo es costoso (código de producción, resultado orientado al cliente, acciones irreversibles)
Necesitas que alguien más verifique el resultado sin hacerte preguntas
La tarea se repetirá y debe producir resultados consistentes

El umbral no es la complejidad – es el costo del fallo. Una tarea simple con altas apuestas necesita una spec. Una tarea compleja con cero apuestas puede empezar con un prompt.

Escribir una spec lleva tiempo. Pero la investigación muestra que se paga sola: enriquecer un enunciado del problema antes de que un agente comience el trabajo produce una mejora del 20% en las tasas de resolución, y los agentes más débiles ven las mayores ganancias. Es más barato mejorar la spec que mejorar el agente.

Las cuatro capas en la práctica

Los Estándares definen cuatro capas obligatorias. Estas capas forman una progresión de madurez acumulativa – cada nivel construye sobre el anterior. Aquí está cómo se ve cada una cuando se hace bien.

Capa 1 – Diseño de prompts

La base. Estás escribiendo una instrucción clara.

Parece razonable pero tiene lagunas:

Escribe una secuencia de 3 emails de incorporación para usuarios de prueba que aún no se han activado. Hazlo amigable y útil. Incluye CTAs.

Mejor – lo suficientemente específico para verificar:

Escribe una secuencia de 3 emails de nutrición para usuarios de prueba que se registraron pero no completaron la incorporación en 7 días. Objetivo: lograr que completen su primer proyecto. Tono: útil, no agresivo. Cada email debe tener menos de 100 palabras con un CTA claro. Email 1 (día 3): destaca la manera más fácil de empezar. Email 2 (día 5): comparte una plantilla que puedan personalizar. Email 3 (día 7): ofrece una llamada de incorporación de 15 minutos. Los asuntos deben ser conversacionales, no promocionales.

El primer prompt se siente completo pero deja preguntas críticas abiertas: ¿qué significa "activado"? ¿Cuántos emails? ¿De qué longitud? ¿A qué apunta el CTA? El agente llenará esas lagunas con suposiciones – y las suposiciones son donde se rompe la calidad.

La regla del ≤20% de corrección: Si consistentemente necesitas corregir más del 20% del resultado de la IA, el problema está en tu prompt, no en el modelo. Invierte en la instrucción, no en editar el resultado.

Capa 2 – Ingeniería de contexto

El contexto es todo lo que el agente necesita saber que no está en el prompt. Andrej Karpathy define la ingeniería de contexto como "el delicado arte y ciencia de llenar la ventana de contexto con exactamente la información correcta para el siguiente paso."

La pregunta clave no es "¿qué podría ser relevante?" – es "¿qué necesita ver el agente ahora mismo?" Más contexto no es mejor contexto. La investigación muestra que los modelos alcanzan muros de rendimiento cuando se sobrecargan con información, independientemente del tamaño de la ventana de contexto.

Cinco criterios de calidad (Vishnyakova, 2026):

Relevante – solo lo necesario para el paso actual. Los datos irrelevantes empeoran activamente el resultado.
Suficiente – todo lo necesario para tomar una decisión sin adivinar. El contexto faltante es la causa arquitectónica principal de las alucinaciones.
Aislado – cada paso o subagente ve solo su propio contexto. Compartir todo provoca fallos compuestos (ver Modos de fallo del contexto).
Económico – tokens mínimos preservando la calidad. Anthropic lo enmarca como encontrar "el conjunto más pequeño posible de tokens de alta señal."
Trazable – cada pieza de contexto atribuible a una fuente. Cuando algo sale mal, necesitas saber qué entrada lo causó.

Un archivo de contexto de equipo no es un volcado cerebral. Es un conjunto curado de hechos que el agente necesita para tareas recurrentes. Mantenlo conciso y solo con advertencias – se carga en cada sesión, por lo que cada línea debe ser universalmente aplicable.

# Contexto del Equipo de Atención al Cliente

## Objetivos
- Retener a los clientes existentes (retención > adquisición)
- Reducir el tiempo de resolución para los tickets de soporte
- Identificar oportunidades de expansión en cuentas existentes

## Restricciones
- Nunca compartir datos de clientes entre cuentas
- Nunca prometer funcionalidades que no estén lanzadas
- Escalar disputas de facturación superiores a $500 a un gestor
- SLA de tiempo de respuesta: primera respuesta en 4 horas

## Terminología
- "Partner" = cuenta de revendedor (no un cliente regular)
- "White-label" = versión de la plataforma con marca del cliente
- "Link branding" = dominio personalizado para links de seguimiento

## Estándares de calidad
- Las respuestas deben abordar la pregunta específica, no FAQs genéricas
- Incluir próximos pasos en cada respuesta
- Si hay incertidumbre, decirlo – no adivinar

Just-in-time vs. anticipado: No cargues todo de antemano. Usa una estrategia híbrida – carga siempre el archivo de contexto del equipo y la terminología; carga datos específicos (registros de clientes, historial de tickets, documentación) bajo demanda. El agente debe saber dónde encontrar la información, no memorizarla toda.

Para un tratamiento más profundo de la ingeniería de contexto, ver la guía de Anthropic Effective Context Engineering for AI Agents.

Capa 3 – Ingeniería de intención

La intención responde: "¿Qué debe optimizar el agente, y qué compensaciones puede hacer?"

Sin intención explícita, los agentes optimizan la métrica más medible disponible – que rara vez es lo que realmente quieres. El caso de estudio de Klarna lo ilustra: su agente de IA manejó dos tercios de las consultas de clientes y ahorró $60M, pero el CEO reconoció públicamente que la calidad había sufrido porque el agente optimizó el costo por token, no el valor de las relaciones con los clientes. Como dice un investigador: "El contexto sin intención es ruido."

Intención para un flujo de trabajo de soporte:

## Jerarquía de objetivos (en orden de prioridad)
1. Exactitud – nunca dar información incorrecta
2. Resolución – resolver el problema real del cliente,
   no solo responder su pregunta
3. Tono – coincidir con la voz de marca (amigable, competente)
4. Eficiencia – mantener las respuestas concisas

## Reglas de compensación
- Exactitud vs velocidad → elegir exactitud
- Tono vs eficiencia → mantenerlo cálido, incluso si es más largo
- Incertidumbre sobre una respuesta técnica → decirlo,
  no adivinar

## Condiciones de escalación
- El cliente menciona acciones legales → inmediatamente
- Disputa de facturación superior a $500 → gestor
- Problema técnico que afecta a múltiples clientes
  → ingeniería
- La misma pregunta hecha tres veces → soporte senior

## Autoridad de decisión
Puede: redactar respuestas, consultar detalles de cuentas,
  citar la base de conocimiento
No debe: prometer reembolsos, compartir datos de otros clientes,
  comprometerse con funcionalidades futuras

Intención para un flujo de trabajo de ingeniería:

## Jerarquía de objetivos (en orden de prioridad)
1. Corrección – el código debe pasar todas las pruebas existentes
2. Mantenibilidad – legible por un desarrollador no familiarizado
   con el código base
3. Rendimiento – cumplir los requisitos de SLA
4. Simplicidad – preferir menos líneas sobre la abstracción

## Reglas de compensación
- Corrección vs velocidad → elegir corrección
- Mantenibilidad vs rendimiento → favorecer la legibilidad
  a menos que el SLA esté en riesgo
- Cuando múltiples enfoques son válidos → elegir el que
  tenga menos acoplamiento con otros módulos

## Condiciones de escalación
- El cambio requiere modificar una API pública → escalar
- El impacto en el rendimiento supera el 10% en rutas críticas
  → escalar
- La solución requiere una migración de base de datos → escalar

## Autoridad de decisión
Puede: refactorizar dentro del alcance de la tarea,
  añadir funciones auxiliares, actualizar pruebas relacionadas
No debe: cambiar APIs públicas, modificar código no relacionado,
  omitir cobertura de pruebas

Capa 4 – Ingeniería de especificaciones

Una especificación es un conjunto de instrucciones completo y autocontenido para una tarea no trivial. Incluye todo lo que el agente necesita y nada de lo que no necesita.

Los siete componentes requeridos (de los Estándares):

Enunciado del problema – qué necesita ocurrir y por qué
Alcance – qué está incluido y explícitamente qué no
Entradas – a qué tiene acceso el agente
Restricciones – las categorías Debe / No Debe / Prefiere / Escalar
Criterios de aceptación – cómo verificar que el resultado es correcto (cómo se ve "listo", objetivamente)
Condiciones de fallo – qué cuenta como un intento fallido
Pruebas de éxito – escenarios específicos que el resultado debe manejar

Las cinco primitivas con ejemplos

Primitiva 1 – Declaraciones de problema autocontenidas

La prueba: ¿podría alguien sin contexto sobre tu proyecto ejecutar esta tarea usando solo lo que está escrito?

Parece completo pero no lo está:

El programador de tareas es demasiado lento para lotes grandes. Arregla el sistema de prioridades para que los trabajos pequeños no queden atrapados detrás de los grandes. Usa BullMQ.

Autocontenido:

El programador de tareas (src/jobs/queue.ts) procesa tareas secuencialmente. Los trabajos grandes (50K+ elementos) bloquean los trabajos más pequeños en la cola – los usuarios con trabajos pequeños esperan más de 30 minutos para que comience el procesamiento. La corrección debe añadir programación basada en prioridades: los trabajos con menos de 5K elementos obtienen mayor prioridad. La configuración del limitador de velocidad (100 req/s) no debe cambiar. Se debe usar la función de prioridad existente de BullMQ si es posible. Si la solución requiere cambiar el esquema de trabajo, escalar antes de implementar.

La primera versión suena accionable pero oculta preguntas: ¿qué archivo? ¿Qué significa "demasiado lento" en números? ¿Cuáles son las restricciones? El agente hará suposiciones sobre todo esto – y pueden ser incorrectas.

La investigación sobre agentes de codificación confirma esto: proporcionar contexto arquitectónico, dependencias entre archivos y pistas de exploración de antemano evita que los agentes desperdicien pasos en la exploración desenfocada del repositorio.

Versión de marketing – parece completo pero no lo está:

Crea una campaña de email drip para usuarios de prueba que no han convertido. Enfócate en mostrar el valor del producto. 3 emails, tono amigable, con CTAs.

Autocontenido:

La conversión de prueba a pago es del 12%. El benchmark de la industria es del 18%. Los usuarios que completan la incorporación en 72 horas convierten al 31%. Diseña una secuencia de 3 emails activada cuando un usuario de prueba no ha completado su primer proyecto en el día 3. Objetivo: lograr que completen la incorporación. Cada email con menos de 100 palabras, un CTA por email, funciona en ES y EN. Sin menciones de precios, sin tácticas de urgencia.

La primera versión produciría una campaña drip genérica. La segunda le da al agente el contexto de negocio (por qué importa) y las restricciones (qué evitar) que producen un resultado dirigido.

Primitiva 2 – Criterios de aceptación

Escribe tres oraciones que permitan a alguien más verificar el resultado sin hacerte preguntas.

Se siente verificable pero no lo es:

El dashboard debe mostrar con precisión las métricas clave y cargar rápidamente en todos los navegadores.

Realmente verificable:

El dashboard muestra MRR, tasa de abandono y usuarios activos para el rango de fechas seleccionado. El MRR coincide con el número del equipo de finanzas dentro de $100. La página carga en menos de 2 segundos en una conexión estándar. Los gráficos se muestran sin errores en Chrome y Firefox.

La primera versión usa palabras que se sienten precisas ("con precisión", "rápidamente", "todos los navegadores") pero que nadie puede verificar sin hacer preguntas de seguimiento. La segunda define números específicos, métricas específicas y navegadores específicos.

Primitiva 3 – Arquitectura de restricciones

Cuatro categorías. Completa las cuatro para cada tarea no trivial.

Ejemplo: Sistema de respuesta automática a tickets de soporte

Categoría	Reglas
Debe	Dirigirse al cliente por su nombre. Referenciar su problema específico. Incluir un próximo paso.
No debe	Nunca compartir credenciales o detalles internos del sistema. Nunca prometer un tiempo de resolución específico. Nunca cerrar automáticamente un ticket.
Prefiere	Enlazar a artículos relevantes de la base de conocimiento cuando existan. Usar el idioma del cliente según la configuración de su cuenta. Mantener las respuestas en menos de 200 palabras.
Escalar	El cliente menciona cancelación. El problema involucra pérdida de datos. El mismo problema reportado 3+ veces en 24 horas. El cliente tiene un plan empresarial.

Primitiva 4 – Descomposición

Divide las tareas en piezas independientes con entradas y salidas claras. Objetivo: subtareas que tomen ≤2 horas y puedan verificarse por sí solas.

Parece descompuesto pero todavía está acoplado:

Diseñar el modelo de datos y construir la API
Construir el frontend que usa la API
Escribir pruebas y desplegar

Realmente independiente:

Paso	Entrada	Salida	Verificación
1. Migración de esquema	Esquema actual + documento de requisitos	Archivo de migración + archivo de reversión	La migración se ejecuta hacia adelante y hacia atrás sin errores
2. Endpoint de API	Migración + spec de API	Manejador de ruta con validación	Los 5 casos de prueba pasan, devuelve los códigos de estado correctos
3. Formulario frontend	Spec de API + mockup de diseño	Componente React con validación de formulario	El formulario se envía correctamente, los errores de validación se muestran correctamente
4. Prueba de integración	Los tres anteriores	Prueba de extremo a extremo	El usuario puede completar el flujo completo en staging

La primera versión tiene dependencias ocultas (el paso 1 combina dos preocupaciones, el paso 2 no puede comenzar hasta que el paso 1 esté completamente listo, el paso 3 combina pruebas con despliegue). La segunda versión tiene entradas, salidas y verificación claras en cada paso. Anthropic recomienda este patrón orquestador-trabajadores para tareas de múltiples componentes.

Primitiva 5 – Diseño de evaluación

Construye 3-5 casos de prueba con resultados conocidos como buenos. Ejecútalos después de cada cambio.

Ejemplo: Generador de líneas de asunto para emails

Caso de prueba	Entrada	Características esperadas del resultado
1. Email de bienvenida	Nuevo usuario, se registró hoy, nombre: María	Contiene el nombre del usuario. Menos de 50 caracteres. Sin palabras que activen filtros de spam.
2. Reactivación	Usuario inactivo 30 días	Referencia un período de tiempo específico o su última actividad. Genera curiosidad. No induce culpa.
3. Anuncio de funcionalidad	Nueva función del editor, todos los usuarios	Destaca el beneficio, no el nombre de la función. Sin jerga técnica.
4. Localización en español	Igual que #1 pero configuración regional del usuario es ES	Español gramaticalmente correcto. No es una traducción palabra por palabra.
5. Caso extremo: sin nombre	El usuario no tiene nombre de pila registrado	No dice "Hola null" o "Hola ". Usa un saludo genérico.

No pruebas el resultado exacto (la IA es no determinista). Pruebas las características del resultado. Esto es evaluación, no pruebas unitarias. Anthropic recomienda combinar cada prompt de evaluación con resultados verificables y rastrear precisión, tiempo de ejecución y tasas de error a lo largo del tiempo.

Modos de fallo del contexto

Cuando el resultado de la IA sale mal, diagnostica qué fallo de contexto lo causó antes de reintentar. Estos cuatro modos de fallo están bien documentados en la literatura de ingeniería de contexto:

Envenenamiento

Un error entra en el contexto y se compone a través de los turnos. El agente alucinó un nombre de función en el paso 2, y luego sigue llamando a esa función inexistente en los pasos 3-5.

Corrección: Limpia el contexto entre pasos. No dejes que las salidas de herramientas de pasos tempranos persistan profundamente en la conversación. Resume en los límites en lugar de arrastrar el historial sin procesar.

Distracción

El contexto es tan largo que el agente repite patrones del historial en lugar de razonar sobre el paso actual. La investigación ha observado esta degradación después de superar los 100K tokens.

Corrección: Comprime o resume el contexto anterior. Cuando la conversación se alarga, crea una nueva sesión con un resumen de las decisiones tomadas hasta ahora.

Confusión

Demasiadas herramientas o demasiada documentación en el contexto. El agente elige la herramienta incorrecta o cita documentación irrelevante porque no puede distinguir qué es relevante.

Corrección: Reduce lo que se carga. Solo expone herramientas y documentos relevantes para la tarea actual. Como dice Anthropic: "Si un humano no puede elegir definitivamente la herramienta correcta, un agente no puede hacerlo mejor."

Conflicto

Información contradictoria en el contexto. La guía de estilo dice "sé conciso" pero la plantilla dice "incluye una explicación detallada". Un estudio de Microsoft/Salesforce mostró una caída del 39% en la calidad cuando había información contradictoria presente.

Corrección: Audita tu contexto en busca de contradicciones. Al actualizar los archivos de contexto, elimina la orientación antigua – no solo añadas nueva orientación junto a ella. Una fuente de verdad por tema.

Escribir specs para diferentes roles

Spec de ingeniería

## Problema
El programador de tareas procesa tareas secuencialmente. Los trabajos
grandes (50K+ elementos) bloquean los trabajos más pequeños en la cola.
Los usuarios con trabajos pequeños esperan más de 30 minutos para que
comience el procesamiento.

## Alcance
- Modificar la cola de trabajos para soportar programación basada en prioridades
- Los trabajos pequeños (< 5K elementos) obtienen mayor prioridad
- NO cambiar los límites de velocidad de procesamiento ni el
  pipeline de renderizado

## Entradas
- Implementación de la cola de trabajos: src/jobs/queue.ts
- Modelo de trabajo: src/models/job.ts
- Pruebas actuales: src/jobs/__tests__/queue.test.ts

## Restricciones
- Debe: mantener el orden FIFO dentro del mismo nivel de prioridad
- Debe: procesar todos los trabajos dentro de los límites de velocidad existentes
- No debe: eliminar ni reordenar trabajos ya en progreso
- No debe: requerir una migración de base de datos
- Prefiere: usar la función de prioridad existente de BullMQ
- Escalar: si la solución requiere cambiar el esquema de trabajo

## Criterios de aceptación
1. Un trabajo de 1K elementos en cola después de un trabajo de 100K comienza
   a procesarse en 5 minutos, no en 30+
2. Ningún trabajo se queda sin procesar – todos los trabajos se completan
   dentro del doble de su duración esperada
3. Las pruebas existentes pasan sin modificación
4. Las nuevas pruebas cubren el ordenamiento por prioridad y
   la prevención del hambre

## Condiciones de fallo
- Cualquier trabajo procesado con entradas incorrectas
- Cualquier trabajo procesado dos veces
- Interbloqueo de la cola bajo envíos concurrentes

## Pruebas de éxito
1. Poner en cola 3 trabajos: 100K, 1K, 500. Verificar que 1K y 500
   comiencen antes de que se complete el de 100K.
2. Poner en cola 20 trabajos pequeños y 1 grande. Verificar que todos se completen.
3. Enviar trabajos concurrentemente desde 3 clientes de API.
   Verificar que no haya duplicados ni trabajos perdidos.

Spec de marketing

## Problema
La conversión de prueba a pago es del 12%. El benchmark de la industria
es del 18%. Los usuarios que completan la incorporación en 72 horas
convierten al 31%. La mayoría de los usuarios de prueba nunca completan
la incorporación.

## Alcance
Diseñar una secuencia de 3 emails de incorporación activada cuando un
usuario de prueba no ha completado su primer proyecto en el día 3.
Objetivo: lograr que completen la incorporación. Esto es solo el
contenido del email – el disparador de automatización ya existe.

## Entradas
- Email de bienvenida actual (adjunto)
- Las 3 plantillas más usadas por uso (adjuntas)
- Guía de voz de marca: amigable, competente, nunca corporativa
- Producto: editor visual, biblioteca de plantillas, gestión de proyectos

## Restricciones
- Debe: cada email con menos de 100 palabras
- Debe: un CTA claro por email
- Debe: funcionar en ES y EN
- No debe: mencionar precios o limitaciones del plan
- No debe: usar tácticas de urgencia ("¡tu prueba expira!")
- Prefiere: mostrar, no decir (enlazar a una plantilla, no a
  una lista de funciones)
- Escalar: si la secuencia necesita más de 3 emails

## Criterios de aceptación
1. Cada email tiene exactamente un CTA que enlaza a una acción específica
   en el producto
2. El tono coincide con la guía de voz de marca
3. Ningún email supera las 100 palabras
4. Los asuntos tienen menos de 50 caracteres
5. Un no-cliente puede entender la propuesta de valor sin conocimiento
   previo del producto

## Condiciones de fallo
- Cualquier email supera las 100 palabras
- El CTA enlaza a una página genérica en lugar de una acción específica
- Aparece lenguaje de urgencia ("tiempo limitado", "expira",
  "última oportunidad")
- La versión en español es una traducción literal en lugar de prosa natural

## Pruebas de éxito
1. Leer el email 1 sin contexto previo. ¿Puedes identificar qué hace el
   producto y qué acción tomar? (sí/no)
2. Leer los 3 en secuencia. ¿La progresión se siente natural, no
   repetitiva? (sí/no)
3. Las versiones en español se leen de forma natural, no como traducciones.
   (verificado por hablante nativo)

Spec de soporte

## Problema
El tiempo de respuesta de soporte promedia 6 horas. El 40% de los tickets
son preguntas ya respondidas en la base de conocimiento. Los agentes
pasan tiempo buscando respuestas que ya existen.

## Alcance
Construir un sistema de respuesta borrador asistida por IA. Cuando llega
un ticket, el sistema busca en la base de conocimiento y redacta una
respuesta para que el agente de soporte la revise y envíe. El agente
siempre revisa antes de enviar – sin respuestas automáticas.

## Entradas
- Artículos de la base de conocimiento (~200 artículos)
- Historial de tickets (últimos 90 días, anonimizado)
- Datos de cuenta del cliente (tipo de plan, antigüedad, actividad reciente)
- Plantillas de respuesta predefinidas (32 plantillas)

## Restricciones
- Debe: un humano revisa cada respuesta antes de enviar
- Debe: citar el artículo de la base de conocimiento utilizado
- Debe: señalar cuando no existe un artículo relevante
  (señal para crear uno)
- No debe: acceder a datos de clientes de otras cuentas
- No debe: prometer tiempos de resolución
- No debe: cerrar tickets automáticamente
- Prefiere: coincidir con el idioma del cliente
- Prefiere: mantener los borradores en menos de 200 palabras
- Escalar: disputas de facturación superiores a $500, menciones de
  cancelación, problemas de pérdida de datos

## Criterios de aceptación
1. Los borradores se generan en 30 segundos tras la creación del ticket
2. El 70%+ de los borradores requieren menos del 20% de edición
3. Los artículos de la base de conocimiento citados son relevantes para la pregunta
4. Los agentes pueden anular o descartar cualquier borrador con un clic

## Condiciones de fallo
- Respuesta enviada sin revisión humana
- Datos del cliente de la cuenta A aparecen en la respuesta de la cuenta B
- El borrador cita un artículo de KB obsoleto o incorrecto
- El sistema genera un borrador para un ticket que debería escalar

## Pruebas de éxito
1. "¿Cómo configuro dominios personalizados?" → El borrador referencia
   el artículo de KB de configuración de dominios con instrucciones correctas
2. "Me cobraron dos veces" → El borrador marca para escalación,
   no intenta resolver la facturación
3. Pregunta en español → El borrador está en español,
   referencia pasos de solución de problemas relevantes
4. Entrada sin sentido → El sistema marca como poco claro, no genera
   un borrador

El bucle de mejora de la spec

Una spec nunca está terminada en el primer intento. Usa el modelo de responsabilidad por fallos:

Escribe la spec usando las cinco primitivas
Ejecútala – deja que el agente la ejecute
Evalúa el resultado contra tus criterios de aceptación
Diagnostica los fallos por capa:

Qué salió mal	Qué capa corregir
El resultado es incorrecto o de baja calidad	Capa 1 – mejora el prompt
El resultado ignora el conocimiento del dominio	Capa 2 – mejora el contexto
El resultado optimiza la cosa incorrecta	Capa 3 – aclara la intención
El resultado está incompleto o no cumple los requisitos	Capa 4 – ajusta la spec

Corrige una capa a la vez. Nunca cambies múltiples capas simultáneamente – no sabrás qué funcionó.
Actualiza la spec con lo que aprendiste. Las mejores specs las escriben personas que han visto fallar a los agentes.

Este enfoque iterativo se alinea con la recomendación de Anthropic de "empezar de manera mínima con el mejor modelo, y luego añadir iterativamente instrucciones basadas en los modos de fallo observados."

Errores comunes

Sobre-especificar. Una spec que describe cada detalle de implementación es simplemente pseudocódigo. Especifica el qué y las restricciones, no el cómo. Deja que el agente elija el enfoque dentro de tus límites.

Sub-especificar. "Hazlo mejor" no es una spec. Si no puedes describir el resultado terminado, no estás listo para delegar.

Volcado de contexto. Cargar todos los documentos que tienes en el contexto "por si acaso". La información irrelevante degrada activamente el resultado. El principio central de Anthropic: encuentra el conjunto más pequeño de tokens de alta señal, no la mayor cantidad de tokens.

Optimizar prompts cuando el problema es el contexto. Si el agente sigue produciendo resultados irrelevantes, añadir "sé más relevante" al prompt no ayudará. El agente necesita información diferente, no mejores instrucciones. Usa el modelo de responsabilidad por fallos para diagnosticar la capa correcta.

Omitir el diseño de evaluación. Sin casos de prueba, dependes de las intuiciones para juzgar la calidad del resultado. Construye los casos de prueba primero – te obligan a aclarar lo que realmente quieres.

Reintentar en lugar de diagnosticar. Cuando el resultado falla, el instinto es regenerar. Para. Averigua qué capa causó el fallo. Corrige esa capa. Luego reintenta.

Referencia rápida

Antes de delegar, confirma:

Puedo describir el problema sin referenciar cosas que el agente no sabe
Puedo escribir tres oraciones que verifiquen el éxito
He listado qué debe ocurrir, qué no debe ocurrir y cuándo detenerse y preguntar
He dividido la tarea en piezas lo suficientemente pequeñas para verificar de forma independiente
Tengo casos de prueba con características conocidas como buenas

Cuando el resultado falla, diagnostica:

Síntoma	Causa probable	Acción
El resultado es incorrecto	Prompt	Mejorar las instrucciones, añadir ejemplos
El resultado ignora tu dominio	Contexto	Añadir o actualizar el archivo de contexto
El resultado optimiza la cosa incorrecta	Intención	Definir jerarquía de objetivos y compensaciones
El resultado está incompleto	Especificación	Añadir requisitos faltantes, ajustar el alcance

Lecturas adicionales

Building Effective Agents – Guía de Anthropic sobre patrones de arquitectura de agentes
Effective Context Engineering for AI Agents – Gestionar el estado completo de tokens a través de los bucles de agentes
Writing Tools for Agents – Principios de diseño de herramientas y metodología de evaluación
Context Engineering for Agents – Marco de cuatro operaciones de LangChain (Escribir, Seleccionar, Comprimir, Aislar)
A Survey of Context Engineering for LLMs – Encuesta académica que establece una taxonomía formal
CodeScout: Contextual Problem Statement Enhancement – Investigación que muestra una mejora del 20% con mejores especificaciones iniciales

← Volver al inicio · Estándares de ejecución · El marco de referencia · Glosario