Flujos de desarrollo con IA e incidentes, plan antes de implementar, CI reproducible y límites de tasa

Tres escenas de la misma semana. Un desarrollador le pidió a Claude Code migrar cuarenta archivos a un cliente de pagos nuevo en un solo pedido y recibió cambios inconsistentes que nadie verificó. La revisión automática de pull requests en CI da resultados distintos según el runner. Y después de lanzar una función que hace muchas llamadas en paralelo, la app recibe errores 429, los reintenta al instante y el incidente empeora.

Cambios grandes: explorar, planificar, implementar, verificar

Un pedido gigante en un solo paso deja a Claude adivinando el alcance y sin forma de saber si terminó bien. El flujo recomendado separa las etapas:

1. Explorar en modo plan (plan mode): Claude lee el código y responde preguntas sin modificar nada.
2. Planificar: Claude propone qué archivos cambian y en qué orden; una persona revisa y corrige el plan antes de tocar código.
3. Implementar por pasos, verificando contra el plan.
4. Verificar con algo que dé pasa o falla: la suite de tests, el build, un linter. Es la diferencia entre una sesión que tenés que vigilar y una que se corrige sola.

Para investigar sin llenar el contexto principal sirven los subagentes, y entre tareas no relacionadas conviene limpiar el contexto. Si el cambio es chico y se describe en una frase, el plan sobra. Para migraciones de cientos de archivos, se puede repartir con un script que llama a Claude por archivo, probando primero con dos o tres.

CI reproducible

En CI, Claude Code corre en modo no interactivo (non-interactive mode) con claude -p. El problema del escenario es que, por defecto, esa ejecución carga lo que encuentre en la máquina: hooks, plugins, servidores MCP, memoria y CLAUDE.md del usuario del runner. Cada runner configurado distinto da un resultado distinto.

El modo bare (bare mode), con --bare, arranca sin leer nada de eso. Lo que el job necesita se pasa explícito:

• --allowedTools para preaprobar solo las herramientas del trabajo;
• --settings y --mcp-config para la configuración y los servidores;
• --append-system-prompt para las instrucciones de la revisión;
• --output-format json para que el pipeline reciba un resultado que puede procesar.

Así el job es el mismo en cualquier runner. Saltear todos los permisos para que nada se trabe, o configurar a mano el ~/.claude de cada máquina, no resuelven la reproducibilidad.

Incidentes con la API

Señal	Qué significa	Qué hacer
429 con retry-after	se superó un límite de tasa (rate limit)	esperar lo que indica el header, backoff exponencial con jitter (exponential backoff with jitter), limitar la concurrencia
429 sin retry-after, por tope de gasto	se alcanzó el límite de gasto mensual	reintentar no sirve: hay que subir el límite
529	la API está sobrecargada	reintentar con backoff
500	error interno	backoff; si persiste, soporte con el ID del pedido
400	el pedido está mal	corregir; reintentar no cambia nada

Los reintentos inmediatos multiplican el tráfico justo cuando sobra. El jitter evita que todos los clientes reintenten en el mismo instante. Los SDK oficiales ya reintentan con backoff y respetan retry-after. Para prevenir: subir el tráfico de forma gradual y usar la caché, porque en la mayoría de los modelos los tokens leídos de la caché no cuentan para el límite de entrada.

Las trampas típicas

• Un prompt más largo con los cuarenta archivos y todas las reglas.
• Pedirle a Claude que revise su propio diff al final en lugar de correr los tests.
• Iniciar una sesión interactiva desde el script de CI.
• Subir los reintentos inmediatos a veinte.
• Pasar a otro modelo “porque tiene otro límite” o tratar el 429 como una caída del proveedor.

En el examen

Si un cambio grande salió inconsistente, buscá explorar y planificar con revisión, implementar por pasos y verificar con tests. Si CI da resultados distintos por máquina, buscá claude -p con --bare y todo pasado por flags. Si hay 429 y reintentos inmediatos, buscá backoff exponencial con jitter, retry-after y límite de concurrencia.