Claude Code para principiantes: guía práctica desde la terminal

Un agente de programación que vive en la terminal

Durante años, la forma habitual de usar inteligencia artificial para programar consistió en copiar fragmentos de código en una ventana de chat, esperar una respuesta y pegarla de vuelta en el editor. Ese flujo funciona para dudas puntuales, pero se rompe en cuanto el problema involucra varios archivos, dependencias entre módulos o pruebas que hay que ejecutar para confirmar que algo realmente funciona.

Claude Code, la herramienta de Anthropic para desarrollo asistido, propone otro enfoque. En lugar de recibir el código a pedazos, trabaja directamente sobre el repositorio local: lee archivos, busca referencias, ejecuta comandos, corre las pruebas y propone cambios coordinados en varios ficheros a la vez. Es lo que suele llamarse un agente, porque no se limita a responder, sino que planifica y ejecuta pasos para alcanzar un objetivo.

Esta guía recorre todo lo necesario para empezar con buen pie: instalación en cada sistema operativo, primera sesión, modos de permisos, memoria del proyecto con CLAUDE.md, comandos esenciales, integración con Git, automatización desde scripts y una serie de errores frecuentes con su solución. Los comandos y opciones corresponden a la documentación oficial vigente al momento de escribir.

En qué se diferencia de un chat de IA convencional

La diferencia más importante es el acceso al contexto. Un chat solo conoce lo que el usuario le pega, mientras que Claude Code puede recorrer la estructura del proyecto por su cuenta y descubrir cómo se relacionan los módulos. Si se le pide que cambie el formato de una fecha en la API, puede localizar la función que la genera, los serializadores que la consumen y las pruebas que la validan, sin que nadie tenga que enumerarlos.

La segunda diferencia es la capacidad de actuar. Además de leer, puede editar archivos, ejecutar comandos de shell, lanzar la suite de pruebas y observar el resultado para corregir su propio trabajo. Ese ciclo de proponer, ejecutar y verificar es el que convierte una sugerencia en un cambio funcional.

La tercera es el control. Todas esas acciones pasan por un sistema de permisos configurable, de modo que el desarrollador decide qué se ejecuta sin preguntar y qué requiere aprobación explícita. Entender ese sistema es tan importante como saber escribir buenas instrucciones, y se trata en detalle más adelante.

Además de la terminal, Claude Code está disponible como aplicación de escritorio, en la web, como extensión de VS Code y de los IDE de JetBrains, y en flujos de CI/CD con GitHub Actions o GitLab. Esta guía se centra en la interfaz de línea de comandos, que es la base de todas las demás.

Requisitos previos y cuentas compatibles

Antes de instalar conviene confirmar que el equipo cumple los requisitos. La documentación oficial indica soporte para macOS 13.0 o superior, Windows 10 1809 o superior (y Windows Server 2019 o superior), Ubuntu 20.04 o superior, Debian 10 o superior y Alpine Linux 3.19 o superior. Se recomiendan al menos 4 GB de RAM, un procesador x64 o ARM64 y conexión a internet. La herramienta funciona con Bash, Zsh, PowerShell o CMD.

En cuanto a la cuenta, Claude Code requiere una suscripción Pro, Max, Team o Enterprise, o bien una cuenta de Claude Console con créditos de API. El plan gratuito de claude.ai no incluye acceso. También es posible usarlo a través de proveedores en la nube como Amazon Bedrock, Google Cloud o Microsoft Foundry, una opción frecuente en empresas que ya centralizan su consumo de modelos en esas plataformas.

Por último, hace falta un proyecto con el que trabajar. Cualquier repositorio sirve, aunque para las primeras pruebas conviene elegir uno pequeño y bajo control de versiones, de forma que cualquier cambio pueda revertirse con Git.

Instalación en macOS, Linux y Windows

El método recomendado es el instalador nativo, que descarga un binario autónomo y lo mantiene actualizado en segundo plano. En macOS, Linux o WSL basta con un comando:

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

Para instalar Claude Code en Windows de forma nativa existen dos variantes según la consola. En PowerShell se usa:

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

Y en CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

No hace falta ejecutar la consola como administrador. En Windows nativo se recomienda instalar Git for Windows, porque aporta Git Bash y permite a Claude Code usar su herramienta de shell Bash; sin él, recurre a PowerShell. Quien prefiera un entorno Linux puede instalar dentro de WSL con el comando de Linux, y en ese caso Git for Windows no es necesario.

También hay alternativas basadas en gestores de paquetes. Con Homebrew existen dos casks: claude-code, que sigue el canal estable, y claude-code@latest, que recibe cada versión en cuanto se publica. En Windows está disponible en WinGet, y en Debian, Fedora, RHEL y Alpine hay repositorios firmados para apt, dnf y apk.

brew install --cask claude-code

winget install Anthropic.ClaudeCode

La instalación mediante npm sigue disponible para quien la necesite. Hay un cambio relevante respecto a guías antiguas: el paquete instala el mismo binario nativo que el instalador y exige Node.js 22 o superior, pero el binario resultante no depende de Node en tiempo de ejecución. Nunca debe instalarse con sudo, porque provoca problemas de permisos y riesgos de seguridad.

npm install -g @anthropic-ai/claude-code

Verificar la instalación y mantenerla actualizada

Al terminar el instalador conviene abrir una terminal nueva para que se recargue el PATH y comprobar la versión:

claude --version

La salida muestra un número de versión seguido del nombre de la herramienta:

2.1.211 (Claude Code)

Si la consola responde que el comando no existe, casi siempre se debe a que el directorio de instalación no está en el PATH. Para un diagnóstico más completo existe claude doctor, que revisa la salud de la instalación, valida los archivos de configuración y sugiere correcciones sin iniciar una sesión.

claude doctor

Las instalaciones nativas se actualizan solas en segundo plano, y el cambio surte efecto en el siguiente arranque. Para forzar la actualización inmediata se usa claude update. Las instalaciones con Homebrew, WinGet o gestores de Linux no se actualizan automáticamente por defecto, de modo que hay que ejecutar brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode o el comando equivalente de cada distribución.

Quien prefiera estabilidad frente a novedad puede cambiar de canal. El ajuste autoUpdatesChannel admite latest, el valor por defecto, o stable, que sirve versiones con aproximadamente una semana de antigüedad y omite las que presentaron regresiones graves:

{
    "autoUpdatesChannel": "stable"
}

Primera sesión: autenticación y exploración del proyecto

Con la herramienta instalada, el siguiente paso es situarse en la carpeta del proyecto e iniciar una sesión:

cd ~/proyectos/biblioteca-api
claude

La primera vez se abre el navegador para iniciar sesión con la cuenta de Claude o de Console. Las credenciales quedan guardadas, por lo que no será necesario repetir el proceso. Si la variable de entorno ANTHROPIC_API_KEY está definida, Claude Code pregunta una vez si debe usarla en lugar de abrir el navegador. Para cambiar de cuenta más adelante basta con escribir /login dentro de la sesión.

Una vez dentro, lo más útil es dejar que el agente explore antes de pedir cambios. No hace falta adjuntar archivos: los lee a medida que los necesita. Algunas preguntas iniciales eficaces son:

¿Qué hace este proyecto y cuáles son sus módulos principales?

¿Dónde está el punto de entrada y cómo se ejecutan las pruebas?

Explica cómo fluye una petición desde la ruta HTTP hasta la base de datos.

Las respuestas a estas preguntas no solo orientan al desarrollador; también permiten verificar si el agente ha entendido bien la arquitectura antes de confiarle modificaciones.

Un proyecto de ejemplo para practicar

Para los ejemplos de esta guía se usará una pequeña API en Python que gestiona préstamos de libros. Su estructura es la siguiente:

biblioteca-api/
├── CLAUDE.md
├── pyproject.toml
├── src/
│   └── biblioteca/
│       ├── __init__.py
│       ├── main.py
│       ├── modelos.py
│       └── prestamos.py
└── tests/
    ├── test_modelos.py
    └── test_prestamos.py

El módulo prestamos.py contiene la lógica de negocio, incluida una función que calcula la fecha de devolución:

from datetime import date, timedelta

DIAS_PRESTAMO = 14

def fecha_devolucion(inicio: date, renovaciones: int = 0) -> date:
    return inicio + timedelta(days=DIAS_PRESTAMO * renovaciones)

La función tiene un error intencionado: cuando no hay renovaciones devuelve la misma fecha de inicio, en lugar de sumar el periodo base. Es el tipo de fallo sutil que sirve para practicar la depuración asistida más adelante.

Pedir cambios de código con instrucciones precisas

La calidad del resultado depende en buena medida de cómo se formula la petición. Una instrucción vaga como “arregla los préstamos” obliga al agente a adivinar. Una instrucción concreta describe el síntoma, el comportamiento esperado y las restricciones:

La función fecha_devolucion en src/biblioteca/prestamos.py devuelve la misma
fecha de inicio cuando renovaciones es 0. Debería sumar 14 días por el préstamo
inicial más 14 días por cada renovación. Corrige la función y añade pruebas
que cubran 0, 1 y 3 renovaciones.

Claude Code localiza el archivo, muestra el cambio propuesto y, según el modo de permisos activo, pide confirmación antes de aplicarlo. Un resultado razonable sería:

from datetime import date, timedelta

DIAS_PRESTAMO = 14

def fecha_devolucion(inicio: date, renovaciones: int = 0) -> date:
    if renovaciones < 0:
        raise ValueError("Las renovaciones no pueden ser negativas")
    return inicio + timedelta(days=DIAS_PRESTAMO * (1 + renovaciones))

Para tareas grandes conviene dividir el trabajo en pasos numerados. Así el agente puede completar y verificar cada etapa antes de pasar a la siguiente:

1. Añade un campo "multa_diaria" al modelo Prestamo.
2. Crea una función que calcule la multa según los días de retraso.
3. Expón un endpoint GET /prestamos/{id}/multa que devuelva el importe.
4. Escribe pruebas para cada paso y ejecútalas.

Un hábito muy recomendable es revisar cada cambio propuesto antes de aprobarlo, al menos durante las primeras semanas. El agente es capaz, pero no infalible, y la revisión humana sigue siendo la última línea de defensa.

Modos de permisos y control de lo que se ejecuta

Cada sesión funciona en un modo de permisos que define qué acciones pueden realizarse sin preguntar. Los modos disponibles en la versión actual son los siguientes:

Un cambio importante respecto a versiones anteriores es el modo auto. En lugar de que el usuario apruebe cada acción, un segundo modelo clasificador revisa las operaciones y bloquea las arriesgadas. En los planes Pro, Max y Team es el modo inicial por defecto en la terminal, mientras que con Enterprise o con una clave de Console se empieza en modo Manual.

Durante la sesión, la combinación Shift+Tab rota entre los modos disponibles y la barra de estado indica cuál está activo. También puede fijarse al arrancar:

claude --permission-mode plan

Usar el modo plan antes de editar es una práctica excelente cuando se aborda una parte desconocida del código. En ese modo el agente analiza y propone un plan detallado sin tocar nada, lo que permite corregir el rumbo antes de que se escriba una sola línea. Desde la propia sesión se puede entrar con /plan seguido de la descripción de la tarea.

Reglas de permisos en settings.json

Los modos establecen la base, y las reglas permiten afinar. En el archivo .claude/settings.json del proyecto, o en ~/.claude/settings.json para todos los proyectos del usuario, se definen listas de herramientas permitidas, denegadas o que siempre deben preguntar:

{
    "permissions": {
        "allow": ["Bash(pytest *)", "Bash(git status)", "Bash(git diff *)"],
        "ask": ["Bash(git push *)"],
        "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
    }
}

Con esta configuración, ejecutar pruebas o consultar el estado de Git no interrumpe el flujo, publicar cambios en el remoto siempre requiere confirmación y leer el archivo de variables de entorno queda prohibido. Las reglas de denegación se aplican en todos los modos, incluso en bypassPermissions, lo que las convierte en la herramienta adecuada para proteger secretos.

El comando /permissions abre un diálogo interactivo para consultar y editar estas reglas sin tocar el JSON a mano. También se puede fijar un modo inicial por proyecto con la clave permissions.defaultMode.

Memoria del proyecto con CLAUDE.md

Cada sesión empieza con una ventana de contexto vacía. Para no repetir una y otra vez cómo se ejecutan las pruebas o qué convenciones sigue el equipo, Claude Code carga automáticamente archivos de instrucciones al inicio. El más importante es el archivo CLAUDE.md del proyecto, que se guarda en la raíz del repositorio y se comparte con el resto del equipo a través de Git.

La forma más rápida de crearlo es el comando /init, que analiza el código y genera un primer borrador con comandos de compilación, instrucciones de prueba y convenciones detectadas. Si el archivo ya existe, sugiere mejoras en lugar de sobrescribirlo. Un ejemplo para el proyecto de muestra sería:

# Biblioteca API

## Comandos

- Instalar dependencias: `pip install -e ".[dev]"`
- Ejecutar pruebas: `pytest -q`
- Lint: `ruff check src tests`

## Convenciones

- Código y nombres de variables en español.
- Toda función pública lleva anotaciones de tipo.
- Cada cambio en src/ debe ir acompañado de pruebas en tests/.

## Arquitectura

- La lógica de negocio vive en src/biblioteca/prestamos.py.
- main.py solo define rutas; no añadir lógica allí.

@docs/decisiones-arquitectura.md

La última línea muestra la sintaxis de importación: un @ seguido de una ruta incorpora otro archivo al contexto. Existen además otras ubicaciones con propósitos distintos. El archivo ~/.claude/CLAUDE.md guarda preferencias personales para todos los proyectos, y CLAUDE.local.md en la raíz contiene ajustes personales de un proyecto concreto que conviene añadir a .gitignore. Para proyectos grandes, la carpeta .claude/rules/ permite dividir las instrucciones en archivos temáticos, como testing.md o api.md.

La documentación recomienda mantener cada archivo por debajo de unas 200 líneas, ya que un texto más largo consume contexto y reduce la adherencia a las instrucciones. Si un repositorio ya usa AGENTS.md, Claude Code puede leerlo cuando no existe un CLAUDE.md. Aparte de estos archivos, la herramienta mantiene una memoria automática con aprendizajes que extrae de las correcciones del usuario, y el comando /memory permite revisarla, editarla o desactivarla.

Comandos esenciales dentro de la sesión

Los comandos slash más útiles se escriben al inicio del mensaje y controlan la propia sesión. Escribir / muestra el menú completo con filtrado por texto. Los más habituales para quien empieza son:

Algunos atajos de teclado complementan estos comandos. La tecla Tab completa nombres de comandos, la flecha hacia arriba recupera mensajes anteriores y Shift+Tab cambia de modo de permisos. Para salir también puede pulsarse Ctrl+D dos veces.

El comando /rewind merece mención especial para principiantes. Funciona como un sistema de puntos de control: si una serie de cambios no convence, permite regresar al estado previo tanto de la conversación como del código, sin depender exclusivamente de Git.

Uso desde la línea de comandos y automatización

Además del modo interactivo, el binario acepta argumentos que lo vuelven útil en scripts. Los más importantes son:

# Iniciar sesión interactiva con una tarea ya planteada
claude "corrige el error de compilación en el módulo de préstamos"

# Consulta puntual que imprime la respuesta y termina
claude -p "resume en tres líneas qué hace src/biblioteca/prestamos.py"

# Continuar la conversación más reciente en este directorio
claude -c

# Elegir una conversación anterior para retomarla
claude -r

El modo -p permite integrarlo en tuberías de Unix. Por ejemplo, se puede pasar la salida de un comando como contexto:

git diff main --stat | claude -p "resume estos cambios para la descripción de un pull request"

En integración continua conviene combinar -p con el modo dontAsk y una lista explícita de herramientas permitidas, de modo que el agente solo pueda ejecutar exactamente lo que se espera:

claude -p "ejecuta las pruebas y explica cualquier fallo" \
  --permission-mode dontAsk \
  --allowedTools "Bash(pytest *)" "Read"

Esta combinación evita que un prompt mal formulado o un contenido inesperado en el repositorio desencadenen acciones fuera del alcance previsto.

Git como parte de la conversación

Claude Code entiende Git y puede operar con él en lenguaje natural, lo que resulta especialmente cómodo para tareas tediosas como redactar mensajes de commit descriptivos:

¿Qué archivos he modificado desde el último commit?

Crea una rama llamada fix/fecha-devolucion y haz commit de los cambios
con un mensaje que explique el error corregido.

Ayúdame a resolver los conflictos de la fusión con la rama main.

Una estrategia sensata es trabajar siempre en ramas dedicadas y dejar las operaciones que afectan al remoto, como git push, bajo la regla ask mostrada antes. De este modo el historial local puede reorganizarse con libertad, pero nada llega al repositorio compartido sin una revisión consciente.

El comando /review analiza el diff de la rama actual o un pull request concreto y señala posibles problemas, mientras que /security-review se centra en vulnerabilidades como inyecciones, fallos de autenticación o exposición de datos en los cambios de la rama.

Depuración y pruebas de forma autónoma

Una de las capacidades más valiosas es el ciclo de depuración completo. En lugar de describir el error y esperar una suposición, se puede pedir al agente que reproduzca el fallo, lo corrija y confirme el arreglo:

Ejecuta pytest. Si hay fallos, identifica la causa raíz, corrígela
y vuelve a ejecutar las pruebas hasta que pasen. No modifiques las pruebas
para que pasen; corrige el código.

En el proyecto de ejemplo, la primera ejecución mostraría algo parecido a esto:

FAILED tests/test_prestamos.py::test_sin_renovaciones - AssertionError: assert datetime.date(2026, 11, 2) == datetime.date(2026, 11, 16)
1 failed, 7 passed in 0.12s

El agente lee el mensaje, abre la función implicada, detecta que falta sumar el periodo inicial, aplica la corrección y vuelve a lanzar la suite:

8 passed in 0.10s

La aclaración final del prompt es importante. Sin ella, un agente podría elegir el camino corto de ajustar la prueba en lugar del código. Explicitar esa restricción es una buena costumbre en cualquier tarea de corrección.

Habilidades personalizadas para tareas repetitivas

Cuando una secuencia de pasos se repite a menudo, como preparar una versión o revisar un endpoint nuevo, conviene empaquetarla como habilidad. Una habilidad es una carpeta dentro de .claude/skills/ con un archivo SKILL.md que describe cuándo usarla y qué hacer:

.claude/
└── skills/
    └── nuevo-endpoint/
        └── SKILL.md

---
name: nuevo-endpoint
description: Crea un endpoint REST nuevo en la API de biblioteca siguiendo las convenciones del proyecto.
---

1. Añade la ruta en src/biblioteca/main.py sin lógica de negocio.
2. Implementa la lógica en el módulo correspondiente con anotaciones de tipo.
3. Crea pruebas en tests/ para el caso feliz y para los errores.
4. Ejecuta pytest y ruff, y corrige cualquier fallo antes de terminar.

Una vez creada, se invoca escribiendo /nuevo-endpoint seguido de la descripción de la tarea. Al estar en el repositorio, el resto del equipo la recibe con el siguiente git pull, lo que ayuda a estandarizar la forma en que todos trabajan con el agente.

Gestión del contexto en sesiones largas

El contexto del modelo es amplio, pero no infinito. En sesiones largas, la conversación acumula lecturas de archivos, salidas de comandos y mensajes previos que ocupan espacio y pueden diluir la atención sobre la tarea actual.

Hay tres herramientas para gestionarlo. El comando /context muestra cuánto espacio está ocupado y qué lo consume. El comando /compact resume lo hablado hasta el momento y libera espacio sin perder el hilo; admite instrucciones opcionales para indicar qué debe conservar el resumen. El comando /clear empieza de cero, algo recomendable cuando se cambia por completo de tarea.

Una pauta práctica es abrir una conversación nueva para cada tarea independiente. Mezclar en la misma sesión una corrección de errores, una refactorización y la redacción de documentación suele producir resultados peores que tratarlas por separado.

Errores comunes y cómo resolverlos

El primer obstáculo habitual es que el comando claude no se reconozca tras instalarlo. La causa casi siempre es el PATH: hay que abrir una terminal nueva y, si persiste, revisar que el directorio de instalación esté incluido. En Windows, otro error frecuente es usar el comando de CMD en PowerShell o al revés; el mensaje indicando que && no es un separador válido revela que se está en PowerShell, mientras que un aviso de que irm no se reconoce indica que se está en CMD.

Un segundo problema es intentar usar la herramienta con una cuenta gratuita de claude.ai, que no incluye acceso. La solución pasa por una suscripción compatible o una cuenta de Console. Al instalar con npm, un aviso EBADENGINE indica una versión de Node.js inferior a la 22; la instalación termina igualmente, pero conviene actualizar Node para evitar sorpresas.

Un tercer escenario es que el agente ignore instrucciones del CLAUDE.md. Suele deberse a archivos demasiado largos o con reglas contradictorias. Reducir el texto, eliminar duplicados y trasladar las reglas específicas a .claude/rules/ mejora la adherencia. Si se necesita garantizar que una acción nunca ocurra, lo correcto es una regla deny o un hook, no una instrucción en lenguaje natural.

Por último, las sesiones que se vuelven lentas o pierden el foco casi siempre tienen el contexto saturado. Un /compact o una conversación nueva suelen resolverlo, y claude doctor ayuda cuando el problema parece de configuración o instalación.

Buenas prácticas de seguridad

Un agente que ejecuta comandos en la máquina del desarrollador merece las mismas precauciones que cualquier herramienta con ese nivel de acceso. La primera regla es proteger los secretos: denegar la lectura de archivos .env, carpetas de credenciales y claves privadas mediante reglas deny.

La segunda es reservar los modos más permisivos para entornos aislados. El modo bypassPermissions y la opción --dangerously-skip-permissions deberían usarse únicamente dentro de contenedores o máquinas virtuales, nunca en el equipo personal con acceso a cuentas y datos reales.

La tercera es desconfiar del contenido externo. Archivos descargados, issues de terceros o páginas web pueden contener instrucciones diseñadas para manipular a un agente. Revisar qué se le pide procesar y mantener operaciones sensibles bajo confirmación reduce ese riesgo. En Linux, macOS y WSL 2 existe además un sandbox para los comandos Bash que limita lo que pueden alcanzar.

Finalmente, trabajar siempre sobre un repositorio con control de versiones y en ramas dedicadas garantiza que cualquier cambio pueda revisarse y revertirse.

Claude Code frente a otras alternativas

Las herramientas de IA para programar se agrupan en varias familias. Los asistentes de autocompletado integrados en el editor sugieren líneas o bloques mientras se escribe; son rápidos y poco intrusivos, pero no ejecutan comandos ni coordinan cambios entre muchos archivos. Los chats web resultan útiles para preguntas conceptuales, aunque obligan a copiar contexto manualmente.

Los agentes de terminal como Claude Code ocupan otro espacio: tareas que requieren explorar el repositorio, modificar varios archivos y verificar el resultado ejecutando código. En la práctica muchos desarrolladores combinan enfoques, con autocompletado para la escritura diaria y un agente para refactorizaciones, depuración o tareas de mantenimiento más amplias.

La elección depende del tipo de trabajo. Para un cambio puntual de una línea, abrir un agente puede ser excesivo; para migrar un módulo completo o investigar un error que atraviesa varias capas, la capacidad de actuar y verificar marca una diferencia notable.

Conclusiones

Claude Code traslada la asistencia de IA desde una ventana de chat al lugar donde realmente ocurre el desarrollo: el repositorio y la terminal. Su capacidad para explorar el proyecto, ejecutar comandos y comprobar sus propios cambios lo convierte en un colaborador útil para depurar, refactorizar y automatizar tareas repetitivas.

Empezar requiere pocos pasos: instalar con el instalador nativo, iniciar sesión con una cuenta compatible y dedicar las primeras conversaciones a que el agente comprenda el código. A partir de ahí, un CLAUDE.md conciso, reglas de permisos bien definidas y el modo plan para las partes desconocidas forman la base de un flujo de trabajo productivo y seguro.

La clave está en tratarlo como a un compañero capaz pero que necesita indicaciones claras y supervisión. Instrucciones específicas, tareas divididas en pasos, revisión de los cambios y protección de los secretos permiten aprovechar su potencia sin renunciar al control sobre el código.