Ya tienes Claude Code instalado. El problema: abres la terminal, escribes claude, y no sabes qué decirle. Esta guía te lleva de ese momento a tener trabajo real terminado — con los comandos exactos, en orden, sin asumir nada.
Si aún no lo has instalado, empieza por la guía de instalación. Si ya lo tienes, sigue aquí.
Lo que vas a lograr en esta guía
Al terminar, vas a haber completado un ciclo real de trabajo con Claude Code: entender un proyecto, pedirle una tarea concreta, revisar los cambios y confirmarlos. Ese ciclo es el 80% del uso diario. Todo lo demás es variación.
Paso 1: abre tu proyecto correctamente
Este detalle importa más de lo que parece. Claude Code entiende mejor tu proyecto cuando lo abres desde la raíz del repositorio, no desde una subcarpeta.
cd /ruta/a/tu-proyecto
claudeSi no tienes un proyecto propio a mano, crea una carpeta vacía y agrega un par de archivos de ejemplo. Claude Code funciona igual.
Al escribir claude entras al modo interactivo. Verás un prompt que dice algo como > o claude>. Ahí es donde escribes.
Paso 2: el primer mensaje (no empieces con "hola")
El error más común al empezar: preguntarle algo genérico como "¿qué puedes hacer?" o peor, empezar directamente con una tarea sin darle contexto.
El primer mensaje que funciona casi siempre es este:
Lee el proyecto y dime qué hace, cómo está organizado, y cuáles son los archivos más importantes.Claude Code va a explorar la estructura de carpetas, leer los archivos principales y darte un resumen. Eso tiene dos beneficios: tú confirmas que entendió bien el proyecto, y Claude tiene contexto para las siguientes tareas.
Si algo del resumen está equivocado, corrígelo ahí mismo:
El archivo principal no es index.js sino server.js. Y la base de datos es PostgreSQL, no SQLite.Paso 3: pide tu primera tarea real
Con el contexto establecido, es momento de pedir trabajo real. La regla: cuanto más específico, mejor resultado.
Genérico (funciona menos):
Arregla los bugs del proyecto.Específico (funciona mejor):
En el archivo src/auth/login.js, la función validateEmail no está manejando el caso de emails con caracteres especiales como + o puntos antes del @. Arréglalo y agrega un test para ese caso.La fórmula que funciona: dónde (archivo o función) + qué está mal o qué falta + qué quieres + opcionalmente, cómo verificarlo.
Paso 4: sigue el progreso y aprueba
Mientras Claude trabaja, verás en la terminal qué archivos está leyendo, qué está editando y qué comandos está corriendo. Puedes interrumpirlo en cualquier momento con Ctrl+C si algo no va bien.
Cuando termina, te muestra un resumen de lo que hizo. Antes de continuar, revisa los cambios con Git:
git diffEsto te muestra exactamente qué líneas cambiaron. Si ves algo raro, puedes pedirle que lo revierta:
Eso no está bien. El cambio en la línea 47 rompe la lógica de validación. Revierte ese archivo y prueba de nuevo sin tocar la parte de validación.Paso 5: iterar hasta tener lo que necesitas
Claude Code no siempre lo clava a la primera. Eso es normal. La ventaja es que el contexto sigue activo — no tienes que repetir todo desde cero. Solo corriges lo que está mal:
Casi. El test que agregaste falla porque está usando la librería de testing equivocada. Este proyecto usa Jest, no Mocha. Ajusta el test.Tres o cuatro iteraciones para una tarea mediana es normal, no una señal de que algo está mal. Cada iteración es más rápida que hacerlo tú desde cero.
Paso 6: crear el archivo CLAUDE.md
Después de tu primera sesión, hay una inversión que vale mucho la pena: crear un archivo CLAUDE.md en la raíz del proyecto con lo que le tuviste que explicar manualmente.
Le puedes pedir a Claude que lo cree por ti:
Crea un archivo CLAUDE.md para este proyecto con todo lo que aprendiste hoy: estructura, tecnologías, convenciones, qué archivos no tocar y cómo correr los tests.En la próxima sesión, Claude leerá ese archivo automáticamente al inicio y no tendrás que explicar el proyecto de nuevo. El tiempo ahorrado en contexto se acumula rápido. Para aprender a configurarlo bien, mira la guía completa de CLAUDE.md.
Los errores más comunes al empezar
- Pedir demasiado en un solo mensaje. "Refactoriza todo el proyecto, agrega tests, documenta el código y arregla los bugs" produce resultados mediocres. Un objetivo claro por sesión produce trabajo bueno.
- No revisar los cambios. Claude Code puede cometer errores, especialmente en lógica de negocio compleja. El
git diffantes de aceptar no es opcional. - Abrir la sesión sin contexto. Si no le dices qué proyecto es ni lees los archivos primero, las respuestas son genéricas. Dos minutos de contexto inicial cambian todo.
- Rendirse en la primera iteración imperfecta. La iteración es parte del flujo. No es que Claude Code sea malo; es que las instrucciones precisas son una habilidad que se desarrolla.
Tu flujo mínimo para cada sesión
cd proyecto && claude— abre el proyecto.- "Léete el proyecto" — o si ya tiene CLAUDE.md, ve directo al paso 3.
- Tarea específica con contexto claro.
git diff— revisa los cambios.- Itera si es necesario.
git add / git commit— cuando estés satisfecho.
En resumen
El primer proyecto con Claude Code tiene una curva de aprendizaje corta. El 90% del valor viene de tres hábitos: dar contexto claro al inicio, pedir tareas específicas (no genéricas), y revisar siempre los cambios antes de aceptarlos. El CLAUDE.md es la inversión que hace que cada sesión siguiente sea más rápida.
En Aldama usamos Claude Code en todos nuestros proyectos de desarrollo. Si quieres que un equipo que ya domina estas herramientas construya algo para ti, lo conversamos. Sin humo.