La restricción que lo explica todo

Según la guía de Claude Code, casi todas las buenas prácticas parten de un hecho: el contexto se llena rápido y el rendimiento empeora al llenarse. Una sola sesión de depuración puede consumir decenas de miles de tokens. Gestionar el contexto es la habilidad principal.

Dale una forma de comprobar su trabajo

Es la recomendación más importante. Un agente se detiene cuando el trabajo parece terminado. Si no tiene una prueba que pueda ejecutar, tú te conviertes en el control de calidad. Dale algo que devuelva aprobado o suspenso: pruebas, una compilación, un linter o una captura para comparar con un diseño.

Pídele además pruebas de lo que dice: la salida de los tests, el comando que ejecutó. Revisar evidencias es más rápido que repetir la comprobación.

Explora, planifica y después programa

1. Explorar: en modo plan, el agente lee archivos y responde preguntas sin tocar nada.
2. Planificar: pídele un plan detallado: qué archivos cambian y cómo.
3. Implementar: que programe siguiendo el plan y ejecute las pruebas.
4. Guardar: que haga el commit con un mensaje descriptivo.

Para cambios pequeños sobra el plan: si puedes describir el cambio en una frase, pídelo directamente.

Sé específico

• Acota: qué archivo, qué escenario, qué tipo de prueba.
• Señala la fuente: "revisa el historial de este archivo y explica por qué la API es así".
• Apunta a ejemplos existentes: "mira cómo están hechos los widgets de la página de inicio y sigue el mismo patrón".
• Describe el síntoma: qué falla, dónde puede estar y qué significa que esté resuelto.

Un archivo de instrucciones corto

CLAUDE.md se lee al empezar cada sesión. Incluye comandos que el agente no puede adivinar, reglas de estilo que difieren de lo habitual, cómo ejecutar las pruebas y peculiaridades del entorno. Deja fuera lo que se deduce leyendo el código. Para cada línea, pregúntate si quitarla haría que el agente se equivocara. Si un archivo es demasiado largo, el agente ignora la mitad.

Gestiona la sesión

• Corrige pronto; interrumpir a tiempo ahorra trabajo.
• Limpia el contexto entre tareas que no tienen relación.
• Si has corregido lo mismo dos veces sin éxito, empieza de cero con un prompt mejor que incorpore lo aprendido.
• Usa subagentes para investigar: exploran en su propio contexto y te devuelven un resumen.

Que otro agente revise

La guía propone un patrón de escritor y revisor: una sesión implementa y otra, con contexto limpio, revisa sin el sesgo de quien escribió el código. Conviene decirle al revisor que señale solo fallos de corrección o de requisitos, porque si se le pide encontrar problemas siempre encontrará alguno, y perseguirlos todos lleva a complicar el código.

Un flujo completo, de principio a fin

Así se ve una tarea real bien llevada con un agente de código, por ejemplo añadir la exportación a Excel en una aplicación existente:

1. Explorar: "Lee cómo se generan hoy los informes en esta aplicación y explícame qué archivos intervienen. No cambies nada todavía."
2. Planificar: "Propón un plan para añadir exportación a Excel del informe mensual. Dime qué archivos tocarías, qué librería usarías y cómo lo vas a probar."
3. Ajustar el plan antes de que escriba una línea: es diez veces más barato corregir un plan que un código ya escrito.
4. Implementar con prueba: "Hazlo. Escribe primero una prueba que genere el Excel con datos de ejemplo y compruebe columnas y totales; después el código, hasta que la prueba pase."
5. Revisar el cambio completo antes de aceptarlo, y pedir a otra sesión que lo revise si toca algo delicado.
6. Guardar lo aprendido: si tuviste que explicarle algo dos veces, va al archivo de instrucciones del proyecto.

Errores frecuentes

• La sesión cajón de sastre: mezclar tareas sin relación.
• Corregir una y otra vez en lugar de empezar de nuevo.
• Confiar sin verificar: si no puedes comprobarlo, no lo publiques.
• La exploración infinita: pedir que "investigue" sin acotar.