Instalación y primer proyecto

En este módulo dejas Claude Code instalado, autenticado y haces tu primera sesión real con un repositorio de prueba. Al terminar tendrás una sesión funcional y un CLAUDE.md generado automáticamente.

Objetivos

• Instalar Claude Code en macOS, Linux o Windows (WSL).
• Autenticarte con tu cuenta de Anthropic.
• Crear un CLAUDE.md automáticamente con /init.
• Hacer tu primer ciclo Read → Plan → Edit → Verify.
• Salir, reanudar y mantener un historial de sesiones.

2.1 Pre-requisitos

Antes de instalar, asegúrate de tener:

• Node.js 18 o superior. Verifica con node --version. Si no lo tienes, instálalo con nvm (recomendado) o desde nodejs.org.
• Git 2.30+. Verifica con git --version. Disponible por defecto en macOS y la mayoría de distros Linux.
• Cuenta de Anthropic con plan Pro, Team, Enterprise o crédito API en console.anthropic.com.
• Terminal moderna. En macOS: Terminal o iTerm2. En Windows: PowerShell o WSL2 (recomendado WSL2 con Ubuntu).

2.2 Instalación de la CLI

La instalación es un único comando vía npm. La CLI se publica en el paquete @anthropic-ai/claude-code.

Una vez termine, comprueba que se ha registrado el binario:

Deberías ver algo similar a 2.4.x (Anthropic, Inc.). Si el comando no se encuentra, repasa el PATH de tu shell y asegúrate de que $(npm prefix -g)/bin está incluido.

Alternativa con Homebrew (macOS)

Esta vía instala la app de escritorio de Claude Code, que incluye la CLI integrada y un panel gráfico. Útil si prefieres una interfaz sobre el terminal.

Verificación final

El comando doctor diagnostica problemas habituales: versión de Node, permisos, conectividad, autenticación. Es lo primero que debes ejecutar si algo no va.

2.3 Autenticación

Hay dos métodos de autenticación según tu plan:

A) Plan Pro/Team/Enterprise — login OAuth

El comando abre tu navegador, te lleva a claude.com y, tras introducir credenciales, devuelve un token a la CLI. El token se guarda en ~/.claude/auth.json con permisos restringidos (chmod 600).

B) Plan API — variable de entorno

Si pagas por API en lugar de tarifa plana, exporta tu key en el shell:

export ANTHROPIC_API_KEY=sk-ant-api03-...

# Para hacerla permanente:
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

2.4 Primera sesión

Vamos a usar un repositorio de práctica. Si no tienes uno, clona este repo público (Express.js sencillo):

Entra al directorio y arranca Claude Code:

cd express-typescript-boilerplate
claude

Verás algo así:

╭───────────────────────────────────────────────╮
│  ✻ Welcome to Claude Code (v2.4.0, Opus 4.7) │
│                                               │
│  cwd: ~/express-typescript-boilerplate        │
│  /help para ver comandos · /exit para salir   │
╰───────────────────────────────────────────────╯

> 

Estás en una sesión interactiva. El cursor está esperando tu primer prompt.

2.5 /init — generar tu primer CLAUDE.md

Antes de pedir cambios, conviene que Claude Code genere un fichero CLAUDE.md a partir del repo. Este fichero le servirá de contexto persistente: contiene un resumen del proyecto, comandos clave, y reglas que aplicarán en futuras sesiones.

Dentro de la sesión, escribe:

> /init

Claude Code va a:

1. Leer package.json, README.md, tsconfig.json, .gitignore.
2. Recorrer la estructura de carpetas con Glob.
3. Hacer git log para entender estilo de commits.
4. Generar un CLAUDE.md con secciones: Overview, Commands, Architecture, Style, Pitfalls.

Ejemplo del fichero generado (resumido):

# CLAUDE.md

## Overview
Express.js + TypeScript boilerplate. Punto de entrada `src/index.ts`.
Servidor HTTP en puerto 3000 (configurable vía PORT).

## Commands
- `npm run dev` — arranca con ts-node-dev (hot reload)
- `npm run build` — compila TypeScript a `dist/`
- `npm test` — ejecuta jest
- `npm run lint` — eslint con config Airbnb

## Architecture
- `src/index.ts` — bootstrap del servidor
- `src/routes/` — definición de rutas
- `src/middlewares/` — middlewares de Express
- `src/utils/` — helpers compartidos

## Style
- TypeScript estricto (`strict: true`)
- ESLint con Airbnb config
- Imports relativos, no alias
- Tests con jest, archivos `*.test.ts` junto al código

## Pitfalls
- El handler de errores global está en src/middlewares/error.ts.
  No lanzar throw sin pasar por next(err).
- Variables sensibles en .env (NO commitear)

2.6 Tu primer ciclo Read → Plan → Edit → Verify

Vamos a pedir un cambio sencillo: añadir un endpoint /health que devuelva el estado del servidor.

> Añade un endpoint GET /health que devuelva
  {"status":"ok","uptime":process.uptime()} en JSON.
  Inclúyelo en src/routes/, registralo en src/index.ts,
  y añade un test que verifique 200 y la forma del JSON.

Claude Code va a:

1. Read. Leer src/routes/index.ts, src/index.ts, los tests existentes para entender el patrón.
2. Plan. Declarar: "voy a crear src/routes/health.ts, registrarlo, y crear src/routes/health.test.ts".
3. Edit. Crear los dos archivos y añadir 1 línea a src/index.ts.
4. Verify. Ejecutar npm test y comprobar que el nuevo test pasa.

Cuando termine, revisa el diff con:

Si te convence, lo commiteas tú (Claude Code no commitea por defecto):

git add .
git commit -m "feat: añade endpoint /health"

2.7 Salir y reanudar

Para salir de la sesión: escribe /exit o pulsa Ctrl+D.

Cuando vuelvas a ejecutar claude en el mismo directorio, la herramienta:

• Carga automáticamente el CLAUDE.md.
• Te ofrece reanudar la conversación anterior con /resume (lista las últimas sesiones por fecha).
• Si no la reanudas, empiezas con contexto limpio pero con CLAUDE.md cargado.

Comandos útiles para gestionar el historial:

Los transcripts se guardan en ~/.claude/projects/<path-del-proyecto>/ en formato JSONL. Puedes consultarlos sin abrir Claude Code: cada línea es un mensaje.

2.8 Configuración inicial: settings.json

Hay tres niveles de configuración. Por orden de precedencia:

Ejemplo mínimo de un settings.json de proyecto:

{
  "model": "claude-opus-4-7",
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run build)", "Bash(git status)"],
    "deny": ["Bash(rm -rf *)", "Bash(git push *)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Las claves más usadas:

• model — modelo por defecto. Sobrescribible con /model.
• permissions.allow — comandos que se ejecutan sin pedir confirmación.
• permissions.deny — comandos bloqueados aunque el agente lo pida.
• env — variables de entorno aplicadas a todos los Bash del agente.
• hooks — scripts disparados por eventos (Módulo 8).

Práctica

Test de comprensión

Resumen

• Instalación: npm install -g @anthropic-ai/claude-code + claude doctor para verificar.
• Autenticación: claude login (Pro/Team/Enterprise) o ANTHROPIC_API_KEY (API).
• /init genera un CLAUDE.md inicial. Edítalo a mano para añadir convenciones del equipo.
• Ciclo Read → Plan → Edit → Verify visible en cada sesión.
• Tres niveles de settings: usuario global, proyecto compartido, proyecto local.

En el Módulo 3 desmenuzamos cada herramienta del agente: Read, Glob, Grep, Edit, Write, Bash. Verás cuándo usa cada una y cómo guiarle para que use la mejor.