Cómo Usar Claude Code: El 90% de los Desarrolladores Lo Usa Mal
Guía práctica de Claude Code: errores comunes, configuración del contexto, y el marco de delegación controlada para developers.
El 90% de los Desarrolladores Usa Claude Code Como un ChatGPT Avanzado
Estáis pegados al terminal. Escribís prompts largos. Esperáis respuestas. Repetís.
*El problema real no es que Claude Code no funcione. Es que lo estáis usando como un buscador con esteroides.*
Claude Code no es un chatbot. Es un agente de ejecución que puede navegar vuestro sistema de archivos, ejecutar comandos, escribir código y modificar proyectos enteros. La diferencia entre usarlo bien y usarlo mal puede significar horas de trabajo ahorradas versus días perdidos depurando código que Claude generó sin contexto real.
La mayoría trata Claude Code como un substituto mejorado de Google. Le preguntan cómo hacer algo en lugar de pedirle que lo haga. Le pasan contexto零零碎碎 en vez de dejarlo explorar el proyecto directamente. Le permiten operar sin supervisión en lugar de establecer límites claros de actuación.
Este artículo os muestra cómo funciona Claude Code realmente. Cómo configurarlo para que tenga contexto real de vuestros proyectos. Y cómo evitar los errores que hacen que el 90% de los developers pierdan más tiempo del que ganan.
Qué Es Claude Code y Por Qué Es Diferente
Claude Code es la interfaz de línea de comandos (CLI) oficial de Anthropic para interactuar con Claude directamente desde el terminal. No es la API. No es la aplicación web de claude.ai. Es un ejecutable que instaláis en vuestro sistema y que permite conversaciones persistentes con acceso privilegiado al sistema de archivos y capacidad de ejecución.
La diferencia fundamental con otros flujos de trabajo es la persistencia del contexto y la capacidad de agente. Cuando iniciáis una sesión en Claude Code, el modelo mantiene memoria del estado actual, puede leer archivos de vuestro proyecto, ejecutar scripts, usar git, y modificar código directamente. No estáis pidiendo información. Estáis delegando tareas.
Instalarlo es directo:
```bash
npm install -g @anthropic-ai/claude-code
claude-code
```
Tras la instalación, os pregunta qué editor preferís ( Vim, Emacs, nano, o sin editor) y ya estáis dentro. El prompt cambia a un cursor parpadeante esperando input. Aquí es donde la mayoría empieza a escribir prompts como si estuvieran en ChatGPT. Error grave.
El Error Fatal: Tratarlo Como un Buscador
El patrón más común que veo en equipos que adoptan Claude Code es el mismo que ya repitieron con Copilot, con ChatGPT, con cada nueva herramienta: usan la IA para buscar información en vez de para ejecutar acciones.
❌ Patrón incorrecto:
```
> ¿Cómo implemento autenticación JWT en Express?
> ¿Cuál es la mejor estructura para un proyecto Next.js?
> ¿Cómo hago un deploy a Vercel?
```
Esto os da información. Información que Google os da mejor porque os muestra fuentes, documentación oficial, y debates de la comunidad. Claude Code no aporta valor extra aquí. Estáis usando un Ferrari para ir al supermercado.
✅ Patrón correcto:
```
> Crea un archivo auth/middleware.ts que valide JWT en las rutas /api/*
> Refactoriza la estructura de src/ para seguir el patrón de feature folders
> Despliega este proyecto a Vercel configurando las variables de entorno necesarias
```
Aquí estáis delegando. Claude tiene contexto del proyecto, puede leer archivos existentes, entender vuestra estructura, y ejecutar acciones concretas. El valor multiplicador aparece cuando le pedís que haga cosas, no que os explique cosas.
Configurar el Contexto: El Archivo .claude/
Claude Code busca automáticamente un directorio `.claude/` en la raíz del proyecto. Dentro puede tener tres archivos que definen cómo se comporta:
`CLAUDE.md` — Instrucciones globales para el proyecto. Aquí definís el stack tecnológico, convenciones de código, estructura de directorios, y cualquier regla específica que queréis que Claude respete siempre. Es el equivalente al system prompt pero específico del proyecto.
```markdown
CLAUDE.md
Stack: Next.js 16 + TypeScript strict + Tailwind CSS 4
Estructura: app/ (site) y app/ (studio)
Convenciones:
Server Components por defecto
'use client' solo cuando es necesario
Rutas dinámicas en [slug]
GROQ para queries a Sanity
No modificar: package.json, tsconfig.json
```
`CONTEXT.md` — Documentación adicional que Claude debe tener en cuenta. Manuales internos, documentación de APIs proprietarias, notas sobre arquitectura.
`instructions/` — Scripts automatizados que se ejecutan bajo ciertas condiciones. Por ejemplo, un script que verifica que todo commit sigue las convenciones deConventional Commits.
Esta configuración es la base. Sin ella, Claude opera con conocimiento genérico. Con ella, tiene las instrucciones específicas de vuestro proyecto y podeis delegarle tareas con precisión.
El Patrón de Interacción Dirigida
La sesión en Claude Code tiene tres modos de operación que debéis alternar según el objetivo. Usarlos correctamente es la diferencia entre automatización real y asistencia superficial.
ModoConsulta (Ask Mode): Activado con `/ask` o `-a`. Claude responde sin ejecutar nada. Útil para revisar código existente, explicar conceptos, o explorar opciones antes de actuar. No hace cambios, solo comunica.
Modo Comando (Command Mode): Activado con `/commit` o `-c`. Claude ejecuta las acciones que le habéis pedido. Puede escribir archivos, ejecutar scripts, hacer git commits. Requiere confirmación explícita antes de cada acción potencialmente destructiva.
Modo Agente (Agent Mode): Activado con `/agent` o `-g`. Claude opera de forma autónoma durante múltiples pasos. Lee archivos, modifica código, ejecuta comandos, todo para completar un objetivo complejo. Se supervisa a través de un log de acciones en tiempo real.
El flujo típico para una tarea compleja es:
1. Start en Ask Mode → explorar el problema, entender el contexto
2. Pasar a Command Mode → ejecutar cambios incrementales con confirmación
3. Para tareas repetitivas o bien definidas → usar Agent Mode con instrucciones claras
```bash
Consultar sin ejecutar
claude-code ask "Explica cómo funciona el sistema de cache en esta app"
// Ejecutar cambio específico con confirmación
claude-code commit "Refactoriza la función getUserProfile para usar caching"
// Operación autónoma con supervisión
claude-code agent "Actualiza todas las dependencias de package.json a sus últimas versiones compatibles"
```
Errores Comunes que Destruyen Productividad
El primer error es dar contexto insuficiente. Si le pedís a Claude que modifique código sin antes dejarlo explorar el proyecto, trabaja con su conocimiento genérico. El resultado es código que "funciona" pero no encaja con vuestra arquitectura.
Sed generosos con el contexto. Dejádselo leer. Escribid `/Read` seguido del path de archivos relevantes o directorios completos. Más contexto = código más preciso.
El segundo error es la falta de supervisión en Agent Mode. Cuando pedís una tarea compleja y dejáis a Claude ejecutarla sin revisar cada paso, el resultado puede ser desastroso. He visto proyectos con refactors completos donde se eliminaron carpetas enteras por malinterpretación del scope.
Supervisad siempre. Agent Mode tiene un log visual de cada acción. Si algo no tiene sentido, detenéis con Ctrl+C antes de que cause daño.
El tercer error es no usar el flag `--no-input` para tareas batch. Cuando tenéis procesos bien definidos que queréis ejecutar sin interacción, el flag desactiva el prompt interactivo:
```bash
claude-code commit "Aplicar formatter a todos los archivos .ts" --no-input
```
Útil para pipelines de CI/CD o scripts automatizados que ya saben exactamente qué necesitan.
Integración con el Flujo de Desarrollo
Claude Code brilla cuando se integra en vuestro workflow existente. Tres integraciones que aportan valor inmediato:
Git Integration: Claude detecta automáticamente cambios en el repo. Puede hacer commits con mensajes bien estructurados, crear branches, resolver merge conflicts, y describir cambios pending sin necesidad de `git diff`.
```bash
Resumir cambios pendientes
claude-code ask "Resume los cambios en este branch frente a main"
// Commit automatizado
claude-code commit "Commit con conventional commits" --message "feat: add user profile caching"
```
Shell Execution: Puede ejecutar comandos de terminal y reportar output. Esto significa que podeis pedirle que ejecute scripts de build, tests, o deployment y analice los resultados.
File Operations: Lee, escribe, renombra, mueve archivos. La diferencia con hacerlo manualmente es que puede hacerlo en contexto de todo el proyecto, manteniendo consistencia.
El Marco de Delegacion Controlada para Claude Code
Después de meses usando Claude Code en proyectos reales con equipos de developers en España, he definido un marco que maximiza resultados y minimiza riesgos. Lo llamo El Marco de Delegación Controlada.
Fase 1: Orientación
Antes de pedir algo a Claude, verificad que tiene contexto. Usad `/Read` para给它 archivos relevantes. Explicitád el stack y las restricciones en la petición. "Estamos en un proyecto Next.js 16 con TypeScript strict mode" no es opcional — es requisito.
Fase 2: Delimitación
Definid claramente qué puede y qué no puede modificar. "Modifica solo archivos dentro de src/features/auth/" previene que toque cosas fuera del scope. Sin delimitación, el código generado puede ser excelente pero irrelevante o destructivo.
Fase 3: Acción Gradual
Para tareas nuevas o con incertidumbre alta: pedid cambios incrementales. "Primero crea el archivo con la estructura básica" → "Ahora añade la lógica de validación" → "Finalmente integra con el resto del sistema". Cada paso se revisa antes de continuar.
Fase 4: Supervisión Activa
Nunca perdáis de vista lo que está haciendo. El log de Claude Code es vuestro safety net. Si algo no tiene sentido, intervenid. Un mensaje de error que no esperábais puede ser un indicator de malentendido en las instrucciones.
Fase 5: Verificación
Siempre verificad el output. No importa que Claude diga que todo está bien — ejecutad los tests, verificad que el código compila, revisad manualmente el resultado. Asumir que AI significa asumir que alguien revisa.
Este marco no es sobre desconfiar de Claude. Es sobre estructurar la colaboración para que sea efectiva. Un developer que sabe cómo delegar puede conseguir en una hora lo que manualmente tomaría tres.
Dónde Claude Code Fallará
Ser honestos sobre las limitaciones es crucial para no perder وقت( وقت ) tiempo en frustración.
No tiene acceso al navegador por defecto. Si necesitáis investigar algo online, debéis hacerlo vosotros o usar herramientas adicionales como el browser tool de la API.
La memoria de sesión es finita. Conversaciones muy largas empiezan a perder contexto earlier. Si vuestra sesión se extiende durante días, lo que se discutió en la primera hora puede no estar presente en la última.
No puede acceder servicios externos como APIs de producción o databases remotas sin configuración adicional. Puede escribir código que las usa, pero no probarlo contra el servicio real.
El código generado puede tener errores sutiles. Es mejor que hace dos años, pero sigue generando código que compila pero no hace lo que se pide. La verificación manual sigue siendo necesaria.
Resumen
Claude Code no es un chatbot mejorado. Es un agente de ejecución que puede navegar vuestros proyectos, ejecutar comandos, y modificar código. La diferencia entre developers que lo usan bien y los que no determinará si ahorráis horas o perderéis tiempo en código incorrecto.
Los puntos clave: configurad `.claude/` correctamente para dar contexto real. Usad los tres modos de operación según el objetivo. Supervisad siempre, especialmente en Agent Mode. Y aplicad el Marco de Delegación Controlada para estructurar la colaboración de forma efectiva.
El developer que sabe cómo delegar tareas a Claude Code tiene una ventaja brutal sobre el que sigue haciendo todo manualmente. Pero esa delegación efectiva requiere configuración, supervisión, y verificación. No es magia. Es disciplina.
Empezad hoy: instalad Claude Code, configurad un CLAUDE.md básico, y pedidle que os explique algo del proyecto que no entendéis bien. Veréis cómo el contexto compartido cambia completamente la calidad de la respuesta.
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