Guía completa de Claude Code: De cero a dominar la ingeniería con agentes de IA

En las oficinas de Anthropic, la herramienta que está redefiniendo el desarrollo de software ya no la programan ingenieros humanos línea por línea: Claude escribe aproximadamente el 90% del código de su propia herramienta, Claude Code.

No se trata de una cifra de marketing ni de una estimación lejana. En apenas tres meses, el equipo de ingeniería de Anthropic logró duplicar el volumen de cambios aceptados en su monorepo mientras que el porcentaje de modificaciones que tuvieron que revertirse por fallos cayó en más de un 40%.

La herramienta que utilizan sus creadores es exactamente la misma que cualquier desarrollador o empresa puede instalar hoy en su máquina. Sin embargo, la diferencia entre quien solo aprovecha un 10% de su capacidad y quien alcanza un 90% de eficiencia no radica en saber programar mejor, sino en comprender cómo piensa un agente de inteligencia artificial por dentro, cómo gestionar su contexto y cómo orquestar su trabajo en bucles autónomos de alta precisión.

Parte 0 · Qué es Claude Code y la Revolución del Bucle Agéntico

La inmensa mayoría de las personas asocia la inteligencia artificial con un cuadro de texto en un navegador web. En ChatGPT o en la interfaz clásica de Claude, el flujo es puramente conversacional: le formulas una consulta, el modelo responde con párrafos o fragmentos de código, y eres tú quien debe seleccionar, copiar, pegar en el editor, ejecutar la terminal, verificar si compila y volver al navegador a reportar los errores.

Claude Code rompe de raíz ese paradigma. No te da instrucciones teóricas: ejecuta el trabajo directamente en tu entorno.

La analogía más clara para comprenderlo es sencilla:

• Un chat tradicional es un consultor senior al que llamas por teléfono: te da consejos técnicos brillantes, pero el teclado y el ratón los manejas tú.
• Claude Code es ese mismo consultor sentado físicamente en tu ordenador, con acceso directo a tu teclado, tu terminal y tu sistema de archivos.

Su funcionamiento se fundamenta en un bucle agéntico estricto: Lee → Piensa → Actúa → Comprueba. Abre archivos, analiza colisiones, aplica parches y ejecuta los tests unitarios. Si encuentra un error, lee el log de la terminal y vuelve a intentar la solución de forma autónoma hasta que el código funcione a la perfección.

Parte 1 · Instalación Rápida y Modos de Despliegue

Para comenzar a operar requieres una cuenta activa de Claude (planes Pro, Max, Team o Enterprise) o bien créditos de API en la consola de Anthropic.

Existen tres formas oficiales de utilizarlo:

1. La App de Escritorio (La vía más accesible): Descarga la aplicación de Claude para Mac o Windows y dirígete a la pestaña Code. Te permite interactuar visualmente seleccionando cualquier carpeta local sin tocar líneas de comando complejas.
2. Entorno Web en la Nube (claude.ai/code): Conecta tus repositorios de GitHub para delegar tareas pesadas de refactorización. La sesión corre en la infraestructura de Anthropic, por lo que puedes cerrar tu portátil y el agente continuará trabajando.
3. La Terminal CLI (El estándar para desarrolladores): El modo de máxima velocidad, automatización y scripting.

# Instalación en macOS y Linux:
curl -fsSL https://claude.ai/install.sh | bash

# Instalación en Windows (PowerShell):
irm https://claude.ai/install.ps1 | iex

# Para iniciar sesión dentro de cualquier carpeta:
claude

Parte 2 · La Ventana de Contexto: Tu Mesa de Trabajo Digital

Si solo retienes un concepto clave de esta guía, debe ser este: la inteligencia artificial no tiene memoria infinita; trabaja sobre una mesa de trabajo con límites estrictos, lo que en ciencia computacional se conoce como ventana de contexto.

Encima de esa mesa coexisten las directrices de tu proyecto (CLAUDE.md), los archivos abiertos, el historial de conversación, los logs de consola y los esquemas de herramientas MCP. Cuando la mesa se satura de información obsoleta, el agente se distrae, alucina y comete fallos evitables.

Por eso, la higiene de la mesa es fundamental:

• /clear: Limpia la mesa por completo. Regla de oro: Una sola tarea por conversación. Tarea nueva, /clear inmediato.
• /compact: Resume la conversación y libera tokens sin perder los acuerdos arquitectónicos clave.
• /context: Permite auditar exactamente qué archivos o herramientas están devorando tu espacio de memoria.

Parte 3 · CLAUDE.md: El Manual de Bienvenida del Proyecto

El archivo CLAUDE.md es el documento en Markdown ubicado en la raíz del repositorio que Claude Code lee automáticamente al arrancar cada conversación. Actúa como el manual de inducción para un nuevo desarrollador.

Para generarlo de forma automática según la estructura de tu proyecto, ejecuta en la terminal:

/init

Lo que sí debes incluir: Comandos exactos de prueba (npm test), carpetas prohibidas (/pagos o /migrations) y estilo de código. Lo que no debes incluir: Documentación kilométrica que exceda una pantalla, pues consumirá espacio innecesario en cada consulta.

Parte 4 · El Método de 5 Pasos para Resultados Consistentes

Quienes obtienen resultados de calidad profesional no ordenan tareas a ciegas. Aplican religiosamente el método de 5 etapas:

1. Explorar: Ordenar al agente que investigue sin modificar archivos: «Lee cómo funciona el módulo de autenticación. No cambies nada todavía.»
2. Planificar: Activar el Modo Plan pulsando Shift + Tab. En este estado, el agente redacta una propuesta técnica detallada que puedes revisar y ajustar antes de autorizar cualquier cambio.
3. Implementar: Con el plan aprobado, se otorga luz verde para la edición del código.
4. Verificar: Exigir validación empírica: «Ejecuta las pruebas unitarias y demuéstrame que funciona.»
5. Guardar: Revisar el diff y asentar los cambios mediante commits limpios en Git.

Controles de emergencia: Si notas que el agente toma una dirección equivocada, pulsa la tecla Esc una vez para frenarlo en seco. Si pulsas Esc dos veces (o usas /rewind), volverás al punto previo de la conversación revirtiendo los cambios en disco.

Parte 5 · Arquitectura de Tres Cerebros: Opus 5.5, Sonnet 5.5 y Haiku 5.5

Mediante el comando /model puedes elegir qué modelo asignas a cada tipo de desafío. Usar el modelo más caro para tareas rutinarias destruye la rentabilidad de tus operaciones.

• Opus 5.5 (El Arquitecto): Máximo razonamiento. Ideal para diseñar planes iniciales, resolver problemas lógicos intrincados y auditar seguridad.
• Sonnet 5.5 (El Constructor): El equilibrio ideal entre velocidad y calidad para la implementación cotidiana de software.
• Haiku 5.5 (El Rápido): 75% más económico que sus versiones previas y ultra veloz. Diseñado para subagentes de búsqueda, organización y tareas mecánicas.

Parte 6 · La Caja de Herramientas: De Asistente a Equipo de Ingeniería

Para transformar a Claude de un asistente aislado a un equipo completo de desarrollo, dispones de cinco piezas modulares:

1. Skills (SKILL.md): Recetas de trabajo estandarizadas. Adoptadas por más de 70 plataformas (Cursor, ChatGPT, Copilot), solo cargan su contenido cuando la tarea lo amerita.
2. Subagentes (/agents): Instancias delegadas que resuelven tareas en mesas de trabajo aisladas y solo devuelven el resultado final, protegiendo tu contexto principal.
3. Hooks (/hooks): Reglas que se ejecutan obligatoriamente en el sistema operativo antes o después de una acción.
4. MCP (Model Context Protocol): Conectores universales (claude mcp add) hacia GitHub, Slack, bases de datos o navegadores.
5. Plugins (/plugin): Paquetes listos para instalar que integran skills, hooks y herramientas de la comunidad.

Parte 7 · Concurrencia y Paralelismo: De Asistente a Equipo de Ingeniería

Para maximizar el rendimiento, los desarrolladores avanzados no esperan a que un agente termine una tarea para iniciar la siguiente. Coordinan múltiples sesiones concurrentes mediante Git Worktrees, lo que permite que una sesión desarrolle una funcionalidad en una rama mientras otra corrige errores en otra rama sobre directorios físicos separados.

Adicionalmente, herramientas como /btw permiten formular preguntas secundarias sin contaminar la sesión principal; /loop repite comprobaciones periódicas; /schedule programa rutinas cron en la nube; y claude -p "..." habilita la ejecución en modo headless para integraciones CI/CD continuas.

Parte 8 · Seguridad y Code Review: La Arquitectura Interna de Anthropic

Cuando un agente posee permisos para alterar código y ejecutar comandos, la seguridad no puede depender de la intuición humana.

El Pipeline de Revisión Multicapa de Anthropic

En su investigación técnica «How the Claude Code team does code review», los ingenieros de Anthropic compartieron el protocolo que les permitió escalar a más de 30.000 cambios diarios con el 90% del código generado por IA:

1. Verify First (Capa Local Pre-PR): El agente debe superar linters, builds y pruebas antes de abrir cualquier PR.
2. AI Review en cada Pull Request: Un grupo de agentes busca fallos en paralelo, mientras un comité de agentes verificadores vota para suprimir comentarios irrelevantes y reportar solo defectos críticos.
3. Escaneos de Seguridad y CI Obligatorio: Filtros automáticos bloquean inyecciones SQL, vulnerabilidades OWASP y fallos de permisos.
4. Aprobación Humana Escalonada por Riesgo: Cambios de bajo riesgo (documentación o código tras feature flags) no requieren firmas humanas (0 aprobaciones). Cambios medios exigen 1 aprobación humana, y cambios críticos de infraestructura exigen 2 aprobaciones de ingenieros senior.
5. Prevención de Bucles Infinitos: Límite estricto de 3 rondas de revisión entre IAs, auditando únicamente los diffs nuevos para evitar discusiones redundantes.
6. De Incidentes a Evals: Cada fallo que llega a producción se convierte en un benchmark automatizado para que ningún agente vuelva a cometerlo.
7. Responsabilidad Final: La regla de oro en Anthropic es inmutable: «You land it, you own it» (quien aprueba el cambio asume la responsabilidad integral del código).

Parte 9 · Los 10 Errores Críticos de Principiante y sus Soluciones

1. Mezclar tareas en la misma sesión: Resuelve siempre con /clear entre objetivos.
2. Pedir código sin contexto de negocio: Explica el impacto comercial y las dependencias operativas de lo que solicitas.
3. Omitir la fase de planificación: Utiliza siempre el modo plan (Shift + Tab) para tareas de más de diez minutos.
4. No exigir validación empírica: Termina siempre con «demuéstrame que los tests pasaron».
5. Archivos CLAUDE.md sobrecargados: Mantén las directrices en menos de una pantalla vertical.
6. Usar Opus para tareas mecánicas: Combina Opus para planificar, Sonnet para codificar y Haiku para rastrear.
7. Instalar plugins sin auditoría previa: Recuerda que los plugins tienen acceso directo a tu entorno.
8. Permitir que el agente avance por un camino erróneo: Interrumpe inmediatamente con Esc ante las primeras desviaciones.
9. Aprobar comandos por fatiga sin leer: Confía en el modo automático desacoplado para filtrar operaciones peligrosas.
10. Reiterar la misma instrucción periódicamente: Documenta cualquier flujo recurrente como una Skill permanente (SKILL.md).

Parte 10 · La Chuleta Maestra de Comandos y Reglas de Oro

Comando	Función Operativa
/init	Inspecciona el proyecto y genera el borrador de CLAUDE.md.
/clear	Limpia la ventana de contexto para iniciar una nueva tarea limpia.
/compact	Condensa el historial reteniendo las decisiones técnicas esenciales.
Shift + Tab	Alterna entre el modo de ejecución y el modo de planificación segura.
Esc / /rewind	Frena la ejecución o revierte las modificaciones de archivos a un punto previo.
/model	Alterna entre los modelos Opus 5.5, Sonnet 5.5 y Haiku 5.5.
/agents	Configura y gestiona subagentes especializados con contexto independiente.
claude mcp add	Conecta el agente con herramientas externas y bases de datos vivas.
/code-review	Ejecuta una auditoría integral de calidad y estilo previa al commit.