Usar Claude Code —o cualquier LLM para programar— es fácil. Usarlo bien requiere entender cómo piensan estos modelos y qué prácticas maximizan su efectividad. Después de trabajar intensamente con ellos, estos son los consejos que más impacto tienen.
1. Da contexto, no solo instrucciones
El error más frecuente es decirle al modelo qué hacer sin decirle por qué. La diferencia entre "refactoriza esta función" y "refactoriza esta función para mejorar la testabilidad, porque vamos a añadir tests unitarios esta semana" es enorme. El contexto de negocio guía las decisiones técnicas.
2. Usa archivos CLAUDE.md para el contexto persistente
Claude Code lee automáticamente un archivo CLAUDE.md en la raíz del proyecto. Úsalo para explicar la arquitectura, las convenciones del proyecto, las decisiones de diseño importantes y qué cosas no debe tocar. Este archivo es tu "briefing" permanente al modelo.
# CLAUDE.md
## Arquitectura
- Backend: FastAPI + PostgreSQL
- Frontend: React 18 con TypeScript
- Autenticación: JWT con refresh tokens
## Convenciones
- Tests: pytest, cobertura mínima 80%
- Commits: formato conventional commits
- No modificar archivos en /legacy/ sin avisar3. Pide razonamiento antes de código
Antes de pedirle que escriba código, pídele que te explique su plan. "¿Cuál sería tu enfoque para implementar esto? Explícame los pasos antes de escribir nada." Esto te permite corregir el rumbo antes de que genere 200 líneas en la dirección equivocada.
4. Trabaja en porciones pequeñas
Los LLMs mantienen mejor la coherencia en tareas acotadas. En lugar de "construye el sistema de autenticación completo", divide en: "implementa el modelo de usuario", luego "añade el endpoint de registro", luego "añade el de login". Cada paso es verificable independientemente.
5. Muéstrale ejemplos de lo que quieres
Los modelos aprenden por analogía. Si tienes un módulo bien escrito en tu proyecto, dile: "Quiero que el nuevo módulo siga el mismo patrón que este". El código existente es el mejor prompt que tienes.
6. Sé explícito con los constraints
No asumas que el modelo sabe tus restricciones. Di explícitamente: "No uses librerías externas para esto", "Mantén compatibilidad con Python 3.9", "No rompas la interfaz pública de esta clase". Los modelos optimizan para lo que les dices, no para lo que das por supuesto.
7. Revisa siempre el código generado
Los LLMs cometen errores sutiles: lógica incorrecta en casos edge, imports que no existen, inconsistencias con el resto del código. El modelo es tu colaborador, no tu sustituto. La revisión de código sigue siendo tu responsabilidad.
8. Usa la capacidad de investigación para debugging
Claude Code puede leer logs, ejecutar el código con inputs específicos y rastrear el origen de un bug a través de múltiples archivos. Para bugs complejos, en lugar de intentar explicar el problema, dale acceso al código y dile: "Este test falla. Investiga el repositorio, encuentra la causa y propón un fix."
9. Itera el prompt, no solo el código
Si el resultado no es lo que esperabas, antes de aceptarlo y modificarlo manualmente, piensa si el problema está en tu prompt. A menudo, reformular la instrucción produce un resultado mucho mejor. "Hazlo más legible" es vago. "Extrae las constantes a variables con nombres descriptivos y añade un comentario por cada bloque lógico" es accionable.
10. Aprovecha el modo "agentic" para flujos completos
Claude Code puede ejecutar flujos completos sin intervención: leer código → identificar problema → escribir fix → ejecutar tests → hacer commit. Para esto funciona, tienes que definir bien el objetivo inicial y confiar en el proceso. No interrumpas constantemente; deja que el agente complete el ciclo.
