Los errores más comunes al construir apps con Claude

Claude es el mejor modelo general-purpose para construir aplicaciones reales en 2026. Pero la mayoría de las apps Claude que auditamos repite los mismos siete errores. Cada uno es simple de arreglar. Ninguno es obvio hasta que ya estás en producción, la factura se ha triplicado, o un cliente ha extraído tu system prompt.

Esta es la lista que compartimos con cada equipo en onboarding.

1. Tratar el context window como un cubo

Un context window de 200K no es espacio gratis. A medida que lo llenas, la precisión y el recall degradan. Anthropic llama a este fenómeno context rot. El error es verter todo en el contexto suponiendo que más datos producen mejores respuestas.

Trata el contexto como un recurso que curas, no como un cubo donde tirar. Mantén solo lo que el modelo necesita para el paso actual. Para agentes con tareas multi-step, usa context editing o summary compaction antes de que la ventana se llene.

2. Asumir que el prompt caching funciona

El prompt caching puede recortar costes hasta un 90% en prompts estables. Pero falla en silencio. Si tu cache breakpoint cae sobre un bloque que cambia entre peticiones (timestamps, variables por usuario, claves JSON ordenadas al azar en los schemas de tools), obtienes cero cache hits sin ningún aviso. La petición pasa. La factura sube.

Loguea cache_creation_input_tokens y cache_read_input_tokens de cada respuesta. Si ambos se quedan en cero durante una semana, la cache no está funcionando. Estabiliza el orden de todo lo anterior al breakpoint. Mueve el contenido dinámico después.

3. Ambigüedad en los schemas de tools

El tool use falla más en tool equivocado y parámetros equivocados. La causa típica son nombres y descripciones de tools demasiado parecidos. notification-send-user y notification-send-channel le parecen igual de correctos al modelo cuando el usuario dice "envía un mensaje".

Invierte en descripciones de tools. Escríbelas para un becario inteligente, no para ti. Prueba con prompts en los límites. Si dos tools se pueden confundir, consolídalos o renómbralos.

4. Tratar la prompt injection como un riesgo teórico

La prompt injection es el principal riesgo de seguridad para agentes de IA en 2026. No es teórica. Los atacantes insertan instrucciones en contenido que el modelo procesa: un issue de GitHub, un PDF, un email. El modelo no sabe distinguir con fiabilidad entre instrucciones de sistema, contenido de usuario y contenido inyectado.

Defensas: permisos del agente al mínimo, ejecución en sandbox, tratar cada input no confiable como hostil, filtrar outputs, nunca devolver contenido crudo no confiable al prompt sin escapar. El OWASP LLM Prompt Injection Prevention cheat sheet es un buen punto de partida.

5. Correr agentes con demasiados permisos

No le des a un agente acceso Bash general, acceso al filesystem, o acceso de red. Los agentes de producción deben correr en contenedores sandbox con el conjunto allowed_tools más pequeño que haga el trabajo. Usa permission callbacks. Usa PreToolUse hooks para bloquear paths sensibles. Inyecta API keys a través de un proxy para que el agente nunca las vea.

El flag --dangerously-skip-permissions existe por un motivo: es peligroso. Nunca lo uses en producción. Incluso con el flag apagado, la approval fatigue es real: los desarrolladores aprueban decenas de prompts por sesión y las acciones inyectadas se cuelan. Haz que las aprobaciones sean raras y significativas.

6. Sin audit trail, sin kill switch

Cada acción de un agente en producción debe loguearse: el tool llamado, los argumentos, el resultado, el usuario que lo disparó, el correlation ID. Los audit trails son cómo averiguas qué salió mal después de que salió mal. Los kill switches son cómo lo paras mientras está saliendo mal.

Si no puedes responder "¿qué estaba haciendo el agente X a las 14:14?" en menos de treinta segundos, no tienes observabilidad.

7. Sin estrategia de versionado del modelo

Anthropic lanza nuevas versiones del modelo con regularidad. Si te fijaste a claude-sonnet-4-5 y construiste los prompts alrededor de sus particularidades, pasar al último Sonnet cambia el comportamiento. Si usas el alias latest, el modelo bajo tu app cambia sin que lo sepas.

Elige una estrategia explícita. Fíjate a un modelo fechado y agenda tests de nuevas versiones, o usa el alias latest y corre una suite de regression tests en cada cambio de modelo. Ambas funcionan. Ninguna estrategia, no.

La lista corta

Cura el contexto. Verifica tu cache. Desambigua tools. Defiéndete de la prompt injection. Dale a los agentes los permisos mínimos que necesiten. Loguea todo y construye un kill switch. Elige una estrategia de versionado.

Ninguno de estos es un defecto específico de Claude. Son errores que comete cualquier equipo que construye con un large language model por primera vez. Los repetimos en proyectos nuevos hasta que codificamos las reglas. Este post es nuestra lista codificada actual.

Si estás construyendo algo con Claude y quieres un segundo par de ojos en tu setup, escríbenos.