Claude Code Tutorial 2026: El 90% de los Desarrolladores Confunde un Agente con un Chat
Claude Code tutorial 2026: deja de usarlo como un chat. Aprende el patrón de interacción dirigida, la arquitectura tool-use y el framework CLAUDE.md para dominarlo.
Claude Code No Te Ayuda a Escribir Código. Toma Tu Terminal, Ejecuta Tus Tests, y Hace Commit Por Ti
La pregunta no es si funciona.
*La pregunta es si estás listo para dejar de ser el que controla. *
El 90% de los desarrolladores que empiezan con Claude Code lo tratan como un ChatGPT con acceso a ficheros.
Le piden que genere una función. Copian el código. Lo pegan. Ejecutan los tests manualmente.
*Eso no es usar Claude Code. Eso es usar un chat con esteroides. *
Claude Code opera como un agente CLI autónomo. Lee tu repositorio completo. Escribe y edita ficheros. Ejecuta comandos en tu terminal. Gestiona git. Corre tests y te devuelve los resultados.
No es una herramienta de autocompletado. No es un chat con superpoderes.
*Es un ingeniero de software trabajando contigo en tu terminal. *
Y si lo tratas como un chat, estás dejando el 80% de su potencial sobre la mesa.
---
El Error Fatal: Tratarlo Como un Buscador
La mayoría venís de Copilot o Cursor. Herramientas que operan en una sola línea, una función, un fichero.
Pedís: "genera una función que valide emails".
Claude Code lo hace. Copiáis. Pegáis. Siguiente.
❌ *Eso es buscar. No es construir. *
Claude Code tiene capacidad de contexto a nivel de proyecto. Puede escanear codebases enteros antes de tocar una línea. Entiende la arquitectura, los patrones existentes, las dependencias entre ficheros.
Si le pedís "renombra el campo `user_id` a `owner_id` en toda la base de datos", no os devuelve 15 snippets para que los cambiéis a mano.
Lo hace él. En 15 ficheros. Y ejecuta los tests para verificar que todo sigue funcionando.
✅ Eso es delegar. Eso es usar un agente.
El cambio mental es sutil pero brutal: *dejas de preguntar "cómo escribo esto" y empiezas a preguntar "es esto correcto" *.
Tu trabajo ya no es picar código. Tu trabajo es revisar decisiones.
---
Configurar el Contexto: El Archivo CLAUDE.md
Antes de pedir nada, configura el contexto de tu proyecto.
Claude Code lee un fichero `CLAUDE.md` en la raíz de tu repositorio. Ahí defines las reglas, patrones y convenciones de tu proyecto.
```markdown
CLAUDE.md - Reglas del proyecto
Stack
Next.js 16 con App Router
Supabase para base de datos y autenticación
Resend para emails transaccionales
Tailwind CSS para estilos
Convenciones
Nombrado: camelCase para variables, PascalCase para componentes
Tests: cada módulo debe tener cobertura mínima del 80%
Commits: conventional commits (feat:, fix:, chore:)
Path alias: usar @/ para imports locales
Restricciones
No modificar ficheros en /lib/migrations sin aprobación explícita
No cambiar interfaces de API públicas sin discusión previa
Mantener compatibilidad con Node 20+
```
Esto no es un prompt decorativo. Es la memoria del proyecto. Claude Code lo consulta antes de cada acción.
*Sin CLAUDE.md trabajas con un agente que no conoce tu proyecto. *
Con CLAUDE.md trabajas con un agente que sabe cómo quieres que se hagan las cosas.
---
El Patrón de Interacción Dirigida
El error más común es lanzar prompts abiertos y esperar magia.
❌ "Refactoriza el código para que sea más limpio"
Esto es vago. Claude Code no sabe qué significa limpio para ti. Va a tomar decisiones arquitectónicas que deberías tomar tú.
✅ "Refactoriza `src/middleware/auth.ts` para usar async/await. Mantén todas las interfaces existentes. No cambies la API pública."
Esto es interacción dirigida. Le dices el fichero, el cambio, y las restricciones.
El patrón tiene tres fases:
1. Delimita el Alcance
Sé específico con los ficheros. No dejes que Claude Code escanee 200 ficheros si el cambio afecta a uno.
```bash
Mal: no acotas nada
claude "refactoriza validación"
Bien: acotas fichero y cambio
claude "refactoriza src/utils/validation.ts para usar Zod en lugar de Joi, mantén la misma API de exportación"
```
2. Usa el Sistema de Permisos
Claude Code no ejecuta nada sin tu aprobación. Bueno, no debería.
Tiene un sistema de permisos por niveles:
Lectura: siempre permitida
Escritura de ficheros: requiere aprobación (puedes ver el diff antes)
Ejecución de comandos: requiere aprobación (puedes ver el comando antes)
Git operations: requiere aprobación explícita
*Esto no es un obstáculo. Es tu red de seguridad. *
Aprueba escrituras en lote, pero revisa cada diff. Nunca apruebes ejecución de comandos sin leerlos antes.
```bash
Claude Code muestra:
┌─────────────────────────────────────────────┐
│ File write: src/utils/validation.ts │
│ +38 lines, -12 lines │
│ Command to execute: npm test │
│ │
│ [A]pprove write [S]kip [D]eny [V]iew │
└─────────────────────────────────────────────┘
```
3. Iteración Progresiva
No esperes que la primera respuesta sea perfecta.
Claude Code brilla en el refinamiento progresivo. Empieza con un cambio pequeño, revisa, ajusta, amplía.
```bash
Primera iteración
claude "añade tipos TypeScript a src/utils/helpers.ts"
Segunda iteración
claude "ahora exporta esos tipos desde src/types/index.ts"
Tercera iteración
claude "genera tests para las nuevas funciones con vitest"
```
Cada iteración construye sobre la anterior. Así es como se usan los agentes de verdad.
---
Demostración en Código: El Loop de Observar y Corregir
Vamos al código. Aquí tienes un ejemplo real de cómo usar Claude Code para refactorizar una función legacy.
Antes: código legacy con callback hell
```typescript
// src/services/user-service.ts
function fetchUserData(userId: string, callback: (err: Error | null, data?: any) => void) {
db.query('SELECT * FROM users WHERE id = ?', [userId], (err, results) => {
if (err) return callback(err);
const orders = [];
db.query('SELECT * FROM orders WHERE user_id = ?', [userId], (err, orderResults) => {
if (err) return callback(err);
orders.push(...orderResults);
db.query('SELECT * FROM payments WHERE user_id = ?', [userId], (err, paymentResults) => {
if (err) return callback(err);
callback(null, { user: results[0], orders, payments: paymentResults });
});
});
});
}
```
Prompt para Claude Code:
```
Refactoriza src/services/user-service.ts para usar async/await con prisma.
Mantén la misma lógica de negocio. No cambies la interfaz de llamada externa.
Usa try-catch para el manejo de errores.
```
Después: el resultado con Claude Code
```typescript
// src/services/user-service.ts
import { prisma } from '@/lib/prisma';
export interface UserData {
user: any;
orders: any[];
payments: any[];
}
export async function fetchUserData(userId: string): Promise<UserData> {
try {
const [user, orders, payments] = await Promise.all([
prisma.user.findUnique({ where: { id: userId } }),
prisma.order.findMany({ where: { userId } }),
prisma.payment.findMany({ where: { userId } }),
]);
if (!user) throw new Error(`User ${userId} not found`);
return { user, orders, payments };
} catch (error) {
console.error(`Error fetching user data for ${userId}:`, error);
throw error;
}
}
```
Claude Code no solo reescribió la función. Eliminó 20 líneas de callback hell, introdujo `Promise.all` para paralelizar queries, y añadió manejo de errores consistente.
*El agente no escribe código nuevo. Elimina complejidad. *
Esa es la métrica que importa: líneas eliminadas, no líneas escritas.
---
Bonus: El Prompt Que Te Ahorra Semanas de Onboarding
Claude Code brilla en un sitio donde casi nadie lo usa: legacy code comprehension.
Tira este prompt contra un repositorio que no conozcas:
```
Eres mi lead engineer. Analiza este repositorio y dame:
1. Arquitectura general (carpetas, patrones, flujo de datos)
2. Dependencias principales y por qué se eligieron
3. Puntos de entrada y salida del sistema
4. Antipatrones que detectes
5. Recomendaciones priorizadas de mejora
```
En segundos tienes un análisis que a un junior le llevaría semanas.
*El bottleneck no es escribir código. Es entender código. *
Claude Code cambia eso.
---
El Framework CLAUDE.md para 2026
Aquí tienes el marco que uso en todos mis proyectos. Llamadlo El Patrón CLAUDE.md:
| Letra | Significado | Acción |
|-------|-------------|--------|
| C | Contexto | Escribe CLAUDE.md con reglas del proyecto antes de la primera interacción |
| L | Límite | Delimita alcance por fichero y por tarea — no dejes que escanee sin control |
| A | Aprobar | Usa el sistema de permisos en niveles: diffs primero, comandos después |
| U | Un paso | Una iteración por prompt — refina progresivamente, no en un solo intento |
| D | Depurar | Ejecuta tests automáticos tras cada cambio — Claude Code puede hacerlo |
| E | Evaluar | Revisa el resultado como si fuera código de un junior — tú eres el senior |
*Cinco letras. Seis pasos. Una regla: no delegues el juicio, delega la ejecución. *
---
Lo Que Viene
El mercado de agentes CLI está explotando. Anthropic lanzó Claude Code. xAI acaba de lanzar Grok Build. Cada semana aparece un nuevo competidor.
Pero el principio es el mismo en todos: *un agente no es un chat. Un agente ejecuta. Tú supervisas. *
Los desarrolladores que entiendan esta diferencia van a multiplicar su productividad por un orden de magnitud.
Los que sigan copiando y pegando desde un chat van a quedarse atrás.
La herramienta no importa tanto como el cambio mental.
*Claude Code es solo el principio. La pregunta es si estás listo para dejar de ser el que pica código y empezar a ser el que decide qué código merece la pena picar. *
Lee el artículo completo en brianmenagomez.com
Más sobre mis servicios en brianmenagomez.com
Herramientas: Conversor IAE CNAE · Gestorias cerca de ti · Calculadora IRPF