Estructura Práctica de Prompts para Agentes de Ejecución de Claude IA

Ingeniería de Prompts para Agentes de Ejecución

Un desarrollador con meses de experiencia construyendo agentes de Claude AI que ejecutan acciones reales—llamadas API, extracción de datos, árboles de decisión de múltiples pasos y recuperación de errores—comparte la estructura de prompt que resolvió problemas persistentes de alucinación. Los primeros intentos resultaron en agentes que alucinaban campos, encadenaban llamadas API innecesarias, silenciosamente ignoraban errores y devolvían datos parciales como si todo estuviera bien.

Principios Clave de Estructura de Prompts

• Escribe prompts como contratos, no como instrucciones: Los prompts en lenguaje natural como "encuentra leads relevantes y envía un mensaje personalizado" invitan a la improvisación. Lo que funciona: definir entradas (esquema exacto, tipos, casos límite), salidas (forma exacta incluyendo estados de error) y reglas de decisión (si X entonces Y, si Z entonces detente).
• Dedica el 40% de tus tokens de prompt al manejo de errores: Sin rutas de error explícitas, Claude o reintenta infinitamente o silenciosamente devuelve basura. Cada modo de falla posible necesita su propia instrucción: qué hacer cuando la API devuelve un 429, qué hacer cuando falta un campo requerido, qué hacer cuando los datos parecen ambiguos.
• Separa "espera" de "detención": Claude no puede distinguir entre "no tienes suficiente información para actuar aún" y "la información es mala, aborta" a menos que especifiques ambos casos. Un agente debía pausar con datos ambiguos pero en su lugar omitía todo lo que no estaba 100% limpio. Agregar instrucciones explícitas para ambos estados mejoró la precisión de la noche a la mañana.
• Coincidencia de patrones > interpretación de roles: "Eres un ingeniero senior" hace casi nada por la calidad de ejecución. Pegar un ejemplo real de buena salida y decir "coincide con este patrón exactamente" funciona 10 veces mejor. Claude es mejor replicando un ejemplo concreto que interpretando una persona abstracta.
• Enruta por complejidad, no por hábito: Usa Opus exclusivamente para decisiones de múltiples pasos donde importan el contexto y los casos límite. Todo lo demás va a Sonnet o Haiku. La mayoría de las tareas de agentes no necesitan Opus, y la diferencia de costo se acumula rápidamente. Los costos de API pasaron de brutales a manejables con un enrutamiento adecuado.
• Fuerza cadena de pensamiento antes de cada acción: Esto cuesta quizás un 15% más de tokens, pero cuando algo se rompe a las 2 a.m., puedes leer exactamente por qué el agente decidió hacer lo que hizo. Sin esto, estás depurando a ciegas.

El desarrollador señala que esta estructura de prompt importa mucho más que la elección del modelo para construir agentes que ejecutan acciones reales (no solo generan texto).