Arquitectura de Agentes: Construyendo Sistemas de Desarrollo Impulsados por IA

TL;DR: Claude Code no es una caja de chat con acceso a archivos. Es un runtime programable con 29 eventos de ciclo de vida documentados, cada uno enganchable con scripts de shell que el modelo no puede saltarse. Apila hooks en despachadores, despachadores en skills, skills en agentes, agentes en flujos de trabajo, y obtienes un harness de desarrollo autónomo que aplica 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. Cero frameworks requeridos. Todo en 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 le permiten al agente aferrarse al mundo más allá de su ventana de contexto.¹ La mayoría de los desarrolladores tratan a los agentes de codificación con IA como asistentes interactivos. Escriben un prompt, lo ven editar un archivo, y siguen adelante. Ese encuadre limita la productividad a lo que puedes supervisar personalmente.

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

La distinción importa porque la infraestructura se compone. 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 de forma consistente, ya sea que lo invoques tú o un agente. Un agente que revisa código por seguridad ejecuta las mismas verificaciones, estés mirando o no.²

Puntos clave

• Los hooks garantizan ejecución; los prompts no. Usa hooks para linting, formateo, verificaciones de seguridad y cualquier cosa que deba ejecutarse cada vez sin importar el comportamiento del modelo. El código de salida 2 bloquea acciones. El código de salida 1 solo advierte.³
• Los skills codifican experticia de dominio que se autoactiva. El campo description lo determina todo. Claude usa razonamiento LLM (no coincidencia de palabras clave) para decidir cuándo aplicar un skill.⁴
• Los subagentes previenen la inflación del contexto. Las ventanas de contexto aisladas para exploración y análisis mantienen ligera la sesión principal. Ejecuta subagentes independientes en paralelo, y usa equipos de agentes cuando los workers necesiten coordinación sostenida.⁵
• La memoria vive en el sistema de archivos. Los archivos persisten a través de las ventanas de contexto. CLAUDE.md, MEMORY.md, los directorios de reglas y los documentos de handoff forman un sistema de memoria externa estructurado.⁶
• La deliberación multi-agente detecta puntos ciegos. Los agentes individuales no pueden cuestionar sus propias suposiciones. Dos agentes independientes con distintas prioridades de evaluación detectan fallos estructurales que las puertas de calidad no pueden abordar.⁷
• El patrón harness es el sistema. CLAUDE.md, hooks, skills, agentes y memoria 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 apoya en la anterior. El Decision Framework al final ofrece una tabla de búsqueda para elegir el mecanismo correcto para cada tipo de problema.

La ruta dorada de cinco minutos

Antes de la inmersión profunda, aquí tienes el camino más corto desde cero hasta un harness funcional. Un hook, un skill, un subagent, un resultado.

Paso 1: crea un hook de seguridad (2 minutos)

Crea .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Conéctalo en .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Resultado: cada comando bash que Claude ejecuta ahora se analiza en busca de credenciales filtradas. El modelo no puede omitir esta verificación.

Paso 2: crea un skill de revisión de código (1 minuto)

Crea .claude/skills/reviewer/SKILL.md con frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) y una lista de verificación: inyección SQL, XSS, secretos codificados, manejo de errores ausente, funciones de más de 50 líneas.

Resultado: Claude activa automáticamente esta experiencia cada vez que mencionas revisar, verificar o auditar.

Paso 3: genera un subagent (30 segundos)

En cualquier sesión de Claude Code, pídele a Claude que revise los últimos 3 commits en busca de problemas de seguridad usando un agente separado. Claude genera un Explore agent que lee el diff, aplica tu skill de revisión y devuelve un resumen. Tu contexto principal se mantiene limpio.

Lo que ahora tienes

Un harness de tres capas: una puerta de seguridad determinista (hook), experiencia de dominio que se activa automáticamente (skill) y análisis aislado que protege tu contexto (subagent). Cada sección a continuación amplía una de estas tres capas.

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. El código barato sin infraestructura de verificación produce bugs a escala. La inversión que rinde no es un mejor prompt. Es el sistema que rodea al modelo y atrapa lo que el modelo pasa por alto.

Tres fuerzas hacen que la arquitectura de agentes sea necesaria:

Las ventanas de contexto son finitas y con pérdida. Cada archivo leído, salida de herramienta y turno de conversación consume tokens. Microsoft Research y Salesforce probaron 15 LLMs a través de más de 200.000 conversaciones simuladas y encontraron una caída de rendimiento promedio del 39% de la interacción de un solo turno a la interacción de múltiples turnos.⁹ La degradación comienza en tan solo dos turnos y sigue una curva predecible: las ediciones precisas de múltiples archivos en los primeros 30 minutos se degradan a una visión de túnel de un solo archivo para el minuto 90. Las ventanas de contexto más largas no arreglan esto. La condición “Concat” del mismo estudio (conversación completa como un único prompt) logró 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 “ejecuta siempre Prettier después de editar archivos” funciona aproximadamente el 80% del tiempo.³ El modelo podría olvidarlo, priorizar la velocidad o decidir que el cambio es “demasiado pequeño.” Para cumplimiento, 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 gana a lo probabilístico.

Las perspectivas individuales pasan por alto problemas multidimensionales. Un solo agente que revisaba un endpoint API verificó la autenticación, validó el saneamiento de entrada y comprobó los encabezados CORS. Certificado de salud impecable. Un segundo agente, al que se le indicó por separado actuar como pentester, encontró que el endpoint aceptaba parámetros de consulta sin límite que podían provocar 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 soluciona.

La arquitectura de agentes aborda las tres: los hooks imponen restricciones deterministas, los subagents gestionan el aislamiento de contexto y la orquestación multi-agente aporta 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 codificación 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 iniciar la sesión y después de cada compactación. Esta es la memoria arquitectónica de largo plazo del agente.

Capa de extensión: las skills aportan experiencia de dominio que se autoactiva según el contexto. Los hooks proporcionan compuertas deterministas que se disparan en cada llamada a herramienta coincidente. Los archivos de memoria persisten el estado entre sesiones. Los agentes personalizados ofrecen 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 exclusivamente en la capa central, observando cómo crece el contexto y suben los costos. Los usuarios avanzados configuran las capas de instrucciones y extensión, y luego usan la capa central solo para orquestación y decisiones finales.²

Harnesses gestionados vs. autoalojados (abril de 2026)

Durante principios de 2026, el camino de “construye tu propio harness” fue la única opción real. En abril de 2026, eso cambió. Anthropic lanzó Claude Managed Agents en beta pública (8 de abril): bucle del harness + ejecución de herramientas + contenedor sandbox + persistencia de estado como una REST API, facturada a tokens estándar más $0,08/hora-sesión. La actualización Agents SDK de OpenAI (16 de abril) formalizó la misma división — harness y cómputo como capas separadas, con proveedores nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) y snapshot/rehydrate para sobrevivir a la pérdida de contenedores.²³²⁴

La superficie más profunda del SDK del lado de OpenAI llegó en openai-agents Python v0.14.0 (lanzado el 15 de abril de 2026; anunciado el 16 de abril): una subclase SandboxAgent de Agent con default_manifest, instrucciones de sandbox y capacidades; un Manifest que describe el contrato de espacio de trabajo limpio (archivos, directorios, archivos locales, repositorios Git, env, usuarios, mounts); un SandboxRunConfig para el cableado por ejecución del cliente de sandbox, inyección de sesión en vivo, sobreescrituras del manifest, snapshots y límites de concurrencia de materialización. Las capacidades integradas cubren acceso a shell, edición de sistema de archivos, inspección de imágenes, skills, memoria de sandbox y compactación. La memoria del sandbox persiste las lecciones extraídas entre ejecuciones y las divulga progresivamente; los workspaces admiten archivos locales, entradas de repositorios Git y mounts remotos (S3, R2, GCS, Azure Blob, S3 Files); los snapshots son portables entre proveedores. Backends: UnixLocalSandboxClient, DockerSandboxClient y clientes alojados para Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel mediante extras opcionales.²⁴

Para proyectos en Python que quieren incrustar el runtime de Claude Code como librería — entre “ejecutar claude en un shell” y “REST API a Managed Agents” — claude-agent-sdk-python es la tercera opción. La serie del 28 al 29 de abril (v0.1.69 → v0.1.71) actualizó el CLI incluido a v2.1.123, elevó el piso de la dependencia mcp a >=1.19.0 (las versiones anteriores descartaban silenciosamente los retornos CallToolResult de las herramientas MCP en proceso, dejando al modelo con un blob de error de validación) y llevó SandboxNetworkConfig a paridad de schema con el SDK de TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

La bifurcación arquitectónica ya es real:

Cuándo elegir cuál: el autoalojado sigue siendo lo correcto para equipos que ya tienen músculo de infraestructura, quieren skills/hooks que controlan o están optimizando profundamente un flujo de trabajo específico. El gestionado es lo correcto para equipos sin ingenieros de plataforma dedicados, cuando el tiempo hasta el valor importa más que la personalización, o cuando las ejecuciones del agente necesitan sobrevivir de forma confiable al cierre del laptop sin que tengas que construir esa capa de persistencia. Los dos son compatibles — puedes ejecutar un harness autoalojado que delegue tareas específicas de larga duración a Managed Agents mediante su REST API.

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 aplica a todos los proyectos. El árbol .claude/ en cada repositorio es específico del proyecto y se comparte vía git. Juntos, conforman el harness completo.

Sistema de Skills

Las skills son extensiones invocadas por el modelo. Claude las descubre y las aplica automáticamente según el contexto, sin que tengas que llamarlas explícitamente.⁴ El momento en que te descubres reexplicando el mismo contexto sesión tras sesión es el momento en que deberías construir una skill.

Cuándo construir una skill

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

Crear una skill

Las skills viven en cuatro ubicaciones posibles, desde el alcance más amplio al más estrecho:⁴

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

---
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

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Referencia de frontmatter

El campo description lo es todo

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

Descripción mala:

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 en busca de tipos específicos de problemas), cuándo usarla (examinar cambios, PRs, análisis de calidad) y frases disparadoras (review, audit, check) que los usuarios escriben de forma natural.

Presupuesto de contexto

Todas las descripciones de skills comparten un presupuesto de contexto que escala dinámicamente al 1 % de la ventana de contexto, con un valor de respaldo de 8.000 caracteres.⁴ Si tienes muchas skills, mantén cada descripción concisa y pon primero el caso de uso clave. Puedes anular el presupuesto mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ pero la mejor solución son descripciones más cortas y precisas. Ejecuta /context durante una sesión para comprobar si se está excluyendo alguna skill.

Archivos de apoyo y organización

Las skills pueden hacer referencia a 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 la skill se activa. Mantén SKILL.md por debajo de 500 líneas y traslada el material de referencia detallado a archivos de apoyo.¹²

Compartir skills mediante Git

Las skills de proyecto (.claude/skills/ en la raíz del repo) 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 tus compañeros de equipo hagan pull, obtendrán la skill automáticamente. Sin instalación, sin configuración. Esta es la forma más efectiva de estandarizar la experiencia en un equipo.

Skills como biblioteca de prompts

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

~/.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. Juntas, forman una base de conocimiento de la que Claude extrae automáticamente según el contexto. Un desarrollador junior obtiene orientación de nivel senior sin pedirla.

Las skills se componen con hooks

Las skills pueden definir sus propios hooks en el frontmatter que se activan solo mientras la skill está en ejecución. 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'"
---

Las skills de filosofía se autoactivan mediante hooks SessionStart, inyectando restricciones de calidad en cada sesión sin invocación explícita. La skill en sí es conocimiento. El hook es la aplicación. Juntos, forman una capa de política.

Errores comunes con las skills

Descripciones demasiado amplias. Una skill git-rebase-helper que se active 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 añadir disable-model-invocation: true y exigir invocación explícita mediante /skill-name.⁴

Demasiadas skills compitiendo por el presupuesto. Más skills significa más descripciones compitiendo por el presupuesto de contexto del 1 %. Si notas que algunas skills no se activan, revisa /context para ver cuáles están excluidas. Prioriza menos skills bien descritas frente a muchas imprecisas.

Información crítica enterrada en archivos de apoyo. Claude lee SKILL.md inmediatamente, pero solo accede a los archivos de apoyo cuando los necesita. Si la información crítica está en un archivo de apoyo, puede que Claude no la encuentre. Pon la información esencial directamente en SKILL.md.⁴

Superficie de skills de SDK (8 de mayo de 2026)

Los harnesses autohospedados sobre claude-agent-sdk-python v0.1.77+ deberían usar la opción skills en ClaudeAgentOptions para declarar las skills disponibles, no el valor heredado "Skill" en allowed_tools.³⁷ El atajo "Skill" está obsoleto y la opción dedicada le da a Claude Code información más estructurada sobre qué skills están disponibles. El CLI incluido en v0.1.77 es v2.1.133.

Arquitectura de hooks

Los hooks son comandos de shell activados por 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 bash de 10 líneas verifica el comando contra una lista de bloqueo y lo rechaza antes de que el shell lo vea siquiera. El hook se dispara independientemente de si el modelo lo desea o no.

Eventos disponibles

Claude Code expone 29 eventos del ciclo de vida documentados en ocho categorías al momento de esta actualización de la guía. La lista de eventos crece con cada versión, así que trata los documentos de referencia como la fuente de verdad y consulta el cheat sheet para ver la tabla completa actual antes de configurar hooks de producción:¹³

Semántica de los códigos de salida

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

Crítico: Cada hook de seguridad debe usar exit 2, no exit 1. Exit 1 es una advertencia sin bloqueo. El comando peligroso se sigue ejecutando. Este es el error de hook más común en los equipos.¹⁴

Configuración de hooks

Los hooks viven 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 filtra un valor específico del evento. Para los eventos de herramientas, coincide con valores de tool_name como Bash, Edit, Write, Read, Glob, Grep, nombres de herramientas MCP como mcp__server__tool, o * para todas las herramientas. Los nombres simples y las listas separadas por | son coincidencias exactas; los valores con otros caracteres son expresiones regulares de JavaScript. Algunos eventos no admiten matchers y siempre se disparan cuando están configurados.¹³

Protocolo de entrada/salida de hooks

Los hooks reciben JSON por 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 un control avanzado, los hooks PreToolUse pueden devolver JSON para modificar la entrada de la herramienta, inyectar contexto o tomar decisiones de permisos. Usa el wrapper hookSpecificOutput — el formato anterior decision/reason de nivel superior está obsoleto para PreToolUse:

{
  "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?¹⁴

Las garantías de formato aseguran consistencia después del hecho. Los hooks PostToolUse en Write/Edit ejecutan tu formateador después de cada cambio de 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'"
          }
        ]
      }
    ]
  }
}

Las garantías de seguridad previenen acciones peligrosas antes de que se ejecuten. Los hooks PreToolUse en Bash inspeccionan los comandos y bloquean los 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

Las 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 los comandos de shell

Claude Code admite cinco tipos de hooks:¹³

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

Hooks de herramientas MCP (type: "mcp_tool") llaman a una herramienta en un servidor MCP ya conectado. Úsalos cuando la lógica de validación ya vive detrás de un límite MCP y no necesita un script de shell separado.

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 matizadas que la regex no puede expresar.

Hooks de agente (type: "agent") generan un subagente con acceso a herramientas (Read, Grep, Glob) para verificación multi-turno. Son experimentales; prefiere los hooks de comando para las puertas de producción y reserva los hooks de agente para verificaciones que realmente requieran inspeccionar archivos reales o salidas de pruebas:

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

Hooks HTTP (type: "http") envían la entrada JSON del evento como una solicitud POST a una URL y reciben JSON de vuelta. Úsalos para webhooks, servicios de notificación externos o validación basada en API (v2.1.63+). No es compatible con eventos SessionStart:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

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 logging:¹³

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

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

Despachadores en lugar de hooks independientes

Ejecutar siete hooks que se disparan todos en el mismo evento, cada uno leyendo stdin de forma independiente, crea condiciones de carrera. Dos hooks que escriban al mismo archivo de estado JSON de forma concurrente truncarán el JSON. Cada hook descendente que analice ese archivo se romperá.²

La solución: un despachador por evento que ejecuta los hooks secuencialmente desde stdin en caché:

#!/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. Pasa JSON de muestra por pipe: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Usa stderr para la salida de depuración. El stderr del código de salida 2 se envía de vuelta a Claude como mensaje de error. El stderr sin bloqueo (exit 1, 3, etc.) aparece solo en modo detallado (Ctrl+O).
3. Vigila los fallos de jq. Las 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 aplicación mientras parece funcionar.
5. Mantén los hooks rápidos. Los hooks se ejecutan de forma síncrona. Mantén todos los hooks por debajo de 2 segundos, idealmente por debajo de 500 ms.

Streaming de eventos de hooks del lado del SDK

Los harnesses autoalojados construidos sobre claude-agent-sdk-python (v0.1.74+, 6 de mayo de 2026) pueden suscribirse a los eventos de hooks directamente desde el flujo de mensajes en lugar de pasar por callbacks de scripts de shell.³⁶ Configura include_hook_events=True en ClaudeAgentOptions y los objetos HookEventMessage (PreToolUse, PostToolUse, Stop y otros) se entregan desde el mismo iterador que los mensajes del asistente y los resultados de las herramientas. Esto refleja la opción includeHookEvents del SDK de TypeScript; el CLI incluido subió a v2.1.129 en la misma versión.

El patrón de flujo de eventos es la opción adecuada cuando tu harness ya vive en Python y quieres las señales de hooks en el mismo flujo de control que la salida del modelo. El contrato de hooks de scripts de shell (códigos de salida, stdin JSON, despachadores) sigue siendo la respuesta adecuada para harnesses que componen múltiples herramientas, comparten hooks entre Claude Code y Codex, o necesitan semántica de códigos de salida para el bloqueo.

Esfuerzo y procedencia de la sesión (7-8 de mayo de 2026)

Dos adiciones en Claude Code v2.1.132 y v2.1.133 dan a los hooks y subprocesos una mejor señal sobre su contexto de ejecución:³⁸³⁹

• effort.level en la entrada del hook. Los hooks ahora reciben un campo JSON effort.level en la misma entrada que lleva tool_input y session_id. El mismo valor se exporta como la variable de entorno $CLAUDE_EFFORT, para que los comandos Bash puedan leerlo sin analizar JSON. Usa esto para escalar el costo del hook con el nivel de esfuerzo: omite la validación costosa en low, ejecuta la puerta de seguridad completa en xhigh o max.
• Variable de entorno CLAUDE_CODE_SESSION_ID en subprocesos Bash. Los subprocesos de la herramienta Bash ahora ven el mismo valor de session_id que ven los hooks, expuesto como CLAUDE_CODE_SESSION_ID. Esto cierra la brecha de procedencia para herramientas que registran estado por sesión y antes no podían correlacionar eventos de subproceso con eventos de hook.

Ambas señales están disponibles sin cambios de código; los hooks existentes que ignoran los nuevos campos siguen funcionando.

Memoria y contexto

Cada 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. Las decisiones arquitectónicas documentadas en el turno 3 podrían no sobrevivir hasta el turno 15.⁹

Los tres mecanismos del colapso multi-turno

El estudio de MSR/Salesforce identificó tres mecanismos independientes, cada uno requiere 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 vive 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 a lo largo de las sesiones. Cuando descubres que ((VAR++)) falla con set -e en bash cuando VAR es 0, lo registras. Tres sesiones después, cuando te encuentras con un caso límite similar de enteros en Python, la entrada de MEMORY.md hace aflorar el patrón.¹⁵

Auto Memory (v2.1.32+): Claude Code registra y recuerda 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 de tema 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 las decisiones clave, el contenido de los archivos y el estado de las tareas.¹⁵

Cuándo compactar: - Después de completar una subtarea distinta (función implementada, bug arreglado) - Antes de comenzar una nueva área del código - Cuando Claude empieza a repetirse o a 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 entre sesiones

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 le da a la sesión sucesora contexto completo a un costo mínimo de tokens. Comenzar una sesión nueva con claude -c (continue) o leer el documento de handoff lleva directo a la implementación.¹⁵

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

Para sesiones que exceden los 60-90 minutos, lanza una instancia fresca de Claude por iteración. El estado persiste a través del sistema de archivos, no a través de la memoria conversacional. Cada iteración recibe 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

Compáralo con una sola sesión larga:

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 sobrecarga por 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 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 salidas de mayor calidad pese a la sobrecarga.

Estrategia 5: curación de memoria gestionada (Dreaming)

Los Managed Agents de Anthropic y Claude añadieron Dreaming como Research Preview el 6 de mayo de 2026.³⁵ Según Anthropic: “Dreaming es un proceso programado que revisa las sesiones de tu agente y los almacenes de memoria, extrae patrones y cura las memorias para que tus agentes mejoren con el tiempo.”³⁵

Dreaming se ejecuta en segundo plano entre sesiones, no en la ruta crítica. Complementa, en lugar de reemplazar, el patrón de sistema-de-archivos-como-memoria: tu archivo MEMORY.md sigue siendo la superficie portante; Dreaming escribe entradas de memoria curadas en el almacén de memoria de Managed Agents, que el agente lee al inicio de la sesión. Los dos patrones coexisten para harnesses que mezclan estado autohospedado en sistema de archivos con curación del lado gestionado.

Dreaming está en Research Preview, así que el comportamiento puede cambiar. Los patrones de session-handoffs y CLAUDE.md documentados arriba siguen siendo el mecanismo de memoria autoritativo para harnesses autohospedados.

Los anti-patrones

Leer archivos enteros cuando solo 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 de error verbosa en el contexto. Después de depurar un bug, tu contexto sostiene más de 40 stack traces de iteraciones fallidas. Un solo /compact después de arreglar el bug libera ese peso muerto.

Empezar cada sesión leyendo cada archivo. 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 subagentes

Los subagentes 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 los resultados como resúmenes. Los resultados de la exploración no inflan tu conversación principal; solo regresan las conclusiones.⁵

Tipos de subagentes integrados

Creación de subagentes personalizados

Define los subagentes 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 del subagente

Aislamiento por worktree

Los subagentes pueden operar en worktrees temporales de git, lo que proporciona una copia aislada y 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 por worktree es esencial para trabajo experimental que podría romper el código base.

Subagentes en paralelo

Usa subagentes en paralelo para tareas de investigación independientes que no necesitan coordinarse entre sí:⁵

> 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 permanece limpio.

El guard de recursión

Sin límites de generación, los agentes delegan en agentes que delegan en agentes, perdiendo contexto y consumiendo tokens en cada paso. El patrón del guard de recursión 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 por profundidad rastrean cadenas padre-hijo (bloqueadas en profundidad 3) pero pasan por alto el ancho: 23 agentes en profundidad 1 siguen siendo “profundidad 1”. Un presupuesto de generación rastrea el total de hijos activos por padre, con un tope configurable. El modelo de presupuesto se ajusta al modo de fallo real (demasiados agentes en total) en lugar de a una métrica indirecta (demasiados niveles de anidación).⁷

Agent Teams (Research Preview)

Agent Teams coordina varias instancias de Claude Code que trabajan de forma independiente, se comunican mediante una bandeja de entrada compartida y una lista de tareas, y pueden cuestionar los hallazgos de las demás:⁵

Habilítalo con: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Cuándo usar agent teams frente a subagentes:

Orquestación multiagente

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

Orquestación entre herramientas (abril de 2026): Google liberó Scion como código abierto el 7 de abril — un hipervisor multiagente que ejecuta Claude Code, Gemini CLI y otros “deep agents” como procesos concurrentes, cada uno con contenedor aislado, git worktree y credenciales propias. Se ejecuta en local, hub o Kubernetes. Filosofía explícita: “aislamiento sobre restricciones” — los agentes operan con alta autonomía dentro de límites impuestos en la capa de infraestructura, no en el prompt.²⁵ Esto extiende directamente el argumento de aislamiento de subagentes a distintos proveedores de herramientas. Si tu flujo de trabajo abarca Claude y modelos de OpenAI, Scion es la primera implementación de referencia real para subagentes entre herramientas con worktree y aislamiento de credenciales por agente.

El debate no es una bala de plata: El cluster de investigación M3MAD-Bench (principios de 2026) descubrió que el debate multiagente se estanca y puede ser subvertido por un consenso engañoso — los argumentos válidos pierden cuando otros agentes afirman con seguridad la respuesta equivocada.²⁶ Tool-MAD mejora esto al dar a cada agente acceso heterogéneo a herramientas y al usar puntajes de Faithfulness/Relevance en la etapa del juez. Si estás construyendo orquestación tipo debate, invierte en (a) heterogeneidad de herramientas por agente y (b) puntuación cuantitativa del juez, en lugar de asumir que más agentes = mejores respuestas.

Orquestación multiagente gestionada y Outcomes (Beta pública)

Si no quieres construir la infraestructura de deliberación descrita a continuación, Multiagent Orchestration entró en Beta pública en Claude Managed Agents el 6 de mayo de 2026.³⁵ Según Anthropic: “Cuando hay demasiado trabajo para que un solo agente lo haga bien, la orquestación multiagente permite que un agente líder divida el trabajo en piezas y delegue cada una a un especialista con su propio modelo, prompt y herramientas”.³⁵ Los especialistas “trabajan en paralelo sobre un sistema de archivos compartido y contribuyen al contexto general del agente líder”.³⁵

El tracing viene incluido. Según Anthropic: “también puedes rastrear cada paso en la Claude Console: qué agente hizo qué, en qué orden y por qué, lo que te da visibilidad completa de cómo se delegó y ejecutó tu tarea”.³⁵

La función complementaria en Beta pública es Outcomes. Según Anthropic: “escribes una rúbrica que describe cómo se ve el éxito y el agente trabaja hacia ella. Un evaluador independiente compara la salida con tus criterios en su propia ventana de contexto, de modo que no se ve influenciado por el razonamiento del agente”.³⁵ Esta es la versión gestionada del patrón de validación de dos puertas documentado más adelante en esta sección: la rúbrica reemplaza la puerta escrita a mano, el evaluador independiente reemplaza el validador de consenso.

La deliberación autohospedada sigue siendo la respuesta correcta cuando la validación necesita integrarse con tu propia superficie de hooks (bloqueo PreToolUse, semántica de códigos de salida, dispatchers personalizados) o cuando el harness debe ejecutarse sin dependencias externas. Multiagent gestionado es la respuesta correcta cuando la delegación estándar más la evaluación por rúbrica es el contrato que realmente necesitas.

Deliberación mínima viable

Empieza 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 aporta una mejora incremental.

El disparador de confianza

No toda tarea necesita deliberación. Un módulo de puntuación de confianza evalúa cuatro dimensiones:¹⁷

1. Ambigüedad - ¿La consulta tiene múltiples interpretaciones válidas?
2. Complejidad del dominio - ¿Requiere conocimiento especializado?
3. Riesgo - ¿Es reversible la decisión?
4. Dependencia del contexto - ¿Requiere comprender el sistema más amplio?

La puntuación se asigna 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 sobreingeniería en tareas simples y a la vez asegura que las decisiones riesgosas reciban escrutinio.⁷

La máquina de estados

Siete fases, cada una bloqueada por la anterior:⁷

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

RESEARCH: Agentes independientes investigan el tema. Cada agente recibe una persona distinta (Arquitecto Técnico, Analista de Seguridad, Ingeniero de Performance, 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 la investigación y generan alternativas. El agente Debate identifica conflictos. El agente Synthesis combina los hallazgos no contradictorios.

RANKING: Cada agente puntúa cada enfoque propuesto a través de 5 dimensiones ponderadas:

La arquitectura de validación de dos puertas

Dos puertas de validación capturan problemas en distintas 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 adaptable a la 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: los disensos tienen razones documentadas 3. Manejo de complejidad: al menos 2 alternativas generadas 4. Confianza del consenso: clasificada como fuerte (sobre 0,85) o moderada (0,70-0,84) 5. Evidencia de mejora: la confianza final supera la confianza inicial

Dos hooks en distintos puntos del ciclo de vida coinciden con cómo ocurren los fallos en realidad: algunos son instantáneos (mal puntaje) y otros son graduales (baja diversidad, falta de documentación de disenso).⁷

Por qué el acuerdo es peligroso

Charlan Nemeth estudió el disenso minoritario desde 1986 hasta su libro de 2018 In Defense of Troublemakers. Los grupos con disidentes toman mejores decisiones que los grupos que llegan a un acuerdo rápido. El disidente no necesita tener razón. El acto de discrepar fuerza a la mayoría a examinar suposiciones que de otro modo omitirían.¹⁸

Wu et al. probaron si los agentes LLM pueden debatir genuinamente y descubrieron que, sin incentivos estructurales para el desacuerdo, los agentes convergen hacia la respuesta inicial que suena con más confianza, sin importar si es correcta.¹⁹ Liang et al. identificaron la causa raíz como “Degeneration-of-Thought”: una vez que un LLM establece confianza en una posición, la autorreflexión no puede generar contraargumentos novedosos, lo que hace estructuralmente necesaria la evaluación multiagente.²⁰

La independencia es la restricción crítica de diseño. Dos agentes evaluando la misma estrategia de despliegue con visibilidad de los hallazgos del otro produjeron puntajes 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 herding.⁷

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 puntajes: Que cada agente puntúe 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 que evaluaban una refactorización de autenticación puntuaron el riesgo de seguridad entre 7,1 y 7,4, al volver a ejecutarlo con aislamiento de contexto fresco los puntajes se dispersaron a 5,8-8,9.

Disenso boilerplate: Agentes que copian el lenguaje de preocupación de otros en lugar de generar objeciones independientes.

Perspectivas minoritarias ausentes: Aprobación unánime desde personas con prioridades en conflicto (un Analista de Seguridad y un Ingeniero de Performance rara vez coinciden en todo).

El detector de conformidad atrapa 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 ofrecen validación suficiente.

Lo que no funcionó en la deliberación

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

Puerta de validación única. La primera implementación ejecutaba un único hook de validación al final de la sesión. Un agente completó la deliberación con un puntaje de consenso de 0,52 (bajo el umbral) y luego continuó con tareas no relacionadas durante 20 minutos antes de que el hook de fin de sesión marcara el fallo. Dividirlo en dos puertas (una al completar la tarea, otra al final de la sesión) capturó los mismos problemas en distintos puntos del ciclo de vida.⁷

El costo de la deliberación

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

A los precios actuales de Opus, una deliberación de 3 agentes cuesta aproximadamente entre $0,68 y $0,90. Una deliberación de 10 agentes cuesta entre $2,25 y $3,00. El sistema activa deliberación en aproximadamente el 10% de las decisiones, por lo que el costo amortizado sobre todas las decisiones es de $0,23-0,30 por sesión. Si vale la pena o no depende de cuánto cuesta una mala decisión.

Cuándo deliberar

Diseño de CLAUDE.md

CLAUDE.md es una política operativa para un agente de IA, no un README para humanos.²¹ El agente no necesita entender por qué usas conventional commits. Necesita saber el comando exacto que debe ejecutar y cómo se ve “terminado”.

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 producen consistentemente cambios no observables en el comportamiento del agente:²¹

Párrafos de prosa sin comandos. “Valoramos código limpio y bien probado” es documentación, no operaciones. El agente lo lee y procede a escribir código sin pruebas 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. “Muévete rápido y entrega rápido” más “Asegura una cobertura de pruebas exhaustiva” más “Mantén el tiempo de ejecución por debajo de 5 minutos” más “Ejecuta pruebas de integración completas 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 aplicación. “Sigue la Google Python Style Guide” sin ruff check --select D no le da al agente ningún mecanismo para verificar el cumplimiento.

Lo que funciona

Instrucciones que priorizan los 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:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Secciones organizadas por tarea:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Reglas de escalación:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Orden de escritura

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

1. Comandos de build y test (el agente los necesita antes de poder hacer cualquier cosa útil)
2. Definición de terminado (previene falsas finalizaciones)
3. Reglas de escalación (previene workarounds destructivos)
4. Secciones organizadas por tarea (reduce el parsing de instrucciones irrelevantes)
5. Alcance de directorios (monorepos: mantiene aisladas las instrucciones por servicio)

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 imports.⁶

Compatibilidad de instrucciones entre herramientas

AGENTS.md es un estándar abierto reconocido por todas las principales herramientas 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 a archivos específicos de cada herramienta:

Los patrones de AGENTS.md (priorizar comandos, definir cierre, organizar por tarea) funcionan en cualquier archivo de instrucciones independientemente de la herramienta. No mantengas conjuntos de instrucciones paralelos que diverjan. Escribe una sola fuente autoritativa y replícala.

Notas de paridad con Codex

Codex ahora tiene equivalentes de primera clase para las principales capas del harness, pero la migración es una traducción de patrones, no una copia de archivos. Codex lee AGENTS.md antes de comenzar el trabajo, superponiendo guía global de ~/.codex con instrucciones del proyecto y de repositorios anidados.³¹ Las skills de Codex usan el mismo modelo mental de SKILL.md con divulgación progresiva: Codex comienza con el nombre, descripción y ruta del archivo de la skill, y luego carga la skill completa solo cuando decide usarla.³² Codex también tiene hooks nativos, hooks empaquetados en plugins, hooks gestionados, soporte de MCP, y workflows explícitos de subagents.³³³⁴

El mapeo práctico:

La diferencia importante: los subagents de Claude pueden seleccionarse automáticamente a partir de descripciones, mientras que Codex actualmente documenta los workflows de subagents como explícitos. Eso hace que las skills y los hooks sean el valor por defecto correcto para el comportamiento siempre activo del harness en Codex; los subagents son para trabajo paralelo deliberado, revisión y exploración.

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 ácida: Pide al agente que explique tus comandos de build. Si no puede reproducirlos textualmente, las instrucciones son demasiado extensas (contenido expulsado del contexto), demasiado vagas (el agente no puede extraer instrucciones accionables), o no se están descubriendo. El análisis de GitHub sobre 2.500 repositorios encontró que la vaguedad causa la mayoría de los fallos.²¹

Patrones de Producción

Patrones de Horizonte Largo de Opus 4.7 (abril de 2026)

Claude Opus 4.7 (16 de abril de 2026) llegó con capacidades específicas que cambian aquello contra lo que un harness debe defenderse:²⁹

• Resiliencia ante fallos de herramientas: Opus 4.7 continúa a pesar de fallos de herramientas que detenían las sesiones de Opus 4.6. Puedes reducir — pero no eliminar — los wrappers defensivos de reintento en el código de los subagentes. Mantén las protecciones a nivel de hooks; recorta el andamiaje en el prompt de “si la herramienta falla, intenta de nuevo tres veces”.
• Nivel de esfuerzo xhigh (solo Opus-4.7): Se sitúa entre high y max. Recomendado por defecto para cargas de trabajo de código y agénticas. En subagentes de larga duración, xhigh supera significativamente a high con un costo de tokens sub-proporcional. max sigue siendo la opción correcta para razonamiento difícil de un solo disparo; xhigh es mejor para tareas sostenidas.
• Techo de presupuesto de tokens: Configurable por ejecución de agente mediante output_config.task_budget (header beta task-budgets-2026-03-13). El modelo ve una cuenta regresiva activa y delimita el alcance del trabajo al presupuesto con elegancia, en lugar de quedarse sin tokens de forma inesperada. Úsalo para bucles agénticos donde quieras un gasto predecible de tokens sin sacrificar calidad en prompts cortos.
• Conciencia de necesidades implícitas: Primer modelo de Claude que pasa las pruebas de “necesidad implícita” — reconociendo cuándo la solicitud literal del usuario subespecifica lo que realmente necesita. Esto hace que la sección de “reglas de aclaración” del CLAUDE.md sea menos necesaria. Si tu CLAUDE.md tiene 200 líneas de barreras del tipo “considera también X cuando el usuario pida Y”, recorta las que ahora están cubiertas de forma nativa.

Base del Worktree, Rutas del Sandbox y Configuraciones de Admin (7 de mayo de 2026)

Claude Code v2.1.133 añade cuatro configuraciones de nivel admin que vale la pena conocer para harnesses de producción:³⁹

La reversión de worktree.baseRef es la que hay que señalar a los usuarios: los agentes que dependían del comportamiento de v2.1.128-v2.1.132 (worktrees derivándose del HEAD local) pierden acceso al trabajo no enviado en worktrees nuevos a menos que opten por reactivarlo.

El Quality Loop

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

1. Implementar - Escribir el código
2. Revisar - Releer cada línea. Detectar erratas, errores de lógica, secciones poco claras
3. Evaluar - Ejecutar el evidence gate. Verificar patrones, casos límite, cobertura de pruebas
4. Refinar - Corregir cada problema. Nunca dejar para “después”
5. Hacer Zoom Out - Verificar puntos de integración, imports, código adyacente en busca de regresiones
6. Repetir - Si algún criterio del evidence gate falla, volver al paso 4
7. Reportar - Listar lo que cambió, cómo se verificó, citar evidencia específica

El Evidence Gate

“Creo que” y “debería” 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 al mismo archivo de estado simultáneamente corrompen JSON. Escribe a archivos .tmp, luego haz mv atómicamente. El SO 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 ante corrupción de estado. Si el estado se corrompe, el patrón de recuperación recrea desde valores predeterminados seguros en lugar de fallar:¹⁶

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++)) retorna código de salida 1 cuando VAR es 0 porque 0++ evalúa a 0, lo cual bash trata como falso. Con set -e activado, esto mata el script. Usa VAR=$((VAR + 1)) en su lugar.¹⁶

Clasificación por Radio de Impacto

Clasifica cada acción del agente por radio de impacto y aplica gates en consecuencia:²

Remote Control (conectarse a Claude Code local desde cualquier navegador o app móvil) convierte el gate “Externo” de una espera bloqueante a una notificación asíncrona. El agente sigue trabajando en la siguiente tarea mientras tú 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 finalizació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: pase/fallo de pruebas, salida del linter, códigos de estado HTTP, verificaciones de existencia de archivos. Una tarea inicial que pidió 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

Una Traza Concreta de Sesión

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

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

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

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

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

5. El agente termina la historia. Se dispara Stop. El quality gate verifica: ¿el agente citó evidencia? ¿Lenguaje evasivo? ¿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 de forma independiente. Si algún revisor marca CRITICAL, la historia regresa a la cola.

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

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

Caso de Estudio: Procesamiento Nocturno de PRD

Un harness de producción procesó 12 PRDs (47 historias) a lo largo de 8 sesiones nocturnas. Las métricas comparan los primeros 4 PRDs (harness mínimo: solo CLAUDE.md) contra los últimos 8 (harness completo: hooks, skills, quality gates, revisión multi-agente).

Las dos fugas de credenciales requirieron rotar claves de API y auditar servicios downstream: aproximadamente 4 horas de respuesta a incidentes. La sobrecarga del harness que previno el equivalente fue de 2,4 segundos de bash por historia. La tasa de finalización falsa cayó del 35% al 4% porque el Stop hook ejecutó las pruebas de forma independiente antes de permitir que el agente reportara como hecho.

Consideraciones de seguridad

Los cinco principios de los agentes confiables (Anthropic, abril de 2026)

Anthropic publicó un marco formal sobre la confiabilidad de los agentes el 9 de abril de 2026.²⁷ Los cinco principios son paralelos —y extienden— el pensamiento del Evidence Gate de esta guía:

Anthropic también donó MCP a la Agentic AI Foundation de la Linux Foundation, sumándose a AGENTS.md (ahora administrado conjuntamente con OpenAI, Google, Cursor, Factory, Sourcegraph). Los estándares de interoperabilidad de agentes ahora son neutrales respecto al proveedor.²⁷

Herramientas de sandbox para skills: Para los equipos que tratan los skills como una superficie de ataque, SandyClaw de Permiso (lanzado el 2 de abril de 2026) ejecuta los skills en un sandbox dedicado y entrega veredictos respaldados por evidencia provenientes de detecciones Sigma/YARA/Nova/Snort. Es el primer producto en la categoría de sandbox para skills.²⁸

El sandbox

Claude Code admite un modo sandbox opcional (habilitado mediante settings.json o el comando /sandbox) que restringe el acceso a la red y las operaciones del sistema de archivos usando aislamiento a nivel del SO (seatbelt en macOS, bubblewrap en Linux). Cuando está habilitado, el sandbox impide que el modelo realice solicitudes arbitrarias a la red o acceda a archivos fuera del directorio del proyecto. Sin sandbox, Claude Code usa un modelo basado en permisos donde tú apruebas o deniegas llamadas individuales a herramientas.¹³

Límites de permisos

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

Defensa contra inyección de prompts

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

Los skills con restricciones de herramientas evitan que un prompt comprometido obtenga acceso de escritura:

allowed-tools: Read, Grep, Glob

Los hooks PreToolUse validan cada llamada a herramienta sin importar cómo se le indicó 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 subagentes limita el radio de impacto. Un subagente con permissionMode: plan no puede realizar cambios incluso si su prompt está comprometido.

Seguridad de los hooks

Los hooks HTTP que interpolan variables de entorno en las cabeceras requieren una lista explícita allowedEnvVars para evitar 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 entre humano y agente

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

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

Aplicación recursiva de hooks

Los hooks también se activan para las acciones de los subagentes.¹³ Si Claude genera un subagente mediante la herramienta Agent, tus hooks PreToolUse y PostToolUse se ejecutan para cada herramienta que use el subagente. Sin la aplicación recursiva de hooks, un subagente podría sortear tus controles de seguridad. El evento SubagentStop te permite ejecutar limpieza o validación cuando un subagente termina.

Esto no es opcional. Un agente que genera un subagente 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 cómo la conversación principal no hace nada.

El costo como arquitectura

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

Nivel de tokens. Compresión del system prompt. Elimina ejemplos de código tutoriales (el modelo conoce los APIs), colapsa reglas duplicadas entre archivos y reemplaza explicaciones por restricciones. “Rechaza 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. Spawns nuevos en lugar de conversaciones largas. Cada historia en una ejecución autónoma recibe un nuevo agente con un contexto limpio. El contexto nunca se infla porque cada agente parte de cero. Briefing en lugar de memoria: los modelos ejecutan mejor un briefing claro que navegar por 30 pasos de contexto acumulado.

Nivel de arquitectura. CLI-first sobre MCP cuando la operación es sin estado. Una llamada claude --print para una evaluación de un solo disparo 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 subagentes

Preguntas frecuentes

¿Cuántos hooks son demasiados?

La restricción es el rendimiento, no la cantidad. Cada hook se ejecuta de forma sincrónica, por lo que el tiempo total de ejecución de los hooks se suma a cada llamada de herramienta que coincida. 95 hooks distribuidos entre la configuración a nivel de usuario y de proyecto se ejecutan sin latencia perceptible cuando cada uno se completa 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. Perfila 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 el código 2. Claude Code cancela la acción pendiente y muestra al modelo la salida de stderr del hook. 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 procede de todos modos.³

¿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 (incluidos 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 ambos existen. Usa rutas absolutas para los archivos de script y evitar problemas con el directorio de trabajo.¹⁴

¿Toda decisión necesita deliberación?

No. El módulo de confianza puntúa las decisiones en cuatro dimensiones (ambigüedad, complejidad, riesgo, dependencia del contexto). Solo las decisiones que puntúan por debajo de 0,70 en confianza general activan la deliberación, aproximadamente el 10 % del total. Las correcciones de documentación, los cambios de nombre de variables y las ediciones rutinarias se saltan la deliberación por completo. La arquitectura de seguridad, los cambios de esquema de base de datos y los despliegues irreversibles la activan de manera consistente.⁷

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

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

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

Una deliberación de 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 de 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 quedan truncados por las ventanas de contexto, así que coloca al principio las instrucciones más críticas: comandos y definiciones de cierre antes que las preferencias de estilo.²¹

¿Puede esto funcionar con herramientas distintas a Claude Code?

Los principios arquitectónicos (hooks como puertas deterministas, skills como experticia de dominio, subagents como contextos aislados, sistema de archivos como memoria) se aplican conceptualmente a cualquier sistema agéntico. La implementación específica usa los eventos del ciclo de vida, los patrones de matcher y el Agent tool de Claude Code. AGENTS.md lleva los mismos patrones a Codex, Cursor, Copilot, Amp y Windsurf.²¹ El patrón de harness es agnóstico de la 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 skill

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

Definición de subagent

---
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

Ubicaciones de archivos

Changelog

Referencias