Cómo configurar Claude Code paso a paso

Claude Code es la herramienta de línea de comandos (CLI) de Anthropic que vive en tu terminal y entiende tu repositorio completo. Se distribuye como paquete npm global, así que necesitas Node.js 18 o superior. Comprueba tu versión con node --version antes de empezar; si estás por debajo, actualiza con nvm. La instalación es un único comando global. En macOS y Linux funciona directamente; en Windows debes trabajar dentro de WSL2 (Ubuntu), porque Claude Code espera un entorno POSIX. Una vez instalado, el binario claude queda disponible en cualquier directorio. Navega hasta la raíz de tu proyecto antes de lanzarlo, ya que Claude Code indexa los archivos desde donde lo ejecutas. Evita instalarlo con sudo: provoca problemas de permisos en la carpeta global de npm que luego cuesta revertir.

# Verifica Node
node --version

# Instala Claude Code globalmente
npm install -g @anthropic-ai/claude-code

# Comprueba la instalación
claude --version

La primera vez que ejecutes claude dentro de un proyecto, la CLI abrirá un flujo de autenticación en el navegador. Tienes dos vías: iniciar sesión con tu suscripción Claude (Pro o Max), que incluye uso de Claude Code sin configurar API key, o usar una clave de API con facturación por consumo si prefieres control granular del gasto. Para builders en España y LATAM que ya pagan Pro/Max, la opción de suscripción es la más rápida y no toca tarjetas adicionales. Si optas por API key, créala en console.anthropic.com y expórtala como variable de entorno. Claude Code guarda las credenciales de forma segura en tu sistema, así que solo autenticas una vez por máquina. El modelo por defecto es claude-opus-4-8; puedes cambiarlo durante la sesión con el comando /model si quieres uno más económico para tareas sencillas.

# Lanza Claude Code en la raíz del proyecto
cd ~/mi-proyecto
claude

# (Alternativa) Autenticación por API key
export ANTHROPIC_API_KEY="sk-ant-..."

CLAUDE.md es el corazón de la configuración: un archivo markdown que Claude Code lee automáticamente al arrancar y que funciona como memoria persistente de tu proyecto. Aquí describes la arquitectura, los comandos frecuentes, las convenciones de estilo y cualquier regla que quieras que respete en cada sesión. Puedes generarlo automáticamente con el comando /init, que analiza tu repo y propone una primera versión, o escribirlo a mano. Cuanto más específico seas, menos tendrás que repetirte: indica el gestor de paquetes, cómo se corren los tests, qué no debe tocar y el idioma de los commits. Coloca el archivo en la raíz. Si trabajas en un monorepo, puedes tener varios CLAUDE.md anidados por subcarpeta y Claude combinará el contexto relevante.

# CLAUDE.md

## Stack
- Node.js + TypeScript, gestor pnpm
- Framework: Next.js 15 (App Router)

## Comandos
- Instalar: `pnpm install`
- Tests: `pnpm test`
- Lint: `pnpm lint`

## Convenciones
- Commits en español, formato Conventional Commits
- No modificar archivos en /legacy sin confirmarlo
- Usar funciones puras y evitar any en TypeScript

Por defecto Claude Code pide confirmación antes de ejecutar comandos o editar archivos, lo cual es sensato pero puede ralentizar tu flujo. La configuración vive en .claude/settings.json dentro del proyecto (versionable y compartible con tu equipo) o en ~/.claude/settings.json para preferencias globales. Puedes definir una lista de comandos permitidos (allow) y denegados (deny) para que la herramienta actúe con autonomía en operaciones seguras y siga pidiendo permiso en las peligrosas, como borrados o pushes. Esto es clave si vas a usar el modo autónomo en tareas largas. Define siempre reglas de denegación para comandos destructivos. El archivo del proyecto tiene prioridad sobre el global, así que puedes relajar o endurecer la política según el repo.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm lint)",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)"
    ]
  }
}

El Model Context Protocol (MCP) permite a Claude Code hablar con herramientas externas: bases de datos, GitHub, Sentry, tu sistema de archivos o APIs internas. Añadir un servidor MCP amplía lo que la IA puede hacer sin salir de la terminal. Se registran con claude mcp add indicando un nombre y el comando que lanza el servidor. Hay servidores oficiales y de la comunidad para los servicios más habituales. Una vez conectado, puedes verificarlo con claude mcp list y Claude detectará automáticamente las herramientas disponibles. Empieza con un servidor sencillo, como el de sistema de archivos o GitHub, para entender el patrón antes de montar integraciones propias. Esta es la puerta de entrada a flujos realmente agénticos.

# Añadir el servidor MCP de GitHub
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Listar servidores conectados
claude mcp list

# Eliminar uno si hace falta
claude mcp remove github

Con todo configurado, lanza una tarea real para validar la instalación de punta a punta. Dentro de la sesión interactiva pídele a Claude que lea el proyecto y haga un cambio acotado, por ejemplo escribir un test o refactorizar una función. Observa cómo respeta las reglas de CLAUDE.md, pide confirmación según tus permisos y usa los servidores MCP cuando aplica. Usa comandos de barra útiles: /clear para limpiar el contexto entre tareas, /cost para ver el consumo de tokens y /review para que revise cambios. Si todo responde como esperas, tu entorno está listo para trabajo diario. Integra Claude Code en tu rutina lanzándolo al abrir cada proyecto; la curva de productividad sube mucho cuando el contexto ya está bien definido.

# Ejemplo de prompt dentro de la sesión
> Lee el proyecto y escribe tests unitarios para src/utils/fechas.ts
>   siguiendo las convenciones de CLAUDE.md

# Comandos útiles durante la sesión
/clear     # limpia el contexto
/cost      # muestra tokens y coste
/review    # revisa cambios pendientes