Introducción

Cuando trabajas con Claude Code en proyectos del mundo real, te darás cuenta rápidamente de que un único agente ejecutándose de forma secuencial no es suficiente para manejar tareas complejas. Esta lección se enfoca en dos mecanismos avanzados: los hooks, que te permiten intervenir en el comportamiento del agente antes y después de cada operación, y los subagentes, que te permiten dividir el trabajo en múltiples flujos de procesamiento en paralelo.

Comprender y aplicar bien estos dos mecanismos es lo que separa un flujo de trabajo automatizado básico de un sistema que realmente puede escalar.

Hooks: Control del Comportamiento Antes y Después de una Operación

Los hooks en Claude Code son funciones callback registradas para ejecutarse en puntos específicos del ciclo de vida de una llamada a una herramienta. Existen dos tipos principales: PreToolUse, que se ejecuta antes de que la herramienta se ejecute, y PostToolUse, que se ejecuta después de que la herramienta finaliza.

La configuración de los hooks se declara en el archivo de configuración, normalmente .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash /scripts/validate_command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash /scripts/run_linter.sh"
          }
        ]
      }
    ]
  }
}

El campo matcher especifica a qué herramienta se aplica este hook. Puedes usar un nombre específico de herramienta como Bash, Write o Edit, o usar un comodín para capturar todas las herramientas.

Cuando se ejecuta el script de un hook, Claude Code pasa información sobre la llamada a la herramienta a través de stdin en formato JSON. Tu script puede leer estos datos para tomar decisiones. El código de salida determina qué sucede a continuación: exit 0 permite que la operación continúe, mientras que exit 2 bloquea la operación y devuelve un mensaje de error al agente.

A continuación se muestra un ejemplo de un script simple de validación usado como hook PreToolUse en la herramienta Bash, que impide que el agente elimine archivos fuera del directorio del proyecto:

#!/bin/bash
input=$(cat)
command=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")

if echo "$command" | grep -qE 'rm -rf /|sudo rm'; then
  echo "Blocked: lệnh xóa nguy hiểm bị từ chối" >&2
  exit 2
fi

exit 0

Los hooks PostToolUse son útiles para tareas como ejecutar automáticamente un linter después de cada escritura de archivo por parte del agente, registrar resultados en un archivo de auditoría o enviar una notificación cuando el agente completa un grupo de operaciones.

Subagentes: Procesamiento de Tareas Complejas en Paralelo

Un subagente es un mecanismo mediante el cual el agente principal (el orquestador) genera y coordina agentes hijos independientes. Cada subagente tiene su propio contexto, su propio acceso a herramientas y puede ejecutarse de forma concurrente con otros subagentes.

En Claude Code, activas un subagente usando la herramienta Task en el prompt del orquestador. El orquestador describe la tarea y el sistema crea un agente hijo con un contexto separado para ejecutarla:

claude -p "Hãy phân tích codebase này bằng cách:
1. Dùng Task tool để tạo subagent A: quét toàn bộ file .py và liệt kê các function chưa có docstring
2. Dùng Task tool để tạo subagent B: kiểm tra tất cả file config và báo cáo các key bị thiếu so với .env.example
3. Tổng hợp kết quả từ cả hai và tạo báo cáo audit.md"

Los subagentes A y B se ejecutan en paralelo y luego el orquestador espera los resultados de ambos antes de sintetizarlos. Esto ahorra un tiempo significativo en comparación con ejecutar las tareas de forma secuencial.

Un punto importante: cada subagente consume su propia ventana de contexto, así que diseña la tarea de cada subagente para que sea específica y autocontenida. Evita situaciones en las que un subagente necesite ir y venir con el orquestador varias veces; eso elimina la ventaja de la paralelización.

Puedes combinar hooks con subagentes: los hooks se aplican tanto al agente principal como a los subagentes, lo que te permite aplicar políticas de control consistentes en todo el sistema sin importar cuántos agentes hijos estén ejecutándose.

Errores Comunes

El error más común al usar hooks es que un script salga con un código de salida incorrecto, provocando que el agente sea bloqueado cuando no debería, o que no sea bloqueado cuando sí debería. Siempre prueba los scripts de hooks de forma independiente antes de integrarlos, canalizando una carga útil JSON de muestra en el script y verificando el código de salida devuelto.

Con los subagentes, un error frecuente es asignar tareas demasiado vagas o mutuamente dependientes a dos subagentes que se ejecutan en paralelo. Por ejemplo, si el subagente B necesita leer un archivo que crea el subagente A, estas dos tareas no pueden ejecutarse en paralelo; el orquestador debe terminar A antes de comenzar B.

Otro error es no manejar el caso en que un subagente falla. El orquestador necesita instrucciones claras sobre qué hacer cuando una tarea hija reporta un error, en lugar de omitirlo silenciosamente y continuar sintetizando resultados incompletos.

Resumen

Los hooks te dan un control granular sobre el comportamiento del agente en cada paso, desde validar comandos peligrosos hasta automatizar QA después de cada operación. Los subagentes desbloquean capacidades de procesamiento en paralelo, ideales cuando una tarea puede descomponerse en partes independientes. Combinando ambos, puedes construir pipelines de automatización que sean a la vez seguros y eficientes para proyectos del mundo real a escala de producción.