Trabajar con Claude Code es una experiencia poderosa — pero como cualquier herramienta poderosa, los resultados dependen enormemente de cómo la usas. La diferencia entre una sesión frustrante llena de correcciones y una sesión fluida donde el código simplemente funciona casi siempre se reduce a lo que hiciste antes de escribir el primer prompt.
Este artículo es para todos: si eres senior, probablemente ya intuyiste algunas de estas cosas, pero aquí las vamos a sistematizar. Si eres junior, esto te va a ahorrar horas de dolores de cabeza.
El Error Más Común: Lanzarse Sin Contexto
La mayoría de los desarrolladores abren Claude Code, escriben “construye un sistema de autenticación con JWT” y esperan magia. A veces funciona. Pero cuando el proyecto crece, cuando hay decisiones de arquitectura que respetar, cuando hay convenciones de equipo… Claude empieza a tomar decisiones que no se alinean con tu realidad.
El problema no es Claude — es que no tiene contexto. Y sin contexto, improvisa.
Paso 1: El Archivo CLAUDE.md — Tu Contrato con el Agente
El archivo CLAUDE.md en la raíz de tu proyecto es la herramienta más importante que tienes. Claude lo lee automáticamente al inicio de cada sesión. Piénsalo como el “onboarding” que le darías a un desarrollador nuevo en tu equipo.
Un buen CLAUDE.md incluye:
Stack y versiones exactas — No “usamos React”, sino “React 18.3 con TypeScript 5.4, Vite como bundler, Tailwind 3.4”. Cuanto más específico, menos sorpresas.
Convenciones del proyecto — ¿Usas camelCase o snake_case? ¿Componentes funcionales solamente? ¿Cómo nombras los archivos de test? ¿Dónde van los tipos globales? Estas decisiones que tú ya tienes automatizadas en la cabeza, Claude no las conoce.
Arquitectura y estructura de carpetas — Un párrafo explicando cómo está organizado el proyecto vale más que mil preguntas. “La lógica de negocio vive en /services, los componentes en /components organizados por feature, los tipos globales en /types.”
Lo que NO debe hacer — Esto es subestimado. Si no quieres que Claude instale dependencias sin pedir permiso, dilo. Si hay partes del código que son legado y no se deben tocar, marcalas. Si tienes un linter configurado y no quieres que lo sobrescriba, especifícalo.
Comandos clave — Los comandos para correr tests, el comando de build, cómo se levanta el ambiente local. Claude puede ejecutarlos para validar su propio trabajo.
Paso 2: Usa /init en Proyectos Existentes
Si estás incorporando Claude Code a un proyecto que ya existe, el comando /init es tu punto de partida. Claude va a explorar la estructura del proyecto, leer los archivos clave, y generar un CLAUDE.md inicial basado en lo que encuentra.
No es perfecto — siempre vas a querer editarlo — pero es un excelente punto de partida que te ahorra 20 minutos de documentar lo obvio.
Paso 3: Descompón el Trabajo Antes de Pedirlo
Claude Code trabaja mejor con tareas bien delimitadas. Antes de empezar una sesión, tómate 5 minutos para pensar en los límites de lo que vas a pedir.
En lugar de: “Implementa el módulo completo de usuarios”
Mejor: “Crea el modelo User con estos campos, el endpoint de registro con validación, y el middleware de autenticación JWT. Los tests van en /tests/auth. No toques el módulo de perfiles todavía.”
La diferencia parece pequeña, pero le estás dando a Claude un scope claro, un lugar donde poner las cosas, y un límite explícito de hasta dónde llegar. Eso reduce errores y reduce el riesgo de que modifique código que no debería.
Paso 4: Modo Exploración vs. Modo Ejecución
Claude Code tiene dos modos de trabajo y saber cuándo usar cada uno cambia todo.
Modo exploración — Pedirle que entienda, analice, o proponga antes de actuar. “Lee el módulo de pagos y dime cómo implementarías el soporte para múltiples monedas sin romper lo existente.” Esto es invaluable antes de cambios grandes. Ves el plan, lo cuestionas, lo ajustas — y solo entonces ejecutas.
Modo ejecución — Pedirle que implemente directamente con instrucciones claras. Ideal cuando ya tienes claro qué quieres y el scope está bien definido.
El error clásico es usar modo ejecución cuando necesitabas exploración primero. Terminas con una implementación técnicamente funcional que no encaja con tu arquitectura, y ahora tienes que deshacer trabajo.
Paso 5: Establece Checkpoints, No Sesiones Largas
Las sesiones muy largas con Claude Code acumulan contexto que eventualmente se vuelve ruido. Es mejor trabajar en bloques — implementar una parte, revisar, hacer commit, y empezar una sesión nueva con contexto limpio para la siguiente parte.
Un flujo que funciona bien:
- Sesión de exploración → entender el problema
- Sesión de implementación → código concreto con scope delimitado
- Revisión humana → leer el diff, entender qué cambió y por qué
- Commit con mensaje descriptivo
- Nueva sesión para el siguiente bloque
Este flujo te mantiene en control del proyecto. No delegas — colaboras.
Los Beneficios en la Ejecución
Cuando preparas bien el contexto, los beneficios son inmediatos y acumulativos:
Menos correcciones — Claude toma decisiones alineadas con tu stack y convenciones desde el primer intento. No tienes que repetir “usa TypeScript estricto” en cada sesión.
Código más consistente — El estilo, la estructura de carpetas, los patrones de error — todo sigue tus convenciones porque las documentaste.
Menos alucinaciones de arquitectura — Sin contexto, Claude puede proponer soluciones válidas que no encajan con tu proyecto. Con contexto, las propuestas son más aterrizadas.
Sesiones más cortas y productivas — Paradójicamente, invertir tiempo en preparación reduce el tiempo total del proyecto. Las correcciones son costosas.
Un historial de decisiones — Tu CLAUDE.md se convierte en documentación viva del proyecto. Cualquier persona (o instancia futura de Claude) puede entender el proyecto leyéndolo.
Checklist Rápido Antes de Empezar
Antes de tu próxima sesión en Claude Code, revisa esto:
- ¿Tienes un
CLAUDE.mdactualizado con el stack, convenciones y restricciones? - ¿El scope de lo que vas a pedir está claro y delimitado?
- ¿Sabes si necesitas exploración o ejecución primero?
- ¿Tienes los tests y el linter corriendo para que Claude pueda validar su trabajo?
- ¿Estás en una rama limpia para poder hacer rollback si algo sale mal?
Si respondiste sí a todo, estás listo. Si no, cinco minutos de preparación ahora te ahorran una hora después.
Claude Code no es un reemplazo del criterio del desarrollador — es un multiplicador de él. Y como todo multiplicador, amplifica tanto lo bueno como lo malo. Ponle buen contexto, dale scope claro, mantente en el loop de revisión, y vas a ver resultados que justifican completamente el cambio en el workflow.