Herramientas IA

Guía Completa de Claude Code 2026: De los Fundamentos a la Arquitectura Multi-Agente

Claude Code es el asistente de programación IA de Anthropic, ahora evolucionado a un sistema operativo IA completo. Esta guía cubre los cuatro modos de permisos, evolución automática de Skills, integración MCP, arquitectura multi-agente y control de costos — con diagramas y ejemplos.

Guía Completa de Claude Code 2026: De los Fundamentos a la Arquitectura Multi-Agente

Claude Code es el asistente de programación IA de línea de comandos de Anthropic que lee y escribe tu código completo, ejecuta comandos de shell y llama APIs externas directamente desde la terminal. En 2025/2026 ha evolucionado mucho más allá de la autocompletación de código, convirtiéndose en un sistema operativo IA completo capaz de gestionar desarrollo, marketing y flujos de trabajo de automatización. Esta guía te lleva desde los conceptos básicos hasta la arquitectura multi-agente avanzada.

Última actualización: 27 de marzo de 2026 · Sintetizado de 31 fuentes de investigación práctica


Tabla de Contenidos

  1. Últimas Actualizaciones 2025/2026
  2. Cuatro Modos de Permisos y Plan Mode
  3. Gestión de Contexto y CLAUDE.md
  4. Sistema de Skills y Auto-Evolución
  5. Sistema de Hooks
  6. Integración MCP y Optimización de Costos
  7. Arquitectura Multi-Agente
  8. Control de Costos en la Práctica
  9. Tres Casos de Uso Reales

¿Cuáles son las Novedades Más Importantes de Claude Code 2026?

Respuesta directa: En 2025/2026, Claude Code añadió el modo Dispatch remoto, /by the way para preguntas secundarias durante tareas, tareas programadas /loop, Fast Mode y Automemory estructurada — convirtiendo el asistente IA de una “herramienta de chat” en un agente autónomo que puede ejecutarse 24/7 en segundo plano.

Cambios Importantes y Nuevas Funcionalidades

FunciónDescripciónMejor para
Modo Dispatch RemotoEnvía instrucciones desde la app móvil de Claude; tu PC las ejecuta en segundo planoIniciar tareas de análisis fuera del escritorio
/by the wayHaz preguntas secundarias durante una tarea sin contaminar la conversación principalConsultas rápidas durante tareas largas
/loop Tareas ProgramadasEjecuta prompts de forma recurrente (ej. resumen diario de PRs)Reportes automatizados, monitoreo
Fast Mode~3x costo, 2.5x velocidad de generaciónProcesamiento paralelo de alto volumen
Effort LevelsAlterna entre profundidad de razonamiento baja/media/alta/UltraAdapta el cómputo a la complejidad
Automemory MejoradaEscritura estructurada de memoria (regla + motivación + aplicación)Retención de contexto entre sesiones

Arquitectura del Modo Dispatch Remoto

Beneficio real: Claude Code actúa como asistente personal 24/7 sin necesidad de ejecutar ningún servidor propio.


¿Cómo Elegir entre los Cuatro Modos de Permisos de Claude Code?

Respuesta directa: Alterna entre modos con Shift + Tab. Usa Edit automatically para el desarrollo diario (el equilibrio perfecto). Cambia siempre a Plan Mode antes de comenzar funcionalidades complejas — es de solo lectura y únicamente genera planos de arquitectura, sin tocar archivos. La investigación muestra que planificar primero ahorra en promedio 10 veces en costos de refactorización.

Presiona Shift + Tab para alternar entre los cuatro modos:

Por Qué Plan Mode es el Más Valioso

Plan Mode es de solo lectura: Claude investiga, lee todo el código relevante y produce un plano detallado — estructura de archivos, dependencias, pasos de implementación — sin modificar nada.

💡 Regla de oro: "Un minuto de planificación ahorra diez minutos de construcción"

Cambios de arquitectura en Plan Mode  Gratis
Refactorizar código incorrecto después  Desperdicia muchos Tokens + tiempo

Flujo de trabajo recomendado:


¿Cómo Gestionar la Memoria de Claude con CLAUDE.md?

Respuesta directa: CLAUDE.md es un archivo de instrucciones que se carga automáticamente al inicio de cada conversación — piénsalo como la “configuración del cerebro” de Claude. Colócalo en ~/.claude/ para reglas globales, o en la raíz del proyecto para reglas específicas del proyecto. Principio más importante: pon las reglas más críticas al principio (sesgo de primacía), mantén el total en 200–500 líneas, y nunca pegues documentación API completa.

CLAUDE.md: Tu Archivo de Configuración del Cerebro IA

CLAUDE.md define las pautas de comportamiento de Claude y se carga antes de cada sesión.

~/.claude/CLAUDE.md          → Reglas globales (todos los proyectos)
./CLAUDE.md                  → Reglas del directorio raíz del proyecto
./src/CLAUDE.md              → Reglas de subdirectorio (sobreescribe el padre)

Sesgo de Primacía

La investigación muestra que los modelos de lenguaje recuerdan el inicio del archivo de manera más confiable. Aprovecha esto:

# ⚠️ REGLAS ABSOLUTAS — NUNCA VIOLAR (¡pon estas primero!)

1. Nunca uses rutas relativas
2. Nunca modifiques el directorio themes/ directamente
3. Todas las operaciones de base de datos deben usar consultas parametrizadas

# Reglas Generales
...otras reglas abajo...

Mejores Prácticas de CLAUDE.md

Comandos de Gestión de Memoria

ComandoFunciónCuándo usarlo
/contextVer uso actual de tokensVerificar costos periódicamente
/clearBorrar completamente la memoria de conversaciónAl cambiar a una nueva tarea
/compact [qué conservar]Comprimir historial de conversaciónPreservar decisiones clave, liberar espacio

Ejemplo:

# Conservar decisiones de arquitectura, borrar todo lo demás
/compact conservar solo esquema de base de datos y decisiones de diseño API

¿Qué son los Skills de Claude Code y Cómo se Auto-Evolucionan?

Respuesta directa: Los Skills son conjuntos de instrucciones que encapsulan flujos de trabajo repetitivos, almacenados en carpetas individuales bajo ~/.claude/skills/. Cada Skill consume solo ~60 Tokens en reposo (divulgación progresiva) y se carga completamente solo cuando se activa. El uso avanzado combina con el framework Autoresearch de Andrej Karpathy para auto-evaluar, optimizar y hacer commit de la mejor versión en segundo plano.

Los Skills son el mecanismo central para encapsular flujos de trabajo repetitivos en procesos automatizados.

Arquitectura de Divulgación Progresiva

En reposo: ~60 Tokens por skill Al activarse: Carga todos los recursos relacionados

Estructura de Directorios de Skills

~/.claude/skills/
└── article-writing/
    ├── SKILL.md              # Instrucciones principales (con frontmatter YAML)
    ├── scripts/
    │   └── check-seo.py      # Scripts de ayuda
    ├── references/
    │   └── brand-voice.md    # Documentos de referencia
    └── assets/
        └── template.html     # Archivos de recursos

Frontmatter YAML del SKILL.md

---
name: article-writing
description: >
  Write blog articles with SEO optimization,
  proper headings, and brand voice compliance.
  Triggered when user asks to write, draft, or
  create any article or blog post.
version: 1.2.0
---

# Article Writing Skill

## Gotchas ⭐
<!-- ¡La sección más valiosa de cualquier Skill! -->
- Nunca uses signos de interrogación en los títulos
- El conteo de palabras debe superar 1500 o el puntaje SEO cae
- El texto alt de las imágenes debe contener la palabra clave principal

## Flujo de Trabajo
1. Analizar palabras clave objetivo
2. Generar esquema (confirmar antes de escribir)
...

Auto-Evolución (Autoresearch)

Combinado con el framework Autoresearch de Andrej Karpathy, los Skills pueden aprender y mejorar automáticamente:

Principio clave: Los criterios de evaluación deben ser preguntas objetivas sí/no, no juicios subjetivos — para que la IA pueda puntuar y optimizar automáticamente.


¿Cómo Previenen los Hooks que la IA Ejecute Comandos Peligrosos?

Respuesta directa: Los Hooks son lógica de interceptación insertada antes/después de que Claude ejecute herramientas, configurada en settings.json. El más útil es PreToolUse: puede bloquear comandos como rm -rf y DROP TABLE, o bloquear directorios específicos (ej. themes/) para evitar modificaciones accidentales. Una vez configurado, Claude muestra un mensaje de bloqueo antes de ejecutar cualquier operación de alto riesgo.

Los Hooks te permiten insertar lógica personalizada antes y después de las operaciones de Claude — la última línea de defensa.

Tipos de Hooks

Ejemplos Prácticos de Hooks

Interceptor de seguridad (/careful):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo '${tool.input.command}' | grep -qE '(rm -rf|DROP TABLE|kubectl delete)' && echo 'BLOCKED: Comando peligroso requiere confirmación manual' && exit 1 || exit 0"
      }]
    }]
  }
}

Bloqueo de directorio (/freeze):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "echo '${tool.input.file_path}' | grep -q 'themes/' && echo 'BLOCKED: El directorio themes/ está bloqueado' && exit 1 || exit 0"
      }]
    }]
  }
}

¿Cómo Integrar MCP para Conectar Claude Code a Servicios Externos?

Respuesta directa: MCP (Model Context Protocol) es el estándar abierto de Anthropic que permite a Claude conectarse a Slack, Notion, bases de datos, navegadores y más a través de un protocolo unificado. Configúralo en ~/.claude/settings.json bajo la clave mcpServers. Advertencia crítica: instalar 2–3 MCPs grandes puede consumir 10,000–20,000 Tokens antes de escribir un solo mensaje.

MCP es el “control remoto universal” que permite a Claude controlar servicios externos.

Arquitectura MCP

⚠️ La Trampa de Costos de MCP

Instala 2–3 MCPs grandes → Antes de escribir nada
ya has consumido ¡10,000–20,000 Tokens!

Las herramientas MCP cargan todas sus definiciones de herramientas y descripciones de parámetros en el Context Window. Algunos MCPs pesan más que todo tu historial de conversación.

Estrategia de Integración Óptima

Stack MCP Recomendado

MCPFunciónCosto en Tokens
Chrome DevToolsControlar navegador local, capturas, scrapingMedio
NotebookLMBase de conocimiento RAG a gran escala, gratisBajo (procesado en Google)
Context7Búsqueda de documentación de librerías en tiempo realBajo
Neon DatabaseOperaciones directas en PostgreSQLMedio

Sub-agents vs Agent Teams: ¿Qué Arquitectura Multi-Agente Elegir?

Respuesta directa: Los Sub-agents son dirigidos por un agente principal (Opus) que delega tareas a agentes trabajadores más baratos (Sonnet/Haiku) en Contexts aislados — controlado en costo y adecuado para tareas bien definidas. Agent Teams es experimental: agentes completamente independientes que se comunican entre sí, consumiendo 7 veces más tokens, adecuado para tareas exploratorias o de debate — siempre usa Git Worktrees para evitar conflictos de archivos.

A medida que los proyectos escalan, paralelizar tareas es clave para aumentar el rendimiento.

Arquitectura de Sub-agents

Ventajas principales de los sub-agents:

  • Cada uno tiene su propio Context Window aislado sin historial previo
  • Solo devuelve resultados — nunca contamina la memoria del agente principal
  • Usa modelos más baratos (Haiku/Sonnet), reduciendo drásticamente el costo

Agent Teams (Experimental)

Habilita en settings.json:

{
  "claude_code_experimental_agent_teams": 1
}

Comparativa Sub-agents vs Agent Teams:

CaracterísticaSub-agentsAgent Teams
ComunicaciónAgente principal dirigeComunicación entre pares
Contexto compartidoNoTablero de tareas compartido
Consumo de tokensModeradoMuy alto (7x+)
Mejor paraTareas paralelas bien definidasTareas exploratorias / debate
Integración GitOpcionalWorktrees muy recomendados

Mejores Prácticas con Git Worktrees

Al usar Agent Teams, siempre usa Git Worktrees para que cada agente trabaje en una carpeta y rama aisladas:

# Crear espacios de trabajo aislados para el equipo de agentes
git worktree add ../project-agent-a feature/agent-a-design
git worktree add ../project-agent-b feature/agent-b-design
git worktree add ../project-agent-c feature/agent-c-design

# Fusionar la mejor versión al terminar
git merge feature/agent-b-design

¿Cómo Controlar los Costos de Tokens de Claude Code?

Respuesta directa: El control de costos se centra en prevenir el “Context Rot” — el fenómeno donde la calidad del razonamiento de la IA se degrada significativamente a medida que el Context Window se llena. Tres hábitos clave: (1) ejecuta /context regularmente; (2) usa /clear al cambiar de tarea; (3) usa siempre Plan Mode antes de implementar, ya que el costo de refactorizar código incorrecto supera con creces el costo de planificar con anticipación.

Context Rot

Cuando el Context Window se llena, los costos se disparan y la calidad del razonamiento de la IA cae significativamente — esto es Context Rot.

Lista de Control de Costos

Antes de cada sesión de trabajo:

  • Ejecutar /context para verificar uso de tokens
  • Confirmar que CLAUDE.md está por debajo de 500 líneas
  • Auditar y eliminar MCPs innecesarios

Al cambiar de tarea:

  • Ejecutar /clear para borrar completamente la memoria
  • O usar /compact para comprimir conservando info clave

Antes de tareas complejas:

  • Usar Plan Mode para confirmar la arquitectura primero
  • Usar Sub-agents en lugar de un solo contexto grande

Estrategia de Selección de Modelo


Tres Casos de Uso Reales

Caso 1: Diseño Web con Bucle de Capturas de Pantalla

El método de diseño web más eficiente hoy — produce páginas pulidas sin escribir nada de CSS.

Resultado: Páginas de diseño premium con 85%+ de fidelidad en 2–3 minutos, sin escribir código.


Caso 2: Base de Conocimiento RAG con NotebookLM

Para documentación masiva (ej. 99,000 líneas de docs de n8n), cargarla directamente en Claude cuesta una fortuna. La solución:

Beneficios:

  • NotebookLM maneja toda la complejidad RAG gratuitamente
  • Claude solo consume tokens mínimos para recibir resultados
  • Soporta bases de conocimiento enormes sin costo adicional

Caso 3: Generación Automatizada de App SaaS

Desde la descripción del requisito hasta una SaaS full-stack funcionando:


Preguntas Frecuentes

¿Claude Code requiere suscripción de pago?

Claude Code está disponible en claude.ai/claude-code o instala con npm install -g @anthropic-ai/claude-code. El precio es por uso (por token), con diferentes tarifas para Haiku, Sonnet y Opus. La suscripción Claude Pro incluye una cuota limitada de Claude Code; el uso adicional se factura por token.

¿En qué se diferencia Claude Code de GitHub Copilot?

GitHub Copilot proporciona principalmente sugerencias de autocompletado dentro del IDE — ayuda mientras escribes. Claude Code es una herramienta de línea de comandos que lee y escribe todo tu código, ejecuta comandos Bash, llama APIs externas y puede ejecutar flujos de trabajo multi-agente en paralelo. El posicionamiento es diferente: Copilot acelera el escribir, Claude Code automatiza el hacer.

¿Qué pasa si pongo CLAUDE.md en el lugar equivocado?

~/.claude/CLAUDE.md es global y se carga para cada proyecto. ./CLAUDE.md solo aplica al proyecto actual. Un CLAUDE.md en un subdirectorio sobreescribe las reglas del padre. En caso de conflicto, el directorio más profundo tiene prioridad. Un error común es poner reglas sensibles de proyecto en el archivo global, filtrándolas a proyectos no relacionados.

¿Son obligatorios los Git Worktrees al usar Agent Teams?

Muy recomendados. Sin Worktrees, múltiples agentes operan en el mismo directorio y casi seguramente tendrán condiciones de carrera al escribir los mismos archivos simultáneamente, causando sobrescrituras. Los Worktrees dan a cada agente una carpeta y rama aisladas para trabajar, que fusionas al terminar — la única forma segura de desarrollo multi-agente en paralelo.

¿Funciona Claude Code en Windows?

Sí, a través de WSL2 (Windows Subsystem for Linux) o directamente con Node.js. Anthropic recomienda macOS o Linux para la mejor experiencia, especialmente para Bash Hooks y operaciones Git donde WSL2 proporciona la mejor compatibilidad.


Resumen

La evolución central de Claude Code en 2025/2026 es: de herramienta a sistema operativo autónomo.

Un principio final para guiar tu uso de Claude Code:

“Primero planifica, luego construye. Primero reglas, luego código. Primero Skills, luego MCP.”

Cada minuto invertido en arquitectura y reglas se devuelve multiplicado en velocidad de desarrollo.


Este artículo sintetiza la documentación oficial de Claude Code y las perspectivas de numerosos desarrolladores en producción. Todos los detalles técnicos están actualizados a marzo de 2026.

TAG