Primeros Pasos con Claude Code
Qué Es Claude Code
Claude Code es la interfaz de línea de comandos oficial de Anthropic, potenciada por inteligencia artificial y diseñada para ingeniería de software. Se ejecuta directamente en tu terminal y se conecta a los modelos de frontera de Claude para ayudarte a leer, escribir y refactorizar código, ejecutar comandos de shell, gestionar flujos de trabajo con git y orquestar cambios complejos en múltiples archivos a lo largo de toda tu base de código. A diferencia de los asistentes de IA basados en navegador donde copias y pegas fragmentos de ida y vuelta, Claude Code opera de forma nativa dentro del directorio de tu proyecto. Ve tu árbol de archivos, comprende la estructura de tu proyecto y puede ejecutar comandos reales con consecuencias reales.
Piensa en él como un ingeniero senior sentado en tu terminal que puede leer cada archivo de tu proyecto, ejecutar tu suite de tests, buscar en documentación y hacer ediciones precisas -- todo mientras te pide permiso antes de hacer cualquier cosa destructiva.
Instalación
Claude Code requiere Node.js versión 18 o superior. Si no tienes Node.js instalado, descárgalo de nodejs.org o usa un gestor de versiones como nvm. Una vez que Node.js esté listo, instala Claude Code de forma global:
npm install -g @anthropic-ai/claude-code
Verifica la instalación:
claude --version
También necesitarás una clave API de Anthropic. Configúrala como variable de entorno o deja que Claude Code te la solicite en el primer inicio:
export ANTHROPIC_API_KEY=sk-ant-tu-clave-aqui
En Windows, usa las variables de entorno del sistema o configúrala en el perfil de tu shell. Claude Code también soporta Amazon Bedrock y Google Vertex AI como proveedores de modelos alternativos si tu organización lo requiere.
Tu Primer Inicio
Navega a cualquier directorio de proyecto y escribe:
claude
Esto inicia una sesión REPL interactiva. Claude carga contexto sobre tu proyecto -- leyendo tu árbol de archivos, cualquier archivo CLAUDE.md y la configuración relevante -- y luego espera tus instrucciones. Verás un prompt donde puedes escribir solicitudes en lenguaje natural.
Para consultas puntuales sin entrar en modo interactivo, usa el modo de impresión:
claude -p "Explica que hace este proyecto basandote en el README y package.json"
El modo de impresión envía tu prompt, obtiene una respuesta y sale. Es perfecto para scripting y consultas rápidas.
Entendiendo la Interfaz
Cuando interactúas con Claude Code, notarás varios elementos distintos en la salida. Las llamadas a herramientas aparecen cuando Claude decide usar una capacidad -- leer un archivo, ejecutar un comando, escribir código. Cada llamada a herramienta se muestra con lo que está haciendo y su resultado. Los prompts de permiso aparecen antes de acciones potencialmente impactantes. Claude te pedirá que apruebes escrituras de archivos, ejecución de comandos y otras operaciones antes de proceder.
Prueba esto como tu primera interacción:
claude
> Explica la estructura de este proyecto y lista los puntos de entrada principales
Claude usará herramientas de lectura de archivos para escanear tu proyecto y luego resumirá lo que encuentra. Observa las llamadas a herramientas desplazándose -- cada una te muestra exactamente lo que Claude está haciendo.
Flags Clave de Línea de Comandos
Claude Code acepta varias flags que controlan su comportamiento:
# Usar un modelo especifico
claude --model claude-sonnet-4-20250514
# Establecer modo de permisos (mas detalles abajo)
claude --permission-mode acceptEdits
# Obtener salida JSON estructurada (util para scripting)
claude -p "Lista todos los comentarios TODO" --output-format json
# Limitar el numero de turnos agentivos
claude --max-turns 10
# Reanudar la sesion mas reciente
claude --resume
# Continuar desde una sesion especifica
claude --resume <session-id>
La flag --output-format json es especialmente útil cuando canalizas Claude Code hacia otras herramientas. Devuelve datos estructurados que puedes analizar con jq o alimentar a scripts posteriores.
Tus Primeras Tareas Reales
Comienza con tareas de solo lectura y bajo riesgo para familiarizarte:
# Explicar un archivo especifico
claude -p "Explica que hace src/utils/auth.ts, funcion por funcion"
# Buscar bugs
claude -p "Revisa src/api/handlers.py en busca de posibles bugs o casos limite"
# Generar un componente
claude
> Crea un componente React llamado UserAvatar que reciba las props name e imageUrl,
> muestre la imagen en un circulo, y use las iniciales como fallback si no hay imagen
Para tu primera operación de escritura, intenta algo pequeño y reversible:
claude
> Agrega comentarios JSDoc a todas las funciones exportadas en src/utils/helpers.ts
Claude te mostrará los cambios propuestos, pedirá permiso para escribir el archivo y los aplicará solo después de que apruebes.
El Sistema de Permisos
El sistema de permisos es la característica de seguridad más importante de Claude Code. Por defecto, Claude pide tu aprobación explícita antes de escribir archivos, ejecutar comandos de shell o realizar cualquier acción que modifique tu sistema. Esto es intencional -- siempre deberías entender lo que Claude está a punto de hacer antes de que lo haga.
Cuando Claude quiere ejecutar un comando o escribir un archivo, verás un prompt como:
Claude wants to run: npm test
Allow? (y/n/always)
Elegir "y" lo permite una vez. Elegir "always" le dice a Claude que puede ejecutar ese tipo específico de comando sin preguntar de nuevo por el resto de la sesión.
Modos de Permisos
Claude Code proporciona seis modos de permisos que controlan cuánta autonomía tiene Claude. Elige el que coincida con tu nivel de confianza:
default -- Claude pide permiso para todo. Escrituras de archivos, comandos de shell, solicitudes web -- todo requiere aprobación. Este es el modo más seguro y donde cada nuevo usuario debería comenzar.
acceptEdits -- Claude puede escribir y editar archivos libremente pero aún pregunta antes de ejecutar comandos de shell. Este es el punto ideal para la mayoría de los desarrolladores una vez que confías en la salida de código de Claude.
plan -- Claude crea un plan detallado y pide aprobación antes de ejecutar. Útil para tareas complejas donde quieres revisar el enfoque antes de que comience cualquier trabajo.
auto -- Claude ejecuta la mayoría de operaciones sin preguntar. Aún respeta una lista configurable de comandos peligrosos denegados. Usa esto para tareas confiables y bien definidas.
dontAsk -- Similar a auto pero con aún menos prompts. Diseñado para entornos headless y CI/CD.
bypassPermissions -- Sin verificaciones de permisos en absoluto. Solo usa esto en entornos completamente aislados como contenedores o VMs desechables.
Prueba esto para ver los modos de permisos en acción:
# Iniciar con modo acceptEdits
claude --permission-mode acceptEdits
> Refactoriza el manejo de errores en src/api/routes.ts para usar un manejador de errores centralizado
Notarás que Claude edita archivos sin preguntar pero aún te solicita confirmación antes de ejecutar cualquier comando.
Canalizando Entrada a Claude
Claude Code funciona bien en pipelines estilo Unix. Puedes canalizar contenido de archivos, salida de comandos o cualquier texto directamente a Claude:
# Canalizar un archivo para analisis
cat src/config.ts | claude -p "Hay algun problema de seguridad en esta configuracion?"
# Canalizar git diff para revision
git diff HEAD~3 | claude -p "Resume estos cambios y senala cualquier cosa riesgosa"
# Canalizar salida de tests para diagnostico
npm test 2>&1 | claude -p "Analiza estos fallos de tests y sugiere correcciones"
Este patrón es poderoso para integrar Claude Code en scripts de shell existentes y flujos de trabajo de automatización.
Consejos Prácticos para Principiantes
Comienza cada nuevo proyecto ejecutando claude en la raíz del proyecto y pidiendo a Claude que explique la estructura del proyecto. Esto construye el contexto de Claude y te da una orientación rápida.
Usa el modo de permisos default durante tu primera semana. Una vez que desarrolles una idea de lo que Claude hace bien, cambia a acceptEdits para iterar más rápido. Reserva el modo auto para tareas que ya hayas ejecutado antes y en las que confíes completamente.
Si Claude comete un error, siempre puedes deshacerlo. Claude Code crea commits convencionales de git, así que git diff y git checkout son tu red de seguridad. Asegúrate de que tu trabajo esté commiteado antes de iniciar tareas de refactorización grandes.
Ejecuta /cost periódicamente para ver cuántos tokens y cuánto dinero ha consumido tu sesión. Esto te ayuda a desarrollar intuición sobre qué tareas son baratas y cuáles son costosas.
Finalmente, sé específico en tus prompts. En lugar de "arregla los bugs," intenta "arregla la excepción de puntero nulo en la función handleUserLogin en src/auth/login.ts que ocurre cuando el objeto usuario no tiene campo email." La especificidad reduce turnos desperdiciados y te da mejores resultados más rápido.