Arquitectura de agentes: cómo crear entornos de desarrollo impulsados por IA

TL;DR: Claude Code no es un cuadro de chat con acceso a archivos. Es un entorno de ejecución programable con 30 eventos documentados del ciclo de vida, cada uno compatible con hooks mediante scripts de shell que el modelo no puede omitir. Agrupa hooks en dispatchers, dispatchers en skills, skills en agentes y agentes en flujos de trabajo, y obtendrás un harness de desarrollo autónomo que aplica restricciones, delega trabajo, conserva memoria entre sesiones y coordina deliberaciones multiagente. Claude Code v2.1.147 incorporó la herramienta Workflow, desactivada de forma predeterminada (CLAUDE_CODE_WORKFLOWS=1), lo que llevó la coordinación multiagente determinista desde scripts creados íntegramente por los usuarios hacia una primitiva nativa del entorno de ejecución; v2.1.149 refuerza la misma lección desde el ámbito de la seguridad mediante correcciones para la omisión de permisos en PowerShell y para la lista de permitidos del entorno aislado de git worktree. Los hooks y evidence gates siguen siendo responsables de la corrección.⁵²⁵³ Esta guía abarca todas las capas de ese conjunto: desde un solo hook hasta un sistema de consenso de 10 agentes. No requiere ningún framework. Todo está hecho con bash y JSON.

Andrej Karpathy acuñó un término para describir lo que crece alrededor de un agente LLM: garras. Son los hooks, scripts y mecanismos de coordinación que permiten al agente aferrarse al mundo que existe fuera de su ventana de contexto.¹ La mayoría de los desarrolladores tratan a los agentes de programación con IA como asistentes interactivos. Escriben un prompt, observan cómo editan un archivo y continúan con otra cosa. Este enfoque limita la productividad a aquello que puedes supervisar personalmente.

El modelo mental de infraestructura es diferente: un agente de programación con IA es un entorno de ejecución programable con un núcleo 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 funciona sujeto a las reglas de nginx. No te sientas frente a nginx a escribir solicitudes. Lo configuras, lo despliegas y lo supervisas.

La diferencia importa porque los beneficios de la infraestructura se acumulan. Un hook que bloquea credenciales en comandos de bash protege cada sesión, cada agente y cada ejecución autónoma. Una skill que incorpora tus criterios de evaluación se aplica de manera uniforme, tanto si la invocas tú como si lo hace un agente. Un agente que revisa la seguridad del código ejecuta las mismas comprobaciones, estés observándolo o no.²

Puntos clave

• Los hooks garantizan la ejecución; los prompts, no. Usa hooks para linting, formateo, comprobaciones de seguridad y cualquier tarea que deba ejecutarse siempre, independientemente del comportamiento del modelo. El código de salida 2 bloquea acciones. El código de salida 1 solo muestra una advertencia.³
• Las skills incorporan conocimientos especializados del dominio y se activan automáticamente. El campo description lo determina todo. Claude utiliza razonamiento LLM (no coincidencia de palabras clave) para decidir cuándo aplicar una skill.⁴
• Los subagents evitan que el contexto se sature. Las ventanas de contexto aisladas para exploración y análisis mantienen ligera la sesión principal. Ejecuta subagents independientes en paralelo y utiliza equipos de agentes cuando los trabajadores necesiten una coordinación continua.⁵
• La memoria reside en el sistema de archivos. Los archivos persisten entre ventanas de contexto. CLAUDE.md, MEMORY.md, los directorios de reglas y los documentos de traspaso forman un sistema estructurado de memoria externa.⁶
• La deliberación multiagente permite detectar puntos ciegos. Un solo agente no puede cuestionar sus propias suposiciones. Dos agentes independientes con distintas prioridades de evaluación detectan fallas estructurales que los controles de calidad no pueden abordar.⁷
• El patrón de harness es el sistema. CLAUDE.md, hooks, skills, agentes y memoria no son funciones independientes. Se combinan para formar una capa determinista entre el modelo y tú, capaz de escalar junto con la automatización.

Cómo usar esta guía

Cada sección se basa en la anterior. El Marco de decisión que aparece al final ofrece una tabla de consulta para elegir el mecanismo adecuado según cada tipo de problema.

La ruta dorada de cinco minutos

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

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

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

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

Conéctalo en .claude/settings.json:

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

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

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

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

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

Paso 3: genera un subagent (30 segundos)

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

Lo que ahora tienes

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

Por qué importa la arquitectura de agentes

Simon Willison enmarca el momento actual en torno a una sola observación: escribir código ahora es barato.⁸ Correcto. Pero el corolario es que la verificación es ahora la parte costosa. El código barato sin infraestructura de verificación produce bugs a escala. La inversión que rinde no es un mejor prompt. Es el sistema que rodea al modelo y atrapa lo que el modelo pasa por alto.

Tres fuerzas hacen que la arquitectura de agentes sea necesaria:

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

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

Las perspectivas individuales pasan por alto problemas multidimensionales. Un solo agente que revisaba un endpoint API verificó la autenticación, validó el saneamiento de entrada y comprobó los encabezados CORS. Certificado de salud impecable. Un segundo agente, al que se le indicó por separado actuar como pentester, encontró que el endpoint aceptaba parámetros de consulta sin límite que podían provocar denegación de servicio mediante amplificación de consultas a la base de datos.⁷ El primer agente nunca lo verificó porque nada en su marco de evaluación trataba la complejidad de las consultas como una superficie de seguridad. Esa brecha es estructural. Ninguna cantidad de ingeniería de prompts la soluciona.

La arquitectura de agentes aborda las tres: los hooks imponen restricciones deterministas, los subagents gestionan el aislamiento de contexto y la orquestación multi-agente aporta perspectivas independientes. Juntos forman el harness.

El patrón harness

El harness no es un framework. Es un patrón: un conjunto componible de archivos, scripts y convenciones que envuelve a un agente de programación con IA en una infraestructura determinista. Sus componentes:

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

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

Capa de extensiones: Los skills aportan conocimientos especializados del dominio que se activan automáticamente según el contexto. Los hooks proporcionan controles deterministas que se ejecutan en cada llamada de herramienta coincidente. Los archivos de memoria conservan el estado entre sesiones. Los agentes personalizados ofrecen configuraciones especializadas de subagents.

Capa de orquestación: Los patrones multiagente coordinan agentes independientes para tareas de investigación, revisión y deliberación. Los límites de creación evitan una recursión descontrolada. La validación por consenso garantiza la calidad.

La idea clave: la mayoría de los usuarios trabaja exclusivamente en la capa central, mientras observa cómo crecen el contexto y los costos. Los usuarios avanzados configuran las capas de instrucciones y extensiones, y luego utilizan la capa central únicamente para la orquestación y las decisiones finales.²

Harnesses administrados frente a autoalojados (abril de 2026)

Durante los primeros meses de 2026, la única opción real era «crear tu propio harness». Eso cambió en abril de 2026. Anthropic lanzó Claude Managed Agents en beta pública el 8 de abril: bucle del harness + ejecución de herramientas + contenedor sandbox + persistencia del estado como una API REST, con un costo de tokens estándar más USD 0,08 por hora de sesión. La actualización de Agents SDK de OpenAI, publicada el 16 de abril, formalizó la misma separación: el harness y la capacidad de cómputo como capas independientes, con proveedores nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel) y funciones de instantánea y rehidratación para resistir la pérdida de un contenedor.²³²⁴

La interfaz más completa de SDK para OpenAI llegó en openai-agents Python v0.14.0 (publicada el 15 de abril de 2026 y anunciada el 16 de abril): una subclase SandboxAgent de Agent con default_manifest, instrucciones de sandbox y capacidades; un Manifest que describe el contrato de un espacio de trabajo nuevo (archivos, directorios, archivos locales, repositorios Git, entorno, usuarios y montajes); y un SandboxRunConfig para configurar en cada ejecución el cliente de sandbox, la inyección de sesiones activas, las anulaciones del manifiesto, las instantáneas y los límites de concurrencia de la materialización. Las capacidades integradas abarcan 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 conserva las lecciones extraídas entre ejecuciones y las revela de forma progresiva; los espacios de trabajo admiten archivos locales, entradas de repositorios Git y montajes remotos (S3, R2, GCS, Azure Blob y S3 Files); las instantáneas son portátiles entre proveedores. Backends: UnixLocalSandboxClient, DockerSandboxClient y clientes alojados para Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel mediante extras opcionales.²⁴

Para los proyectos de Python que quieran integrar el entorno de ejecución de Claude Code como una biblioteca —entre «invocar claude mediante el shell» y «usar la API REST de Managed Agents»—, claude-agent-sdk-python es la tercera opción. La serie del 28 y 29 de abril (v0.1.69 → v0.1.71) actualizó el CLI incluido a la versión v2.1.123, elevó la versión mínima de la dependencia mcp a >=1.19.0 (las versiones anteriores descartaban silenciosamente los valores CallToolResult devueltos por las herramientas MCP en proceso, por lo que el modelo solo recibía un bloque con un error de validación) y equiparó SandboxNetworkConfig con el esquema de TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Al 1 de agosto de 2026, el paquete se encuentra en la versión v0.2.128 en PyPI (incluye Claude CLI v2.1.220 y ahora exige como mínimo mcp >=1.23.0), mientras que TypeScript SDK está en la versión v0.3.220. La serie 0.2.x amplía de manera incremental la interfaz 0.1.x descrita aquí: las opciones include_hook_events, skills y de configuración del sandbox que aparecen más adelante siguen vigentes; las versiones recientes se han centrado en la limpieza de subprocesos y la confiabilidad del flujo NDJSON.⁸⁶

Si tu harness incluye una capa de voz o en tiempo real, openai-agents-python v0.17.0 (8 de mayo de 2026) actualizó RealtimeAgent para usar gpt-realtime-2 de forma predeterminada.⁴¹ Las sesiones existentes en tiempo real adoptan automáticamente el nuevo valor predeterminado; especifica explícitamente el modelo anterior si necesitas conservar su comportamiento para una evaluación.

En julio de 2026, la opción administrada también incorporó una propuesta multiagente por parte de OpenAI: openai-agents-python v0.18.2 (11 de julio) y openai-agents-js v0.13.2 (10 de julio) añaden compatibilidad con múltiples agentes alojados en beta: orquestación administrada por OpenAI de varios agentes como servicio alojado, la contraparte directa de la beta pública de Managed Multiagent Orchestration de Anthropic que se aborda en la sección Orquestación multiagente.⁷³ Ambos proveedores ofrecen ahora, en el nivel multiagente, la misma disyuntiva que la tabla siguiente describe para los agentes individuales: el proveedor ejecuta el bucle de delegación y tú renuncias a la interfaz de hooks.

La bifurcación arquitectónica ya es una realidad:

Cuándo elegir cada opción: el modelo autoalojado sigue siendo adecuado para equipos que ya cuentan con una sólida capacidad de infraestructura, quieren controlar sus skills y hooks, o buscan optimizar a fondo un flujo de trabajo específico. El modelo administrado es adecuado para equipos sin ingenieros de plataforma dedicados, cuando obtener valor rápidamente importa más que la personalización o cuando las ejecuciones de los agentes necesitan continuar de forma confiable al cerrar una computadora portátil, sin que tengas que crear esa capa de persistencia. Ambas opciones son compatibles: puedes ejecutar un harness autoalojado que delegue tareas específicas de larga duración a Managed Agents mediante su API REST.

Cómo se ve el harness en el 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 una función. El árbol ~/.claude/ es una infraestructura personal que se aplica a todos los proyectos. El árbol .claude/ de cada repositorio es específico del proyecto y se comparte mediante git. Juntos forman el harness completo.

Sistema de skills

Los skills son extensiones invocadas por el modelo. Claude los descubre y aplica automáticamente según el contexto, sin que tengas que llamarlos de forma explícita.⁴ En cuanto notes que estás explicando de nuevo el mismo contexto en distintas sesiones, es momento de crear un skill.

Cuándo crear un skill

Los skills sirven para el conocimiento que Claude siempre tiene disponible. Los comandos slash sirven para las acciones que activas explícitamente. Si estás decidiendo entre ambos, pregúntate: «¿Debe Claude aplicar esto automáticamente o debo decidir cuándo ejecutarlo?».

Creación de un skill

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

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

El campo de descripción lo es todo

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

Descripción deficiente:

description: Helps with code

Descripción eficaz:

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 eficaz incluye qué hace (revisar código para detectar tipos específicos de problemas), cuándo usarlo (al examinar cambios, PR o analizar la calidad) y frases activadoras (revisar, auditar, comprobar) que los usuarios escriben de forma natural.

Ten en cuenta que la activación automática es una opción graduable, no una regla inamovible: desde la versión v2.1.215, Claude ya no invoca por sí mismo los skills incluidos /verify y /code-review; estos solo se ejecutan cuando se invocan explícitamente. Se trata de una reversión deliberada de la activación basada en descripciones para los skills de revisión intensiva, cuyas ejecuciones no solicitadas costaban más de lo que aportaban.⁷⁴

Presupuesto de contexto

Todas las descripciones de los skills comparten un presupuesto de contexto que se ajusta dinámicamente al 1 % de la ventana de contexto, con un valor alternativo de 8.000 caracteres.⁴ Si tienes muchos skills, procura que cada descripción sea concisa y coloca primero el caso de uso principal. Puedes modificar el presupuesto mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ pero la mejor solución es escribir descripciones más breves y precisas. Ejecuta /context durante una sesión para comprobar si se está excluyendo algún skill.

Archivos auxiliares y organización

Los skills pueden hacer referencia a archivos adicionales del mismo directorio:

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

Haz referencia a ellos desde SKILL.md mediante enlaces relativos. Claude lee estos archivos cuando los necesita después de que se activa el skill. Mantén SKILL.md por debajo de las 500 líneas y traslada el material de referencia detallado a archivos auxiliares.¹²

Compartir skills mediante Git

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

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

Cuando tus compañeros de equipo hacen pull, reciben el skill automáticamente. Sin instalación ni configuración. Esta es la manera más eficaz de estandarizar el conocimiento especializado en todo un equipo.

Los skills como biblioteca de prompts

Además de los skills con un único propósito, la estructura de directorios funciona como una biblioteca organizada de prompts:

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

Cada skill codifica una faceta distinta de tu conocimiento especializado. En conjunto, forman una base de conocimientos de la que Claude se nutre automáticamente según el contexto. Un desarrollador junior recibe orientación de nivel sénior sin tener que pedirla.

Los skills se combinan con hooks

Los skills pueden definir sus propios hooks en el frontmatter, los cuales se activan únicamente mientras se ejecuta el skill. Esto genera un comportamiento específico del dominio que no contamina otras sesiones:²

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

Los skills de filosofía se activan automáticamente mediante hooks de SessionStart, que incorporan restricciones de calidad en cada sesión sin necesidad de invocarlos explícitamente. El skill es el conocimiento. El hook se encarga de aplicarlo. Juntos forman una capa de políticas.

Errores comunes con los skills

Descripciones demasiado amplias. Un skill git-rebase-helper que se activa ante cualquier prompt relacionado con Git (rebases, fusiones, cherry-picks e incluso git status) contamina el contexto en el 80 % de las sesiones. La solución consiste en hacer más específica la descripción o agregar disable-model-invocation: true y exigir una invocación explícita mediante /skill-name.⁴

Demasiados skills compitiendo por el presupuesto. Cuantos más skills tengas, más descripciones competirán por el presupuesto de contexto del 1 %. Si notas que algunos no se activan, consulta /context para comprobar cuáles están excluidos. Prioriza unos pocos skills bien descritos en lugar de muchos skills imprecisos.

Información crítica oculta en archivos auxiliares. Claude lee SKILL.md de inmediato, pero solo accede a los archivos auxiliares cuando los necesita. Si la información crítica está en uno de estos archivos, es posible que Claude no la encuentre. Incluye 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 o posterior deben utilizar la opción skills de ClaudeAgentOptions para declarar los skills disponibles, en lugar del valor heredado "Skill" en allowed_tools.³⁷ La forma abreviada "Skill" está obsoleta y la opción específica proporciona a Claude Code información más estructurada sobre los skills disponibles. La versión de CLI incluida en v0.1.77 es la 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 amplía ese directorio para admitir plugins: ahora, un plugin colocado en .claude/skills/ se carga automáticamente sin necesidad de registrarlo en un marketplace, y claude plugin init <name> crea allí la estructura inicial de uno nuevo, con el manifiesto y SKILL.md ya conectados.⁵⁸ Esto cierra la brecha entre las 2 modalidades de herramientas de proyecto que antes residían en lugares distintos: por un lado, un skill independiente incorporado directamente al repositorio; por otro, un plugin que agrupa un skill, hooks y un servidor MCP, pero que antes necesitaba un marketplace para instalarse. El efecto práctico para el diseño de harnesses es que las herramientas limitadas al proyecto ya no necesitan pasar por un registro para distribuirse: escríbelas, incorpóralas al repositorio y tus compañeros de equipo obtendrán la misma superficie al ejecutar git pull. Los plugins siguen cubriendo el caso de uso de paquetes instalables (hooks + skills + servidores MCP + agentes en un solo ZIP); el cambio es que un proyecto ya no tiene que montar un marketplace solo para cargar uno desde su propio árbol.

Ocultar la superficie incluida como medida de gobernanza (8 de junio de 2026)

Los skills son capacidades, y cada capacidad amplía la superficie de ataque. Claude Code v2.1.169 incorpora una opción disableBundledSkills —y la variable de entorno correspondiente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS— que oculta por completo al modelo los skills, workflows y comandos slash integrados que se incluyen de forma predeterminada.⁶⁰ En un harness reforzado o regulado, esto supone una reducción deliberada de la superficie de ataque: un operador que haya auditado y aprobado un conjunto específico de skills personales y del proyecto puede suprimir todo lo que Anthropic incluye de fábrica, de modo que el modelo solo razone sobre la superficie que el operador ha validado. Trátalo de la misma manera que una lista de herramientas permitidas: la configuración predeterminada ofrece capacidades amplias, y desactivarla es una decisión de gobernanza, no una simple opción de comodidad.

.claude/skills anidados y resolución por proximidad (16 de junio de 2026)

Claude Code v2.1.178 hizo que las herramientas del proyecto fueran sensibles a la ubicación. Ahora, los skills de directorios .claude/skills anidados se cargan cuando trabajas con archivos dentro de ese directorio, no solo desde la raíz del repositorio; 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 resolviera según su proximidad al directorio de trabajo: cuando el nombre de un agente, workflow o estilo de salida entra en conflicto entre distintos directorios .claude/ anidados, prevalece el que está más cerca del directorio de trabajo, y al guardar un workflow en el ámbito del proyecto se utiliza el directorio .claude/workflows/ existente más cercano en lugar de usar siempre el de la raíz.⁶³ Para un monorepo o un repositorio de repositorios, esta es la diferencia entre una única superficie global plana y herramientas por paquete que se activan según el contexto: services/api/.claude/skills/ puede contener skills específicos de API que solo aparecen mientras trabajas en ese árbol, sin entrar en conflicto con un skill del mismo nombre en services/web/.

Arquitectura de hooks

Los hooks son comandos de shell que se activan mediante eventos del ciclo de vida de Claude Code.³ Se ejecutan fuera de LLM como scripts comunes, no como prompts interpretados por el modelo. ¿El modelo quiere ejecutar rm -rf /? Un script de bash de 10 líneas compara el comando con una lista de bloqueo y lo rechaza antes de que el shell llegue a verlo. El hook se activa independientemente de que el modelo quiera o no.

Eventos disponibles

Claude Code ofrece 30 eventos documentados del ciclo de vida en ocho categorías a partir de esta actualización de la guía. La lista de eventos crece con cada versión, así que considera la documentación de referencia como la fuente de verdad y consulta la hoja de referencia rápida para ver la tabla completa y actualizada antes de configurar hooks de producción:¹³

DirectoryAdded (v2.1.219) cierra la brecha del espacio de trabajo durante una sesión. La lista de eventos se había mantenido estable desde que MessageDisplay llegó en la v2.1.152; DirectoryAdded es el primer evento nuevo del ciclo de vida desde entonces y se activa después de que /add-dir —o la solicitud de control register_repo_root de SDK— registra un nuevo directorio de trabajo durante una sesión.⁸⁴ La brecha que cierra es real: hasta ahora, un harness podía validar exhaustivamente un espacio de trabajo en SessionStart y luego ver cómo se incorporaba un segundo repositorio sin que se activara ningún hook. Todo lo que compruebes sobre el espacio de trabajo al inicio —verificaciones de confianza, análisis de secretos, reglas de alcance de rutas derivadas del árbol o carga de políticas por repositorio— debe volver a ejecutarse aquí, porque el conjunto de directorios de una sesión ya no queda fijo al iniciarla. El evento es informativo, no bloqueante, así que úsalo como activador para volver a derivar el estado y registrar la procedencia, no como gate; si nunca debe permitirse agregar un directorio, deniégalo en la configuración en lugar de intentar vetarlo desde un hook. La parte correspondiente a SDK llegó en la misma versión (TypeScript v0.3.219 agrega DirectoryAdded a los eventos del ciclo de vida del protocolo de control), por lo que los harnesses alojados en SDK lo reciben en igualdad de condiciones que los alojados en CLI.⁸⁵

Semántica de los códigos de salida

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

Configuración de hooks

Los hooks se guardan en archivos de configuración. Usa el nivel de proyecto (.claude/settings.json) para los hooks compartidos y el nivel de usuario (~/.claude/settings.json) para los 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. En los eventos de herramientas, coincide con valores de tool_name como Bash, Edit, Write, Read, Glob, Grep, nombres de herramientas de MCP como mcp__server__tool o * para todas las herramientas. Los nombres simples y las listas separadas por | son coincidencias exactas; los valores con otros caracteres son expresiones regulares de JavaScript. Algunos eventos no admiten matchers y siempre se activan cuando están configurados.¹³ A partir de Claude Code v2.1.195, los matchers que contienen identificadores con guion (code-reviewer, mcp__brave-search) realizan una coincidencia exacta en lugar de coincidir accidentalmente con subcadenas: un hook dirigido a un agente o servidor ya no se activa con cada nombre que simplemente contenga esa cadena; para incluir todas las herramientas de un servidor MCP con guion, escribe el patrón explícito mcp__brave-search__.*.⁶⁶ La v2.1.214 aplicó el mismo rigor a los patrones de rutas: una condición if: de un hook que utiliza un patrón de un solo segmento dir/** ahora coincide únicamente con <cwd>/dir, no con todos los directorios llamados dir en cualquier lugar del árbol; escribe **/dir/** cuando realmente quieras abarcar cualquier profundidad.⁷⁴ Al igual que con el cambio de la v2.1.195, la corrección sustituye una amplitud accidental por una intención declarada; audita todas las condiciones de hooks que dependieran silenciosamente del comportamiento anterior a cualquier profundidad.

Protocolo de entrada/salida de hooks

Los hooks reciben JSON mediante stdin con todo el contexto:

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

Para tener un control avanzado, los hooks PreToolUse pueden generar JSON para modificar la entrada de la herramienta, inyectar contexto o tomar decisiones sobre permisos. Usa el contenedor hookSpecificOutput; el formato anterior con decision/reason en el nivel superior está obsoleto para PreToolUse:

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

Tres tipos de garantías

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

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

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

Las garantías de seguridad evitan acciones peligrosas antes de que se ejecuten. Los hooks PreToolUse en Bash inspeccionan los comandos y bloquean patrones destructivos con el 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 los puntos de decisión. Los hooks PreToolUse en comandos git commit ejecutan tu linter o conjunto de pruebas y bloquean el commit si las comprobaciones de calidad fallan:

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

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

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

Claude Code admite cinco tipos de hooks:¹³

Los hooks de comandos (type: "command") ejecutan scripts de shell. Son rápidos, deterministas y no consumen tokens. Hooks de herramientas de MCP (type: "mcp_tool") llaman a una herramienta en un servidor MCP ya conectado. Úsalos cuando la lógica de validación ya se encuentre detrás de un límite de MCP y no necesite un script de shell independiente.

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

Agent hooks (type: "agent") generan un subagent con acceso a herramientas (Read, Grep, Glob) para realizar verificaciones de varios turnos. Son experimentales; para los controles de producción, prefiere los command hooks y reserva los agent hooks para comprobaciones que realmente requieran inspeccionar archivos o resultados de pruebas:

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

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

HTTP hooks (type: "http") envían la entrada de JSON del evento como una solicitud POST a una URL y reciben JSON como respuesta. Úsalos para webhooks, servicios externos de notificaciones o validaciones basadas 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
          }
        ]
      }
    ]
  }
}

Async Hooks

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

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

Usa async para notificaciones, telemetría y copias de seguridad. Nunca lo uses para el formato, la validación ni ninguna operación que deba completarse antes de la siguiente acción.

Dispatchers en lugar de hooks independientes

Ejecutar siete hooks que se activan con el mismo evento y leen stdin de forma independiente genera condiciones de carrera. Si dos hooks escriben simultáneamente en el mismo archivo de estado de JSON, truncarán el JSON. Todos los hooks posteriores que analicen ese archivo dejarán de funcionar.²

La solución: un dispatcher por evento que ejecute los hooks secuencialmente a partir de una copia en caché de stdin:

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

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

Depuración de hooks

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

1. Prueba los scripts de forma independiente. Pasa un JSON de ejemplo mediante una canalización: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Usa stderr para la salida de depuración. El stderr del código de salida 2 se devuelve a Claude como mensaje de error. El stderr no bloqueante (códigos de salida 1, 3, etc.) solo aparece en el modo detallado (Ctrl+O).
3. Presta atención a los fallos de jq. Las rutas incorrectas de JSON devuelven null silenciosamente. Prueba las expresiones de jq con 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 la rapidez de los hooks. Los hooks se ejecutan de manera síncrona. Procura que todos tarden menos de 2 segundos, idealmente menos de 500 ms.

Transmisión de eventos de hooks del lado del SDK

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

El patrón de flujo de eventos es el adecuado cuando tu harness ya está implementado en Python y quieres incorporar las señales de hooks al mismo flujo de control que la salida del modelo. El contrato de hooks mediante scripts de shell (códigos de salida, JSON por stdin y dispatchers) sigue siendo la opción correcta para los harnesses que combinan varias herramientas, comparten hooks entre Claude Code y Codex o necesitan la semántica de los códigos de salida para bloquear acciones.

La serie de julio de 2026 (v0.3.205–v0.3.208) del SDK de TypeScript convirtió el propio protocolo transmitido en un contrato más estricto.⁷⁰ Las interrupciones ahora devuelven confirmaciones tipadas: una interrupción confirma qué mensajes en cola siguen pendientes mediante UUID en still_queued, y las sesiones anuncian la capacidad interrupt_receipt_v1 en system/init, por lo que un coordinador puede distinguir entre «la interrupción se aplicó» y «la interrupción llegó tarde, después de que un mensaje ya estuviera en curso». Los frames de command_lifecycle informan los estados en cola/iniciado/completado/cancelado/descartado de cada mensaje: la primera respuesta oficial a «¿qué pasó con el mensaje que envié?» sin tener que inferirlo de la transcripción. También se incorporaron cambios menores: un tipo AgentToolCompletedOutput para las cargas útiles de finalización de los subagents, y los callbacks canUseTool ahora pueden devolver {behavior: 'allow'} sin un campo updatedInput.

Una línea de esa serie establece un mínimo de seguridad, no una función: la v0.3.208 corrigió un problema por el que la cancelación de una llamada durante un hook pendiente se convertía en un resultado exitoso del hook; esto significaba que una herramienta controlada por un hook PreToolUse podía ejecutarse después de que quien hizo la llamada la hubiera cancelado.⁷⁰ Si tu harness usa hooks del lado del SDK como control de permisos y depende de la cancelación para detener el trabajo en curso, considera la v0.3.208 como la versión mínima; en versiones anteriores, «cancelado» no significaba de forma confiable «bloqueado». La v0.2.127 de Python (24 de julio de 2026) representa el segundo caso de omisión de este tipo en un mes: query() cerraba stdin al recibir el primer frame result mientras los subagents en segundo plano seguían ejecutándose, por lo que sus llamadas a herramientas de SDK-MCP fallaban con "Stream closed" y omitían por completo los hooks PreToolUse.⁸⁵ Dale un nombre al patrón y vigílalo: la aplicación de hooks del lado del SDK falla de forma permisiva en los límites del ciclo de vida —cancelación, desmontaje y cierre del flujo—, donde el transporte desaparece antes de recopilar el veredicto del hook; además, falla silenciosamente, porque un hook omitido se ve exactamente igual que uno que dio su aprobación. Fija ambas versiones mínimas del SDK y conserva la capa de hooks de shell como el mecanismo de control que puedes demostrar.

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

Dos incorporaciones de las versiones v2.1.132 y v2.1.133 de Claude Code proporcionan a los hooks y subprocesos mejores señales sobre su contexto de ejecución:³⁸³⁹

• effort.level en la entrada del hook. Los hooks ahora reciben un campo effort.level de JSON en la misma entrada que contiene tool_input y session_id. El mismo valor se exporta como la variable de entorno $CLAUDE_EFFORT, para que los comandos Bash puedan leerlo sin analizar JSON. Úsalo para ajustar el costo del hook según el nivel de esfuerzo: omite las validaciones costosas en low y ejecuta el control de seguridad completo en xhigh o max.
• Variable de entorno CLAUDE_CODE_SESSION_ID en los subprocesos de Bash. Los subprocesos de la herramienta Bash ahora reciben el mismo valor de session_id que ven los hooks, expuesto como CLAUDE_CODE_SESSION_ID. Esto elimina la brecha de procedencia de las herramientas que registran el estado por sesión y que antes no podían correlacionar los eventos de subprocesos con los eventos de hooks.

Ambas señales están disponibles sin necesidad de cambiar el código; los hooks existentes que ignoren los campos nuevos seguirán funcionando.

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

La v2.1.136 de Claude Code agregó un nuevo nivel de denegación estricta al modo automático y corrigió un conjunto de problemas relacionados con plugins y MCP que afectaban a los harnesses de larga duración:⁴⁰ - settings.autoMode.hard_deny. Reglas del clasificador del modo automático que bloquean incondicionalmente, sin importar la intención del usuario ni las excepciones de autorización. Se ubica por encima de los comparadores de autorización y denegación existentes como un mecanismo de gobernanza no negociable. Úsalo para reglas que nunca deben anularse (force-push a main, archivos que contienen secretos, acceso a bases de datos de producción), incluso cuando un operador haya aprobado la categoría general en su configuración personal. - autoMode.classifyAllShell (v2.1.193). De forma predeterminada, el clasificador del modo automático solo revisa los comandos de shell que coinciden con patrones de ejecución de código arbitrario. Esta configuración envía todos los comandos de Bash/PowerShell al clasificador —la postura de cobertura máxima para un harness gobernado— y la misma versión muestra los motivos de denegación en la transcripción, la notificación emergente y /permissions, lo que convierte los bloqueos silenciosos en decisiones auditables. Codex reforzó la superficie equivalente en la versión v0.142.2: los comandos de PowerShell que contienen regiones AST ejecutables que su clasificador de seguridad no puede inspeccionar ahora requieren aprobación en lugar de permitirse silenciosamente.⁶⁶ - El ask del hook establece el límite inferior del clasificador (v2.1.211). La cuestión de precedencia entre los hooks y el modo automático ya está resuelta: un hook PreToolUse que devuelve una decisión de permiso ask establece como resultado final mínimo una solicitud de confirmación; el modo automático no puede volver a elevarlo a una autorización para comandos Bash ejecutados fuera del sandbox.⁶⁹ Para un harness gobernado, este es el nivel de garantía que faltaba: el ask de un hook es una detención determinista con intervención humana que se mantiene incluso con posturas de permisos completamente automáticas. Usa ask (no solo bloqueos con salida 2) para las operaciones en las que quieras una decisión humana en vez de una negativa. - El modelo del clasificador queda fijado por sesión (v2.1.210). El clasificador del modo automático usa Sonnet 5 de forma predeterminada y queda fijado durante la sesión, por lo que cambiar de modelo a mitad de sesión ya no altera cuál realiza las clasificaciones de permisos.⁶⁹ La coherencia de la clasificación es una propiedad de gobernanza; esto elimina una fuente discreta de desviación. - Los servidores MCP ya no desaparecen después de /clear. Los servidores configurados en .mcp.json, los plugins y los conectores de claude.ai desaparecían silenciosamente del conjunto activo después de ejecutar /clear en la extensión de VS Code, el plugin de JetBrains y Agent SDK. La corrección llegó en la versión v2.1.136. Si observaste que «el servidor MCP X desapareció a mitad de la sesión», esta era la causa. - Pérdida del token de actualización de OAuth de MCP durante actualizaciones simultáneas. Los usuarios con varios servidores MCP remotos ya no deberían tener que volver a autenticarse todos los días. Las escrituras simultáneas de las actualizaciones se sobrescribían entre sí. - El modo de planificación ahora bloquea correctamente la escritura de archivos. Una regla de autorización Edit(...) coincidente eludía la protección contra escritura del modo de planificación. Ahora este modo se aplica independientemente de las reglas de autorización. - Los hooks Stop y UserPromptSubmit de los plugins ya no fallan a mitad de la sesión. La limpieza de la caché eliminaba archivos de versiones de plugins que la sesión en curso todavía utilizaba, lo que afectaba específicamente a estos dos eventos de hook. La corrección mantiene fijadas las versiones en uso. - Entrada skills en plugin.json. Configurar skills ocultaba el directorio skills/ predeterminado del plugin. Ahora la entrada se combina correctamente, y dirigirla a la ruta de un archivo genera un error explícito en lugar de fallar silenciosamente. - Las variables de entorno de hooks SessionStart mediante CLAUDE_ENV_FILE quedaban obsoletas. Las variables exportadas por los hooks SessionStart mediante CLAUDE_ENV_FILE quedaban obsoletas después de /resume o /clear. Se corrigió en la versión v2.1.136. Ahora las sesiones vuelven a cargar el archivo de entorno cuando ocurren estos eventos.

Para los harnesses de gobernanza, los elementos de interés operativo son autoMode.hard_deny (un mecanismo nuevo) y la corrección de la desaparición de MCP (un fallo silencioso que interrumpía las sesiones largas). Todo lo demás son mejoras prácticas menores.

Argumentos estructurados de hooks y continuación después de un bloqueo (11 de mayo de 2026)

La versión v2.1.139 de Claude Code añadió dos detalles de hooks relevantes para los harnesses de producción: una forma de ejecución args: string[] para hooks de comandos y continueOnBlock para hooks PostToolUse.⁴²⁴⁴ Prefiere args cuando un hook necesite valores dinámicos o marcadores de posición de rutas. Ejecuta el comando directamente sin un shell, lo que elimina toda una clase de errores de uso de comillas e inyección.

Usa continueOnBlock cuando un hook PostToolUse deba devolverle a Claude el motivo de su rechazo y continuar el turno en lugar de finalizar el flujo. Considéralo una función para mejorar la experiencia del operador, no una forma de eludir la seguridad. Una puerta de control bloqueante debe seguir impidiendo el resultado inseguro.

La misma versión proporciona CLAUDE_PROJECT_DIR a los servidores stdio de MCP y permite que las configuraciones de plugins hagan referencia a ${CLAUDE_PROJECT_DIR} en los comandos.⁴² Las herramientas de MCP deben resolver las rutas relativas al proyecto a partir de ese valor, no del directorio de trabajo del proceso que haya iniciado el servidor. Las versiones de principios de julio de 2026 (v2.1.203–v2.1.206) extendieron el mismo principio al nivel del protocolo: roots/list de MCP ahora incluye los directorios de trabajo adicionales de la sesión y emite notificaciones roots/list_changed cuando cambian; así, un servidor que respete las raíces de MCP sigue la estructura real del espacio de trabajo con varios directorios en lugar de suponer que existe un único directorio de proyecto.⁶⁸

La versión v2.1.140 de Claude Code es, principalmente, una versión de confiabilidad para operadores de harnesses: corrige los hooks ConfigChange que no se ejecutaban al cambiar la configuración, resuelve casos extremos en los que disableAllHooks y allowManagedHooksOnly no se combinaban correctamente entre distintos niveles de configuración, y evita que los diálogos de permisos expongan variables de entorno no previstas devueltas por los resultados de los hooks.⁴⁹ Esto aumenta la confiabilidad de los patrones de gobernanza existentes en esta sección; no requiere una arquitectura de hooks nueva.

La versión v2.1.141 de Claude Code añade un campo terminalSequence a la salida de los hooks para emitir notificaciones de escritorio, cambiar títulos de ventanas y hacer sonar alertas sin una terminal controladora.⁵⁰ Considéralo un mecanismo de señalización para operadores, no de aplicación de políticas. Las puertas de seguridad y calidad deben seguir comunicando los fallos mediante el contrato de bloqueo habitual: una salida estructurada del hook junto con el comportamiento de salida que impide la acción insegura. La misma versión añade claude agents --cwd <path> para limitar Agent View a un directorio, CLAUDE_CODE_PLUGIN_PREFER_HTTPS para instalar plugins en entornos sin claves de GitHub SSH, y ANTHROPIC_WORKSPACE_ID para reglas de federación de identidades de carga de trabajo que abarquen más de un espacio de trabajo.⁵⁰ Estos son detalles arquitectónicos para harnesses de equipo: vistas operativas más acotadas, menos supuestos al instalar plugins y un alcance explícito de tokens empresariales.

La versión v2.1.142 de Claude Code es más importante para la orquestación de sesiones en segundo plano que para la semántica de los hooks.⁵¹ claude agents ahora puede despachar sesiones en segundo plano con indicadores explícitos de directorio, configuración, MCP, plugin, permisos, modelo y esfuerzo, en lugar de depender del estado de un wrapper. En esa versión, el modo rápido pasó a usar Opus 4.7 de forma predeterminada, con CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 como opción para fijar el modelo en un harness cuya dependencia del comportamiento de Opus 4.6 se haya medido; desde la versión v2.1.219, Opus 4.7 ya no forma parte del modo rápido y /fast se aplica a Opus 5 y Opus 4.8.⁸⁴ La detección de SKILL.md en la raíz de los plugins y la visibilidad de los LSP proporcionados por plugins reducen la ambigüedad del empaquetado. Las correcciones de MCP_TOOL_TIMEOUT, los worktrees preexistentes de sesiones en segundo plano, la suspensión y reactivación del daemon, la limpieza posterior a las actualizaciones y la limpieza de la caché de plugins resuelven problemas de confiabilidad que, de otro modo, parecerían errores de orquestación.

Orientación mediante hooks Stop, autoridad entre sesiones y multi-agent v2 (junio de 2026)

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

Los hooks Stop/SubagentStop incorporaron un canal de orientación. Desde la versión v2.1.163 de Claude Code, un hook Stop o SubagentStop puede devolver hookSpecificOutput.additionalContext para proporcionar comentarios a Claude y mantener el turno en curso, sin que la respuesta se etiquete como un error del hook. Antes, el único mecanismo real de un hook Stop era el bloqueo con salida 2, que se presenta como un error y cuenta para el límite de bloqueos consecutivos. Para un harness con puertas de calidad, esta es una primitiva más limpia: un hook Stop que detecte «dijiste que habías terminado, pero las pruebas fallan» ahora puede inyectar «esto es lo que todavía falla; continúa» en vez de imponer un bloqueo estricto. Usa el bloqueo para condiciones que realmente deban detener la ejecución y additionalContext para indicar «todavía no has terminado; este es el motivo».

Los mensajes entre sesiones ya no transfieren autoridad prestada. La versión v2.1.166 reforzó el caso de varias sesiones: los mensajes retransmitidos mediante SendMessage desde otra sesión de Claude ya no transfieren la autoridad del usuario de origen, por lo que la sesión receptora rechaza las solicitudes de permisos retransmitidas y el modo automático las bloquea. Si tu orquestación permite que los agentes se envíen mensajes entre sí, considera cada 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 las herramientas, extendido a la comunicación entre agentes. Desde la versión v2.1.199, Claude Code también detecta y advierte cuando un SendMessage se dirige de forma incorrecta porque dos agentes comparten el mismo nombre; es un complemento de confiabilidad para este límite de autoridad, ya que un mensaje recibido por el agente equivocado con el mismo nombre constituye una categoría propia de error de orquestación. La resiliencia del modelo se convirtió en una configuración de primer nivel. La configuración fallbackModel ahora encadena hasta tres modelos de respaldo, que se prueban en orden cuando el principal está sobrecargado o no está disponible, y cada turno vuelve a intentarse automáticamente una vez con el modelo alternativo ante errores inesperados y no reintentables de API. Para un harness autónomo de larga ejecución, esto convierte una interrupción transitoria del modelo principal en una degradación controlada, en lugar de una ejecución perdida. claude agents --json también incorporó un campo waitingFor (v2.1.162) que muestra qué está esperando una sesión en segundo plano bloqueada, como una solicitud de permiso, lo que mejora la observabilidad de cualquier coordinador que sondee una flota de agentes.

Modo seguro para gobernanza en un entorno aislado y resolución de problemas. Claude Code v2.1.169 incorpora la opción --safe-mode (y la variable de entorno correspondiente CLAUDE_CODE_SAFE_MODE), que inicia una sesión con todas las personalizaciones deshabilitadas a la vez: CLAUDE.md, plugins, skills, hooks y servidores MCP.⁶⁰ Es lo opuesto al harness: un entorno aislado deliberado. Úsalo para responder la pregunta que todo operador termina haciéndose: «¿Este comportamiento proviene del modelo o de algo que configuré?». Cuando un hook se activa de forma incorrecta, una skill se activa cuando no debería o un servidor MCP contamina el contexto, --safe-mode te ofrece una referencia conocida y vacía con la cual comparar. También funciona como un mecanismo básico de gobernanza: una forma de ejecutar el modelo sin ninguna de las facultades persistentes que normalmente le concede tu harness, algo importante cuando necesitas reproducir un resultado sin que influya ninguna estructura definida por el operador.

Una nota sobre los niveles de modelos. Desde Claude Code v2.1.197 (30 de junio de 2026), Claude Sonnet 5 es el modelo predeterminado incluido para las sesiones nuevas —contexto nativo de 1M, precio promocional de $2/$10 por MTok hasta el 31 de agosto— y reemplaza a Opus 4.8 como opción inicial. Esta guía considera Opus 5 (claude-opus-5) el modelo agentic predeterminado recomendado: el modelo con el que conviene ejecutar harnesses autónomos, salvo que elijas deliberadamente otro, porque los bucles de agentes prolongados y de alto impacto son precisamente donde la profundidad de razonamiento de Opus justifica su costo. Opus 5 se lanzó el 24 de julio de 2026 como el nuevo Opus predeterminado en Claude Code v2.1.219 —contexto de 1M, $5/$25 por MTok (el mismo precio que Opus 4.8, al que reemplaza) y modo rápido a $10/$50 con aproximadamente 2,5 veces la velocidad predeterminada—, y Anthropic informa que supera por más del doble a Opus 4.8 en Frontier-Bench v0.1, mientras queda a menos de un 0,5 % de la puntuación de Fable 5 en CursorBench 3.2 por la mitad del costo.⁸⁴⁸⁷ El mismo precio, más capacidad y un modelo que Anthropic describe como «mucho más sólido al verificar su trabajo e iterar con cuidado» constituyen esa rara mejora que no necesita justificarse por costos para el trabajo con harnesses; migrar desde 4.8 solo requiere cambiar el identificador. Cambia a Sonnet 5 para trabajos sensibles al costo o de alto volumen donde destaque su relación entre velocidad e inteligencia. Por encima de Opus se encuentra Claude Fable 5 (claude-fable-5), lanzado el 9 de junio de 2026: un nuevo nivel que se presenta como el modelo más potente de Anthropic, un sistema «Mythos-class» adaptado para un uso general seguro y seleccionable en Claude Code v2.1.170 mediante /model claude-fable-5.⁶⁰ Recurre deliberadamente al nivel superior para aquellas decisiones en las que la profundidad bruta de razonamiento justifique el costo, no como configuración general para toda una flota. La transición a Opus 5 tiene dos consecuencias de mantenimiento: Opus 4.7 deja de admitir el modo rápido (/fast ahora se aplica a Opus 5 y Opus 4.8), y la alternativa Fable-5 del clasificador del modo automático —«el mejor modelo Opus disponible» desde v2.1.176— ahora se resuelve como Opus 5.⁸⁴

Codex lanzó multi-agent v2. Codex CLI v0.137.0 mantiene la elección del entorno de ejecución en cada hilo, ofrece valores predeterminados más claros para el seguimiento y los metadatos de los agentes generados (hide_spawn_agent_metadata ahora es true de forma predeterminada) y propaga los eventos sin procesar del agente principal a los listeners secundarios. Su modelo de subagents sigue siendo explícito: tipos de agentes integrados default/worker/explorer, agentes personalizados definidos mediante TOML y controles de concurrencia (agents.max_threads con valor predeterminado 6 y agents.max_depth con valor predeterminado 1). La misma versión incorpora una extensión v1 de skills con resolución del catálogo de skills en cada turno y nuevos eventos de colaboradores del ciclo de vida para el inicio de hilos y los errores de turno, lo que reduce la brecha con la superficie de hooks y skills de Claude Code, al tiempo que mantiene como límite predeterminado la postura de aislamiento del kernel. Después, Codex v0.138.0–v0.139.0 reforzó multi-agent v2 para producción: las cargas útiles de los mensajes entre agentes ahora están cifradas, un catálogo v2 de configuración de agentes junto con una caché LRU de residencia administra qué agentes permanecen residentes, y la concurrencia se contabiliza según la ejecución activa, no según los hilos generados, por lo que los agentes inactivos ya no ocupan un espacio.⁶¹ El ciclo de vida de API también maduró: close_agent pasó a llamarse interrupt_agent (v0.139.0) para reflejar que interrumpe un agente en ejecución, en lugar de limitarse a cerrar un identificador; además, las advertencias de inicio de MCP generadas por un subagent ahora quedan restringidas al hilo propietario, en vez de duplicarse en la transcripción del agente principal.⁶¹ Para quienes desarrollan orquestación con Codex, estas son las diferencias entre una demostración y una flota: transporte cifrado de mensajes, residencia limitada, concurrencia contabilizada por ejecución y advertencias que no atraviesan los límites del hilo. Codex v0.140.0 abrió entonces un punto de integración entre herramientas: /import incorpora de forma selectiva la configuración inicial, la configuración del proyecto y los chats recientes de Claude Code en Codex, y las sesiones ahora pueden eliminarse permanentemente (codex delete / /delete, con medidas de confirmación).⁶⁴ /import es el primer reconocimiento oficial de que los operadores alternan entre harnesses: la configuración que creas para uno ya no queda atrapada allí.

Memoria y contexto

Toda conversación con IA opera dentro de una ventana de contexto finita. A medida que la conversación crece, el sistema comprime los turnos anteriores para dejar espacio al contenido nuevo. Esta compresión implica pérdida de información. Es posible que las decisiones de arquitectura documentadas en el turno 3 no sobrevivan hasta el turno 15.⁹

Los tres mecanismos del colapso en múltiples turnos

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

Estrategia 1: el sistema de archivos como memoria

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

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

El archivo MEMORY.md registra 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 números enteros en Python, la entrada de MEMORY.md vuelve a mostrar ese 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 independientes para las notas detalladas.⁶ A partir de la versión v2.1.210, una escritura en MEMORY.md que supera el límite de tamaño genera un error en lugar de truncarse silenciosamente⁶⁹: la falla se manifiesta al escribir, en vez de provocar que algunas entradas de memoria desaparezcan sin aviso. Si tu harness automatiza las escrituras en memoria, controla ese error; la plataforma te está indicando que el archivo necesita depuración, no otro intento.

Depuración de la memoria por encima de su volumen (mayo de 2026): Un preprint reciente de arXiv sobre la cooperación entre agentes LLM plantea que ampliar la información recuperada puede convertirse en un modo de falla: en los experimentos de los autores, un historial visible más extenso perjudicó la cooperación en 18 de 28 configuraciones de juegos entre modelos.⁴⁸ Tómalo como una advertencia de diseño, no como una ley definitiva. La regla para producción ya es bastante clara: mantén MEMORY.md breve, enlaza los detalles y coloca resúmenes que permitan tomar decisiones en los documentos de traspaso. Los volcados de transcripciones sin procesar, los registros de herramientas y los extensos flujos de información recuperada deben estar en un almacenamiento donde puedan buscarse, no incorporarse automáticamente al prompt activo.

Estrategia 2: compactación proactiva

El comando /compact de Claude Code resume la conversación y libera espacio de contexto, a la vez que conserva las decisiones clave, el contenido de los archivos y el estado de la tarea.¹⁵

Cuándo compactar: - Después de completar una subtarea independiente (función implementada, error corregido) - Antes de comenzar a trabajar en una nueva área del código base - Cuando Claude empieza a repetirse o a olvidar el contexto anterior - Aproximadamente cada 25-30 minutos durante sesiones intensivas

Instrucciones personalizadas de compactación en CLAUDE.md:

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

La compactación protege la conversación; el comando /cd (Claude Code v2.1.169) protege la caché del prompt. Permite trasladar una sesión a un nuevo directorio de trabajo mientras está en curso, sin afectar la caché acumulada durante el turno.⁶⁰ Antes, cambiar de directorio implicaba iniciar una sesión nueva con la caché vacía. En una sesión prolongada que pasa de un repositorio a otro relacionado —algo habitual al trabajar con monorepos y múltiples servicios—, /cd conserva intacto el costoso prefijo almacenado en caché mientras redirige el contexto del sistema de archivos.

Estrategia 3: traspasos entre sesiones

Para las tareas que abarcan varias sesiones, crea documentos de traspaso que registren el estado completo:

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

La estructura Status/Files/Decision/Blocked/Next proporciona a la sesión sucesora todo el contexto con un costo mínimo de tokens. Al iniciar una nueva sesión con claude -c (continuar) o leer el documento de traspaso, puedes pasar directamente a la implementación.¹⁵

Estrategia 4: iteración con contexto nuevo (el Ralph loop)

Para sesiones que superan los 60-90 minutos, inicia una instancia nueva de Claude en cada iteración. El estado persiste mediante el sistema de archivos, no mediante la memoria de la conversación. Cada iteración recibe el presupuesto completo de contexto:¹⁶

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

Compáralo con una sola sesión prolongada:

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

El enfoque de usar un contexto nuevo en cada iteración intercambia una sobrecarga del 15-20 % en el paso de orientación (leer los archivos de estado y revisar el historial de git) por disponer de todos los recursos cognitivos en cada iteración.¹⁶ El cálculo de costo-beneficio es el siguiente: para sesiones de menos de 60 minutos, una sola conversación resulta más eficiente. Después de 90 minutos, trabajar con un contexto nuevo genera resultados de mayor calidad a pesar de la sobrecarga.

Estrategia 5: depuración administrada de la memoria (Dreaming)

Los Claude Managed Agents de Anthropic incorporaron Dreaming como Research Preview el 6 de mayo de 2026.³⁵ Según Anthropic: «Dreaming es un proceso programado que revisa las sesiones y los almacenes de memoria de tus agentes, extrae patrones y depura los recuerdos para que tus agentes mejoren con el tiempo».³⁵

Dreaming se ejecuta en segundo plano entre sesiones, no en la ruta crítica. Complementa el patrón del sistema de archivos como memoria en lugar de sustituirlo: tu archivo MEMORY.md sigue siendo la superficie fundamental; Dreaming escribe entradas de memoria depuradas en el almacén de memoria de Managed Agents, que el agente lee al inicio de la sesión. Ambos patrones coexisten en los harnesses que combinan el estado del sistema de archivos alojado por cuenta propia con la depuración administrada.

Dreaming está en Research Preview, por lo que su comportamiento puede cambiar. Los patrones de traspaso entre sesiones y CLAUDE.md documentados anteriormente siguen siendo el mecanismo de memoria de referencia para los harnesses alojados por cuenta propia.

Los antipatrones

Leer archivos completos cuando solo necesitas 10 líneas. Leer un único 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 resultados de error detallados en el contexto. Después de depurar un error, el contexto puede contener más de 40 stack traces de intentos fallidos. Ejecutar /compact una sola vez tras corregirlo elimina ese peso muerto.

Comenzar cada sesión leyendo todos los archivos. Deja que las herramientas glob y grep de Claude Code encuentren los archivos relevantes cuando sean necesarios; así evitarás precargar innecesariamente más de 100.000 tokens.¹⁵

Patrones de subagents

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

Tipos de subagents integrados

Creación de subagents personalizados

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Campos de configuración de subagents

Aislamiento mediante worktree

Los subagents pueden operar en worktrees temporales de git, 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 mediante worktree es esencial para el trabajo experimental que podría dañar la base de código.

El aislamiento solo es aislamiento si se mantiene. Claude Code v2.1.210 corrigió un error que permitía que los subagents aislados mediante worktree modificaran el checkout principal, exactamente el fallo que este mecanismo existe para evitar.⁶⁹ Si dependes de isolation: worktree como límite de seguridad y no solo como una comodidad, considera v2.1.210 como la versión mínima. El cambio complementario en los permisos va en la dirección contraria: desde v2.1.211, las reglas de “permitir siempre” persisten en la raíz del repositorio entre worktrees, por lo que una regla aceptada dentro de un worktree se aplica a los worktrees hermanos del mismo repositorio.⁶⁹ Esta es la ergonomía adecuada para agentes que trabajan en paralelo mediante worktrees, pero significa que un permiso concedido durante un experimento desechable perdura más allá del experimento; concédelo pensando en todo el repositorio, no solo en el worktree que tienes delante.

v2.1.216 terminó el trabajo y llevó el aislamiento mediante worktree de una simple corrección de errores a un mecanismo con garantías estrictas.⁷⁴ La corrección de v2.1.210 impidió que los subagents en worktrees modificaran el checkout principal mediante invocaciones normales de git, pero el propio git ofrece redirecciones explícitas —git -C <path>, --git-dir y las variables de entorno GIT_DIR/GIT_WORK_TREE—, y un subagent aislado mediante worktree todavía podía dirigir cualquiera de ellas al checkout compartido. Ahora todas esas vías de escape están cerradas. La misma versión corrigió que las sesiones de worktree terminaran ocasionalmente en un worktree residual de otro proyecto, impidió que las escrituras de workflows y tareas programadas siguieran un enlace simbólico colocado en .claude hacia un destino externo al proyecto e hizo que /rewind se negara a atravesar enlaces simbólicos y enlaces físicos. El patrón en las cuatro correcciones es el mismo: un límite de aislamiento debe resistir la redirección deliberada —anulaciones mediante el entorno de git, colocación de enlaces simbólicos—, no solo el comportamiento predeterminado. Si isolation: worktree es un límite de seguridad en tu harness y no una comodidad, v2.1.216 es la nueva versión mínima.

Subagents en paralelo

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

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

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

El recursion guard

Sin límites de creación, los agentes delegan en agentes que, a su vez, delegan en otros agentes; 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 fundamental: Usa presupuestos de creación, no solo límites de profundidad. Los límites basados en profundidad rastrean las cadenas entre padres e hijos (bloqueadas al alcanzar una profundidad de 3), pero no controlan la amplitud: 23 agentes con profundidad 1 siguen estando en una “profundidad de 1”. Un presupuesto de creación rastrea el total de hijos activos por cada padre y lo limita a un máximo configurable. El modelo presupuestario corresponde al modo de fallo real (demasiados agentes en total), en lugar de usar una métrica indirecta (demasiados niveles de anidamiento).⁷

El valor predeterminado de profundidad de anidamiento ha cambiado tres veces; no construyas sobre él. Claude Code v2.1.172 (10 de junio de 2026) permitió que los sub-agents crearan sus propios sub-agents, con hasta 5 niveles de anidamiento, cuando antes la delegación se limitaba, en la práctica, a un solo nivel.⁶² Esto se mantuvo desde v2.1.172 hasta v2.1.216. v2.1.217 (21 de julio de 2026) redujo el valor a 1 y desactivó de forma predeterminada la creación anidada. Después, v2.1.219 (24 de julio de 2026) encontró un punto intermedio: “Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting.”⁸⁴ Cinco, luego uno y después tres; los últimos dos cambios ocurrieron en un plazo de tres días.

La interpretación útil no es que alguno de esos números sea el correcto, sino que la plataforma todavía está buscando el valor predeterminado adecuado, por lo que “lo que venga de fábrica” es precisamente lo que un harness no debería heredar. Trata la profundidad de anidamiento como una partida presupuestaria explícita: establece CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH según la profundidad que realmente necesite tu arquitectura —para la mayoría de las orquestaciones será 1 o 2—, de modo que una actualización no pueda cambiar silenciosamente hasta dónde delega tu flota. El argumento central no cambia con esta inestabilidad: las cadenas de agentes que delegan en otros agentes consumen contexto y tokens más rápido de lo que producen resultados, y la profundidad es un riesgo que debes presupuestar, no una capacidad que debas intentar aprovechar. El recursion guard anterior evita que un árbol profundo se despliegue en cientos de agentes activos, sin importar hacia dónde cambie después el valor predeterminado; además, un límite que establezcas tú mismo es el único valor de profundidad que seguirá significando lo que crees después de la próxima versión.

Ahora el modo automático evalúa las creaciones antes de iniciarlas. Claude Code v2.1.178 cerró la brecha de gobernanza correspondiente: en el modo automático, el clasificador de permisos evalúa la creación de subagents antes de que se inicien, no solo cuando comienzan a realizar acciones.⁶³ Antes se podía crear un subagent para solicitar una acción que la sesión principal no habría podido realizar; la creación en sí era el mecanismo de evasión. La evaluación en el momento de la creación hace que el recursion guard y el modelo de permisos finalmente converjan: no se puede usar un hijo para encubrir una acción que la política prohíbe.

La plataforma ahora incluye un presupuesto de creación nativo. Claude Code v2.1.212 (julio de 2026) incorporó protecciones propias contra bucles descontrolados: las sesiones tienen un límite predeterminado de 200 creaciones de subagents (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION permite ajustarlo y /clear reinicia el contador), mientras que WebSearch tiene un límite de 200 llamadas por sesión (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ El patrón de presupuesto de creación que esta sección documenta como scripting de usuario desde v1.0 ahora está integrado en la plataforma, lo que valida el modelo basado en presupuestos frente al modelo basado en profundidad. Pero ten en cuenta la calibración: 200 creaciones son un orden de magnitud superior al presupuesto de 12 agentes de la configuración anterior. Los límites nativos son fusibles contra un bucle verdaderamente descontrolado, no presupuestos adaptados a tu arquitectura. Conserva el mecanismo de protección de usuario para presupuestos por padre, seguimiento de profundidad y límites que reflejen lo que tu orquestación debería hacer en realidad; deja que el límite de la plataforma atrape lo que consiga superarlo.

El conjunto de protecciones propias ahora abarca cuatro ejes. Tres respaldan exactamente lo que rastrea el mecanismo de protección de usuario de esta sección: creaciones totales por sesión (v2.1.212, límite de 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), profundidad de anidamiento (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, cuyo valor predeterminado actual es 3 y ha demostrado ser inestable) y ejecución concurrente (v2.1.217, valor predeterminado de 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS; un mensaje ya no puede desplegar sin límites agentes en segundo plano).⁷⁸⁸⁴ v2.1.219 añade un cuarto eje que los mecanismos de protección de usuario generalmente no tenían: la amplitud de la orquestación, es decir, la cantidad de agentes que puede contener un único workflow planificado, distribuida como una pauta predeterminada de “aspira a usar menos de 15 agentes” y configurable desde cualquier archivo de configuración mediante workflowSizeGuideline (se explica en la sección sobre la herramienta Workflow más adelante). El patrón de presupuesto de creación ahora cuenta con respaldo en todos los ejes para los que fue diseñado, más uno que no contemplaba.

La observación sobre la calibración sigue vigente, aunque de manera desigual. Las 200 creaciones y los 20 agentes concurrentes son fusibles: un orden de magnitud por encima del presupuesto de deliberación de 12 agentes de la configuración anterior, dimensionados para detectar un bucle descontrolado en vez de definir una arquitectura. La pauta de amplitud es el primer valor nativo que opera en la misma escala que un presupuesto real: 15 agentes por workflow está justo al lado de los 12 de esta guía, lo bastante cerca como para que adoptar el valor predeterminado de la plataforma no te cueste nada y discrepar de él exija una razón concreta. Ajusta los tres fusibles a valores que puedas defender; ajusta la pauta de amplitud a la forma de la orquestación que querías construir.

Agent Teams (versión preliminar de investigación)

Agent Teams coordina varias instancias de Claude Code que trabajan de forma independiente, se comunican mediante un Mailbox 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 y cuándo usar subagents:

Agent View y bucles de objetivos (mayo de 2026)

Claude Code v2.1.139 añadió Agent View, una interfaz en versión preliminar de investigación que se inicia con claude agents y muestra en una sola pantalla las 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 ofrece al trabajo multiagente una vista operativa que los resúmenes finales no pueden proporcionar.

Usa Agent View cuando implementes formalmente un patrón de subagents o de equipo: inspecciona qué sesiones están bloqueadas, cuáles siguen en ejecución y si la distribución del trabajo coincide con la arquitectura prevista. No lo consideres una prueba de calidad. Ofrece observabilidad; las pruebas, los review gates y los informes de evidencia siguen determinando si el trabajo es sólido.

La misma versión añadió /goal, que establece una condición de finalización y permite que Claude continúe durante varios turnos hasta cumplirla, incluso en usos interactivos, con -p y mediante Remote Control.⁴² Trata /goal como un bucle de finalización limitado a la sesión, no como sustituto de gates deterministas. Resulta útil para mantener al agente enfocado en un objetivo, pero las pruebas, las comprobaciones de citas y despliegues, y los hooks de seguridad deben seguir respaldados por comandos o scripts cuando un fallo tenga que bloquear el proceso.

Herramienta Workflow (v2.1.147+)

Claude Code v2.1.147 añade una herramienta Workflow, desactivada de forma predeterminada, para la orquestación multiagente determinista. Habilítala con CLAUDE_CODE_WORKFLOWS=1.⁵² Esto es importante desde el punto de vista arquitectónico porque proporciona a Claude Code una primitiva propia de orquestación para flujos que antes requerían scripts de despacho personalizados, estado en 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. Conserva los hooks PreToolUse y PostToolUse como capa de bloqueo, mantén presupuestos de creación o presupuestos de pasos del workflow para evitar una amplitud descontrolada, conserva un estado auditable del sistema de archivos y mantén los informes finales de evidencia fuera de la autoevaluación del modelo. En la práctica: usa Workflow para definir la forma de la orquestación; usa hooks, pruebas y review gates para determinar la verdad.

Ahora los workflows dinámicos incorporan una postura sobre la amplitud (v2.1.219). Los workflows dinámicos usan de manera predeterminada una pauta de tamaño mediano —“aspira a usar menos de 15 agentes”—, con otros tamaños y una opción sin restricciones disponibles en Dynamic workflow size dentro de /config; además, la pauta actual aparece en la línea de estado del workflow en ejecución.⁸⁴ El número es orientativo, no obligatorio: guía al planificador en lugar de bloquear un plan amplio. Lo que hace que valga la pena configurarlo es el mecanismo de distribución: la nueva clave de configuración workflowSizeGuideline puede establecerse desde cualquier archivo de configuración —incluidos los ajustes administrados y los del proyecto—, y está incluida en los tipos de configuración de TypeScript SDK desde v0.3.219, por lo que la amplitud de la orquestación puede convertirse en algo que un equipo o una organización estandaricen, en lugar de algo que cada operador tenga que redescubrir.⁸⁵ Establécela a nivel de proyecto para codificar cómo se descompone realmente el trabajo de tu base de código. Dos observaciones para el operador: la fila de /config se oculta cuando un archivo de configuración controla el valor, lo cual es el comportamiento correcto, pero parece indicar que falta un ajuste si no sabes el motivo; además, como la pauta guía al planificador en vez de controlar la ejecución, pertenece a la columna de forma, no a la de seguridad. El límite de creaciones sigue siendo el encargado de contener una amplitud descontrolada.

Conviene conservar la idea de que este es un cuarto eje de protección propio: la amplitud de la orquestación, junto con la cantidad de creaciones, la profundidad de anidamiento y la ejecución concurrente; además, es el primero que Anthropic ha calibrado con un tamaño de trabajo plausible en vez de como fusible contra un descontrol. Quince agentes por workflow está en el mismo orden de magnitud que el presupuesto de deliberación de 12 agentes que esta guía utiliza desde v1.0. Cuando el valor predeterminado de la plataforma y tu propio presupuesto convergen desde direcciones opuestas, eso es lo más cercano a una corroboración independiente que pueden alcanzar estas cifras.

Bifurcación de sesiones y MCP en segundo plano automático (julio de 2026)

Claude Code v2.1.212 reformuló dos primitivas de orquestación.⁶⁹ Ahora /fork crea una nueva sesión en segundo plano a partir del estado actual de la conversación: la línea bifurcada se ejecuta de manera independiente mientras la original sigue trabajando, y el comportamiento anterior dentro de la sesión pasó a llamarse /subtask. La distinción es importante para el diseño de la orquestación: /subtask es un desvío acotado dentro del ciclo de vida de una sesión; /fork es una forma económica de crear una sesión paralela en segundo plano que hereda todo el contexto, más parecida a la creación de un bucle Ralph que a un subagent. Si los scripts de tu harness suponían que /fork permanecía dentro de la sesión, ahora despacharán trabajo en segundo plano.

La misma versión envía automáticamente a segundo plano las llamadas lentas a MCP: una llamada a una herramienta MCP que dure más de dos minutos se traslada automáticamente a una ejecución en segundo plano (ajusta el umbral con CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Un servidor MCP lento ya no detiene el bucle agéntico, pero esto también significa que “la herramienta respondió” y “el turno continuó” ya no son el mismo evento; por lo tanto, los hooks o scripts que daban por supuesta la finalización síncrona de MCP deben basarse en el resultado de la herramienta, no en el límite del turno.

Para la orquestación sin interfaz, v2.1.211 añadió --forward-subagent-text (variable de entorno: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), que reenvía el texto del asistente del subagent a la salida de stream-json.⁶⁹ Ahora, un proceso coordinador que consume el flujo del agente principal puede observar directamente el progreso de los subagents, en vez de consultar las transcripciones o esperar el resumen final: el complemento de observabilidad para los subagents que se ejecutan en segundo plano de forma predeterminada. v2.1.219 lo amplió más allá del primer nivel: los subagents creados a una profundidad de 2 o mayor ahora también aparecen en el flujo reenviado, identificados mediante el id de tool_use del Agent que los creó.⁸⁴ Esa clave es la base sobre la que debes construir. Con el anidamiento nuevamente activado de forma predeterminada, un flujo plano de texto de subagents resulta ambiguo: el id le indica al coordinador qué padre produjo cada hijo, de modo que el árbol de delegación pueda reconstruirse a partir del flujo en vez de inferirse. Si tu consumidor del flujo se diseñó para un solo nivel de subagents, ahora verá texto de agentes cuya existencia desconocía; agrupa por el id de tool_use que originó la creación, en lugar de asumir que cada línea reenviada pertenece a un hijo directo.

Orquestación multiagente

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

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

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

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

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

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

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

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

Deliberación mínima viable

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

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

Este patrón cubre el 80% del valor. Todo lo demás aporta una mejora incremental.

El disparador de confianza

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

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

La puntuación se asigna a tres niveles:

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

La máquina de estados

Siete fases, cada una bloqueada por la anterior:⁷

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

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

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

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

La arquitectura de validación de dos puertas

Dos puertas de validación capturan problemas en distintas etapas:⁷

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

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

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

Por qué el acuerdo es peligroso

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

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

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

Detección de acuerdo falso

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

Agrupación de puntajes: Que cada agente puntúe dentro de 0,3 puntos en una escala de 10 señala contaminación de contexto compartido en lugar de evaluación independiente. Cuando cinco agentes que evaluaban una refactorización de autenticación puntuaron el riesgo de seguridad entre 7,1 y 7,4, al volver a ejecutarlo con aislamiento de contexto fresco los puntajes se dispersaron a 5,8-8,9.

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

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

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

Lo que no funcionó en la deliberación

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

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

El costo de la deliberación

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

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

Cuándo deliberar

Diseño de CLAUDE.md

CLAUDE.md es una política operativa para un agente de IA, no un README para humanos.²¹ El agente no necesita entender por qué usas commits convencionales. Necesita conocer el comando exacto que debe ejecutar y cómo se define que una tarea está “terminada”.

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 ningún cambio observable en el comportamiento del agente de manera consistente:²¹

Párrafos de texto sin comandos. “Valoramos el código limpio y bien probado” es documentación, no una instrucción operativa. El agente lo lee y procede a escribir código sin pruebas porque no hay ninguna instrucción que pueda ejecutar.

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

Prioridades contradictorias. “Avanza rápido y publica cuanto antes”, además de “Garantiza una cobertura de pruebas completa”, “Mantén el tiempo de ejecución por debajo de 5 minutos” y “Ejecuta todas las pruebas de integración antes de cada commit”. El agente no puede cumplir las cuatro condiciones a la vez, por lo que termina omitiendo la verificación.²¹

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

Qué funciona

Instrucciones que comienzan con 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 redacción

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

1. Comandos de compilación y pruebas (el agente los necesita antes de poder hacer algo útil)
2. Definición de terminado (evita falsos cierres)
3. Reglas de escalamiento (evitan soluciones alternativas destructivas)
4. Secciones organizadas por tarea (reducen el procesamiento de instrucciones irrelevantes)
5. Delimitación por directorios (en monorepos, mantiene aisladas las instrucciones de cada servicio)

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

La plataforma ahora audita tu CLAUDE.md por ti. Desde las versiones de principios de julio de 2026 (v2.1.203–v2.1.206), /doctor analiza CLAUDE.md y propone recortar el contenido que el modelo puede deducir por sí mismo del código base: estructuras de directorios repetidas, convenciones del framework que el código ya refleja y listas de comandos que duplican los scripts de los paquetes.⁶⁸ Esta es una confirmación directa del planteamiento de esta sección: las instrucciones justifican los tokens que consumen cuando codifican aquello que el agente no puede inferir —políticas, umbrales y definiciones de cierre—, no lo que puede leer del disco. Ejecuta /doctor después de un crecimiento considerable de CLAUDE.md y toma sus propuestas de recorte como punto de partida; aun así, conserva las reglas operativas que pueda marcar como “deducibles” si son restricciones esenciales y no simples descripciones.

Importaciones de archivos

Haz referencia a otros archivos desde 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 desde el directorio personal (@~/.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 herramientas principales de programación con IA.²¹ Si tu equipo utiliza varias herramientas, adopta AGENTS.md como fuente canónica y replica las secciones pertinentes en los archivos específicos de cada herramienta:

Los patrones de AGENTS.md —comandos primero, cierre definido y organización por tareas— funcionan en cualquier archivo de instrucciones, sin importar la herramienta. No mantengas conjuntos paralelos de instrucciones que terminen divergiendo. Escribe una única fuente autoritativa y replícala.

Notas sobre la paridad con Codex

Codex ya cuenta con equivalentes nativos para las principales capas del harness, pero migrar exige traducir patrones, no copiar archivos. Codex lee AGENTS.md antes de comenzar a trabajar y combina las directrices globales de ~/.codex con las instrucciones del proyecto y las de los repositorios anidados.³¹ Los skills de Codex utilizan el mismo modelo mental de SKILL.md con divulgación progresiva: Codex comienza con el nombre, la descripción y la ruta del archivo del skill; después carga el skill completo solo cuando decide utilizarlo.³² Codex también ofrece hooks nativos, hooks incluidos en plugins, hooks administrados, compatibilidad con MCP y flujos de trabajo explícitos con subagents.³³³⁴

Codex v0.138.0–v0.139.0 reforzó ese proceso de detección de AGENTS.md en espacios de trabajo no triviales: la carga ahora se realiza mediante la abstracción del sistema de archivos del entorno y conserva las rutas lógicas durante el recorrido de detección, por lo que selecciona el archivo correcto incluso cuando el espacio de trabajo se encuentra en un sistema de archivos remoto o en un árbol con enlaces simbólicos.⁶¹ Esto es importante siempre que tu AGENTS.md canónico sea la fuente autoritativa y el agente opere sobre un repositorio montado, materializado en un contenedor o enlazado simbólicamente: casos en los que un recorrido ingenuo de las rutas selecciona silenciosamente el archivo de instrucciones equivocado o no selecciona ninguno. Si replicas un único AGENTS.md autoritativo entre distintos servicios, considera esta versión como el mínimo necesario para confiar en que el archivo que el agente cargó realmente sea el que escribiste.

Codex v0.141.0 reforzó después la propia 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 que los conecta), 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 controla ejecutores de Codex a través de un límite de red, esto marca la diferencia entre asumir que el relay es confiable y disponer de cifrado de extremo a extremo; considéralo el punto de partida para cualquier topología de ejecutores remotos.

Las versiones de julio de 2026 muestran cómo los dos entornos de ejecución convergen en los mismos componentes fundamentales desde direcciones opuestas.⁷² Codex v0.143.0 hace que las herramientas MCP se carguen mediante búsqueda de herramientas de forma predeterminada: los esquemas de las herramientas se posponen y se recuperan bajo demanda, en lugar de cargarse de antemano en el contexto. Es el mismo patrón de carga diferida de herramientas que Claude Code ofrece mediante su interfaz ToolSearch, y la solución adecuada en ambos entornos ante la saturación del contexto cuando existe un gran número de herramientas MCP. Codex v0.144.0 agrega un modo de aprobación de aplicaciones writes: las acciones de solo lectura se ejecutan sin solicitar confirmación, mientras que las escrituras requieren aprobación. Es un componente de permisos realmente nuevo, situado entre el modo de solo lectura y la aprobación automática, que la lista de modos de Claude Code no expresa directamente (su equivalente más cercano es el modo plan, que bloquea por completo las escrituras en vez de solicitar aprobación para cada una). La misma versión lleva la autenticación interactiva de MCP a disponibilidad general. Además, v0.144.5 amplía la detección de comandos peligrosos y refleja las protecciones contra comandos destructivos que Claude Code incorporó en v2.1.183 y v2.1.208. Para diseñar un harness que funcione en distintos entornos de ejecución, la convergencia es lo importante: la carga diferida de herramientas, la aprobación gradual de escrituras y el bloqueo de comandos peligrosos según su intención se están convirtiendo en requisitos básicos, no en elementos diferenciadores entre proveedores.

Codex v0.145.0 profundiza la convergencia en dos frentes.⁷⁶ La interfaz opcional multi-agent V2 se estabilizó: ahora se pueden configurar los modelos de los sub-agents, los niveles de razonamiento y la concurrencia, y se restauraron los roles de agentes que se habían eliminado anteriormente. Esta es la respuesta de Codex a la configuración del modelo y el nivel de esfuerzo de cada subagent en el frontmatter de .claude/agents/. Además, /import evolucionó hasta ofrecer una migración completa entre distintos harnesses: más allá de la importación de la configuración de Claude Code incorporada en v0.140.0, ahora migra la configuración tanto de Claude Code como de Cursor, incluidos servidores MCP, plugins, sesiones, comandos y memorias específicas del proyecto. Para los equipos que utilizan ambos entornos, el costo de migración entre ellos continúa disminuyendo en una dirección; las capas del harness que construyas sobre Claude Code —servidores, skills como comandos y memoria— son cada vez más un estado portátil en vez de una dependencia exclusiva de un proveedor.

La correspondencia práctica:

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 subagents como explícitos. Esto hace que los skills y hooks sean la opción predeterminada adecuada para el comportamiento permanente del harness en Codex; los subagents quedan reservados para trabajos paralelos deliberados, revisiones y exploración.

Cómo 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 de fuego: Pídele al agente que explique tus comandos de compilación. Si no puede reproducirlos literalmente, las instrucciones son demasiado extensas —y el contenido quedó fuera del contexto—, demasiado ambiguas —por lo que el agente no puede extraer instrucciones ejecutables— o no están siendo detectadas. El análisis de GitHub sobre 2.500 repositorios determinó que la ambigüedad causa la mayoría de los fallos.²¹

Patrones de producción

Patrones de largo alcance 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 debe protegerse un harness:²⁹

• Resiliencia ante fallos de herramientas: Opus 4.7 continúa trabajando tras fallos de herramientas que detenían las sesiones de Opus 4.6. Puedes reducir —pero no eliminar— los envoltorios defensivos de reintentos en el código de subagents. Conserva las protecciones a nivel de hooks; 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 sitúa entre high y max. Es el valor predeterminado recomendado para programación y cargas de trabajo basadas en agentes. En subagents de larga duración, xhigh supera de manera significativa a high con un costo de tokens proporcionalmente menor. max sigue siendo la opción adecuada para razonamientos difíciles de una sola ejecución; xhigh es mejor para tareas sostenidas.
• Límite del presupuesto de tokens: Se puede configurar para cada ejecución del agente mediante output_config.task_budget (encabezado beta task-budgets-2026-03-13). El modelo ve una cuenta regresiva en curso y adapta de manera gradual el alcance del trabajo al presupuesto, en lugar de agotarlo inesperadamente. Úsalo en bucles basados en agentes cuando quieras un gasto de tokens predecible sin sacrificar la calidad en prompts breves.
• Detección de necesidades implícitas: Es el primer modelo de Claude que supera las pruebas de «necesidades implícitas», es decir, reconoce cuándo la solicitud literal del usuario no especifica por completo lo que realmente necesita. Esto hace menos necesaria la sección de «reglas de aclaración» de CLAUDE.md. Si tu CLAUDE.md contiene 200 líneas de protecciones del tipo «también considera X cuando el usuario solicite Y», elimina las que el modelo ya cubre de forma nativa.

Base de worktrees, rutas del sandbox y configuración administrativa (7 de mayo de 2026)

Claude Code v2.1.133 incorpora cuatro opciones de configuración de nivel administrativo que conviene conocer para los 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 subir en los worktrees nuevos, a menos que vuelvan a habilitarlo explícitamente.

Encuesta de comentarios de OTel para la observabilidad empresarial (8 de mayo de 2026)

Claude Code v2.1.136 añadió CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL para volver a habilitar la encuesta de calidad dentro de la sesión en empresas que capturan las respuestas mediante OpenTelemetry.⁴⁰ Si tu organización envía los eventos de OTel a una plataforma central de observabilidad, esta variable de entorno reincorpora la encuesta al flujo de datos para que la señal de calidad atraviese la misma canalización que las métricas de latencia y errores. Trátala como una opción voluntaria: el valor predeterminado mantiene la encuesta deshabilitada, lo cual es correcto para implementaciones que no usan OTel.

Lanzadores corporativos y rendimiento a escala de MCP (julio de 2026)

Dos cambios de v2.1.207 son importantes para las implementaciones de producción.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permite que los entornos administrados inicien el proceso de Claude Code mediante un binario envoltorio corporativo: el punto de integración para agentes de endpoints, comprobaciones de políticas durante el inicio y entornos donde cada proceso debe ejecutarse bajo un supervisor obligatorio. Si antes tu empresa simulaba esto con alias del shell o scripts de inicio bifurcados, este es el punto de integración compatible.

La misma versión redujo la sobrecarga de ejecución donde más se percibe en los harnesses: rondas de uso de herramientas hasta 7 veces más rápidas en sesiones con una gran cantidad de herramientas de MCP y transcripciones de sesión 79 veces más pequeñas.⁶⁸ Esto atenúa —sin invalidar— las recomendaciones de El costo como arquitectura: priorizar CLI sigue siendo la mejor opción para operaciones sin estado de una sola ejecución, pero un harness que incorpora decenas de herramientas de MCP ya no paga la penalización por ronda que tenía en primavera, y almacenar transcripciones deja de ser un costo oculto de las ejecuciones autónomas prolongadas.

El quality loop

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

1. Implementar - Escribe el código
2. Revisar - Vuelve a leer cada línea. Detecta errores tipográficos, fallos lógicos y secciones poco claras
3. Evaluar - Ejecuta el evidence gate. Comprueba los patrones, los casos límite y la cobertura de las pruebas
4. Perfeccionar - Corrige todos los problemas. Nunca los pospongas para «más adelante»
5. Ampliar la perspectiva - Revisa los puntos de integración, las importaciones y el código adyacente para detectar regresiones
6. Repetir - Si algún criterio del evidence gate falla, vuelve al paso 4
7. Informar - Enumera qué cambió y cómo se verificó, y cita evidencia específica

El evidence gate

«Creo» y «debería» no constituyen evidencia. Cita rutas de archivos, resultados de pruebas o código específico.

Si no puedes proporcionar evidencia para alguna fila, vuelve a Perfeccionar.²²

Autoridad humana para fusionar cambios

Un estudio de arXiv de mayo de 2026 sobre 29.585 ciclos de vida de solicitudes de incorporación de cambios de agentes de IA separa la autonomía operativa de la gobernanza de las fusiones.⁴⁷ La lección arquitectónica útil es sencilla: los agentes pueden iniciar el trabajo, hacer avanzar las ramas, abrir PRs, revisar el trabajo y resumir los riesgos, mientras que la autoridad para fusionar cambios permanece como un límite de gobernanza independiente.

Haz explícito ese límite en el harness. Permite que los agentes preparen PRs y recopilen evidencia; exige aprobación humana para las fusiones, los lanzamientos y las operaciones destructivas en repositorios, salvo que la organización tenga una política de automatización auditada por separado. Cuando la automatización ejecute una fusión, conserva registros que distingan al ejecutor de la persona o política que la autorizó.

Patrones de manejo de errores

Escrituras atómicas de archivos. Cuando varios agentes escriben simultáneamente en el mismo archivo de estado, se corrompe JSON. Escribe en archivos .tmp y luego usa mv de forma atómica. El sistema operativo garantiza que mv sea atómico dentro del 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 tras la corrupción del estado. Si el estado se corrompe, el patrón de recuperación lo vuelve a crear a partir de valores predeterminados seguros en lugar de bloquearse:¹⁶

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 con ((VAR++)). ((VAR++)) devuelve el código de salida 1 cuando VAR es 0 porque 0++ se evalúa como 0, valor que bash considera falso. Con set -e habilitado, esto termina el script. Usa VAR=$((VAR + 1)) en su lugar.¹⁶

Clasificación del radio de impacto

Clasifica cada acción del agente según su radio de impacto y aplica los controles correspondientes:²

Remote Control (conexión a una instancia local de Claude Code desde cualquier navegador o aplicación móvil) convierte el control «Externo», que normalmente causa una espera bloqueante, en una notificación asíncrona. El agente continúa trabajando en la siguiente tarea mientras revisas la anterior desde tu teléfono.²

Especificación de tareas para ejecuciones autónomas

Las tareas autónomas eficaces incluyen tres elementos: objetivo, criterios de finalización y referencias 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 poder verificarse mediante una máquina: aprobación o fallo de pruebas, resultados del linter, códigos de estado HTTP y comprobaciones de existencia de archivos. Una tarea inicial que pedía al agente «escribir pruebas que pasen» produjo assert True y assert 1 == 1. Técnicamente correcto. En la práctica, inútil.¹⁶

Modos de fallo que debes vigilar

Traza concreta de una sesión

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

1. Se activa SessionStart. El dispatcher incorpora la fecha actual, la detección del proyecto, las restricciones filosóficas y la inicialización del seguimiento de costos. Cinco hooks, 180 ms en total.

2. El agente lee el PRD y planifica la primera historia. Se activa UserPromptSubmit. El dispatcher incorpora el contexto activo del proyecto y la línea base de desviación de la sesión.

3. El agente llama a Bash para ejecutar las pruebas. Se activa PreToolUse:Bash. Comprobación de credenciales, validación del sandbox y detección del proyecto. 90 ms. Se ejecutan las pruebas. Se activa PostToolUse:Bash: se registra la señal periódica de actividad y se comprueba la desviación.

4. El agente llama a Write para crear un archivo. Se activa PreToolUse:Write: comprobación del alcance de los archivos. Se activa PostToolUse:Write: comprobación del linting y seguimiento de commits.

5. El agente termina la historia. Se activa Stop. El quality gate comprueba si el agente citó evidencia, si utilizó lenguaje evasivo y si hay comentarios TODO en el diff. Si alguna comprobación falla, devuelve el código de salida 2 y el agente continúa.

6. Verificación independiente: Un agente nuevo ejecuta el conjunto de pruebas sin confiar en el informe del agente anterior.

7. Se inician en paralelo tres agentes de revisión de código. Cada uno revisa el diff de manera independiente. Si algún revisor señala un problema CRITICAL, la historia vuelve a la cola.

8. La historia supera las comprobaciones. Se carga la siguiente. El ciclo se repite con las 5 historias.

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

Caso práctico: 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 y revisión multiagente).

Las dos filtraciones de credenciales obligaron a rotar las claves de API y auditar los servicios dependientes: aproximadamente 4 horas de respuesta a incidentes. La sobrecarga del harness que evitó un incidente equivalente fue de 2,4 segundos de bash por historia. La tasa de finalizaciones falsas cayó del 35 % al 4 % porque el hook Stop ejecutó las pruebas de forma independiente antes de permitir que el agente informara que había terminado.

Consideraciones de seguridad

Los cinco principios de los 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 reflejan —y amplían— el enfoque de evidence gate de esta guía:

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

Turno sin estado e identidad autodeclarada de MCP (julio de 2026). La especificación de MCP está en plena transición hacia un núcleo sin estado (SEP-2575), que elimina el protocolo de enlace de inicialización con estado que antes comunicaba la identidad del servidor. Un cambio en el borrador de la especificación, integrado el 16 de julio (PR #3002), restaura la identidad como una superficie opcional: los servidores pueden incluir un objeto io.modelcontextprotocol/serverInfo en el campo _meta de la respuesta, mientras que clientInfo pasa a ser opcional en las solicitudes.⁷¹ Lo relevante para la seguridad es lo que la especificación establece sobre la confianza: esta identidad es autodeclarada y no está verificada; sirve únicamente para su visualización y registro, y NO DEBE determinar decisiones de seguridad. Si tu harness basa listas de permitidos, reglas de permisos o auditorías mediante registros en el nombre declarado por un servidor MCP, ese nombre es una afirmación, no una credencial. Vincula la confianza al transporte y a la configuración (qué servidor configuraste tú y en qué endpoint), nunca a lo que el servidor afirma ser. La revisión definitiva de la especificación sin estado está programada para el 28 de julio de 2026; se espera que los detalles del protocolo incluidos en esta sección queden consolidados en la próxima actualización.

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

El sandbox

Claude Code admite un modo sandbox opcional (que se habilita 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 y bubblewrap en Linux). Cuando está habilitado, el sandbox impide que el modelo realice solicitudes de red arbitrarias o acceda a archivos fuera del directorio del proyecto. Sin el sandbox, Claude Code utiliza un modelo basado en permisos en el que apruebas o rechazas cada llamada a una herramienta.¹³

Base mínima de seguridad de mayo de 2026. Claude Code v2.1.149 corrigió una evasión de permisos del directorio de trabajo en PowerShell, varias deficiencias en el análisis de permisos relacionadas con reglas de autorización y variables obsoletas de PowerShell, y un error en la lista de escritura permitida del sandbox para worktrees de git, que abarcaba toda la raíz del repositorio principal en lugar de limitarse a los componentes internos compartidos de git.⁵³ Si tu harness permite PowerShell o agentes aislados mediante worktrees, considera la versión v2.1.149 o posterior como el mínimo y mantén restringidas las reglas del shell. Las excepciones amplias como PowerShell(*) y los permisos de escritura para todo el repositorio son atajos de orquestación, no límites de seguridad.

Refuerzo del sandbox de OpenAI Agents SDK (v0.17.0, 8 de mayo de 2026). Por parte de OpenAI, openai-agents-python v0.17.0 reforzó un límite paralelo: LocalFile.src y LocalDir.src ahora deben permanecer dentro del base_dir de materialización (el directorio de trabajo actual del proceso SDK cuando se aplica el manifiesto), salvo que se conceda acceso explícito al origen mediante Manifest.extra_path_grants con SandboxPathGrant.⁴¹ Los orígenes locales relativos se resuelven desde base_dir; las rutas absolutas deben estar ya dentro de ese directorio o contar con una concesión. Esto resuelve un problema del límite de los artefactos locales: las versiones anteriores permitían que los manifiestos incorporaran rutas arbitrarias del host al espacio de trabajo del sandbox. Para migrar, declara las raíces confiables del host en el nivel del manifiesto mediante SandboxPathGrant(path=..., read_only=True) para montajes de solo lectura. Considera extra_path_grants una configuración confiable de la aplicación; nunca generes concesiones a partir de resultados del modelo ni de entradas de manifiesto que no sean confiables.

Base mínima posterior de OpenAI Agents SDK (v0.17.3). Las versiones 0.17.1 a 0.17.3 añadieron más refuerzos para el sandbox y las sesiones: límites para la extracción de archivos comprimidos, validación de subrutas de GitRepo, errores más claros de los proveedores de sandbox, exclusión de las credenciales de los puntos de montaje de los comandos del sandbox, rechazo de raíces relativas para el espacio de trabajo del sandbox y manejo del estado terminal del sandbox de Vercel.⁵⁴ Si utilizas sandboxes alojados por OpenAI o respaldados por proveedores, en lugar de depender únicamente de los hooks de Claude Code, considera la versión 0.17.3 como la base mínima actual para los patrones de esta sección.

Tres patrones de contención entre productos (Anthropic, mayo de 2026)

La publicación de ingeniería de Anthropic, «Cómo contenemos Claude en distintos productos» (25 de mayo de 2026), es la formulación del propio proveedor de los principios que esta sección enseña de manera fragmentada: el sandbox definido en la configuración que se describió antes, la base mínima del aislamiento mediante worktrees y el enfoque de tratar todo como no confiable.⁸¹ Su idea central consiste en ajustar la solidez de la contención a la superficie del producto; ese ajuste constituye en sí mismo la lección: no existe un único diseño de aislamiento correcto, sino un aislamiento adaptado a quién supervisa y a qué puede salir mal.

• Contenedores efímeros de gVisor (claude.ai). La ejecución del lado del servidor se realiza en contenedores de gVisor sobre infraestructura aislada, con un sistema de archivos efímero para cada sesión. El modelo de amenazas se centra en el aislamiento de la infraestructura y entre inquilinos; nunca se puede acceder a la computadora del usuario, por lo que no hay nada local que proteger.
• Sandbox del sistema operativo con intervención humana (Claude Code). El patrón descrito en el párrafo anterior sobre el sandbox, expresado como política: Seatbelt en macOS y bubblewrap en Linux, con lectura permitida, escritura limitada al espacio de trabajo y red denegada de forma predeterminada; la persona aprueba aquello que el límite no cubre. Anthropic publicó el código fuente del entorno de ejecución (sandbox-runtime) para que el límite pueda auditarse. La publicación reconoce con franqueza el eslabón débil: se aprueba cerca del 93 % de las solicitudes de permisos, y el clasificador de auto mode —que detecta alrededor del 83 % de los comportamientos excesivamente entusiastas antes de su ejecución y reduce en un 84 % las solicitudes de aprobación— existe precisamente porque la fatiga ante las aprobaciones es una propiedad de seguridad, no una queja de UX. Esta es la postura de check-layer que la guía ha seguido desde la versión v2.1.193.
• Máquinas virtuales selladas (Claude Cowork). Máquinas virtuales completas sobre hipervisores de la plataforma —el framework Virtualization de Apple en macOS y HCS en Windows— que solo tienen montados el espacio de trabajo seleccionado y la carpeta .claude; ningún otro elemento del host es visible. Las credenciales nunca entran en la máquina virtual: permanecen en el llavero del host y cada sesión recibe un token con alcance limitado que puede revocarse de forma independiente. Un proxy MITM defensivo dentro de la máquina virtual lo hace cumplir y solo permite solicitudes que contengan el token de sesión aprovisionado para esa máquina virtual. Una clave incorporada por un atacante se rechaza en el límite porque solo la máquina virtual conoce su procedencia.

Los principios de diseño que sustentan esta clasificación son la parte transferible. Contén primero en la capa del entorno y orienta después en la capa del modelo: toda defensa probabilística tiene una tasa de error distinta de cero, por lo que los límites deterministas deben detener lo que la orientación mediante prompts no detecte; es el argumento de esta guía de que los hooks garantizan la ejecución, reformulado por el proveedor. Adapta la solidez del aislamiento a la capacidad de supervisión del usuario: un desarrollador puede evaluar un comando de bash antes de aprobarlo; un trabajador del conocimiento no puede hacerlo, por lo que Code muestra un diálogo de permisos y Cowork utiliza una máquina virtual sellada. Prefiere mecanismos ampliamente probados en lugar de código de aislamiento personalizado: los hipervisores, seccomp y entornos de ejecución de contenedores han resistido mejor el escrutinio adversario que los proxies personalizados con listas de permitidos y los analizadores de configuración de Anthropic. Trata la configuración local del proyecto y los resultados de las herramientas como no confiables: la publicación indica que se debe tratar la apertura de un proyecto y la carga de configuración como cualquier solicitud entrante de internet, y los resultados de las herramientas como una superficie de ataque incluso cuando la herramienta sea confiable. Es la misma postura que esta guía aplica a los mensajes entre agentes, el contenido leído por subagents y la identidad autodeclarada de MCP. Mantén las credenciales fuera del sandbox: utiliza tokens con alcance limitado, revocables y específicos de cada sesión, en lugar de claves generales que el agente pudiera filtrar.

La superficie de configuración está alcanzando al primer principio (v2.1.219). «Contén primero en la capa del entorno» es una idea fácil de respaldar, pero hasta ahora ha resultado incómoda de configurar porque el sandbox de Claude Code resolvía lo que sus reglas no cubrían mediante preguntas; una solicitud de permisos es una defensa probabilística disfrazada de determinista, como admite la cifra de aprobación del 93 % citada antes. sandbox.network.strictAllowlist elimina la pregunta para el tráfico saliente: cuando se configura, se rechaza directamente la solicitud de un comando dentro del sandbox dirigida a un host que no está en la lista de permitidos, en lugar de solicitar aprobación.⁸⁴ Combínala con sandbox.filesystem.disabled, incorporada en v2.1.216, y ambas configuraciones formarán una postura de seguridad en lugar de un conjunto de opciones inconexas: la contención del sistema de archivos y la red pueden seleccionarse de manera independiente, y ahora es posible hacer determinista la contención de red. Para un harness sin supervisión, esta última es la más importante porque el tráfico saliente es el punto en el que una instrucción inyectada se convierte en una filtración de datos, y el caso límite de la fatiga ante las aprobaciones es que no haya nadie frente al teclado que pueda sufrirla. El costo es el habitual de un límite determinista: la lista de permitidos debe ser correcta y, si olvidas un host, la operación falla con una denegación opaca en lugar de una pregunta. Enumera los hosts que tus agentes necesitan legítimamente y elimina la solicitud.

Nada de esto sustituye la capa de hooks; se ubica por debajo de ella. Los patrones de contención constituyen la base determinista, y el historial de aplicación mediante worktrees de esta guía contiene la misma lección a menor escala: un límite solo cuenta si resiste la redirección deliberada, y los mecanismos con más probabilidades de resistir son aquellos que no se crearon específicamente para la ocasión.

Límites de permisos

El sistema de permisos controla las operaciones en varios niveles:

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

Claude Code v2.1.178 amplió las reglas de permisos desde el nivel de las herramientas hasta el nivel de los parámetros: Tool(param:value) busca coincidencias en los parámetros de entrada de una herramienta y utiliza * como comodín. El ejemplo canónico es Agent(model:opus), una regla que impide iniciar subagents con un nivel específico de modelo.⁶³ Desde el punto de vista arquitectónico, esto resuelve una limitación que la tabla anterior de cuatro niveles no podía expresar: antes se permitía o denegaba una herramienta por completo, pero no era posible restringir cómo se invocaba. Ahora, una política de gobernanza puede establecer «los subagents pueden iniciarse, pero no con el nivel Fable 5» o «Bash está permitido, pero no con este indicador» como una regla determinista, en vez de una solicitud incluida en el prompt.

Una configuración administrada complementaria, enforceAvailableModels (v2.1.175), restringe la selección de modelos desde el nivel superior: fija el modelo Default e impide que la configuración del usuario o del proyecto amplíe la lista administrada availableModels.⁶³ Ambas medidas se complementan: la lista de permitidos define qué niveles existen en la sesión, mientras que las reglas a nivel de parámetros limitan cómo los subagents pueden utilizarlos. Desde la versión v2.1.196, los administradores también pueden definir un modelo predeterminado para toda la organización desde la consola de la organización, que aparece como «Org default» en /model. De este modo, toda una flota hereda un valor predeterminado administrado sin que cada operador tenga que fijar uno: una base mínima que complementa el límite máximo de la lista de permitidos.

Las reglas de autorización limitadas por ruta se anclan al directorio de trabajo (julio de 2026)

Claude Code v2.1.214 corrigió una coincidencia excesiva y poco visible en las reglas de permisos limitadas por ruta: una regla de autorización con un patrón dir/** de un solo segmento —por ejemplo, Edit(src/**)— aprobaba automáticamente las modificaciones en cualquier directorio llamado src, a cualquier profundidad, incluidos vendor/some-package/src/ y todos los demás directorios src/ anidados que el autor de la regla nunca pretendió autorizar. Ahora estas reglas solo se anclan a <cwd>/dir; si realmente quieres que coincidan a cualquier profundidad, debes declararlo mediante **/dir/**.⁷⁴ Las reglas de denegación y consulta conservan deliberadamente la coincidencia anterior a cualquier profundidad. Esa asimetría constituye el diseño seguro correcto: una regla de autorización que coincide de forma demasiado restringida falla de manera segura (recibes una solicitud), mientras que una regla de denegación demasiado restringida falla de manera insegura (una ruta bloqueada logra pasar). Por eso las autorizaciones se volvieron más estrictas y las denegaciones conservaron su amplitud. Si tu configuración depende de patrones de autorización de un solo segmento para abarcar rutas anidadas, estos dejaron de hacerlo silenciosamente en v2.1.214. La corrección funciona según lo previsto, pero conviene revisar tus listas de permitidos y volver a declarar la amplitud que realmente deseas.

Medidas de protección de auto mode contra comandos destructivos (junio de 2026)

Claude Code v2.1.183 redujo el radio de impacto de auto mode para las operaciones que pueden eliminar trabajo o desmantelar entornos silenciosamente. Ahora auto mode bloquea por completo, salvo que las hayas solicitado explícitamente durante la sesión: las operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend cuando el agente no creó el commit durante esta sesión; y el desmantelamiento de infraestructura (terraform destroy, pulumi destroy, cdk destroy), a menos que hayas indicado la pila específica.⁶⁵ Desde el punto de vista arquitectónico, esto complementa la evaluación de inicios y las reglas a nivel de parámetros descritas antes: en vez de controlar qué herramienta se usa o cómo se inicia, controla por intención un pequeño conjunto de comandos irreversibles específicos. El agente todavía puede ejecutarlos, pero únicamente cuando recibe una instrucción explícita, no por iniciativa propia. En un harness autónomo, incorpora el mismo principio en tus propios hooks PreToolUse: los comandos que destruyen estado merecen una regla de denegación predeterminada que solo pueda levantarse mediante una señal explícita del operador.

Julio de 2026: auto mode llega al entorno empresarial y una solicitud se vuelve irrenunciable. Auto mode alcanzó la disponibilidad general en Amazon Bedrock, Google Vertex AI y Microsoft Foundry con la versión v2.1.207, junto con la configuración administrada disableAutoMode para que las empresas puedan desactivarlo. La postura del clasificador como check-layer ya está disponible en todas las plataformas empresariales oficiales, y deshabilitarla constituye una decisión explícita de gobernanza, no una limitación de la plataforma.⁶⁸ Después, v2.1.208 convirtió la protección contra eliminaciones catastróficas en una restricción absoluta: las solicitudes de confirmación para eliminaciones catastróficas ahora se imponen tanto sobre --dangerously-skip-permissions como sobre auto mode.⁶⁸ Se trata de un precedente notable: es la primera confirmación de Claude Code que ninguna postura de permisos puede omitir, ni siquiera el indicador explícito para evadirlos. Los diseños de harnesses autónomos que asumían que --dangerously-skip-permissions significaba literalmente cero solicitudes deben contemplar esta excepción; se activa precisamente cuando un ciclo sin supervisión puede causar el daño más irreversible.

Medidas de protección contra la fabricación de evidencia (julio de 2026)

Las versiones v2.1.203 a v2.1.206 cerraron dos vías mediante las cuales un agente podía fabricar su propio registro de auditoría.⁶⁸ En primer lugar, una regla de auto mode ahora impide la manipulación de los archivos de transcripción: el registro de la sesión ya no puede ser reescrito por las llamadas a herramientas de esa misma sesión. En segundo lugar, las notificaciones de tareas en segundo plano ahora indican expresamente que no hubo intervención humana mientras se ejecutaba la tarea. Esta segunda medida aborda una falla sutil: anteriormente, un modelo que resumía una tarea en segundo plano podía presentar (o inventar) una «aprobación» dentro de la transcripción que nunca ocurrió, sin que nada en la notificación la contradijera. Ahora la propia notificación funciona como evidencia en contra.

La lección arquitectónica se extiende al evidence gate: las transcripciones, las notificaciones y los registros son superficies de auditoría, y aquello que se audita no debe poder modificarlas. La plataforma ya aplica esta regla a su propia transcripción; haz lo mismo en tu harness: los informes de evidencia, los resultados de pruebas y los registros de deliberación deben quedar fuera de las rutas en las que el modelo puede escribir.

Defensa contra prompt injection

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

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

allowed-tools: Read, Grep, Glob

Los hooks PreToolUse validan cada llamada a una herramienta, sin importar cómo se haya instruido al modelo:

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

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

La base de seguridad de la plataforma aumentó en julio de 2026. Claude Code v2.1.210 reforzó el Agent tool contra la prompt injection indirecta transportada en contenido leído por un subagent: un archivo, una página web o el resultado de una herramienta que estén contaminados y que un subagent incorpore tienen menos capacidad para influir en la propia superficie de delegación.⁶⁹ Además, v2.1.211 reforzó el eslabón humano de la cadena: las vistas previas de permisos ahora neutralizan caracteres Unicode de anulación bidireccional, ancho cero y apariencia similar, por lo que ya no es posible crear un comando que parezca inofensivo en el diálogo de aprobación mientras ejecuta algo distinto.⁶⁹ La segunda corrección es especialmente importante en los harnesses donde una persona aprueba rápidamente las vistas previas renderizadas: la propia visualización también era una superficie de inyección. Ningún cambio sustituye las defensas de la capa de hooks descritas antes; ambos elevan la base de seguridad que las sustenta.

Los registros y las medidas de protección de los agentes son superficies de seguridad

Dos avisos de mayo de 2026 refuerzan un mismo patrón: la infraestructura de agentes crea nuevos lugares desde los que el contenido confidencial y las políticas ejecutables pueden filtrarse o escapar. El aviso GHSA-f3jg-756w-gm35 de GitHub describe un problema en el filtro de cargas útiles de Gryph Agents, por el cual el contenido confidencial de las cargas útiles de herramientas podía permanecer en registros locales de SQLite con el comportamiento de registro predeterminado.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p documenta una evasión del sandbox de medidas de protección con código personalizado de LiteLLM en un endpoint de proxy protegido para administradores.⁴⁶

La regla para producción es tratar las transcripciones de agentes, las cargas útiles de herramientas, los registros de SQLite y la ejecución de medidas de protección como infraestructura confidencial. Oculta los datos sensibles antes de almacenarlos, aplica límites de retención y mantén el código personalizado de las medidas de protección dentro de un sandbox y disponible para revisión. Una regla en el prompt que diga «no registres secretos» no basta; la ruta de registro y de las medidas de protección necesita pruebas deterministas.

Seguridad de los hooks

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

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

División de responsabilidades entre personas y agentes

La seguridad en las arquitecturas de agentes exige una división clara de responsabilidades entre las personas y los agentes:¹⁷

El patrón es el siguiente: las personas son responsables de las decisiones que exigen contexto organizacional, juicio ético o dirección estratégica. Los agentes se encargan de las decisiones que requieren búsquedas computacionales en espacios amplios de posibilidades. Los hooks hacen cumplir el límite.

Aplicación recursiva de hooks

Los hooks también se activan con las acciones de los subagents.¹³ Si Claude inicia un subagent mediante el Agent tool, tus hooks PreToolUse y PostToolUse se ejecutan con cada herramienta que utilice el subagent. Sin la aplicación recursiva de hooks, un subagent podría evadir tus controles de seguridad. El evento SubagentStop te permite ejecutar tareas de limpieza o validación cuando termina un subagent.

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

El costo como arquitectura

El costo es una decisión arquitectónica, no un detalle operativo posterior.² Hay tres niveles:

Nivel de tokens. Comprime el prompt del sistema. Elimina ejemplos de código didácticos (el modelo conoce los APIs), consolida las reglas duplicadas entre archivos y sustituye las explicaciones por restricciones. «Rechaza las llamadas a herramientas que coincidan con rutas confidenciales» cumple la misma función que una explicación de 15 líneas sobre por qué no deben leerse las credenciales.

Nivel de agentes. Prefiere inicios nuevos en vez de conversaciones largas. Cada historia de una ejecución autónoma recibe un agente nuevo con un contexto limpio. El contexto nunca crece sin control porque cada agente comienza desde cero. Usa briefings en lugar de memoria: los modelos ejecutan mejor un briefing claro que navegar por 30 pasos de contexto acumulado.

Nivel de arquitectura. Prioriza CLI sobre MCP cuando la operación no tiene estado. Una llamada a claude --print para una evaluación puntual cuesta menos y no añade sobrecarga de conexión. MCP resulta apropiado cuando la herramienta necesita un 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?

La restricción es el rendimiento, no la cantidad. 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 la configuración de 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 implementarlos.¹⁴

¿Pueden los hooks 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 de nivel de proyecto (confirmados en tu repositorio, compartidos con tu equipo) o en ~/.claude/settings.json para hooks de nivel de usuario (personales, aplicados a todos los proyectos). Los hooks de nivel de proyecto tienen prioridad cuando ambos existen. Usa rutas absolutas para los archivos de script a fin de evitar problemas con el directorio de trabajo.¹⁴

¿Toda 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, los cambios de nombre de variables y las 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 consistente.⁷

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

Prueba tanto las rutas exitosas como las de fallo. Éxito: los agentes discrepan de forma productiva y alcanzan 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 de agente deterministas y verifican que ambas puertas de validación detecten todos los modos de fallo documentados. Un sistema de deliberation de producción ejecuta 141 pruebas en tres capas: 48 pruebas de integración bash, 81 pruebas unitarias de Python y 12 simulaciones de pipeline end-to-end.⁷

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

Una deliberation de 3 agentes agrega entre 30 y 60 segundos de tiempo de reloj (los agentes se ejecutan secuencialmente mediante Agent tool). Una deliberation de 10 agentes agrega entre 2 y 4 minutos. Los hooks de consenso y pride check se ejecutan cada uno en menos de 200 ms. El cuello de botella principal es el tiempo de inferencia de LLM por agente, no la sobrecarga de orquestación.⁷

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

Mantén cada sección por debajo de 50 líneas y el archivo total por debajo de 150 líneas. Los archivos largos se truncan por las ventanas de contexto, así que coloca 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) se aplican conceptualmente a cualquier sistema agentic. La implementación específica usa los eventos de ciclo de vida, patrones de 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