Construyendo endpoints de API con Claude: Lecciones prácticas de ingeniería de prompts de un proyecto con más de 70 endpoints

Ingeniería de prompts práctica para agentes que toman acciones

Un desarrollador que construyó una API de automatización de LinkedIn con más de 70 endpoints, ejecución del lado del servidor y autenticación mediante extensión de Chrome usó Claude para escribir aproximadamente el 80% del código. El proyecto reveló lecciones específicas sobre cómo estructurar prompts para agentes que realizan acciones como llamadas a API, extracción de datos y árboles de decisión versus agentes que solo conversan.

El enfoque contractual para los prompts

El desarrollador descubrió que las instrucciones en lenguaje natural como "encuentra leads relevantes en LinkedIn y envíales una solicitud de conexión personalizada" causaban problemas: Claude alucinaba campos, omitía validaciones y encadenaba llamadas a API innecesarias. Lo que funcionó fue tratar cada prompt de agente como una firma de función con restricciones explícitas:

• ENTRADAS: Exactamente lo que el agente recibe (esquema, tipos, casos límite)
• LÍMITES: Lo que el agente NO debe hacer (sin conjeturas de respaldo, sin campos omitidos, sin datos inventados)
• CONTRATO DE SALIDA: Forma exacta de lo que se devuelve, incluyendo estados de error
• REGLAS DE DECISIÓN: Si X entonces Y, si Z entonces detente — sin ambigüedad

Lecciones específicas aprendidas

"Sé creativo" es problemático para agentes de acción: Cada vez que se dejaba espacio para interpretación en prompts de toma de acciones, Claude producía resultados inesperados. Para agentes que ejecutan acciones reales, cero creatividad es preferible, reservando la creatividad para tareas de generación de contenido.

El manejo de errores es esencial: Aproximadamente el 40% de los tokens de los prompts se dedicaron a "qué hacer cuando las cosas salen mal". Sin esto, Claude o bien reintentaba infinitamente o silenciosamente tragaba errores y devolvía datos parciales como si todo estuviera bien.

Compensaciones de cadena de pensamiento: Forzar a cada agente a generar un paso de razonamiento antes de actuar cuesta aproximadamente un 15% más de tokens pero ahorra horas de depuración. Cuando algo falla, el desarrollador puede leer exactamente por qué el agente decidió hacer lo que hizo.

Coincidencia de patrones sobre prompts de personaje: En lugar de usar prompts como "eres un ingeniero senior", el desarrollador pega un ejemplo real de buena salida y dice "coincide con este patrón exactamente". Claude funciona mejor en coincidencia de patrones que en interpretación de roles.

Estrategia de selección de modelo: Las tareas simples de extracción y formato se dirigen a Sonnet (o incluso Haiku), mientras que solo el razonamiento complejo usa Opus. Este enfoque redujo los costos de API de dolorosos a manejables, ya que la mayoría de las tareas de agentes no requieren Opus.