Arquitectura de Agentes: Cómo Construir Entornos de Desarrollo Potenciados por IA

TL;DR: Claude Code no es un chat con acceso a archivos. Es un runtime programable con 22 eventos de ciclo de vida, cada uno conectable mediante shell scripts que el modelo no puede omitir. Apila hooks en dispatchers, dispatchers en skills, skills en agents, agents en workflows, y obtienes un harness de desarrollo autónomo que impone restricciones, delega trabajo, persiste memoria entre sesiones y orquesta deliberación multi-agente. Esta guía cubre cada capa de ese stack: desde un solo hook hasta un sistema de consenso de 10 agentes. Sin frameworks. Solo bash y JSON.

Andrej Karpathy acuñó un término para lo que crece alrededor de un agente LLM: claws (garras). Los hooks, scripts y orquestación que permiten al agente agarrarse al mundo fuera de su ventana de contexto.¹ La mayoría de los desarrolladores tratan a los agentes de programación con IA como asistentes interactivos. Escriben un prompt, observan cómo edita un archivo y siguen adelante. Ese enfoque limita la productividad a lo que puedas supervisar personalmente.

El modelo mental de infraestructura es diferente: un agente de programación con IA es un runtime programable con un kernel LLM. Cada acción que toma el modelo pasa por hooks que tú controlas. Defines políticas, no prompts. El modelo opera dentro de tu infraestructura de la misma forma en que un servidor web opera dentro de las reglas de nginx. No te sientas frente a nginx a escribir peticiones. Lo configuras, lo despliegas y lo monitoreas.

La distinción importa porque la infraestructura se acumula. Un hook que bloquea credenciales en comandos bash protege cada sesión, cada agente, cada ejecución autónoma. Un skill que codifica tu rúbrica de evaluación se aplica consistentemente, ya sea que lo invoques tú o un agente. Un agente que revisa código en busca de vulnerabilidades ejecuta las mismas verificaciones estés observando o no.²

Puntos Clave

• Los hooks garantizan la ejecución; los prompts no. Usa hooks para linting, formateo, verificaciones de seguridad y cualquier cosa que deba ejecutarse siempre, independientemente del comportamiento del modelo. El código de salida 2 bloquea acciones. El código de salida 1 solo advierte.³
• Los skills codifican experiencia de dominio que se activa automáticamente. El campo description lo determina todo. Claude usa razonamiento LLM (no coincidencia de palabras clave) para decidir cuándo aplicar un skill.⁴
• Los subagents previenen la saturación de contexto. Ventanas de contexto aisladas para exploración y análisis mantienen la sesión principal ligera. Hasta 10 pueden ejecutarse en paralelo.⁵
• La memoria vive en el sistema de archivos. Los archivos persisten entre ventanas de contexto. CLAUDE.md, MEMORY.md, directorios de rules y documentos de handoff forman un sistema de memoria externa estructurado.⁶
• La deliberación multi-agente detecta puntos ciegos. Un solo agente no puede cuestionar sus propias suposiciones. Dos agentes independientes con diferentes prioridades de evaluación detectan fallas estructurales que los quality gates no pueden abordar.⁷
• El patrón harness es el sistema. CLAUDE.md, hooks, skills, agents y memory no son funciones independientes. Se componen en una capa determinista entre tú y el modelo que escala con la automatización.

Cómo Usar Esta Guía

Cada sección se construye sobre la anterior. El Marco de Decisión al final proporciona una tabla de consulta para elegir el mecanismo adecuado para cada tipo de problema.

Por qué importa la arquitectura de agentes

Simon Willison enmarca el momento actual en torno a una sola observación: escribir código ahora es barato.⁸ Correcto. Pero el corolario es que la verificación es ahora la parte costosa. Código barato sin infraestructura de verificación produce errores a escala. La inversión que realmente vale la pena no es un mejor prompt, sino el sistema alrededor del modelo que atrapa lo que el modelo pasa por alto.

Tres fuerzas hacen necesaria la arquitectura de agentes:

Las ventanas de contexto son finitas y con pérdida. Cada lectura de archivo, salida de herramienta y turno de conversación consume tokens. Microsoft Research y Salesforce probaron 15 LLMs en más de 200.000 conversaciones simuladas y encontraron una caída promedio del 39% en rendimiento entre la interacción de un solo turno y la de múltiples turnos.⁹ La degradación comienza en tan solo dos turnos y sigue una curva predecible: ediciones precisas de múltiples archivos en los primeros 30 minutos se degradan a visión de túnel en un solo archivo hacia el minuto 90. Ventanas de contexto más grandes no resuelven esto. La condición “Concat” del mismo estudio (la conversación completa como un solo prompt) alcanzó el 95,1% del rendimiento de un solo turno con contenido idéntico. La degradación proviene de los límites entre turnos, no de los límites de tokens.

El comportamiento del modelo es probabilístico, no determinista. Decirle a Claude “siempre ejecuta Prettier después de editar archivos” funciona aproximadamente el 80% de las veces.³ El modelo puede olvidarlo, priorizar la velocidad o decidir que el cambio es “demasiado pequeño”. Para cumplimiento normativo, seguridad y estándares de equipo, el 80% no es aceptable. Los hooks garantizan la ejecución: cada Edit o Write activa tu formateador, siempre, sin excepciones. Lo determinista supera a lo probabilístico.

Las perspectivas únicas pasan por alto problemas multidimensionales. Un solo agente revisando un endpoint API verificó la autenticación, validó la sanitización de entrada y comprobó los headers CORS. Resultado limpio. Un segundo agente, con instrucciones separadas como pentester, encontró que el endpoint aceptaba parámetros de consulta sin límite que podían desencadenar una denegación de servicio mediante amplificación de consultas a la base de datos.⁷ El primer agente nunca lo verificó porque nada en su marco de evaluación trataba la complejidad de las consultas como una superficie de seguridad. Esa brecha es estructural. Ninguna cantidad de ingeniería de prompts la corrige.

La arquitectura de agentes aborda los tres problemas: los hooks imponen restricciones deterministas, los subagents gestionan el aislamiento de contexto y la orquestación multiagente proporciona perspectivas independientes. Juntos forman el harness.

El patrón harness

El harness no es un framework. Es un patrón: un conjunto componible de archivos, scripts y convenciones que envuelven a un agente de código con IA en infraestructura determinista. Los componentes:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Capa de instrucciones: Los archivos CLAUDE.md y los directorios de reglas definen lo que el agente sabe sobre tu proyecto. Se cargan automáticamente al inicio de la sesión y después de cada compactación. Esta es la memoria arquitectónica a largo plazo del agente.

Capa de extensión: Los skills proporcionan experiencia de dominio que se activa automáticamente según el contexto. Los hooks proporcionan puertas deterministas que se disparan en cada llamada a herramienta coincidente. Los archivos de memoria persisten el estado entre sesiones. Los agentes personalizados proporcionan configuraciones especializadas de subagents.

Capa de orquestación: Los patrones multiagente coordinan agentes independientes para investigación, revisión y deliberación. Los presupuestos de spawn previenen la recursión descontrolada. La validación por consenso asegura la calidad.

La idea clave: la mayoría de los usuarios trabajan enteramente en la capa núcleo, observando cómo el contexto se infla y los costos aumentan. Los usuarios avanzados configuran las capas de instrucciones y extensión, y luego usan la capa núcleo solo para orquestación y decisiones finales.²

Cómo se ve el harness en disco

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Cada archivo en esta estructura cumple un propósito. El árbol ~/.claude/ es infraestructura personal que se aplica a todos los proyectos. El árbol .claude/ en cada repositorio es específico del proyecto y se comparte vía git. Juntos forman el harness completo.

Sistema de skills

Los skills son extensiones invocadas por el modelo. Claude los descubre y aplica automáticamente según el contexto, sin que tengas que llamarlos explícitamente.⁴ El momento en que te descubras re-explicando el mismo contexto entre sesiones es el momento en que deberías construir un skill.

Cuándo construir un skill

Los skills son para conocimiento que Claude siempre tiene disponible. Los slash commands son para acciones que tú disparas explícitamente. Si estás decidiendo entre ambos, pregúntate: “¿Debería Claude aplicar esto automáticamente, o debería yo decidir cuándo ejecutarlo?”

Cómo crear un skill

Los skills pueden residir en cuatro ubicaciones posibles, del alcance más amplio al más específico:⁴

Cada skill requiere un archivo SKILL.md con YAML frontmatter:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Controles de Seguridad
Al revisar código, verifica:

### Validación de Entrada
- Toda entrada de usuario sanitizada antes de operaciones con la base de datos
- Consultas parametrizadas (sin interpolación de cadenas en SQL)
- Codificación de salida para contenido HTML renderizado

### Autenticación
- Tokens de sesión validados en cada endpoint protegido
- Verificación de permisos antes de mutaciones de datos
- Sin credenciales codificadas ni claves API en el código fuente

Referencia de Frontmatter

El Campo Description Lo Es Todo

Al inicio de sesión, Claude Code extrae el name y description de cada skill y los inyecta en el contexto de Claude. Cuando envías un mensaje, Claude usa razonamiento de modelo de lenguaje para decidir si algún skill es relevante. Un análisis independiente del código fuente de Claude Code confirma el mecanismo: las descripciones de skills se inyectan en una sección available_skills del prompt del sistema, y el modelo usa comprensión de lenguaje estándar para seleccionar skills relevantes.¹⁰

Mala descripción:

description: Helps with code

Descripción efectiva:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

La descripción efectiva incluye: qué hace (revisar código para tipos específicos de problemas), cuándo usarlo (examinar cambios, PRs, análisis de calidad), y frases disparadoras (review, audit, check) que los usuarios escriben naturalmente.

Presupuesto de Contexto

Todas las descripciones de skills comparten un presupuesto de contexto que escala dinámicamente al 2% de la ventana de contexto, con un respaldo de 16.000 caracteres.⁴ Si tienes muchos skills, mantén cada descripción concisa. Puedes sobreescribir el presupuesto mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ pero la mejor solución es escribir descripciones más cortas y precisas. Ejecuta /context durante una sesión para verificar si algún skill está siendo excluido.

Archivos de Soporte y Organización

Los skills pueden referenciar archivos adicionales en el mismo directorio:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Haz referencia a ellos desde SKILL.md con enlaces relativos. Claude lee estos archivos bajo demanda cuando el skill se activa. Mantén SKILL.md por debajo de 500 líneas y mueve el material de referencia detallado a archivos de soporte.¹²

Compartir Skills vía Git

Los skills de proyecto (.claude/skills/ en la raíz del repositorio) se comparten mediante control de versiones:⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Cuando los compañeros de equipo hacen pull, obtienen el skill automáticamente. Sin instalación, sin configuración. Esta es la forma más efectiva de estandarizar experiencia en un equipo.

Skills como Biblioteca de Prompts

Más allá de skills de propósito único, la estructura de directorios funciona como una biblioteca organizada de prompts:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Cada skill codifica una faceta diferente de tu experiencia. En conjunto, forman una base de conocimiento de la que Claude extrae automáticamente según el contexto. Un desarrollador junior recibe orientación de nivel senior sin pedirla.

Los Skills se Componen con Hooks

Los skills pueden definir sus propios hooks en el frontmatter que se activan solo mientras el skill se ejecuta. Esto crea comportamiento específico del dominio que no contamina otras sesiones:²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Los skills de filosofía se activan automáticamente mediante hooks de SessionStart, inyectando restricciones de calidad en cada sesión sin invocación explícita. El skill en sí es conocimiento. El hook es aplicación. Juntos, forman una capa de políticas.

Errores Comunes con Skills

Descripciones demasiado amplias. Un skill git-rebase-helper que se activa ante cualquier prompt relacionado con git (rebases, merges, cherry-picks, incluso git status) contamina el contexto en el 80% de las sesiones. La solución es ajustar la descripción o agregar disable-model-invocation: true y requerir invocación explícita con /skill-name.⁴

Demasiados skills compitiendo por el presupuesto. Más skills significa más descripciones compitiendo por el presupuesto de contexto del 2%. Si notas que ciertos skills no se activan, revisa /context para ver los excluidos. Prioriza menos skills bien descritos sobre muchos vagos.

Información crítica enterrada en archivos de soporte. Claude lee SKILL.md inmediatamente pero solo accede a los archivos de soporte cuando es necesario. Si hay información crítica en un archivo de soporte, Claude podría no encontrarla. Coloca la información esencial directamente en SKILL.md.⁴

Arquitectura de Hooks

Los hooks son comandos de shell que se activan mediante eventos del ciclo de vida de Claude Code.³ Se ejecutan fuera del LLM como scripts simples, no como prompts interpretados por el modelo. ¿El modelo quiere ejecutar rm -rf /? Un script de bash de 10 líneas verifica el comando contra una lista de bloqueo y lo rechaza antes de que el shell lo vea. El hook se dispara sin importar si el modelo lo desea o no.

Eventos disponibles

Claude Code expone 22 eventos de ciclo de vida en seis categorías:¹³

Semántica de códigos de salida

Los códigos de salida determinan si los hooks bloquean acciones:³

Crítico: Todo hook de seguridad debe usar exit 2, no exit 1. Exit 1 es una advertencia no bloqueante. El comando peligroso se ejecuta de todas formas. Este es el error de hooks más común entre equipos.¹⁴

Configuración de hooks

Los hooks residen en archivos de configuración. A nivel de proyecto (.claude/settings.json) para hooks compartidos. A nivel de usuario (~/.claude/settings.json) para hooks personales:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

El campo matcher es una expresión regular que coincide con nombres de herramientas: Bash, Write, Edit, Read, Glob, Grep, Agent, o * para todas las herramientas. Usa "" (cadena vacía) para eventos sin herramientas como UserPromptSubmit.

Protocolo de entrada/salida de hooks

Los hooks reciben JSON en stdin con el contexto completo:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

Para control avanzado, los hooks PreToolUse pueden generar JSON como salida para modificar la entrada de la herramienta, inyectar contexto o tomar decisiones de permisos:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Tres tipos de garantías

Antes de escribir cualquier hook, pregúntate: ¿qué tipo de garantía necesito?¹⁴

Garantías de formato aseguran consistencia después de los hechos. Los hooks PostToolUse en Write/Edit ejecutan tu formateador después de cada cambio en un archivo. La salida del modelo no importa porque el formateador normaliza todo.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Garantías de seguridad previenen acciones peligrosas antes de que se ejecuten. Los hooks PreToolUse en Bash inspeccionan comandos y bloquean patrones destructivos con código de salida 2:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Garantías de calidad validan el estado en puntos de decisión. Los hooks PreToolUse en comandos git commit ejecutan tu linter o suite de pruebas y bloquean el commit si las verificaciones de calidad fallan:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Tipos de hooks más allá de comandos de shell

Claude Code soporta tres tipos de hooks:¹³

Hooks de comando (type: "command") ejecutan scripts de shell. Rápidos, deterministas, sin costo de tokens.

Hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo Claude rápido. El modelo devuelve { "ok": true } para permitir o { "ok": false, "reason": "..." } para bloquear. Úsalos para evaluaciones con matices que una expresión regular no puede capturar.

Hooks de agente (type: "agent") generan un subagent con acceso a herramientas (Read, Grep, Glob) para verificación de múltiples turnos. Úsalos cuando la verificación requiere inspeccionar archivos reales o resultados de pruebas:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hooks asíncronos

Los hooks pueden ejecutarse en segundo plano sin bloquear la ejecución. Agrega async: true para operaciones no críticas como notificaciones y registro:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Usa async para notificaciones, telemetría y respaldos. Nunca uses async para formato, validación o cualquier cosa que deba completarse antes de la siguiente acción.

Dispatchers en lugar de hooks independientes

Ejecutar siete hooks que se disparan en el mismo evento, cada uno leyendo stdin de forma independiente, crea condiciones de carrera. Dos hooks escribiendo al mismo archivo de estado JSON de forma concurrente truncarán el JSON. Cada hook posterior que parsea ese archivo fallará.²

La solución: un dispatcher por evento que ejecuta los hooks secuencialmente desde stdin cacheado:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Depuración de hooks

Cinco técnicas para depurar hooks que fallan silenciosamente:¹⁴

1. Prueba los scripts de forma independiente. Envía JSON de ejemplo por pipe: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Usa stderr para salida de depuración. Todo lo escrito en stderr aparece en el contexto de Claude.
3. Vigila las fallas de jq. Rutas JSON incorrectas devuelven null silenciosamente. Prueba las expresiones jq contra la entrada real de la herramienta.
4. Verifica los códigos de salida. Un hook PreToolUse que usa exit 1 no proporciona ninguna protección real, aunque parezca funcionar.
5. Mantén los hooks rápidos. Los hooks se ejecutan de forma síncrona. Mantén todos los hooks bajo 2 segundos, idealmente bajo 500ms.

Memoria y contexto

Toda conversación con IA opera dentro de una ventana de contexto finita. A medida que la conversación crece, el sistema comprime los turnos anteriores para hacer espacio al contenido nuevo. La compresión tiene pérdidas. Decisiones arquitectónicas documentadas en el turno 3 pueden no sobrevivir hasta el turno 15.⁹

Los tres mecanismos del colapso multi-turno

El estudio de MSR/Salesforce identificó tres mecanismos independientes, cada uno requiriendo una intervención diferente:⁹

Estrategia 1: El sistema de archivos como memoria

La memoria más confiable a través de los límites de contexto reside en el sistema de archivos. Claude Code lee CLAUDE.md y los archivos de memoria al inicio de cada sesión y después de cada compactación.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

El archivo MEMORY.md captura errores, decisiones y patrones entre sesiones. Cuando descubres que ((VAR++)) falla con set -e en bash cuando VAR es 0, lo registras. Tres sesiones después, al encontrar un caso límite similar con enteros en Python, la entrada en MEMORY.md hace emerger el patrón.¹⁵

Auto Memory (v2.1.32+): Claude Code registra y recupera automáticamente el contexto del proyecto. Mientras trabajas, Claude escribe observaciones en ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory carga las primeras 200 líneas en tu system prompt al inicio de la sesión. Mantenlo conciso y enlaza a archivos temáticos separados para notas detalladas.⁶

Estrategia 2: Compactación proactiva

El comando /compact de Claude Code resume la conversación y libera espacio de contexto, preservando decisiones clave, contenido de archivos y estado de las tareas.¹⁵

Cuándo compactar: - Después de completar una subtarea definida (función implementada, bug corregido) - Antes de comenzar con una nueva área del codebase - Cuando Claude empieza a repetirse u olvidar contexto anterior - Aproximadamente cada 25-30 minutos durante sesiones intensivas

Instrucciones personalizadas de compactación en CLAUDE.md:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Estrategia 3: Handoffs de sesión

Para tareas que abarcan múltiples sesiones, crea documentos de handoff que capturen el estado completo:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

La estructura Status/Files/Decision/Blocked/Next proporciona a la sesión sucesora el contexto completo con un costo mínimo de tokens. Iniciar una nueva sesión con claude -c (continuar) o leer el documento de handoff lleva directamente a la implementación.¹⁵

Estrategia 4: Iteración con contexto fresco (el Ralph Loop)

Para sesiones que superan los 60-90 minutos, genera una instancia fresca de Claude por iteración. El estado persiste a través del sistema de archivos, no de la memoria conversacional. Cada iteración obtiene el presupuesto completo de contexto:¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Compara con una sola sesión prolongada:

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

El enfoque de contexto fresco por iteración intercambia un 15-20% de overhead en el paso de orientación (lectura de archivos de estado, escaneo del historial de git) a cambio de recursos cognitivos completos por iteración.¹⁶ El cálculo de costo-beneficio: para sesiones de menos de 60 minutos, una sola conversación es más eficiente. Más allá de 90 minutos, el contexto fresco produce resultados de mayor calidad a pesar del overhead.

Los anti-patrones

Leer archivos completos cuando necesitas 10 líneas. Una sola lectura de un archivo de 2.000 líneas consume 15.000-20.000 tokens. Usa offsets de línea: Read file.py offset=100 limit=20 ahorra la gran mayoría de ese costo.¹⁵

Mantener salida verbosa de errores en el contexto. Después de depurar un bug, tu contexto contiene más de 40 stack traces de iteraciones fallidas. Un solo /compact después de corregir el bug libera ese peso muerto.

Comenzar cada sesión leyendo todos los archivos. Deja que las herramientas glob y grep de Claude Code encuentren los archivos relevantes bajo demanda, ahorrando más de 100.000 tokens de pre-carga innecesaria.¹⁵

Patrones de Subagents

Los subagents son instancias especializadas de Claude que manejan tareas complejas de forma independiente. Comienzan con un contexto limpio (sin contaminación de la conversación principal), operan con herramientas específicas y devuelven resultados como resúmenes. Los resultados de exploración no inflan tu conversación principal; solo las conclusiones regresan.⁵

Tipos de Subagents Integrados

Creación de Subagents Personalizados

Define subagents en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de Configuración de Subagents

Aislamiento con Worktree

Los subagents pueden operar en git worktrees temporales, proporcionando una copia aislada completa del repositorio:⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

El aislamiento con worktree es esencial para trabajo experimental que podría romper la base de código.

Subagents en Paralelo

Claude Code soporta hasta 10 subagents en paralelo.⁵ Usa la ejecución paralela para tareas de investigación independientes:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Cada agente se ejecuta en su propia ventana de contexto, encuentra el código relevante y devuelve un resumen. El contexto principal se mantiene limpio.

El Recursion Guard

Sin límites de generación, los agentes delegan a agentes que delegan a otros agentes, donde cada uno pierde contexto y consume tokens. El patrón de recursion guard impone presupuestos:¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Lección crítica: Usa presupuestos de generación, no solo límites de profundidad. Los límites basados en profundidad rastrean cadenas padre-hijo (bloqueados en profundidad 3), pero no detectan la amplitud: 23 agentes en profundidad 1 sigue siendo “profundidad 1”. Un presupuesto de generación rastrea el total de hijos activos por padre, con un máximo configurable. El modelo de presupuesto se mapea al modo de fallo real (demasiados agentes en total) en lugar de una métrica indirecta (demasiados niveles de anidamiento).⁷

Agent Teams (Vista Previa de Investigación)

Los Agent Teams coordinan múltiples instancias de Claude Code que trabajan de forma independiente, se comunican mediante un buzón compartido y una lista de tareas, y pueden cuestionar los hallazgos de los demás:⁵

Habilitar con: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Cuándo usar Agent Teams en lugar de subagents:

Orquestación Multi-Agente

Los sistemas de IA con un solo agente tienen un punto ciego estructural: no pueden cuestionar sus propias suposiciones.⁷ La deliberación multi-agente fuerza una evaluación independiente desde múltiples perspectivas antes de que cualquier decisión quede fijada.

Deliberación Mínima Viable

Comienza con 2 agentes y 1 regla: los agentes deben evaluar de forma independiente antes de ver el trabajo del otro.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Este patrón cubre el 80% del valor. Todo lo demás añade mejoras incrementales.

El Disparador de Confianza

No todas las tareas necesitan deliberación. Un módulo de puntuación de confianza evalúa cuatro dimensiones:¹⁷

1. Ambigüedad — ¿Tiene la consulta múltiples interpretaciones válidas?
2. Complejidad del dominio — ¿Requiere conocimiento especializado?
3. Riesgo — ¿Es la decisión reversible?
4. Dependencia del contexto — ¿Requiere comprender el sistema en su conjunto?

La puntuación se mapea a tres niveles:

El umbral se adapta según el tipo de tarea. Las decisiones de seguridad requieren un consenso de 0,85. Los cambios de documentación solo necesitan 0,50. Esto evita sobre-ingeniería en tareas simples mientras asegura que las decisiones riesgosas reciban el escrutinio adecuado.⁷

La Máquina de Estados

Siete fases, cada una condicionada por la anterior:⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: Agentes independientes investigan el tema. Cada agente recibe una persona diferente (Arquitecto Técnico, Analista de Seguridad, Ingeniero de Rendimiento, entre otros). El aislamiento de contexto garantiza que los agentes no puedan ver los hallazgos de los demás durante la investigación.

DELIBERATION: Los agentes ven todos los hallazgos de investigación y generan alternativas. El agente de Debate identifica conflictos. El agente de Síntesis combina hallazgos no contradictorios.

RANKING: Cada agente puntúa cada enfoque propuesto en 5 dimensiones ponderadas:

La Arquitectura de Validación de Dos Puertas

Dos puertas de validación detectan problemas en diferentes etapas:⁷

Puerta 1: Validación de Consenso (hook PostToolUse). Se ejecuta inmediatamente después de que cada agente de deliberación completa: 1. La fase debe haber alcanzado al menos RANKING 2. Mínimo 2 agentes completados (configurable) 3. La puntuación de consenso cumple el umbral adaptativo por tarea 4. Si algún agente disintió, las preocupaciones deben estar documentadas

Puerta 2: Pride Check (hook Stop). Se ejecuta antes de que la sesión pueda cerrarse: 1. Métodos diversos: múltiples personas únicas representadas 2. Transparencia de contradicciones: las disidencias tienen razones documentadas 3. Manejo de complejidad: al menos 2 alternativas generadas 4. Confianza de consenso: clasificada como fuerte (superior a 0,85) o moderada (0,70-0,84) 5. Evidencia de mejora: la confianza final supera la confianza inicial

Dos hooks en diferentes puntos del ciclo de vida coinciden con la forma en que realmente ocurren los fallos: algunos son instantáneos (puntuación baja) y otros son graduales (baja diversidad, documentación de disidencias faltante).⁷

Por Qué el Acuerdo es Peligroso

Charlan Nemeth estudió la disidencia minoritaria desde 1986 hasta su libro de 2018 In Defense of Troublemakers. Los grupos con disidentes toman mejores decisiones que los grupos que alcanzan un acuerdo rápido. El disidente no necesita tener razón. El acto de disentir obliga a la mayoría a examinar suposiciones que de otro modo pasarían por alto.¹⁸

Wu et al. probaron si los agentes de LLM pueden genuinamente debatir y descubrieron que, sin incentivos estructurales para el desacuerdo, los agentes convergen hacia la respuesta inicial que suena más segura, independientemente de su corrección.¹⁹ Liang et al. identificaron la causa raíz como “Degeneración del Pensamiento”: una vez que un LLM establece confianza en una posición, la autorreflexión no puede generar contraargumentos novedosos, lo que hace que la evaluación multi-agente sea estructuralmente necesaria.²⁰

La independencia es la restricción de diseño crítica. Dos agentes evaluando la misma estrategia de despliegue con visibilidad de los hallazgos del otro produjeron puntuaciones de 0,45 y 0,48. Los mismos agentes sin visibilidad: 0,45 y 0,72. La brecha entre 0,48 y 0,72 es el costo del efecto manada.⁷

Detección de Acuerdo Falso

Un módulo de detección de conformidad rastrea patrones que sugieren que los agentes están de acuerdo sin una evaluación genuina:⁷

Agrupación de puntuaciones: Que todos los agentes puntúen dentro de 0,3 puntos en una escala de 10 señala contaminación de contexto compartido en lugar de evaluación independiente. Cuando cinco agentes evaluando una refactorización de autenticación puntuaron el riesgo de seguridad entre 7,1 y 7,4, al re-ejecutar con aislamiento de contexto fresco las puntuaciones se dispersaron a 5,8-8,9.

Disidencia formulaica: Agentes copiando el lenguaje de preocupaciones de los demás en lugar de generar objeciones independientes.

Ausencia de perspectivas minoritarias: Aprobación unánime de personas con prioridades en conflicto (un Analista de Seguridad y un Ingeniero de Rendimiento rara vez están de acuerdo en todo).

El detector de conformidad captura los casos obvios (aproximadamente el 10-15% de las deliberaciones donde los agentes convergen demasiado rápido). Para el 85-90% restante, las puertas de consenso y pride check proporcionan validación suficiente.

Lo Que No Funcionó en la Deliberación

Rondas de debate en formato libre. Tres rondas de intercambio de texto para una discusión sobre indexación de base de datos produjeron 7.500 tokens de debate. Ronda 1: desacuerdo genuino. Ronda 2: posiciones reiteradas. Ronda 3: argumentos idénticos con diferentes palabras. La puntuación estructurada por dimensiones reemplazó el debate en formato libre, reduciendo el costo en un 60% mientras mejoraba la calidad del ranking.⁷

Una sola puerta de validación. La primera implementación ejecutaba un único hook de validación al final de la sesión. Un agente completó la deliberación con una puntuación de consenso de 0,52 (por debajo del umbral), luego continuó con tareas no relacionadas durante 20 minutos antes de que el hook de fin de sesión señalara el fallo. Dividir en dos puertas (una al completar la tarea, otra al finalizar la sesión) detectó los mismos problemas en diferentes puntos del ciclo de vida.⁷

Costo de la Deliberación

Cada agente de investigación procesa aproximadamente 5.000 tokens de contexto y genera entre 2.000 y 3.000 tokens de hallazgos. Con 3 agentes, eso representa entre 15.000 y 24.000 tokens adicionales por decisión. Con 10 agentes, aproximadamente entre 50.000 y 80.000 tokens.⁷

Al precio actual de Opus, una deliberación con 3 agentes cuesta aproximadamente $0,68-0,90. Una deliberación con 10 agentes cuesta $2,25-3,00. El sistema activa la deliberación en aproximadamente el 10% de las decisiones, por lo que el costo amortizado entre todas las decisiones es de $0,23-0,30 por sesión. Si eso vale la pena depende de cuánto cuesta una mala decisión.

Cuándo Deliberar

Diseño de CLAUDE.md

CLAUDE.md es política operativa para un agente de IA, no un README para humanos.²¹ El agente no necesita entender por qué usas commits convencionales. Necesita saber el comando exacto a ejecutar y cómo se ve el resultado esperado.

La Jerarquía de Precedencia

Los archivos de reglas se cargan automáticamente y proporcionan contexto estructurado sin saturar CLAUDE.md.⁶

Lo Que Se Ignora

Estos patrones de forma consistente no producen ningún cambio observable en el comportamiento del agente:²¹

Párrafos de prosa sin comandos. “Valoramos el código limpio y bien testeado” es documentación, no operaciones. El agente lo lee y procede a escribir código sin tests porque no hay una instrucción accionable.

Directivas ambiguas. “Ten cuidado con las migraciones de base de datos” no es una restricción. “Ejecuta alembic check antes de aplicar migraciones. Aborta si falta la ruta de downgrade.” sí lo es.

Prioridades contradictorias. “Avanza rápido y despliega pronto” más “Asegura cobertura de tests exhaustiva” más “Mantén el tiempo de ejecución por debajo de 5 minutos” más “Ejecuta tests de integración completos antes de cada commit.” El agente no puede satisfacer las cuatro simultáneamente y por defecto omite la verificación.²¹

Guías de estilo sin mecanismo de cumplimiento. “Sigue la guía de estilo Python de Google” sin ruff check --select D no le da al agente ningún mecanismo para verificar el cumplimiento.

Lo Que Funciona

Instrucciones orientadas a comandos:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Definiciones de cierre:

## Definición de terminado
Una tarea está completa cuando TODOS los siguientes criterios se cumplen:
1. `ruff check .` termina con código 0
2. `pytest -v` termina con código 0 sin fallos
3. `mypy app/ --strict` termina con código 0
4. Los archivos modificados han sido preparados y confirmados
5. El mensaje de commit sigue el formato convencional: `type(scope): description`

Secciones organizadas por tarea:

## Al escribir código
- Ejecuta `ruff check .` después de cada cambio en un archivo
- Agrega type hints a todas las funciones nuevas

## Al revisar código
- Verifica problemas de seguridad: `bandit -r app/`
- Comprueba la cobertura de pruebas: `pytest --cov=app --cov-fail-under=80`

## Al publicar una versión
- Actualiza la versión en `pyproject.toml`
- Ejecuta la suite completa: `pytest -v && ruff check . && mypy app/`

Reglas de escalamiento:

## Cuando estés bloqueado
- Si las pruebas fallan después de 3 intentos: detente y reporta la prueba fallida con la salida completa
- Si falta una dependencia: revisa `requirements.txt` primero, luego pregunta
- Nunca: elimines archivos para resolver errores, hagas force push ni omitas pruebas

Orden de escritura

Si empiezas desde cero, agrega las secciones en este orden de prioridad:²¹

1. Comandos de compilación y pruebas (el agente los necesita antes de poder hacer cualquier cosa útil)
2. Definición de terminado (previene completaciones falsas)
3. Reglas de escalamiento (previene soluciones destructivas)
4. Secciones organizadas por tarea (reduce el análisis de instrucciones irrelevantes)
5. Alcance por directorio (monorepos: mantiene las instrucciones de cada servicio aisladas)

Omite las preferencias de estilo hasta que las primeras cuatro estén funcionando.

Importación de archivos

Referencia otros archivos dentro de CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Sintaxis de importación: relativa (@docs/file.md), absoluta (@/absolute/path.md) o directorio home (@~/.claude/file.md). Profundidad máxima: 5 niveles de importaciones.⁶

Compatibilidad de instrucciones entre herramientas

AGENTS.md es un estándar abierto adoptado por más de 60.000 proyectos y reconocido por todas las herramientas principales de codificación con IA.²¹ Si tu equipo usa múltiples herramientas, escribe AGENTS.md como la fuente canónica y replica las secciones relevantes en los archivos específicos de cada herramienta:

Los patrones en AGENTS.md (comando primero, definido por clausura, organizado por tarea) funcionan en cualquier archivo de instrucciones sin importar la herramienta. No mantengas conjuntos de instrucciones paralelos que se desincronicen. Escribe una fuente autoritativa y replícala.

Probando tus instrucciones

Verifica que el agente realmente lee y sigue tus instrucciones:

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

La prueba de fuego: Pide al agente que explique tus comandos de compilación. Si no puede reproducirlos textualmente, las instrucciones son demasiado verbosas (el contenido fue empujado fuera del contexto), demasiado vagas (el agente no puede extraer instrucciones accionables) o no están siendo descubiertas. El análisis de GitHub sobre 2.500 repositorios encontró que la vaguedad causa la mayoría de los fallos.²¹

Patrones de producción

El quality loop

Un proceso de revisión obligatorio para todos los cambios no triviales:

1. Implementar — Escribe el código
2. Revisar — Relee cada línea. Detecta errores tipográficos, errores de lógica, secciones poco claras
3. Evaluar — Ejecuta el evidence gate. Verifica patrones, casos extremos, cobertura de pruebas
4. Refinar — Corrige cada problema. Nunca lo dejes para “después”
5. Ampliar la vista — Revisa puntos de integración, importaciones, código adyacente en busca de regresiones
6. Repetir — Si algún criterio del evidence gate falla, vuelve al paso 4
7. Reportar — Lista qué cambió, cómo se verificó, cita evidencia específica

El evidence gate

“Creo que” y “debería funcionar” no son evidencia. Cita rutas de archivos, salida de pruebas o código específico.

Si no puedes producir evidencia para alguna fila, vuelve a Refinar.²²

Patrones de manejo de errores

Escrituras atómicas de archivos. Múltiples agentes escribiendo simultáneamente al mismo archivo de estado corrompe JSON. Escribe en archivos .tmp y luego usa mv atómicamente. El sistema operativo garantiza que mv es atómico en el mismo sistema de archivos.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Recuperación de estado corrupto. Si el estado se corrompe, el patrón de recuperación lo recrea desde valores predeterminados seguros en lugar de fallar catastróficamente:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

La trampa de ((VAR++)) en bash. ((VAR++)) devuelve código de salida 1 cuando VAR es 0 porque 0++ evalúa a 0, que bash interpreta como falso. Con set -e habilitado, esto mata el script. Usa VAR=$((VAR + 1)) en su lugar.¹⁶

Clasificación del radio de impacto

Clasifica cada acción del agente por radio de impacto y aplica la compuerta correspondiente:²

Remote Control (conectarse al Claude Code local desde cualquier navegador o aplicación móvil) transforma la compuerta “Externo” de una espera bloqueante a una notificación asíncrona. El agente continúa trabajando en la siguiente tarea mientras revisas la anterior desde tu teléfono.²

Especificación de tareas para ejecuciones autónomas

Las tareas autónomas efectivas incluyen tres elementos: objetivo, criterios de completación y punteros de contexto:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Los criterios deben ser verificables por máquina: pruebas aprobadas/fallidas, salida del linter, códigos de estado HTTP, verificaciones de existencia de archivos. Una tarea temprana que pedía al agente “escribir pruebas que pasen” produjo assert True y assert 1 == 1. Técnicamente correcto. Prácticamente inútil.¹⁶

Modos de fallo a vigilar

Traza concreta de una sesión

Traza de sesión de una ejecución autónoma procesando un PRD con 5 historias:²

1. SessionStart se dispara. El dispatcher inyecta: fecha actual, detección de proyecto, restricciones de filosofía, inicialización del seguimiento de costos. Cinco hooks, 180ms en total.

2. El agente lee el PRD, planifica la primera historia. UserPromptSubmit se dispara. El dispatcher inyecta: contexto del proyecto activo, línea base de desvío de sesión.

3. El agente llama a Bash para ejecutar pruebas. PreToolUse:Bash se dispara. Verificación de credenciales, validación de sandbox, detección de proyecto. 90ms. Las pruebas se ejecutan. PostToolUse:Bash se dispara: latido de actividad registrado, verificación de desvío.

4. El agente llama a Write para crear un archivo. PreToolUse:Write se dispara: verificación de alcance de archivo. PostToolUse:Write se dispara: verificación de lint, seguimiento de commit.

5. El agente termina la historia. Stop se dispara. Verificaciones de la compuerta de calidad: ¿el agente citó evidencia? ¿Lenguaje ambiguo? ¿Comentarios TODO en el diff? Si alguna verificación falla, exit 2 y el agente continúa.

6. Verificación independiente: Un agente nuevo ejecuta la suite de pruebas sin confiar en el auto-reporte del agente anterior.

7. Tres agentes de revisión de código se generan en paralelo. Cada uno revisa el diff independientemente. Si algún revisor marca CRITICAL, la historia vuelve a la cola.

8. La historia pasa. Se carga la siguiente. El ciclo se repite para las 5 historias.

Total de hooks disparados en las 5 historias: ~340. Tiempo total en hooks: ~12 segundos. Esa sobrecarga previno tres filtraciones de credenciales, un comando destructivo y dos implementaciones incompletas en una sola ejecución nocturna.

Consideraciones de seguridad

El sandbox

Claude Code se ejecuta en un sandbox que restringe el acceso a la red y las operaciones del sistema de archivos. El sandbox impide que el modelo realice solicitudes de red arbitrarias o acceda a archivos fuera del directorio del proyecto.¹³

Límites de permisos

El sistema de permisos controla las operaciones en múltiples niveles:

Defensa contra inyección de prompts

Skills y hooks proporcionan defensa en profundidad contra la inyección de prompts:

Skills con restricciones de herramientas impiden que un prompt comprometido obtenga acceso de escritura:

allowed-tools: Read, Grep, Glob

hooks PreToolUse validan cada llamada a herramienta sin importar cómo se haya formulado el prompt al modelo:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

El aislamiento de subagents limita el radio de impacto. Un subagent con permissionMode: plan no puede realizar cambios aunque su prompt esté comprometido.

Seguridad de hooks

Los hooks HTTP que interpolan variables de entorno en encabezados requieren una lista explícita de allowedEnvVars para prevenir la exfiltración arbitraria de variables de entorno:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

La división de responsabilidades humano-agente

La seguridad en arquitecturas de agentes requiere una división clara entre las responsabilidades humanas y las del agente:¹⁷

El patrón: los humanos son responsables de las decisiones que requieren contexto organizacional, juicio ético o dirección estratégica. Los agentes son responsables de las decisiones que requieren búsqueda computacional en grandes espacios de posibilidades. Los hooks hacen cumplir ese límite.

Aplicación recursiva de hooks

Los hooks se disparan también para las acciones de subagents.¹³ Si Claude genera un subagent a través del Agent tool, tus hooks PreToolUse y PostToolUse se ejecutan para cada herramienta que el subagent utilice. Sin la aplicación recursiva de hooks, un subagent podría evadir tus controles de seguridad. El evento SubagentStop te permite ejecutar limpieza o validación cuando un subagent finaliza.

Esto no es opcional. Un agente que genera un subagent sin tus hooks de seguridad es un agente que puede hacer force-push a main, leer archivos de credenciales o ejecutar comandos destructivos mientras tus controles observan la conversación principal sin hacer nada.

El costo como arquitectura

El costo es una decisión arquitectónica, no una consideración operativa tardía.² Tres niveles:

Nivel de tokens. Compresión del system prompt. Elimina ejemplos de código de tutoriales (el modelo ya conoce las APIs), consolida reglas duplicadas entre archivos y reemplaza explicaciones con restricciones. “Rechazar llamadas a herramientas que coincidan con rutas sensibles” hace el mismo trabajo que una explicación de 15 líneas sobre por qué no se deben leer las credenciales.

Nivel de agente. Instancias nuevas en lugar de conversaciones largas. Cada historia en una ejecución autónoma recibe un agente nuevo con un contexto limpio. El contexto nunca se infla porque cada agente comienza desde cero. Briefing en lugar de memoria: los modelos ejecutan un briefing claro mejor de lo que navegan 30 pasos de contexto acumulado.

Nivel de arquitectura. CLI primero sobre MCP cuando la operación es sin estado. Una llamada claude --print para una evaluación puntual cuesta menos y no añade sobrecarga de conexión. MCP tiene sentido cuando la herramienta necesita estado persistente o streaming.

Marco de decisión

Cuándo usar cada mecanismo:

Skills vs hooks vs subagents

Preguntas frecuentes

¿Cuántos hooks son demasiados?

El rendimiento, no la cantidad, es la restricción. Cada hook se ejecuta de forma síncrona, por lo que el tiempo total de ejecución de hooks se suma a cada llamada de herramienta que coincida. 95 hooks entre configuraciones de nivel usuario y nivel proyecto se ejecutan sin latencia perceptible cuando cada hook finaliza en menos de 200 ms. El umbral a vigilar: si un hook PostToolUse añade más de 500 ms a cada edición de archivo, la sesión se siente lenta. Mide el rendimiento de tus hooks con time antes de desplegarlos.¹⁴

¿Pueden los hooks impedir que Claude Code ejecute un comando?

Sí. Los hooks PreToolUse bloquean cualquier acción de herramienta al salir con código 2. Claude Code cancela la acción pendiente y muestra la salida stderr del hook al modelo. Claude ve el motivo del rechazo y sugiere una alternativa más segura. El código de salida 1 es una advertencia no bloqueante donde la acción sigue adelante.³

¿Dónde debo colocar los archivos de configuración de hooks?

Las configuraciones de hooks van en .claude/settings.json para hooks a nivel de proyecto (commiteados en tu repositorio, compartidos con tu equipo) o en ~/.claude/settings.json para hooks a nivel de usuario (personales, aplicados a cada proyecto). Los hooks a nivel de proyecto tienen prioridad cuando existen ambos. Usa rutas absolutas para los archivos de scripts para evitar problemas con el directorio de trabajo.¹⁴

¿Todas las decisiones necesitan deliberación?

No. El módulo de confianza evalúa las decisiones en cuatro dimensiones (ambigüedad, complejidad, impacto, dependencia del contexto). Solo las decisiones con una puntuación de confianza general por debajo de 0,70 activan la deliberación, aproximadamente el 10% del total de decisiones. Correcciones de documentación, renombrar variables y ediciones rutinarias omiten la deliberación por completo. Cambios en la arquitectura de seguridad, esquemas de base de datos y despliegues irreversibles la activan de forma consistente.⁷

¿Cómo pruebo un sistema diseñado para producir desacuerdo?

Prueba tanto las rutas de éxito como las de fallo. Éxito: los agentes discrepan productivamente y alcanzan consenso. Fallo: los agentes convergen demasiado rápido, nunca convergen o exceden los presupuestos de generación. Las pruebas end-to-end simulan cada escenario con respuestas deterministas de agentes, verificando que ambas puertas de validación detecten cada modo de fallo documentado. Un sistema de deliberación en producción ejecuta 141 pruebas en tres capas: 48 pruebas de integración bash, 81 pruebas unitarias de Python y 12 simulaciones de pipeline end-to-end.⁷

¿Cuál es el impacto en latencia de la deliberación?

Una deliberación con 3 agentes añade entre 30 y 60 segundos de tiempo real (los agentes se ejecutan secuencialmente a través del Agent tool). Una deliberación con 10 agentes añade entre 2 y 4 minutos. Los hooks de consenso y pride check se ejecutan cada uno en menos de 200 ms. El cuello de botella principal es el tiempo de inferencia de LLM por agente, no la sobrecarga de orquestación.⁷

¿Qué tan largo debe ser un archivo CLAUDE.md?

Mantén cada sección por debajo de 50 líneas y el archivo total por debajo de 150 líneas. Los archivos largos se truncan por las ventanas de contexto, así que coloca las instrucciones más críticas al principio: comandos y definiciones de closures antes que preferencias de estilo.²¹

¿Puede esto funcionar con herramientas distintas a Claude Code?

Los principios arquitectónicos (hooks como puertas deterministas, skills como experiencia de dominio, subagents como contextos aislados, sistema de archivos como memoria) se aplican conceptualmente a cualquier sistema agéntico. La implementación específica utiliza los eventos del ciclo de vida de Claude Code, patrones de matcher y el Agent tool. AGENTS.md lleva los mismos patrones a Codex, Cursor, Copilot, Amp y Windsurf.²¹ El patrón de harness es agnóstico de herramienta aunque los detalles de implementación sean específicos de cada una.

Tarjeta de Referencia Rápida

Configuración de Hooks

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Frontmatter de Skills

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Definición de Subagents

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Códigos de Salida

Comandos Clave

Ubicación de Archivos

Registro de Cambios

Referencias