Empezar con Claude Code en 2026: de la instalación al primer commit

Qué es realmente Claude Code

Claude Code no es una interfaz de chat. Es un agente de línea de comandos que lee tu sistema de archivos, ejecuta comandos de bash, edita archivos e itera sobre su propia salida hasta alcanzar el objetivo que le describes. Lo arrancas dentro del directorio de un proyecto, le das una tarea, y va resolviendo el problema paso a paso — leyendo el código existente, haciendo cambios, ejecutando pruebas y volviendo atrás si algo falla.

La implicación práctica: Claude Code rinde mejor con problemas reales y acotados, dentro de bases de código reales. Pedirle «ayúdame con mi proyecto» genera deriva. Pedirle «añade validación de entrada a la función createUser en src/api/users.ts y actualiza las pruebas correspondientes» produce resultados.

Paso 1 — Instalar

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

Confirma que la instalación funcionó:

claude --version
# → claude-code 1.x.x

Si aparece un error de permisos en macOS o Linux, lo correcto es ajustar la propiedad del directorio global de npm en lugar de ejecutar npm con sudo. La documentación de Anthropic cubre esto en la sección de prerrequisitos. En Windows, abrir la terminal como administrador resuelve la mayoría de los errores de permisos, pero la ruta vía WSL2 es más estable para uso agéntico intensivo.

Paso 2 — Autenticarte

claude login

Esto abre una ventana del navegador para completar OAuth. Una vez completado, las credenciales quedan guardadas en ~/.claude/ y no tendrás que repetir este paso a menos que cambies de cuenta.

Si vas a usar una clave de API directamente — por ejemplo, en un entorno de CI o en una máquina sin navegador — define la variable de entorno en su lugar:

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

El nivel Claude Pro incluye una cuota mensual de tokens que cubre un uso individual moderado. Si vas a correr Claude Code sobre bases de código grandes, escribir pruebas extensas o ejecutarlo en bucles, lo más probable es que llegues al tope de Pro y necesites complementar con créditos de API. La consola de Anthropic muestra tu uso en tiempo real — revísala tras tus primeras sesiones para calibrar.

Paso 3 — Escribe tu CLAUDE.md

Un CLAUDE.md mínimo pero efectivo cubre cinco cosas:

# Project: [name]

## Stack
- Runtime: Node 20, TypeScript 5.3
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL via Prisma
- Tests: Vitest, run with `npm test`

## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint` — fix before committing
- Migrate: `npx prisma migrate dev`

## Rules
- All new API routes go in src/app/api/
- Zod for all input validation — no raw req.body access
- Never touch the /legacy/ directory
- Do not remove console.error calls in error handlers

## Do not
- npm install packages without asking first
- Modify .env files
- Run database migrations without confirmation

La sección «Do not» es la que la mayoría de desarrolladores se salta en su primera pasada — y es la que evita los errores caros. Si hay archivos que Claude no debe tocar nunca, nómbralos. Si hay comandos que no debe ejecutar de forma autónoma, dilo de forma explícita.

Para un tratamiento más a fondo de la estructura del CLAUDE.md, ver nuestro artículo sobre escribir un CLAUDE.md que de verdad funcione. El pack Septim Starter ($9) incluye una plantilla probada en producción para cinco tipos de proyecto comunes — Next.js, Python Flask, Rails, Go y Node a secas — para que no arranques desde un archivo en blanco.

Paso 4 — Dale una tarea real

cd ~/projects/my-app
claude

En el prompt, dale una tarea lo bastante específica para que tenga un estado-final claro. Buenas primeras tareas para principiantes:

• Añadir un limitador de tasa a la ruta /api/login — 5 intentos por minuto por IP, 429 al superar
• Escribir pruebas unitarias para cada función de src/lib/date-utils.ts — apuntando al 90% de cobertura de ramas
• Refactorizar src/components/UserTable.tsx para usar React Query en lugar de llamadas crudas a fetch

Claude Code va a leer los archivos relevantes, proponer cambios y pedir permiso antes de escribir en disco o ejecutar comandos. En la configuración por defecto va a confirmar antes de cualquier escritura — ese es el modo correcto para aprender. Puedes aflojar o apretar esos permisos en ~/.claude/settings.json una vez que entiendas el comportamiento de la herramienta.

Qué pasa durante el bucle agéntico

Una tarea típica de Claude Code recorre este ciclo:

1. Leer los archivos fuente relevantes para entender la estructura actual
2. Proponer un plan de implementación y listar los archivos que tocará
3. Escribir los cambios archivo por archivo, con explicación
4. Correr la suite de pruebas (si está configurada en CLAUDE.md) e iterar sobre los fallos
5. Reportar la finalización y listar cada archivo modificado

En tareas directas — añadir un campo a un formulario, escribir una pequeña función utilitaria, arreglar un error de tipos — esto corre en menos de dos minutos. En tareas mayores (refactorizar un módulo, añadir una funcionalidad de extremo a extremo), planifica entre 5 y 15 minutos y unas cuantas rondas de iteración.

Paso 5 — Revisa tus costos

La consola de Anthropic en console.anthropic.com muestra tu uso de tokens desglosado por modelo y fecha. Tras tus primeras dos o tres sesiones, revisa el panel para entender tu ritmo de gasto antes de empezar a usar Claude Code para tareas más largas.

Los tres patrones que disparan costos inesperados:

• Archivos grandes en contexto. Si Claude Code lee un archivo de 10.000 líneas para responder una pregunta sobre una sola función, pagaste por 10.000 líneas de tokens de entrada. Apúntalo a archivos específicos en lugar de hacerle preguntas amplias sobre todo el código base.
• Reconstrucción repetida del contexto. Cada mensaje nuevo en una sesión vuelve a enviar todo el historial de conversación. Las sesiones largas se ponen caras. Arranca sesiones nuevas para tareas no relacionadas, en lugar de seguir una sola sesión todo el día.
• Aparición de subagentes. Claude Code puede lanzar subagentes para trabajo en paralelo. Cada subagente trae su propio contexto. Si corres varios agentes, tu costo escala en consecuencia. La guía del Tokenocalipsis cubre esto en detalle — ver el desglose de costos de subagentes.

Una tarea de programación bien acotada cuesta típicamente entre $0,05 y $0,40 en créditos de API, dependiendo del tamaño y la complejidad de los archivos. Una sesión donde le pides a Claude Code que entienda todo tu código base antes de hacer nada puede costar varios dólares. El CLAUDE.md que escribiste en el paso 3 reduce ese segundo patrón de forma importante — el contexto pre-suministrado reemplaza tokens que de otra forma se gastarían en exploración.

Errores frecuentes en la primera sesión

Pedirle a Claude Code «mira mi proyecto y dime qué está mal»

Esto quema la ventana de contexto en una expedición de pesca. La salida es una revisión genérica que puede identificar problemas reales, pero a un costo de tokens significativo. Usa Septim Drills ($29) para ejercicios estructurados de revisión de código, o apunta Claude Code a un archivo concreto con una pregunta concreta.

No leer el plan antes de aprobarlo

Claude Code propone un plan antes de ejecutar. Léelo. En tareas complejas, el plan a veces incluye pasos que no aprobarías — eliminar una tabla, quitar una capa de caché, tocar un archivo que excluiste de forma explícita. Cazar eso en la fase de plan es gratis. Cazarlo después de que las escrituras se hicieron es un git revert.

Ejecutarlo sin control de versiones

Claude Code escribe en disco. Córrelo solo en repositorios con un árbol de trabajo limpio para poder hacer git diff de cada cambio y git checkout . a cualquier cosa que no te convenza. Si todavía no usas git, inicializa un repositorio antes de empezar tu primera sesión.

Saltarse el CLAUDE.md

Sin un CLAUDE.md, Claude Code infiere el contexto del proyecto explorando archivos. Esa inferencia cuesta tokens y muchas veces se equivoca sobre las convenciones, los comandos prohibidos y los runners de pruebas. Los 20 minutos que inviertas en el CLAUDE.md del paso 3 te van a ahorrar más que eso a lo largo de tu primera semana de uso.

Adónde ir después

Una vez que hayas completado unas cuantas tareas con éxito, el siguiente paso natural es extender Claude Code con servidores MCP — integraciones que le dan acceso a herramientas externas como tu base de datos, GitHub o un navegador. Ver el tutorial de servidores MCP para un recorrido práctico.

Si estás corriendo Claude Code dentro de un equipo y quieres montar revisión automatizada de PRs, la guía de configuración de revisión de PRs cubre la configuración del GitHub Action de extremo a extremo.

Para gestión de costos a escala — una vez que pases la fase de principiante y uses Claude Code a diario — ver la guía de monitoreo de costos y el artículo sobre gestión de contexto.