Arquitectura de agentes: cómo crear arneses 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 conectable mediante hooks con scripts de shell 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 hace cumplir restricciones, delega trabajo, conserva memoria entre sesiones y orquesta deliberación multi-agent. Claude Code v2.1.147 agregó la herramienta Workflow, desactivada por defecto (CLAUDE_CODE_WORKFLOWS=1), lo que mueve la orquestación multi-agent determinista desde scripts puramente de userland hacia una primitiva de runtime de primera parte; v2.1.149 refuerza la misma lección desde el lado de la seguridad con correcciones de omisión de permisos en PowerShell y una corrección de allowlist para el sandbox de git-worktree. Hooks y evidence gates siguen siendo responsables de la corrección.⁵²⁵³ Esta guía cubre cada capa de esa pila: desde un solo hook hasta un sistema de consenso de 10 agentes. No se requieren frameworks. Todo bash y JSON.

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

El modelo mental de infraestructura es distinto: un agente de programación con AI es un runtime programable con un kernel LLM. Cada acción que realiza el modelo pasa por hooks que tú controlas. Defines políticas, no prompts. El modelo opera dentro de tu infraestructura del mismo modo 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. Una skill que codifica tu rúbrica de evaluación se aplica de forma consistente tanto si la invocas tú como si lo hace un agente. Un agente que revisa código por seguridad ejecuta las mismas comprobaciones estés mirando o no.²

Puntos clave

• Los hooks garantizan la ejecución; los prompts no. Usa hooks para linting, formateo, comprobaciones de seguridad y cualquier cosa que deba ejecutarse siempre, sin depender del comportamiento del modelo. El código de salida 2 bloquea acciones. El código de salida 1 solo advierte.³
• Las 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 una skill.⁴
• Los subagents evitan que el contexto se infle. Las ventanas de contexto aisladas para exploración y análisis mantienen ligera la sesión principal. Ejecuta subagents 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 entre ventanas de contexto. CLAUDE.md, MEMORY.md, directorios de reglas y documentos de traspaso forman un sistema estructurado de memoria externa.⁶
• La deliberación multi-agent detecta puntos ciegos. Los agentes individuales no pueden cuestionar sus propias suposiciones. Dos agentes independientes con distintas prioridades de evaluación detectan fallas estructurales que los quality gates no pueden abordar.⁷
• El harness pattern es el sistema. CLAUDE.md, hooks, skills, agents 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 Marco de Decisión al final ofrece una tabla de consulta para elegir el mecanismo adecuado 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 de 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 de 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: las skills aportan experiencia de dominio que se activa automáticamente según el contexto. Los hooks aportan compuertas deterministas que se disparan en cada llamada de herramienta coincidente. Los archivos de memoria persisten el estado entre sesiones. Los agents 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 garantiza la calidad.

La idea clave: la mayoría de los usuarios trabaja por completo en la capa central, viendo cómo el contexto se infla y los costos suben. Los usuarios avanzados configuran las capas de instrucción y extensión, y luego usan la capa central solo para la orquestación y las decisiones finales.²

Harnesses gestionados vs. autohospedados (abril de 2026)

Durante principios de 2026, la vía de “construye tu propio harness” era 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 API REST, facturado a tokens estándar más $0,08 por hora-sesión. La actualización de 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/rehidratación para sobrevivir a la pérdida del contenedor.²³²⁴

La superficie más profunda de SDK del lado de OpenAI llegó en openai-agents Python v0.14.0 (lanzada el 15 de abril de 2026; anunciada el 16 de abril): una subclase SandboxAgent de Agent con default_manifest, instrucciones del sandbox y capacidades; un Manifest que describe el contrato del workspace nuevo (archivos, directorios, archivos locales, repos de Git, env, usuarios, mounts); un SandboxRunConfig para el cableado por ejecución del cliente del sandbox, inyección de sesión en vivo, anulaciones de manifest, snapshots y límites de concurrencia de materialización. Las capacidades integradas cubren acceso al shell, edición del sistema de archivos, inspección de imágenes, skills, memoria del 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 repos de Git y mounts remotos (S3, R2, GCS, Azure Blob, S3 Files); los snapshots son portables entre proveedores. Backends: UnixLocalSandboxClient, DockerSandboxClient y clientes hospedados para Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel mediante extras opcionales.²⁴

Para proyectos de Python que quieran integrar el runtime de Claude Code como librería — entre “ejecutar claude por shell” y “API REST a Managed Agents” — claude-agent-sdk-python es la tercera opción. La serie del 28-29 de abril (v0.1.69 → v0.1.71) elevó el CLI incluido a v2.1.123, subió 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 la paridad de esquema con el SDK de TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

Si tu harness incluye una capa de voz o tiempo real, openai-agents-python v0.17.0 (8 de mayo de 2026) actualizó RealtimeAgent para que use gpt-realtime-2 por defecto.⁴¹ Las sesiones de tiempo real existentes adoptan el nuevo predeterminado automáticamente; fija el modelo anterior explícitamente si necesitas mantener el comportamiento previo para evaluación.

La bifurcación arquitectónica ya es real:

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

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 de 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 por git. Juntos, conforman 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.⁴ En el momento en que notes que estás volviendo a explicar el mismo contexto entre sesiones, deberías crear un skill.

Cuándo crear un Skill

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

Crear un Skill

Los skills viven en cuatro ubicaciones posibles, del alcance más amplio al más estrecho:⁴

Cada skill requiere un archivo SKILL.md con frontmatter de 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 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 system prompt, y el modelo usa comprensión lingüística estándar para seleccionar 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 usarlo (al 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 una alternativa de 8.000 caracteres.⁴ Si tienes muchos skills, mantén cada descripción concisa y pon primero el caso de uso clave. Puedes sobrescribir el presupuesto mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ pero la mejor solución es usar descripciones más cortas y precisas. Ejecuta /context durante una sesión para revisar si se está excluyendo algún skill.

Archivos de Apoyo 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

Referencia esos archivos 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 apoyo.¹²

Compartir Skills mediante Git

Los 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 hacen pull, obtienen el skill automáticamente. Sin instalación, sin configuración. Esta es la forma más efectiva de estandarizar experiencia dentro de un equipo.

Skills como Biblioteca de Prompts

Más allá de los 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 distinta de tu experiencia. En conjunto, forman una base de conocimiento de la que Claude toma información automáticamente según el contexto. Un desarrollador junior recibe orientación de nivel senior sin tener que pedirla.

Los Skills se Componen con Hooks

Los skills pueden definir sus propios hooks en frontmatter, que se activan solo mientras el skill se ejecuta. Esto crea comportamiento específico del dominio sin contaminar 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 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 con 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 exigir invocación explícita con /skill-name.⁴

Demasiados skills compitiendo por presupuesto. Más skills significa más descripciones compitiendo por el presupuesto de contexto del 1%. Si notas que algunos skills no se activan, revisa /context para ver cuáles quedaron excluidos. Prioriza menos skills bien descritos en lugar de muchos skills vagos.

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

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

Los harnesses autoalojados en claude-agent-sdk-python v0.1.77+ deberían usar la opción skills en ClaudeAgentOptions para declarar los skills disponibles, no el valor heredado "Skill" en allowed_tools.³⁷ La abreviatura "Skill" está obsoleta, 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.

Convergencia de Plugins y Skills en .claude/skills/ (29 de mayo de 2026)

Los skills siempre se han cargado desde el directorio .claude/skills/ de un proyecto. Claude Code v2.1.157 extiende ese directorio a plugins: un plugin colocado en .claude/skills/ ahora se carga automáticamente sin registrarlo en un marketplace, y claude plugin init <name> crea allí uno nuevo con el manifest y SKILL.md ya conectados.⁵⁸ Eso cierra la brecha entre las dos formas de tooling de proyecto que antes vivían en lugares distintos: un skill básico confirmado directamente en el repo, frente a un plugin que empaqueta un skill más hooks y un servidor MCP, pero que antes necesitaba un marketplace para instalarse. El efecto práctico para el diseño de harnesses: el tooling con alcance de proyecto ya no necesita pasar por un registro para entregarse; escríbelo, haz commit y tus compañeros obtienen la misma superficie con git pull. Los plugins siguen cubriendo el caso de uso instalable en paquete (hooks + skills + servidores MCP + agents en un ZIP); el cambio es que un proyecto ya no tiene que levantar un marketplace solo para cargar uno desde su propio árbol.

Ocultar la Superficie Incluida como Gobernanza (8 de junio de 2026)

Los skills son capacidad, y la capacidad es superficie de ataque. Claude Code v2.1.169 agrega una configuración disableBundledSkills (y la variable de entorno correspondiente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) que oculta por completo al modelo los skills incluidos, workflows y slash commands integrados.⁶⁰ Para un harness endurecido o regulado, esto es una reducción deliberada de superficie de ataque: un operador que ha auditado y aprobado un conjunto específico de skills de proyecto y personales puede suprimir todo lo que Anthropic trae de fábrica, de modo que el modelo solo razone sobre la superficie que el operador validó. Trátalo igual que una allowlist de tools: el valor predeterminado es capacidad amplia, y desactivar ese valor predeterminado es una decisión de gobernanza, no un interruptor de conveniencia.

.claude/skills Anidados y Resolución por Cercanía (16 de junio de 2026)

Claude Code v2.1.178 hizo que el tooling de proyecto fuera consciente de la ubicación. Los skills en directorios .claude/skills anidados ahora se cargan cuando trabajas en archivos bajo ese directorio, no solo desde la raíz del repo; si hay un conflicto de nombres, el skill anidado aparece como <dir>:<name> para que ambos sigan siendo accesibles.⁶³ La misma versión hizo que el resto de la superficie del proyecto se resuelva según lo más cercano al directorio de trabajo: cuando el nombre de un agent, workflow u output-style colisiona entre directorios .claude/ anidados, gana el que está más cerca del directorio de trabajo, y guardar un workflow con alcance de proyecto apunta al .claude/workflows/ existente más cercano en lugar de ir siempre a la raíz.⁶³ Para un monorepo o un repo de repos, esta es la diferencia entre una superficie global plana y tooling por paquete que se activa en contexto: services/api/.claude/skills/ puede llevar skills específicos de API que aparecen solo mientras trabajas en ese árbol, sin colisionar con un skill de services/web/ que tenga el mismo nombre.

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 revisa el comando contra una lista de bloqueo y lo rechaza antes de que el shell llegue a verlo. El hook se dispara quiera o no el modelo.

Eventos disponibles

Claude Code expone 29 eventos documentados del ciclo de vida en ocho categorías al momento de actualizar esta guía. La lista de eventos crece con cada versión, así que trata la documentación de referencia como la fuente de verdad y revisa la hoja de referencia para ver la tabla completa actual antes de conectar hooks de producción:¹³

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 igual se ejecuta. Este es el error de hooks más común entre 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 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 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 control avanzado, los hooks PreToolUse pueden devolver JSON para modificar la entrada de la herramienta, inyectar contexto o tomar decisiones de permiso. Usa el wrapper hookSpecificOutput; el formato antiguo de nivel superior decision/reason 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, pregunta: ¿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 evitan 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

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 fallan las revisiones de calidad:

#!/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 admite cinco tipos de hooks:¹³

Command hooks (type: "command") ejecutan scripts de shell. Rápidos, deterministas y sin costo de tokens.

MCP tool hooks (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.

Prompt hooks (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 una regex no puede expresar.

Agent hooks (type: "agent") generan un subagent con acceso a herramientas (Read, Grep, Glob) para verificación de varios turnos. Son experimentales; prefiere command hooks para gates de producción y reserva agent hooks para revisiones que realmente requieren inspeccionar archivos reales o salida de pruebas:

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

A partir de Claude Code v2.1.140, la entrada de agent hook incluye subagent_type, lo que permite que un hook compartido distinga una ejecución de security-reviewer de un explorer o un worker genérico sin adivinar a partir del texto del prompt.⁴⁹

HTTP hooks (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 externos de notificación o validación basada en API (v2.1.63+). No son compatibles 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 formato, validación ni nada que deba completarse antes de la siguiente acción.

Dispatchers en lugar de hooks independientes

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

La solución: un dispatcher por evento que ejecuta hooks de forma secuencial 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 en silencio:¹⁴

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 salida de depuración. Stderr con código de salida 2 se devuelve a Claude como mensaje de error. El stderr no bloqueante (exit 1, 3, etc.) aparece solo en modo verbose (Ctrl+O).
3. Vigila las fallas de jq. Las rutas JSON incorrectas devuelven null en silencio. Prueba las expresiones jq contra entradas reales de herramientas.
4. Verifica los códigos de salida. Un hook PreToolUse que usa exit 1 no aplica ninguna restricción aunque parezca 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 500ms.

Streaming de eventos de hooks del lado de SDK

Los harnesses self-hosted creados sobre claude-agent-sdk-python (v0.1.74+, 6 de mayo de 2026) pueden suscribirse a eventos de hooks directamente desde el stream 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) salen del mismo iterador que los mensajes del assistant y los resultados de herramientas. Esto refleja la opción includeHookEvents del SDK TypeScript; el CLI incluido se actualizó a v2.1.129 en la misma versión.

El patrón de event-stream es la opción correcta cuando tu harness ya vive en Python y quieres señales de hooks en el mismo flujo de control que la salida del modelo. El contrato de hooks con scripts de shell (códigos de salida, stdin JSON, dispatchers) sigue siendo la respuesta adecuada para harnesses que componen varias herramientas, comparten hooks entre Claude Code y Codex, o necesitan semántica de códigos de salida para bloquear.

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

Dos adiciones en Claude Code v2.1.132 y v2.1.133 dan a 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, así que los comandos Bash pueden leerlo sin parsear JSON. Usa esto para escalar el costo del hook según el nivel de esfuerzo: omite validación costosa en low, ejecuta el gate de seguridad completo 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 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 subprocesos con eventos de hooks.

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

autoMode.hard_deny y correcciones de hooks/plugins en v2.1.136 (8 de mayo de 2026)

Claude Code v2.1.136 agregó un nuevo nivel hard-deny al modo auto y corrigió un conjunto de problemas de plugins y MCP que afectaban harnesses de larga ejecución:⁴⁰

• settings.autoMode.hard_deny. Reglas del clasificador de modo auto que bloquean incondicionalmente, sin importar la intención del usuario ni excepciones allow. Esto se ubica por encima de los matchers allow/deny existentes como una palanca de gobernanza no negociable. Úsalo para reglas que nunca deben poder anularse (force-push a main, archivos con secretos, acceso a bases de datos de producción), incluso cuando un operador haya aprobado la categoría más amplia en su configuración personal.
• Los servidores MCP ya no desaparecen después de /clear. Los servidores configurados en .mcp.json, plugins y conectores de claude.ai salían silenciosamente del conjunto activo después de un /clear en la extensión de VS Code, el plugin de JetBrains y el SDK Agent. La corrección llega en v2.1.136. Si viste “MCP server X went missing mid-session”, esta era la causa.
• Pérdida de refresh-token de OAuth MCP durante refresh concurrente. Los usuarios con varios servidores MCP remotos ya no deberían necesitar reautenticarse a diario. Las escrituras concurrentes de refresh se sobrescribían entre sí.
• Plan mode ahora bloquea correctamente las escrituras de archivos. Una regla allow Edit(...) coincidente estaba eludiendo la protección contra escritura de plan-mode. Plan mode ahora se aplica sin importar las reglas allow.
• Los hooks Stop y UserPromptSubmit de plugins ya no fallan a mitad de sesión. La limpieza de caché estaba eliminando archivos de versión de plugin todavía usados por la sesión en ejecución, rompiendo específicamente estos dos eventos de hook. La corrección mantiene fijadas las versiones en uso.
• Entrada skills en plugin.json. Configurar skills ocultaba la carpeta predeterminada skills/ del plugin. Ahora la entrada se compone correctamente, y apuntarla a una ruta de archivo genera un error explícito en lugar de fallar en silencio.
• Variables de entorno de hook SessionStart con CLAUDE_ENV_FILE que quedaban obsoletas. Las variables exportadas por hooks SessionStart mediante CLAUDE_ENV_FILE quedaban obsoletas después de /resume o /clear. Corregido en v2.1.136. Las sesiones ahora vuelven a cargar el archivo de entorno en estos eventos.

Para harnesses de gobernanza, los puntos operativamente interesantes son autoMode.hard_deny (nueva palanca) y la corrección de desaparición de MCP (falla silenciosa que rompía sesiones largas). Todo lo demás es una mejora de calidad de vida.

Argumentos estructurados de hooks y continuación al bloquear (11 de mayo de 2026)

Claude Code v2.1.139 agregó dos detalles de hooks que importan para harnesses de producción: una forma exec args: string[] para command hooks, y continueOnBlock para hooks PostToolUse.⁴²⁴⁴ Prefiere args cuando un hook necesita valores dinámicos o placeholders de rutas. Genera el comando directamente sin shell, lo que elimina toda una clase de errores de comillas e inyección.

Usa continueOnBlock cuando un hook PostToolUse deba devolver su razón de rechazo a Claude y continuar el turno en lugar de terminar el flujo. Trátalo como una función de experiencia del operador, no como un bypass de seguridad. Un gate bloqueante todavía debe bloquear el resultado inseguro.

La misma versión pasa CLAUDE_PROJECT_DIR a servidores stdio MCP y permite que las configuraciones de plugins referencien ${CLAUDE_PROJECT_DIR} en comandos.⁴² Las herramientas MCP deberían resolver rutas relativas al proyecto desde ese valor, no desde el directorio de trabajo del proceso que haya lanzado el servidor.

Claude Code v2.1.140 es principalmente una versión de confiabilidad para operadores de harnesses: corrige hooks ConfigChange que no se disparaban con cambios de configuración, cierra casos límite donde disableAllHooks y allowManagedHooksOnly no se componían correctamente entre niveles de configuración, y evita que los diálogos de permisos expongan variables de entorno no deseadas devueltas por resultados de hooks.⁴⁹ Eso hace que los patrones de gobernanza existentes en esta sección sean más confiables; no exige una nueva arquitectura de hooks.

Claude Code v2.1.141 agrega un campo terminalSequence en la salida de hooks para notificaciones de escritorio, títulos de ventana y campanas sin una terminal de control.⁵⁰ Trátalo como señalización para operadores, no como aplicación de reglas. Los gates de seguridad y calidad deberían seguir comunicando fallas mediante el contrato normal de bloqueo: salida estructurada de hook más el comportamiento de salida que evita la acción insegura. La misma versión agrega claude agents --cwd <path> para acotar Agent View a un directorio, CLAUDE_CODE_PLUGIN_PREFER_HTTPS para instalaciones de plugins en entornos sin claves SSH GitHub, y ANTHROPIC_WORKSPACE_ID para reglas de federación de identidad de workload que cubren más de un workspace.⁵⁰ Esos son detalles de arquitectura para harnesses de equipo: vistas operativas más estrechas, menos supuestos de instalación de plugins y scoping explícito de tokens empresariales.

Claude Code v2.1.142 es más importante para la orquestación de sesiones en segundo plano que para la semántica de hooks.⁵¹ claude agents ahora puede despachar sesiones en segundo plano con flags explícitos de directorio, configuración, MCP, plugin, permisos, modelo y esfuerzo, en lugar de depender del estado del wrapper. Fast mode ahora usa Opus 4.7 de forma predeterminada; fija CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 solo si un harness ha medido dependencia del comportamiento de Opus 4.6. El descubrimiento de SKILL.md en la raíz de plugins y la visibilidad LSP provista por plugins reducen la ambigüedad de empaquetado. Las correcciones a MCP_TOOL_TIMEOUT, worktrees preexistentes de sesiones en segundo plano, sleep/wake del daemon y limpieza posterior a actualizaciones, además de la limpieza de caché de plugins, cierran brechas de confiabilidad que de otro modo parecen errores de orquestación.

Dirección con stop-hook, autoridad entre sesiones y multi-agent v2 (junio de 2026)

Cuatro cambios de principios de junio importan para el diseño de harnesses y multi-agent.⁵⁹

Los hooks Stop/SubagentStop ganaron un canal de dirección. A partir de Claude Code v2.1.163, un hook Stop o SubagentStop puede devolver hookSpecificOutput.additionalContext para entregar feedback a Claude y mantener el turno en marcha, sin que la respuesta se etiquete como error de hook. Antes de esto, la única palanca real de un Stop hook era el bloqueo exit-2, que se lee como error y cuenta para el límite de bloqueos consecutivos. Para un harness con quality gate, este es un primitivo más limpio: un Stop hook que detecta “dijiste terminado pero las pruebas están en rojo” ahora puede inyectar “esto es lo que todavía falla, continúa” en lugar de bloquear duro. Usa el bloqueo para condiciones genuinas de detención y additionalContext para “todavía no está listo, esta es la razón”.

La mensajería entre sesiones ya no transporta autoridad prestada. v2.1.166 reforzó el caso multi-sesión: los mensajes retransmitidos mediante SendMessage desde otra sesión Claude ya no transportan la autoridad del usuario de origen, así que una sesión receptora rechaza solicitudes de permiso retransmitidas y auto mode las bloquea. Si tu orquestación hace que los agents se envíen mensajes entre sí, trata un mensaje entrante como datos no confiables, no como una instrucción autenticada. Es el mismo principio que la sección de seguridad aplica a la salida de herramientas, extendido a la mensajería entre agents.

La resiliencia de modelos se volvió una configuración de primera clase. La configuración fallbackModel ahora encadena hasta tres modelos de respaldo, probados en orden cuando el principal está sobrecargado o no está disponible, y un turno reintenta automáticamente una vez en el fallback ante errores API inesperados no reintentables. Para un harness autónomo de larga ejecución, esto convierte una caída transitoria del modelo principal en una degradación elegante en lugar de una ejecución perdida. claude agents --json también agregó un campo waitingFor (v2.1.162) que muestra qué espera una sesión en segundo plano bloqueada, como un prompt de permiso: una mejora de observabilidad para cualquier coordinador que sondee una flota de agents.

Safe mode para gobernanza clean-room y troubleshooting. Claude Code v2.1.169 agrega un flag --safe-mode (y la variable de entorno correspondiente CLAUDE_CODE_SAFE_MODE) que inicia una sesión con todas las personalizaciones desactivadas a la vez: CLAUDE.md, plugins, skills, hooks y servidores MCP.⁶⁰ Es el inverso del harness: un clean-room deliberado. Úsalo para responder la pregunta que todo operador termina haciendo: “¿este comportamiento viene del modelo o de algo que configuré?” Cuando un hook se dispara mal, una skill se activa cuando no debería, o un servidor MCP contamina el contexto, --safe-mode te da una línea base conocida y vacía contra la cual comparar. También es un primitivo de gobernanza: una forma de ejecutar el modelo base sin ninguna de las autoridades persistentes que tu harness normalmente concede, lo cual importa cuando necesitas reproducir un resultado sin que ningún andamiaje definido por el operador influya en él.

Una nota sobre niveles de modelos. Esta guía trata Opus 4.8 como el valor predeterminado agentic de Claude Code: el modelo que ejecuta harnesses autónomos salvo que selecciones otra cosa. Al 9 de junio de 2026, Anthropic lanzó Claude Fable 5 (claude-fable-5), un nuevo nivel por encima de Opus descrito como su modelo más poderoso: un sistema “Mythos-class” hecho seguro para uso general, seleccionable en Claude Code v2.1.170 mediante /model claude-fable-5.⁶⁰ Opus 4.8 sigue siendo el valor agentic predeterminado; recurre al nivel superior de forma deliberada, en las decisiones donde la profundidad de razonamiento en bruto justifica el costo, no como configuración general para una flota.

Codex lanzó multi-agent v2. Codex CLI v0.137.0 mantiene la elección de runtime en cada thread, expone valores predeterminados más limpios de seguimiento y metadatos para agents generados (hide_spawn_agent_metadata ahora es true por defecto), y propaga eventos raw del parent a listeners child. Su modelo de subagent sigue siendo explícito: tipos de agents integrados default/worker/explorer, agents personalizados definidos en TOML y controles de concurrencia (agents.max_threads predeterminado 6, agents.max_depth predeterminado 1). La misma versión agrega una extensión skills v1 con resolución del catálogo de skills por turno y nuevos eventos de lifecycle contributor thread-start/turn-error, reduciendo la brecha con la superficie de hooks/skills de Claude Code mientras mantiene la postura de kernel-sandbox como límite predeterminado. Luego Codex v0.138.0-v0.139.0 reforzó multi-agent v2 para producción: los payloads de mensajes entre agents ahora están cifrados, un catálogo de configuración de agents v2 más un LRU de residencia de agents administran qué agents permanecen residentes, y la concurrencia se cuenta por ejecución activa en lugar de por threads generados, así que los agents inactivos ya no consumen un slot.⁶¹ El lifecycle API también maduró: close_agent pasó a llamarse interrupt_agent (v0.139.0) para reflejar que interrumpe un agent en ejecución en lugar de simplemente cerrar un handle, y las advertencias de inicio MCP generadas por un subagent ahora quedan acotadas al thread propietario en lugar de duplicarse hacia arriba en la transcripción del parent.⁶¹ Para cualquiera que construya orquestación del lado de Codex, estos son la diferencia entre una demo y una flota: transporte de mensajes cifrado, residencia acotada, concurrencia contabilizada por ejecución y advertencias que no se filtran a través del límite de thread. Codex v0.140.0 abrió después una conexión entre herramientas: /import trae selectivamente setup, configuración de proyecto y chats recientes desde Claude Code hacia Codex, y las sesiones pasaron a poder eliminarse permanentemente (codex delete / /delete, con salvaguardas de confirmación).⁶⁴ /import es el primer reconocimiento oficial de que los operadores se mueven entre harnesses: la configuración que construyes para uno ya no queda atrapada ahí.

Memoria y contexto

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

Los 3 mecanismos del colapso multi-turno

El estudio de MSR/Salesforce identificó 3 mecanismos independientes, cada uno de los cuales requiere una intervención distinta:⁹

Estrategia 1: El sistema de archivos como memoria

La memoria más confiable a través de 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 compaction.⁶

~/.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, cuando encuentras un caso límite similar con enteros en Python, la entrada de MEMORY.md hace visible 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 archivos temáticos separados para notas detalladas.⁶

Curación de memoria por encima del volumen de memoria (mayo de 2026): Un preprint reciente de arXiv sobre cooperación entre agents de LLM plantea la recuperación ampliada como un posible modo de falla: en los experimentos de los autores, un historial visible más largo degradó la cooperación en 18 de 28 configuraciones de modelo-juego.⁴⁸ Tómalo como una advertencia de diseño, no como una ley definitiva. La regla de producción ya es bastante clara: mantén MEMORY.md corto, enlaza los detalles y coloca resúmenes listos para decisiones en los handoffs. Los volcados crudos de transcripciones, los logs de herramientas y los feeds largos de recuperación pertenecen al almacenamiento con búsqueda, no automáticamente al prompt activo.

Estrategia 2: Compaction proactiva

El comando /compact de Claude Code resume la conversación y libera espacio de contexto mientras preserva decisiones clave, contenidos de archivos y estado de la tarea.¹⁵

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

Instrucciones personalizadas de compaction en CLAUDE.md:

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

Compaction protege la conversación; el comando /cd (Claude Code v2.1.169) protege el prompt cache. Mueve una sesión a un nuevo directorio de trabajo en medio del flujo sin romper la caché acumulada durante el turno.⁶⁰ Antes de esto, cambiar de directorio implicaba una sesión nueva y una caché fría. Para una sesión larga que pivota de un repositorio a otro hermano, algo común en trabajos con monorepos y varios servicios, /cd mantiene intacto el prefijo cacheado costoso mientras redirige el contexto del sistema de archivos.

Estrategia 3: Handoffs de sesión

Para tareas que abarcan varias 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 todo el contexto con un costo mínimo en tokens. Empezar una sesión nueva con claude -c (continue) 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, inicia una instancia fresca de Claude por iteración. El estado persiste a través del sistema de archivos, no mediante memoria conversacional. Cada iteración obtiene todo el presupuesto 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 (leer archivos de estado, revisar el historial de git) a cambio de recursos cognitivos completos en cada 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 los 90 minutos, el contexto fresco produce resultados de mayor calidad a pesar de la sobrecarga.

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

Los Managed Agents de Claude de Anthropic agregaron Dreaming como Research Preview el 6 de mayo de 2026.³⁵ Según Anthropic: “Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

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 de carga principal; Dreaming escribe entradas de memoria curadas en el almacén de memoria de Managed Agents, que el agent lee al inicio de la sesión. Los dos patrones coexisten para harnesses que mezclan estado de sistema de archivos autogestionado con curación del lado gestionado.

Dreaming está en Research Preview, por lo que su comportamiento puede cambiar. Los patrones de session handoffs y CLAUDE.md documentados arriba siguen siendo el mecanismo de memoria autoritativo para harnesses autogestionados.

Los anti-patrones

Leer archivos completos cuando necesitas 10 líneas. Leer un solo archivo de 2.000 líneas consume entre 15.000 y 20.000 tokens. Usa desplazamientos 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 contiene más de 40 stack traces de iteraciones fallidas. Un solo /compact después de corregir el bug libera ese peso muerto.

Empezar cada sesión leyendo todos los archivos. Deja que las herramientas glob y grep de Claude Code encuentren los archivos relevantes bajo demanda, lo que ahorra más de 100.000 tokens de precarga innecesaria.¹⁵

Patrones de subagents

Los subagents son instancias especializadas de Claude que manejan tareas complejas de forma independiente. Empiezan 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 la exploración no inflan tu conversación principal; solo regresan las conclusiones.⁵

Tipos de subagents integrados

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

Aislamiento con worktree

Los subagents pueden operar en git worktrees temporales, lo que proporciona una copia completa y aislada 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 el codebase.

Subagents en paralelo

Usa subagents 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 agent 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 agents delegan en agents que delegan en otros agents, y cada uno pierde contexto y consume tokens. El patrón 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 (bloqueadas en profundidad 3), pero no capturan la amplitud: 23 agents en profundidad 1 siguen siendo “profundidad 1”. Un presupuesto de generación rastrea el total de hijos activos por padre, con un tope máximo configurable. El modelo de presupuesto se ajusta al modo de falla real (demasiados agents en total), no a una métrica indirecta (demasiados niveles de anidación).⁷

La delegación recursiva ahora es una profundidad de primera clase. A partir de Claude Code v2.1.172 (10 de junio de 2026), los sub-agents pueden generar sus propios sub-agents, con anidación de hasta 5 niveles de profundidad; antes, la delegación era efectivamente de un solo nivel.⁶² Esto vuelve más importante el recursion guard anterior, no menos: la plataforma ahora permite exactamente las cadenas de agents-que-delegan-en-agents que consumen contexto y tokens, así que el presupuesto de generación y el tope de profundidad son lo que evita que un árbol de 5 niveles se abra en cientos de agents activos. Trata los 5 niveles como un techo que la plataforma permite, no como un valor predeterminado al que debas aspirar.

El modo auto ahora evalúa las generaciones antes de lanzarlas. Claude Code v2.1.178 cerró la brecha de gobernanza de emparejamiento: en modo auto, las generaciones de subagents son evaluadas por el clasificador de permisos antes de que el subagent se lance, no solo una vez que empieza a realizar acciones.⁶³ Antes, un subagent podía generarse para solicitar una acción que la sesión principal habría tenido bloqueada; la generación en sí era el bypass. Evaluar en el momento de la generación significa que el recursion guard y el modelo de permisos por fin se encuentran: un hijo no puede usarse como paso de lavado para una acción que la política prohíbe.

Agent Teams (Research Preview)

Agent Teams coordina varias instancias de Claude Code que trabajan de forma independiente, se comunican mediante un buzón y una lista de tareas compartidos, y pueden cuestionar los hallazgos de los demás:⁵

Habilítalo con: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Cuándo usar agent teams frente a subagents:

Agent View y bucles de objetivo (mayo de 2026)

Claude Code v2.1.139 agregó Agent View, una interfaz en research-preview que se inicia con claude agents y muestra, desde una sola pantalla, sesiones de Claude Code en ejecución, bloqueadas y completadas.⁴²⁴³ La documentación oficial la presenta como una forma de despachar y gestionar muchas sesiones, ver qué está haciendo cada una e identificar cuáles necesitan intervención del operador.⁴³ Esto da al trabajo multi-agent una vista operativa que los resúmenes finales no pueden ofrecer.

Usa Agent View cuando promuevas un patrón de subagent o de equipo: inspecciona qué sesiones están bloqueadas, cuáles siguen ejecutándose y si la distribución del trabajo coincide con la arquitectura prevista. No lo trates como prueba de calidad. Es observabilidad; las pruebas, los review gates y los informes de evidencia siguen decidiendo si el trabajo es sólido.

La misma versión agregó /goal, que establece una condición de finalización y permite que Claude continúe entre turnos hasta cumplirla, incluso en usos interactivos, con -p y con Remote Control.⁴² Trata /goal como un bucle de finalización con alcance de sesión, no como sustituto de gates deterministas. Es útil para mantener a un agent enfocado en un objetivo, pero las pruebas, las comprobaciones de citas, las verificaciones de deploy y los hooks de seguridad deben seguir respaldados por comandos o scripts cuando una falla debe bloquear el avance.

Herramienta Workflow (v2.1.147+)

Claude Code v2.1.147 agrega una herramienta Workflow, desactivada de forma predeterminada, para orquestación multi-agent determinista. Habilítala con CLAUDE_CODE_WORKFLOWS=1.⁵² Arquitectónicamente, esto es importante porque le da a Claude Code una primitiva de orquestación de primera clase para flujos que antes requerían scripts de dispatch personalizados, estado de mailbox y convenciones de coordinación entre subagents.

No elimines el harness que la rodea. Un Workflow puede estructurar la ejecución, pero no reemplaza tu modelo de seguridad. Mantén los hooks PreToolUse y PostToolUse como capa de bloqueo, conserva presupuestos de generación o presupuestos de pasos de workflow para evitar amplitud descontrolada, mantén el estado del sistema de archivos auditable y deja los informes finales de evidencia fuera de la autoevaluación del modelo. En la práctica: usa Workflow para la forma de la orquestación; usa hooks, pruebas y review gates para la verdad.

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 AI, no un README para humanos.²¹ El agente no necesita entender por qué usas commits convencionales. 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.⁶

Qué se ignora

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

Párrafos en prosa sin comandos. “Valoramos el 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. “Avanza rápido y publica pronto” más “Asegura una cobertura de pruebas completa” más “Mantén el tiempo de ejecución por debajo de 5 minutos” más “Ejecuta todas las pruebas de integración antes de cada commit.” El agente no puede satisfacer las cuatro al mismo tiempo y, por defecto, omite la verificación.²¹

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

Qué funciona

Instrucciones centradas en 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 escalamiento:

## 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 empiezas desde cero, agrega secciones en este orden de prioridad:²¹

1. Comandos de compilación y prueba (el agente los necesita antes de poder hacer algo útil)
2. Definición de terminado (evita falsas finalizaciones)
3. Reglas de escalamiento (evita soluciones destructivas)
4. Secciones organizadas por tarea (reduce el procesamiento de instrucciones irrelevantes)
5. Alcance por directorio (monorepos: mantiene aisladas las instrucciones de cada servicio)

Omite las preferencias de estilo hasta que las primeras cuatro funcionen.

Importaciones 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 reconocido por todas las principales herramientas de codificación con AI.²¹ Si tu equipo usa varias herramientas, escribe AGENTS.md como fuente canónica y replica las secciones relevantes en archivos específicos de cada herramienta:

Los patrones de AGENTS.md (centrados en comandos, definidos por cierre y organizados por tarea) funcionan en cualquier archivo de instrucciones, sin importar la herramienta. No mantengas conjuntos paralelos de instrucciones que se desvíen con el tiempo. Escribe una fuente autoritativa y replícala.

Notas de paridad de Codex

Codex ahora tiene equivalentes de primera clase para las principales capas de harness, pero la migración es una traducción de patrones, no una copia de archivos. Codex lee AGENTS.md antes de que empiece el trabajo, combinando la guía global de ~/.codex con instrucciones del proyecto y de repositorios anidados.³¹ Codex skills usa el mismo modelo mental de SKILL.md con divulgación progresiva: Codex empieza con el nombre, la descripción y la ruta del archivo del skill, y luego carga el skill completo solo cuando decide usarlo.³² Codex también tiene hooks nativos, hooks incluidos en plugins, hooks administrados, soporte para MCP y flujos de trabajo explícitos con subagent.³³³⁴

Codex v0.138.0–v0.139.0 reforzó ese descubrimiento de AGENTS.md para espacios de trabajo no triviales: ahora la carga pasa por la abstracción de sistema de archivos del entorno y conserva las rutas lógicas durante el recorrido de descubrimiento, de modo que se selecciona el archivo correcto incluso cuando el espacio de trabajo es un sistema de archivos remoto o un árbol con symlinks.⁶¹ Esto importa siempre que tu AGENTS.md canónico sea la fuente autoritativa y el agente opere sobre un checkout montado, materializado en contenedor o con symlinks: los casos donde un recorrido ingenuo de rutas elige silenciosamente el archivo de instrucciones equivocado o ninguno. Si replicas un único AGENTS.md autoritativo entre servicios, trata esto como la base mínima para confiar en que el archivo que el agente cargó realmente es el que escribiste.

Luego, Codex v0.141.0 reforzó la ruta de ejecución remota: los ejecutores remotos ahora se conectan mediante canales Noise-relay autenticados y cifrados de extremo a extremo (el plano de control y el ejecutor ya no confían en el relay entre ellos), la ejecución remota multiplataforma conserva el directorio de trabajo y el shell nativos del ejecutor, y TLS acepta firmas de certificados P-521 para proxies empresariales.⁶⁵ Si tu orquestación maneja ejecutores de Codex a través de un límite de red, esta es la diferencia entre asumir un relay confiable y tener cifrado de extremo a extremo: trátalo como la línea base para cualquier topología con ejecutores remotos.

El mapeo práctico:

La diferencia importante: los subagents de Claude pueden seleccionarse automáticamente a partir de sus descripciones, mientras que Codex actualmente documenta los flujos de trabajo con subagent como explícitos. Eso hace que skills y hooks sean el valor predeterminado correcto para el comportamiento always-on del harness en Codex; los subagents son para trabajo paralelo deliberado, revisión y exploración.

Probar tus instrucciones

Verifica que el agente realmente lea y siga 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 decisiva: Pídele al agente que explique tus comandos de compilación. Si no puede reproducirlos textualmente, las instrucciones son demasiado extensas (contenido desplazado fuera del contexto), demasiado vagas (el agente no puede extraer instrucciones accionables) o no se están descubriendo. El análisis de GitHub de 2.500 repositorios encontró que la vaguedad causa la mayoría de las fallas.²¹

Patrones de producción

Patrones de largo horizonte de Opus 4.7 (abril de 2026)

Claude Opus 4.7 (16 de abril de 2026) se lanzó con capacidades específicas que cambian aquello contra lo que un harness necesita protegerse:²⁹

• Resiliencia ante fallas de herramientas: Opus 4.7 continúa a pesar de fallas 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 subagent. Conserva las protecciones a nivel de hook; recorta el andamiaje dentro del prompt del tipo “si la herramienta falla, inténtalo de nuevo tres veces”.
• Nivel de esfuerzo xhigh (solo Opus-4.7): Se ubica entre high y max. Es el valor predeterminado recomendado para cargas de trabajo de codificación y agentic. En subagents de larga duración, xhigh supera de forma significativa a high con un costo de tokens menos que proporcional. max sigue siendo la opción correcta para razonamiento difícil de una sola pasada; xhigh es mejor para tareas sostenidas.
• Techo de presupuesto de tokens: Configurable por ejecución de agente mediante output_config.task_budget (encabezado beta task-budgets-2026-03-13). El modelo ve una cuenta regresiva en curso y ajusta con elegancia el alcance del trabajo al presupuesto, en lugar de quedarse sin tokens de forma inesperada. Úsalo para bucles agentic donde quieres un gasto de tokens predecible sin sacrificar calidad en prompts cortos.
• Conciencia de necesidades implícitas: Primer modelo Claude en superar pruebas de “necesidad implícita”: reconocer cuándo la solicitud literal del usuario no especifica por completo lo que realmente necesita. Esto hace que la sección de “reglas de aclaración” de CLAUDE.md sea menos necesaria. Si tu CLAUDE.md tiene 200 líneas de protecciones del tipo “también considera X cuando el usuario pida Y”, elimina las que ahora ya están cubiertas de forma nativa.

Base de worktree, rutas de sandbox y configuración de administrador (7 de mayo de 2026)

Claude Code v2.1.133 agrega cuatro configuraciones de nivel administrador que conviene conocer para harnesses de producción:³⁹

La reversión de worktree.baseRef es la que debes señalar a los usuarios: los agentes que dependían del comportamiento de v2.1.128-v2.1.132 (worktrees que creaban ramas desde el HEAD local) pierden acceso al trabajo sin push en worktrees nuevos, salvo que vuelvan a activarlo explícitamente.

Encuesta de feedback OTel para observabilidad enterprise (8 de mayo de 2026)

Claude Code v2.1.136 agregó CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL para volver a habilitar la encuesta de calidad dentro de la sesión para empresas que capturan las respuestas mediante OpenTelemetry.⁴⁰ Si tu organización envía eventos OTel a una pila central de observabilidad, esta variable de entorno vuelve a poner la encuesta en la ruta de datos para que la señal de calidad fluya por el mismo pipeline que las métricas de latencia y error. Trátala como opt-in: el valor predeterminado mantiene la encuesta suprimida, lo cual es correcto para despliegues que no usan OTel.

The Quality Loop

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

1. Implementar - Escribe el código
2. Revisar - Vuelve a leer cada línea. Detecta errores tipográficos, errores de lógica y secciones poco claras
3. Evaluar - Ejecuta el evidence gate. Revisa patrones, casos límite y cobertura de pruebas
4. Refinar - Corrige cada problema. Nunca lo difieras para “después”
5. Alejar el zoom - Revisa puntos de integración, imports y código adyacente en busca de regresiones
6. Repetir - Si falla algún criterio del evidence gate, vuelve al paso 4
7. Reportar - Enumera qué cambió, cómo se verificó y cita evidencia específica

The Evidence Gate

“Creo” 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.²²

Autoridad humana para merge

Un estudio de arXiv de mayo de 2026 sobre 29.585 ciclos de vida de pull requests de agentes de IA separa la agencia operativa de la gobernanza de merges.⁴⁷ La lección útil de arquitectura es simple: los agentes pueden iniciar trabajo, hacer avanzar ramas, abrir PRs, revisar trabajo y resumir riesgos, mientras que la autoridad para hacer merge permanece como un límite de gobernanza separado.

Haz explícito ese límite en el harness. Deja que los agentes preparen PRs y recopilen evidencia; exige aprobación humana para merges, releases y operaciones destructivas en repositorios, salvo que la organización tenga una política de automatización auditada por separado. Cuando la automatización ejecute un merge, conserva logs que distingan al ejecutor de la persona o política que lo autorizó.

Patrones de manejo de errores

Escrituras atómicas de archivos. Varios agentes escribiendo simultáneamente en el mismo archivo de estado corrompen JSON. Escribe en archivos .tmp y luego usa mv de forma atómica. 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 corrupción de estado. Si el estado se corrompe, el patrón de recuperación lo 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 bash ((VAR++)). ((VAR++)) devuelve código de salida 1 cuando VAR es 0 porque 0++ se evalúa como 0, lo que bash trata como falso. Con set -e habilitado, esto mata el script. Usa VAR=$((VAR + 1)) en su lugar.¹⁶

Clasificación de blast radius

Clasifica cada acción del agente por blast radius y aplica gates en consecuencia:²

Remote Control (conectarse a Claude Code local desde cualquier navegador o app móvil) convierte el gate “External” de una espera bloqueante en una notificación asincrónica. El agente sigue 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 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: aprobación/falla de pruebas, salida de linter, códigos de estado HTTP, comprobaciones 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 falla a vigilar

Un rastro de sesión concreto

Un rastro de sesión de una ejecución autónoma que procesa un PRD con 5 historias:²

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

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

3. El agente llama a Bash para ejecutar pruebas. PreToolUse:Bash se dispara. Revisión de credenciales, validación de sandbox, detección del proyecto. 90 ms. Las pruebas se ejecutan. PostToolUse:Bash se dispara: se registra el heartbeat de actividad, revisión de deriva.

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

5. El agente termina la historia. Stop se dispara. Revisiones del quality gate: ¿el agente citó evidencia? ¿Lenguaje evasivo? ¿Comentarios TODO en el diff? Si alguna revisión falla, sale con 2 y el agente continúa.

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

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

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

Total de hooks disparados en 5 historias: ~340. Tiempo total en hooks: ~12 segundos. Ese overhead evitó tres filtraciones 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) en 8 sesiones nocturnas. Las métricas comparan los primeros 4 PRDs (harness mínimo: solo CLAUDE.md) con los últimos 8 (harness completo: hooks, skills, quality gates, revisión multiagente).

Las dos filtraciones de credenciales exigieron rotar claves de API y auditar servicios downstream: aproximadamente 4 horas de respuesta a incidentes. El overhead del harness que evitó el equivalente fue de 2,4 segundos de bash por historia. La tasa de finalización falsa cayó de 35% a 4% porque el Stop hook ejecutó pruebas de forma independiente antes de permitir que el agente reportara que había terminado.

Consideraciones de seguridad

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

Anthropic publicó un marco formal para la confiabilidad de los agentes el 9 de abril de 2026.²⁷ Los cinco principios son paralelos al enfoque de Evidence Gate de esta guía, y lo amplían:

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

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

El Sandbox

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

Piso de seguridad de mayo de 2026. Claude Code v2.1.149 corrigió una omisión de permisos de directorio de trabajo en PowerShell, varios vacíos de análisis de permisos en reglas allow de PowerShell y variables obsoletas, y un bug de allowlist de escritura en sandbox de git-worktree que cubría toda la raíz del repositorio principal en lugar de solo los componentes internos compartidos de git.⁵³ Si tu harness permite PowerShell o agentes aislados por worktree, trata v2.1.149+ como el piso y mantén reglas de shell estrictas. PowerShell(*) amplio y las excepciones de escritura para todo el repositorio son atajos de orquestación, no límites de seguridad.

Bloqueo de sandbox de OpenAI Agents SDK (v0.17.0, 8 de mayo de 2026). Del lado de OpenAI, openai-agents-python v0.17.0 endureció un límite paralelo: LocalFile.src y LocalDir.src ahora están restringidos a estar dentro del base_dir de materialización (el directorio de trabajo actual del proceso SDK cuando se aplica el manifest), salvo que la fuente se conceda explícitamente mediante Manifest.extra_path_grants con SandboxPathGrant.⁴¹ Las fuentes locales relativas se resuelven desde base_dir; las rutas absolutas ya deben estar dentro de él o llevar una concesión. Esto cierra un problema de límite de artefactos locales: las versiones anteriores permitían que los manifests incorporaran rutas arbitrarias del host a un espacio de trabajo sandbox. Migración: declara raíces confiables del host en el nivel del manifest con SandboxPathGrant(path=..., read_only=True) para montajes de solo lectura. Trata extra_path_grants como configuración confiable de la aplicación; nunca llenes concesiones a partir de la salida del modelo ni de entradas de manifest no confiables.

Piso posterior de OpenAI Agents SDK (v0.17.3). La línea 0.17.1-0.17.3 agregó más endurecimiento de sandbox y sesión: límites de extracción de archivos, validación de subrutas de GitRepo, errores más claros de proveedor de sandbox, credenciales de mountpoint fuera de comandos de sandbox, rechazo de raíces relativas para espacios de trabajo sandbox, y manejo de estado de terminal en Vercel-sandbox.⁵⁴ Si usas sandboxes alojados por OpenAI o respaldados por proveedores en lugar de solo hooks de Claude Code, trata 0.17.3 como el piso actual para los patrones de esta sección.

Límites de permisos

El sistema de permisos controla operaciones en varios niveles:

Reglas de permisos a nivel de parámetros (junio de 2026)

Claude Code v2.1.178 extendió las reglas de permisos desde el nivel de herramienta hasta el nivel de parámetro: Tool(param:value) coincide contra los parámetros de entrada de una herramienta, con * como comodín. El ejemplo canónico es Agent(model:opus): una regla que bloquea que se creen subagents en un nivel específico de modelo.⁶³ Arquitectónicamente, esto cierra un vacío que la tabla de cuatro niveles anterior no podía expresar: antes permitías o denegabas una herramienta completa, pero no podías restringir cómo se llamaba. Una política de gobernanza ahora puede decir “los subagents pueden crearse, pero no en el nivel Fable 5” o “Bash está permitido, pero no con esta flag” como una regla determinista en lugar de una solicitud a nivel de prompt.

Una configuración administrada complementaria, enforceAvailableModels (v2.1.175), restringe la selección de modelos desde arriba: fija el modelo Default e impide que configuraciones de usuario o de proyecto amplíen la allowlist administrada availableModels.⁶³ Ambas se componen: la allowlist define qué niveles existen para la sesión, y las reglas a nivel de parámetros restringen cómo los subagents los usan.

Guardrails de Auto Mode para comandos destructivos (junio de 2026)

Claude Code v2.1.183 redujo el radio de impacto de auto mode para las operaciones que pierden trabajo silenciosamente o desmontan entornos. Auto mode ahora bloquea de forma estricta, salvo que las hayas pedido explícitamente en la sesión: operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend cuando el commit no fue hecho por el agente en esta sesión; y desmontaje de infraestructura (terraform destroy, pulumi destroy, cdk destroy) salvo que hayas nombrado el stack específico.⁶⁵ Arquitectónicamente, esto complementa la evaluación de spawn y las reglas a nivel de parámetros anteriores: en lugar de controlar qué herramienta o cómo se crea, controla un conjunto pequeño de comandos irreversibles específicos por intención; el agente aún puede ejecutarlos, pero solo con instrucción explícita, no por iniciativa propia. Para un harness autónomo, codifica el mismo principio en tus propios hooks PreToolUse: los comandos que destruyen estado merecen una regla de denegación predeterminada que solo una señal explícita del operador pueda levantar.

Defensa contra Prompt Injection

Los skills y hooks ofrecen defensa en profundidad contra prompt injection:

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

Aislamiento de subagent limita el radio de impacto. Un subagent con permissionMode: plan no puede hacer cambios aunque su prompt esté comprometido.

Los logs de agentes y los guardrails son superficies de seguridad

Dos avisos de mayo de 2026 refuerzan un patrón: la infraestructura de agentes crea nuevos lugares donde contenido sensible y políticas ejecutables pueden filtrarse o escapar. GitHub Advisory GHSA-f3jg-756w-gm35 cubre un problema de filtro de payloads en Gryph Agents donde contenido sensible de tool-payload podía permanecer en logs SQLite locales bajo el comportamiento de registro predeterminado.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p cubre un escape de sandbox de guardrail de código personalizado de LiteLLM en un endpoint proxy protegido por administrador.⁴⁶

La regla de producción: trata las transcripciones de agentes, tool payloads, logs SQLite y ejecución de guardrails como infraestructura sensible. Redacta antes de persistir, aplica límites de retención y mantén el código personalizado de guardrails en sandbox y revisable. Una regla a nivel de prompt de “no registres secretos” no basta; la ruta de logging y guardrails necesita pruebas deterministas.

Seguridad de hooks

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

La seguridad en arquitecturas de agentes requiere una división clara entre responsabilidades humanas 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 disparan para acciones de subagents.¹³ Si Claude crea un subagent mediante la Agent tool, tus hooks PreToolUse y PostToolUse se ejecutan para cada herramienta que usa el subagent. Sin aplicación recursiva de hooks, un subagent podría eludir tus compuertas de seguridad. El evento SubagentStop te permite ejecutar limpieza o validación cuando un subagent termina.

Esto no es opcional. Un agente que crea 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 compuertas ven que la conversación principal no hace nada.

El costo como arquitectura

El costo es una decisión arquitectónica, no una idea 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 deben leerse credenciales.

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

Nivel de arquitectura. CLI primero antes que MCP cuando la operación es stateless. Una llamada claude --print para una evaluación puntual cuesta menos y no agrega 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, así que el tiempo total de ejecución de hooks se suma a cada llamada de herramienta coincidente. 95 hooks entre configuraciones a nivel de usuario y de proyecto se ejecutan sin latencia perceptible cuando cada hook termina en menos de 200 ms. El umbral que debes vigilar: si un PostToolUse hook agrega 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.¹⁴

¿Los hooks pueden bloquear que Claude Code ejecute un comando?

Sí. Los PreToolUse hooks 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. La salida 1 es una advertencia no bloqueante donde la acción continúa de todos modos.³

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

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

¿Cada decisión necesita deliberation?

No. El módulo de confianza puntúa las decisiones en cuatro dimensiones (ambigüedad, complejidad, impacto, dependencia del contexto). Solo las decisiones con una confianza general inferior a 0,70 activan deliberation, aproximadamente el 10% del total de decisiones. Las correcciones de documentación, cambios de nombre de variables y ediciones rutinarias omiten deliberation por completo. La arquitectura de seguridad, los cambios de esquema de base de datos y los despliegues irreversibles la activan de forma constante.⁷

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

Prueba tanto las rutas exitosas como las rutas de fallo. Éxito: los agentes discrepan de forma productiva y llegan a consenso. Fallo: los agentes convergen demasiado rápido, nunca convergen o exceden los presupuestos de spawn. Las pruebas end-to-end simulan cada escenario con respuestas deterministas de agentes, verificando que ambas puertas de validación detecten todos los modos de fallo documentados. Un sistema de deliberation en producción ejecuta 141 pruebas en tres capas: 48 pruebas de integración bash, 81 pruebas unitarias de Python y 12 simulaciones end-to-end de pipeline.⁷

¿Cuál es el impacto de latencia de deliberation?

Una deliberation de 3 agentes agrega 30-60 segundos de tiempo real (los agentes se ejecutan secuencialmente mediante el Agent tool). Una deliberation de 10 agentes agrega 2-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 primero las instrucciones más críticas: comandos y definiciones de cierre antes que preferencias de estilo.²¹

¿Esto puede funcionar con herramientas distintas de Claude Code?

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

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

Registro de cambios

Referencias