Dominar Claude Code Parte 1: Primeros Pasos

Imagina esto: estás mirando un codebase legacy enorme, con cientos de archivos, y alguien te pide que "solo añadas una pequeña funcionalidad." Podrías pasar horas rastreando imports, entendiendo patrones y averiguando cómo se conecta todo. O podrías escribir claude en tu terminal y pedirle que te explique la arquitectura en lenguaje llano.

Esa es la promesa de Claude Code—un programador IA en pareja que no solo autocompleta tu código, sino que realmente entiende todo tu proyecto y puede ejecutar tareas de forma autónoma. Vamos a configurarte.

La Brecha de Productividad Es Real

Hay algo que nadie quiere decir en voz alta: si no estás usando herramientas como Claude Code, ya te estás quedando atrás.

Los desarrolladores que lo han descubierto están operando a 10-100x la productividad de los que no. Esto no es hype. Es lo que pasa cuando puedes entregar funcionalidades completas en una hora en vez de un día, cuando puedes refactorizar arquitectura en minutos en vez de semanas, cuando puedes depurar problemas complejos haciendo que una IA lea miles de archivos en segundos.

Mientras algunos desarrolladores rastrean codebases manualmente, otros ya terminaron y pasan a la siguiente tarea. Mientras algunos leen documentación, otros ya entregaron. Mientras algunos depuran línea por línea, otros lo resolvieron y siguieron adelante.

Esta guía es todo lo que aprendí en un año de uso diario de Claude Code. Cada truco que me ahorró horas. Cada flujo de trabajo que multiplicó mi output. Cada cambio de mentalidad que marcó la diferencia entre frustración y flow.

Si eres desarrollador en solitario, esto cambiará tu carrera. Si lideras un equipo, esto cambiará toda tu organización. La brecha se está ampliando rápido. Asegurémonos de que estés del lado correcto.

¿Qué Es Exactamente Claude Code?

Claude Code es el asistente de programación agéntico de Anthropic que vive en tu terminal. A diferencia de las herramientas tradicionales de autocompletado que sugieren los siguientes caracteres, Claude Code puede:

• Navegar todo tu codebase — Lee, entiende y conecta los puntos a través de cientos de archivos
• Ejecutar tareas de múltiples pasos — "Refactoriza este módulo a TypeScript" no es solo una sugerencia; Claude realmente lo hace
• Gestionar flujos de git — Commits, ramas, descripciones de PR — todo mediante lenguaje natural
• Funcionar en cualquier sitio — Terminal, VS Code, JetBrains, o incluso directamente en GitHub con menciones @claude

Piensa en ello menos como un autocompletado y más como un desarrollador junior muy entusiasta que escribe 1000x más rápido que tú, puede leer todo tu codebase en segundos y tiene paciencia infinita para explicar cosas.

Aquí está el truco: los LLMs avanzan a toda velocidad sin ninguna barrera de contención si les dejas. Los desarrolladores que más sacan de Claude Code no solo son buenos haciendo prompts—son buenos configurando estructura que canalice toda esa velocidad en algo útil en vez de caótico.

Antes de Instalar

Necesitarás una de estas dos cosas:

Opción A: Suscripción Claude Pro o Max

Si ya pagas Claude Pro ($20/mes) o Max ($100/mes), estás cubierto. El uso de Claude Code está incluido y te autentificas simplemente iniciando sesión en tu cuenta de Claude.

Opción B: API Key de Anthropic

¿Prefieres pago por uso? Crea una cuenta en console.anthropic.com, añade facturación y genera una API key. Solo pagas por lo que usas.

Consejo: Si tienes tanto una API key configurada como variable de entorno COMO una suscripción de Claude, la API key tiene prioridad — lo que significa que te cobrarán por token en vez de usar tu suscripción. Ejecuta /status dentro de Claude Code para verificar qué método de autenticación está activo.

Requisitos del sistema:

• Node.js 18 o superior (comprueba con node --version)
• macOS, Linux o Windows

Instalación

El método de instalación por npm está obsoleto. Estas son las formas oficiales de instalar Claude Code:

macOS o Linux (Recomendado):

Curl -fsSL https://claude.ai/install.sh | bash

Homebrew (macOS/Linux):

Brew install --cask claude-code

Windows (PowerShell):

Irm https://claude.ai/install.ps1 | iex

Windows (WinGet):

Winget install Anthropic.ClaudeCode

Después de la instalación, Claude Code se actualiza automáticamente en segundo plano. Los usuarios de Homebrew y WinGet necesitan actualizar manualmente con brew upgrade claude-code o winget upgrade Anthropic.ClaudeCode.

Primer Lanzamiento

Navega a cualquier directorio de proyecto y ejecuta:

Claude

Lo que pasa después depende de tu configuración:

1. Se abre el navegador para autenticación
2. Inicia sesión con tu cuenta de Claude o credenciales de la consola Anthropic
3. Autoriza a Claude Code para acceder a tu cuenta
4. Se crea automáticamente un workspace "Claude Code" dedicado para seguimiento de uso

Eso es todo. Ya estás dentro.

Lo Primero Que Deberías Hacer

Ejecuta este comando inmediatamente:

/terminal-setup

Esto instala atajos de terminal que te permiten usar Shift + Enter para input multilínea. Sin esto, estás atrapado escribiendo todo en una sola línea — lo cual se vuelve doloroso rápido cuando escribes prompts detallados.

Por qué importa: Imagina intentar explicar un bug complejo en una línea versus poder estructurar tus pensamientos en múltiples párrafos. El input multilínea transforma la eficacia con la que te comunicas con Claude.

Dos Formas de Trabajar

Modo Interactivo (Tu Herramienta del Día a Día)

Claude

Abre una sesión REPL donde tienes una conversación de ida y vuelta. Claude mantiene el contexto durante toda la sesión, recuerda lo que discutiste y puede manejar tareas complejas de múltiples pasos.

Úsalo para:

• Construir nuevas funcionalidades
• Depurar problemas complicados
• Revisiones de código y refactorización
• Explorar codebases desconocidos

Modo Plan (Pensar Antes de Actuar)

Pulsa Shift+Tab dos veces antes de enviar tu mensaje para entrar en Modo Plan. En este estado de solo lectura, Claude puede explorar tu codebase, investigar enfoques y proponer soluciones — pero no puede modificar ningún archivo.

Úsalo para:

• Decisiones de arquitectura antes de implementar
• Entender código desconocido
• Evaluar diferentes enfoques para un problema
• Refactorizaciones complejas donde quieres ver el plan primero

El Modo Plan se cubre en profundidad en Parte 2: El Modelo Mental.

Modo One-Shot (Preguntas Rápidas)

Claude -p "tu pregunta aquí"

Ejecuta un solo comando y sale. Sin sesión interactiva, solo pregunta → respuesta → listo.

Úsalo para:

• Consultas rápidas: claude -p "qué hace el middleware de auth?"
• Scripts automatizados: claude -p "lista todos los comentarios TODO" >> todos.txt
• Pipelines CI/CD: claude -p "genera changelog de los commits recientes"

Comandos Esenciales

Una vez dentro de una sesión interactiva, estos comandos slash controlan el comportamiento de Claude:

/help — Muestra todos los comandos disponibles incluyendo los personalizados. Úsalo cuando olvides un comando o quieras descubrir nuevas funcionalidades.

/clear — Borra el historial de conversación. ¡Úsalo a menudo! Empieza de cero entre tareas no relacionadas para ahorrar tokens.

/compact — Comprime el contexto de la conversación. Úsalo cuando el contexto se está alargando pero quieres mantener algo de historial.

/model — Cambia entre Opus, Sonnet o Haiku. Opus para razonamiento complejo, Haiku para tareas rápidas, Sonnet para equilibrio.

/config — Abre la configuración de ajustes. Úsalo para ajustar permisos, valores predeterminados y preferencias.

/status — Muestra el estado actual y método de autenticación. Úsalo para verificar qué cuenta/API key se está usando.

/cost — Muestra el uso de tokens. Vigila el consumo.

/context — Ve lo que está en el contexto actual de Claude. Te ayuda a entender lo que Claude "sabe" ahora mismo.

/vim — Habilita edición estilo vim. Si eres usuario de vim, te sentirás como en casa.

/init — Inicializa o actualiza CLAUDE.md. Ejecútalo después de funcionalidades grandes o refactorizaciones para mantener el contexto del proyecto actualizado.

Comandos de Gestión de Sesión

/terminal-setup — Instala el atajo Shift+Enter para input multilínea.

/allowed-tools — Configura qué herramientas puede usar Claude (acceso a archivos, bash, etc.).

/hooks — Configura hooks de automatización para ciertos eventos.

/mcp — Gestiona servidores del Model Context Protocol.

/agents — Crea y gestiona subagentes para tareas paralelas.

/install-github-app — Configura la integración con GitHub Actions para menciones @claude.

Gestión de Sesiones desde el Terminal

A veces necesitas continuar donde lo dejaste:

# Continúa tu última sesión exactamente donde la dejaste
Claude -c

# Navega y selecciona de sesiones recientes
Claude -r

El flag -r es particularmente útil cuando te das cuenta de "espera, estaba trabajando en ese bug de auth hace dos días y Claude había descubierto algo." Puedes saltar de vuelta a esa conversación exacta.

Tu Primera Tarea Real

Aquí va una gran forma de probar tu configuración. Navega a cualquier proyecto y ejecuta:

Claude

Luego escribe:

Explica la arquitectura de este proyecto. ¿Cuáles son los componentes principales
y cómo se conectan? ¿Dónde debería mirar si quisiera añadir un nuevo
endpoint de API?

Claude escaneará tu codebase, identificará patrones y te dará una visión general estructurada. Esta es genuinamente una de las mejores formas de hacer onboarding en cualquier proyecto desconocido — ya sea un trabajo nuevo, una contribución open-source o tu propio código de hace seis meses.

El Sistema de Permisos

Claude no modifica tus archivos en silencio. Antes de hacer cambios, verás prompts como:

Claude wants to edit src/auth.ts
Allow? [y]es / [n]o / [a]lways allow for this file

Tus opciones:

• y — Permitir esta acción específica
• n — Bloquearla
• a — Permitir siempre este tipo de acción (sin más prompts para operaciones similares)

Mi recomendación: Empieza con y para todo hasta que entiendas los patrones de comportamiento de Claude. Una vez que confíes en él para ciertas operaciones (como editar archivos de test), cambia a a para acelerar tu flujo de trabajo.

Permisos avanzados: Para control detallado con listas de permitidos/denegados, hooks automatizados y políticas de permisos para equipos, consulta Configuración de Ajustes en la Parte 3.

Integración con IDE

Claude Code funciona nativamente con varios IDEs:

VS Code — Busca "Claude Code" en Extensiones (Cmd/Ctrl+Shift+X). Integración completa con diffs inline y conversaciones multi-pestaña.

Cursor — Puede requerir instalación manual del VSIX. Basado en VS Code, funciona genial una vez instalado.

Windsurf — Configuración similar a Cursor. Fork de VS Code que soporta extensiones VSIX.

JetBrains — Plugin disponible. Funciona con IntelliJ, WebStorm, PyCharm y otros IDEs de JetBrains.

Importante: La extensión de VS Code no es un reemplazo del CLI — es un launcher que proporciona una interfaz más agradable. El Claude Code real sigue ejecutándose como el mismo motor bajo el capó. Puedes tener múltiples instancias corriendo en paralelo en diferentes partes de tu codebase.

El Cambio de Mentalidad: La Estructura Habilita la Velocidad

Esto es lo que separa a los desarrolladores que aman Claude Code de los que lo encuentran frustrante: los que tienen éxito lo tratan como colaborar con un desarrollador junior muy capaz pero muy entusiasta.

Ese junior escribe increíblemente rápido, nunca se cansa y puede absorber todo tu codebase en segundos. Pero también avanzará felizmente sin barreras si le dejas. Las prácticas que hacen funcionar la programación asistida por IA no son nuevas — son las mismas cosas que los desarrolladores experimentados han hecho durante años. Solo que ahora se vuelven críticas.

Git Es Tu Red de Seguridad

Haz commits frecuentes, en trozos pequeños. Si Claude se desvía, puedes simplemente hacer git checkout . o revertir a un estado bueno conocido. Piensa en los commits como puntos de guardado en un videojuego.

Suena básico, pero lo cambia todo. Cuando sabes que siempre puedes volver atrás, eres libre de dejar que Claude experimente. Cuando no estás seguro, dudas, microgestiones y pierdes la mayor parte de la ventaja de velocidad.

Si estás oxidado con Git, la documentación oficial de GitHub es genuinamente excelente para empezar.

Planifica Antes de Hacer Prompts

Escribe lo que vas a construir antes de empezar con los prompts. Un documento markdown simple con tus objetivos, decisiones de arquitectura y restricciones hace maravillas. Guárdalo en tu repositorio para que Claude pueda referenciarlo.

Y en serio — usa el Modo Plan. Está literalmente en el nombre. Cuando le pides a Claude que planifique algo, te hace preguntas aclaratorias, luego propone un plan y te da la opción de aceptarlo. Si no estás satisfecho por cualquier razón, di que no y dile a Claude qué te gustaría cambiar. Itera todo lo que necesites.

Esto te obliga a ti a pensar, y le da al LLM contexto crucial. Shift+Tab dos veces, luego "diseña un formulario de login" es infinitamente mejor que "constrúyeme un formulario de login."

Divide las Tareas Grandes en Issues

En vez de "hey Claude, constrúyeme un sistema de autenticación de usuarios," divídelo en piezas discretas: "Crea el modelo User," "Añade gestión de sesiones," "Construye el formulario de login." Un PR por issue.

Crea plantillas de issues en GitHub (solicitud de funcionalidad, reporte de bug — estas dos cubren el 90% de los casos) y haz commit de ellas en el control de versiones. GitHub las usa automáticamente cuando alguien crea un issue a través de la UI.

Una vez que tengas un plan sólido y lo entiendas, pídele a Claude que cree un issue en GitHub usando tu plantilla. O si tienes un plan grande, pídele a Claude que lo divida en trozos más pequeños y manejables, luego convierte las piezas con las que te sientas cómodo en issues.

Tests Primero (Sí, En Serio)

Pídele a Claude que escriba tests antes de la implementación. Suena contraintuitivo, pero obliga al LLM a pensar claramente sobre cómo se ve "terminado" — y te da una red de seguridad. Si los tests no pasan, algo falla en la implementación.

Esto se llama TDD (desarrollo guiado por tests), o "pasar de rojo a verde" basado en los colores típicos del CLI para tests fallidos vs. aprobados. No es solo buena práctica — es como mantienes la honestidad de Claude.

Los Linters Atrapan Decisiones "Creativas"

ESLint, Prettier, Rubocop, markdownlint, yamllint — lo que se ajuste a tu stack. Configúralos con hooks de pre-commit de Git. Esto atrapa muchas de las decisiones estilísticas que toman los LLMs que no encajan con tu codebase.

Ejemplo: Claude adora saltarse la línea vacía entre un encabezado y una lista con viñetas en archivos markdown. Ni idea de por qué. Pero la práctica estándar es incluirla. Así que instalas markdownlint, configuras tus preferencias de reglas en un archivo de configuración, lo ejecutas en cualquier archivo markdown que Claude toque, y problema resuelto.

CLAUDE.md: El Manual de Instrucciones de Tu Proyecto

Crea un archivo CLAUDE.md en la raíz de tu proyecto con tus estándares de código, preferencias y contexto del proyecto. Claude lo lee automáticamente al inicio de cada sesión.

Pero no lo hagas demasiado grande. Los LLMs tienen una memoria a corto plazo sorprendentemente pobre comparada con las cosas aleatorias que aparentemente pueden sacar de la nada sobre eventos de hace 300 años (gracias, datos de entrenamiento). Mantenlo enfocado en tus preferencias y detalles clave del proyecto.

Ejecuta /init después de cualquier implementación grande de funcionalidad o refactorización para mantener CLAUDE.md actualizado. Claude te dirá si hay algo que añadir o actualizar, o simplemente dirá "se ve bien, no se necesitan cambios."

Errores Comunes de Principiante (Y Cómo Evitarlos)

1. Saltarse /terminal-setup

Te preguntarás por qué tus prompts detallados se sienten apretados. Solo ejecútalo.

2. Nunca usar /clear

Cada mensaje que envías incluye todo el contexto anterior. Después de terminar una tarea, limpia la pizarra. Tu factura de tokens te lo agradecerá.

3. Ser demasiado vago

"Arregla el bug" vs "Arregla la excepción de puntero nulo en auth.ts en la línea 42 donde se accede a user.id antes de la verificación de nulidad" — uno de estos te da mejores resultados.

4. Pedirle a Claude que cambie código que no ha leído

Siempre deja que Claude analice primero. "Lee el módulo de auth y explícame cómo funcionan las sesiones" antes de "reescribe la gestión de sesiones."

5. Meter tareas masivas en un solo prompt

"Reescribe toda la aplicación en TypeScript" es abrumador. Divídelo: "Convierte el módulo de usuario a TypeScript, luego haremos auth después."

6. No revisar /status

Si te preguntas por qué te están cobrando cuando tienes una suscripción, comprueba qué método de autenticación está activo.

7. Saltarse el Modo Plan

"Solo constrúyelo" se siente más rápido. No lo es. Shift+Tab dos veces y tómate cinco minutos para planificar — ahorra horas de deshacer trabajo que fue en la dirección equivocada.

8. Sin red de seguridad

Si no haces commits frecuentes, estás a una mala generación de una tarde frustrante. Haz commit antes de cambios grandes. Haz commit después de cambios exitosos. Los commits son gratis.

Qué Viene Después

Ahora tienes Claude Code instalado y entiendes no solo los comandos, sino la mentalidad que hace que la programación asistida por IA funcione. La estructura y las barreras no son restricciones — son lo que hace que la velocidad sea realmente útil en vez de caótica.

En Parte 2: El Modelo Mental, profundizaremos en cómo Claude Code realmente "piensa" — entendiendo ventanas de contexto, uso de herramientas y cómo estructurar tus prompts para obtener resultados consistentemente mejores. Este conocimiento transforma a Claude de un asistente a veces útil en un compañero de ingeniería confiable.