Arquitectura de agentes: cómo crear sistemas 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 31 eventos de ciclo de vida documentados, cada uno conectable mediante scripts de shell que el modelo no puede omitir. Apila 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 organiza la deliberación multiagente. Los flujos de trabajo dinámicos de Claude Code (v2.1.154+) convirtieron la orquestación determinista multiagente en una primitiva nativa: decenas o cientos de agentes en segundo plano mediante /workflows; además, la plataforma ahora ejecuta subagents en segundo plano de forma predeterminada (20 simultáneos, anidamiento de profundidad 3), permite que tus sesiones se envíen mensajes entre sí como pares (v2.1.224) y ejecuta sesiones en la nube en runners autohospedados. Los hooks y los evidence gates siguen siendo responsables de la corrección.⁵²⁵³⁸⁷ Esta guía cubre cada capa de esa pila: desde un solo hook hasta un sistema de consenso de 10 agentes. No se requieren frameworks. Todo con bash y JSON.

Andrej Karpathy acuñó un término para lo que crece alrededor de un agente LLM: claws. Los hooks, scripts y la orquestación que permiten al agente aferrarse al mundo fuera de su ventana de contexto.¹ La mayoría de los desarrolladores tratan a los agentes de programación con IA como asistentes interactivos. Escriben un prompt, observan cómo edita un archivo y continúan. Ese 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 kernel LLM. Cada acción que realiza el modelo pasa por hooks que controlas. Defines políticas, no prompts. El modelo opera dentro de tu infraestructura del mismo modo que un servidor web opera dentro de las reglas de nginx. No te sientas frente a nginx a escribir solicitudes. Lo configuras, lo implementas y lo supervisas.

La diferencia importa porque la infraestructura se acumula. Un hook que bloquea credenciales en comandos bash protege cada sesión, cada agente y cada ejecución autónoma. Una skill que codifica tu criterio de evaluación se aplica de forma consistente, tanto si la invocas tú como si lo hace un agente. Un agente que revisa código en busca de problemas de seguridad ejecuta las mismas comprobaciones, estés observando o no.²

Conclusiones clave

• Los hooks garantizan la ejecución; los prompts no. Usa hooks para linting, formato, comprobaciones de seguridad y todo lo que deba ejecutarse siempre, sin importar el comportamiento del modelo. El código de salida 2 bloquea acciones. El código de salida 1 solo advierte.³
• Las skills codifican experiencia de dominio que se activa automáticamente. El campo description lo determina todo. Claude usa razonamiento LLM (no coincidencia de palabras clave) para decidir cuándo aplicar una skill.⁴
• Los subagents evitan la saturación de contexto. Las ventanas de contexto aisladas para exploración y análisis mantienen la sesión principal liviana. Ejecuta subagents independientes en paralelo y usa equipos de agentes cuando los trabajadores necesiten coordinación sostenida.⁵
• La memoria vive en el sistema de archivos. Los archivos persisten entre ventanas de contexto. CLAUDE.md, MEMORY.md, directorios de reglas y documentos de transferencia forman un sistema estructurado de memoria externa.⁶
• La deliberación multiagente detecta puntos ciegos. Los agentes individuales no pueden cuestionar sus propias suposiciones. Dos agentes independientes con distintas prioridades de evaluación detectan fallas estructurales que los quality gates no pueden abordar.⁷
• El patrón de harness es el sistema. CLAUDE.md, hooks, skills, agentes y memoria no son funciones independientes. Se combinan en una capa determinista entre tú y el modelo que escala con la automatización.

Cómo usar esta guía

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

La ruta dorada de cinco minutos

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

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

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

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

Conéctalo en .claude/settings.json:

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

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

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

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

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

Paso 3: genera un subagent (30 segundos)

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

Lo que ahora tienes

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

Por qué importa la arquitectura de agentes

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

Tres fuerzas hacen que la arquitectura de agentes sea necesaria:

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

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

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

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

El patrón Harness

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

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

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

Capa de extensión: Las skills aportan experiencia de dominio y se activan automáticamente según el contexto. Los hooks proporcionan compuertas deterministas que se ejecutan en cada llamada a 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 investigación, revisión y deliberación. Los presupuestos de creación evitan la recursión descontrolada. La validación por consenso asegura la calidad.

La idea clave: la mayoría de los usuarios trabaja por completo en la Capa central, mientras observa cómo crece el contexto y aumentan los costos. Los usuarios avanzados configuran las capas de Instrucciones y Extensiones, y luego usan la Capa central solo para la orquestación y las decisiones finales.²

Harnesses administrados frente a autoalojados (abril de 2026)

Durante los primeros meses de 2026, la ruta de «crear tu propio harness» era la única opción real. En abril de 2026, eso cambió. Anthropic lanzó Claude Managed Agents en beta pública (8 de abril): bucle de harness + ejecución de herramientas + contenedor sandbox + persistencia de estado como una REST API, facturado con tokens estándar más $0,08 por hora de sesión. La actualización de Agents SDK de OpenAI (16 de abril) formalizó la misma separación: harness y cómputo como capas independientes, con proveedores sandbox nativos (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) y snapshot/rehydrate para sobrevivir a la pérdida de contenedores.²³²⁴

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

Para proyectos de Python que quieran integrar el tiempo de ejecución de Claude Code como una biblioteca —entre «ejecutar claude desde el shell» y «REST API a 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 v2.1.123, elevó el requisito mínimo de la dependencia mcp a >=1.19.0 (las versiones anteriores descartaban silenciosamente los retornos CallToolResult de las herramientas MCP en proceso y dejaban al modelo con un bloque de error de validación), e incorporó SandboxNetworkConfig con paridad de esquema respecto de TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Al 2026-08-12, el paquete está en v0.2.137 en PyPI y TypeScript SDK en v0.3.229 (ambos verificados en los registros activos); la línea 0.2.x es incremental sobre la superficie 0.1.x descrita aquí: las opciones include_hook_events, skills y de configuración sandbox que aparecen a continuación siguen vigentes, y las versiones recientes se han centrado en la limpieza de subprocesos y la fiabilidad de los streams NDJSON.⁹⁰⁸⁶

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

En julio de 2026, la columna administrada también obtuvo una historia multiagente del lado de OpenAI: openai-agents-python v0.18.2 (11 de julio) y openai-agents-js v0.13.2 (10 de julio) agregan soporte multiagente alojado en beta: orquestación administrada por OpenAI de varios agentes como servicio alojado, la contraparte directa de la beta pública Managed Multiagent Orchestration de Anthropic tratada en la sección Orquestación multiagente.⁷³ Ambos proveedores ofrecen ahora en el nivel multiagente la misma alternativa que la tabla siguiente describe para agentes individuales: el proveedor ejecuta el bucle de delegación y tú renuncias a la superficie de hooks.

La bifurcación arquitectónica ahora es real:

Cuándo elegir cada uno: el autoalojamiento sigue siendo adecuado para equipos que ya cuentan con capacidad de infraestructura, quieren skills/hooks bajo su control u optimizan profundamente un flujo de trabajo específico. La opción administrada es adecuada para equipos sin ingenieros de plataforma dedicados, cuando el tiempo hasta obtener valor importa más que la personalización, o cuando las ejecuciones de agentes deben sobrevivir de forma confiable al cierre de laptops sin que construyas esa capa de persistencia. Ambos son compatibles: puedes ejecutar un harness autoalojado que delegue tareas específicas de larga duración a Managed Agents mediante su REST API.

Cómo se ve el harness en 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 tiene un propósito. El árbol ~/.claude/ es 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, conforman el harness completo.

Sistema de skills

Las skills son extensiones invocadas por el modelo. Claude las detecta y aplica automáticamente según el contexto, sin que tengas que llamarlas explícitamente.⁴ En cuanto notes que estás explicando de nuevo el mismo contexto entre sesiones, es momento de crear una skill.

Cuándo crear una skill

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

Crear una skill

Las skills se encuentran en cuatro posibles ubicaciones, de la mayor a la menor amplitud:⁴

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

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

# Code Review Expertise

## Security Checks
When reviewing code, verify:

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

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

Referencia de frontmatter

El campo de descripción lo es todo

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

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 tipos de problemas específicos), cuándo usarla (al examinar cambios, PRs y análisis de calidad) y frases desencadenantes (revisar, auditar, verificar) que los usuarios escriben de forma natural.

Ten en cuenta que la activación automática es un control gradual, no una ley: desde la versión v2.1.215, Claude ya no se autoinvoca las skills incluidas /verify y /code-review; se ejecutan solo mediante invocación explícita, un retroceso deliberado de la activación basada en descripciones para skills de revisión pesadas cuyos usos no solicitados costaban más de lo que aportaban.⁷⁴

Presupuesto de contexto

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

Archivos de apoyo y organización

Las skills pueden hacer referencia a archivos adicionales en el mismo directorio:

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

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

Compartir skills mediante Git

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

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

Cuando los integrantes del equipo hacen pull, reciben la skill automáticamente. Sin instalación ni configuración. Esta es la forma más efectiva de estandarizar conocimiento especializado en un equipo.

Las skills como biblioteca de prompts

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

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

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

Las skills se combinan con hooks

Las skills pueden definir sus propios hooks en el frontmatter, que se activan solo mientras se ejecuta la skill. Esto crea 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'"
---

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

Errores comunes con las skills

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

Demasiadas skills compitiendo por el presupuesto. Más skills significan más descripciones compitiendo por el 1 % del presupuesto de contexto. Si notas que las skills no se activan, revisa /context para ver las excluidas. Prioriza menos skills bien descritas por encima de muchas imprecisas.

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

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

Los harnesses autohospedados en claude-agent-sdk-python v0.1.77+ deben usar la opción skills en ClaudeAgentOptions para declarar las skills disponibles, no el valor heredado "Skill" en allowed_tools.³⁷ La abreviatura "Skill" está obsoleta y la opción dedicada brinda a Claude Code información más estructurada sobre cuáles skills están disponibles. El CLI incluido en v0.1.77 es v2.1.133.

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

Las skills siempre se han cargado desde el directorio .claude/skills/ de un proyecto. Claude Code v2.1.157 extiende ese directorio a los plugins: un plugin colocado en .claude/skills/ ahora se carga automáticamente sin registro en marketplace, y claude plugin init <name> crea allí uno nuevo con el manifiesto y SKILL.md ya conectados.⁵⁸ Eso cierra la brecha entre las dos formas de herramientas de proyecto que antes vivían en lugares diferentes: una skill simple confirmada directamente en el repositorio, frente a un plugin que agrupa una skill junto con hooks y un servidor MCP, pero que antes necesitaba un marketplace para instalarse. El efecto práctico para el diseño de harnesses: las herramientas con alcance de proyecto ya no necesitan un desvío por un registro para distribuirse; escríbelas, confírmalas y los integrantes del equipo obtendrán la misma superficie con git pull. Los plugins siguen siendo propietarios del caso de uso de instalación empaquetada (hooks + skills + servidores MCP + agents en un ZIP); el cambio es que un proyecto ya no tiene que crear un marketplace solo para cargar uno desde su propio árbol. Esa convergencia ahora tiene una base entre proveedores: Agent Plugins 1.0.0 (publicado el 6 de agosto de 2026) estandariza la misma forma de paquete —un manifiesto plugin.json, directorios skills/ de carpetas SKILL.md, mcp.json opcional— como “el formato de paquete portátil para agentes de IA”, adoptado en el lanzamiento por VS Code, Cursor, GitHub Copilot, ChatGPT & Codex y Kiro. Es explícitamente una capa de empaquetado alrededor de Agent Skills y MCP, no un reemplazo; ten en cuenta que Anthropic, autor de la especificación Agent Skills, aún no forma parte de la coalición, así que trata la portabilidad hacia afuera de Claude-Code como compatibilidad a nivel de formato, no como un contrato bidireccional oficial.⁸⁹

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

Las skills son capacidad, y la capacidad es superficie de ataque. Claude Code v2.1.169 agrega una configuración disableBundledSkills (y la variable de entorno correspondiente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) que oculta por completo del modelo las skills incluidas, los workflows y los slash commands integrados.⁶⁰ Para un harness reforzado o regulado, esto constituye una reducción deliberada de la superficie de ataque: un operador que haya auditado y aprobado un conjunto específico de skills de proyecto y personales puede suprimir todo lo que Anthropic incluye de fábrica, de modo que el modelo solo razone sobre la superficie que el operador evaluó. Trátalo igual que una lista de herramientas permitidas: el valor predeterminado ofrece capacidades amplias, y desactivarlo es una decisión de gobernanza, no un simple interruptor de comodidad.

.claude/skills anidadas y resolución de la más cercana (16 de junio de 2026)

Claude Code v2.1.178 hizo que las herramientas de proyecto fueran conscientes de la ubicación. Las skills en directorios .claude/skills anidados ahora se cargan cuando trabajas en archivos bajo ese directorio, no solo desde la raíz del repositorio; cuando hay un conflicto de nombres, la skill anidada aparece como <dir>:<name> para que ambas sigan siendo accesibles.⁶³ La misma versión hizo que el resto de la superficie del proyecto se resuelva desde el directorio más cercano al directorio de trabajo: cuando un nombre de agent, workflow o estilo de salida entra en conflicto entre directorios .claude/ anidados, gana el que esté más cerca del directorio de trabajo, y un guardado de workflow con alcance de proyecto se dirige al .claude/workflows/ existente más cercano en vez de dirigirse siempre a la raíz.⁶³ Para un monorepo o un repositorio de repositorios, esta es la diferencia entre una superficie global plana y herramientas por paquete que se activan según el contexto: un services/api/.claude/skills/ puede contener skills específicas de API que aparezcan solo mientras trabajas en ese árbol, sin entrar en conflicto con una 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 del LLM como scripts simples, no como prompts interpretados por el modelo. ¿El modelo quiere ejecutar rm -rf /? Un script bash de 10 líneas comprueba el comando con una lista de bloqueo y lo rechaza antes de que el shell siquiera lo vea. El hook se activa independientemente de que el modelo lo quiera o no.

Eventos disponibles

Claude Code expone 31 eventos documentados del ciclo de vida en ocho categorías a la fecha de esta actualización de la guía. La lista de eventos crece con las versiones, así que considera la documentación de referencia como la fuente de verdad y consulta la hoja de referencia para ver la tabla completa actual antes de conectar hooks de producción:¹³

DirectoryAdded (v2.1.219) cierra la brecha del espacio de trabajo a mitad de sesión. La lista de eventos se había mantenido estable desde que llegó MessageDisplay en 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— registre 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 añadía un segundo repositorio sin que se activara ningún hook. Todo lo que afirmes sobre el espacio de trabajo al inicio —comprobaciones de confianza, análisis de secretos, reglas de alcance de rutas derivadas del árbol, carga de políticas por repositorio— debe volver a ejecutarse aquí, porque el conjunto de directorios de una sesión ya no es fijo al iniciarse. El evento es informativo en lugar de bloqueante, así que trátalo como un disparador para volver a derivar el estado y registrar la procedencia, no como una barrera; si nunca debe poder añadirse un directorio, niégalo en la configuración en lugar de intentar vetarlo desde un hook. La parte de SDK llegó en la misma versión (TypeScript v0.3.219 añade DirectoryAdded a los eventos del ciclo de vida del protocolo de control), por lo que los harnesses alojados en SDK lo ven en las mismas condiciones que los de CLI.⁸⁵

Semántica de los códigos de salida

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

Configuración de hooks

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

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

El campo matcher filtra un valor específico del evento. Para eventos de herramientas, coincide con valores de tool_name como Bash, Edit, Write, Read, Glob, Grep, nombres de herramientas MCP como mcp__server__tool, o * para todas las herramientas. Los nombres simples y las listas separadas por | son coincidencias exactas; los valores con otros caracteres son expresiones regulares JavaScript. Algunos eventos no admiten matchers y siempre se activan cuando están configurados.¹³ A partir de Claude Code v2.1.195, los matchers que contienen identificadores con guiones (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 para cada nombre que simplemente contiene la cadena; para cubrir todas las herramientas de un servidor MCP con guiones, escribe el patrón explícito mcp__brave-search__.*.⁶⁶ v2.1.214 aplicó la misma disciplina a los patrones de ruta: una condición if: de un hook que usa un patrón de un solo segmento dir/** ahora coincide solo con <cwd>/dir, no con cada directorio llamado dir en cualquier parte del árbol; escribe **/dir/** cuando realmente quieras indicar cualquier profundidad.⁷⁴ Al igual que con el cambio de v2.1.195, la corrección cambia una amplitud accidental por una intención declarada; audita cualquier condición de hook que dependiera silenciosamente del comportamiento anterior de cualquier profundidad.

Protocolo de entrada/salida de hooks

Los hooks reciben JSON en stdin con el contexto completo:

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

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

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

Tres tipos de garantías

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

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

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

Las garantías de seguridad evitan acciones peligrosas antes de que se ejecuten. Los hooks PreToolUse en Bash inspeccionan comandos y bloquean patrones destructivos con 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 suite de pruebas y bloquean el commit si fallan las comprobaciones de calidad:

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

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

Tipos de hooks más allá de 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 tienen costo de tokens.

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

Los hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo rápido de Claude. El modelo devuelve { "ok": true } para permitir o { "ok": false, "reason": "..." } para bloquear. Úsalos para evaluaciones matizadas que regex no puede expresar.

Los hooks de agente (type: "agent") generan un subagent con acceso a herramientas (Read, Grep, Glob) para una verificación de varios turnos. Son experimentales; prefiere los hooks de comandos para los gates de producción y reserva los hooks de agente para verificaciones que realmente requieran inspeccionar archivos reales o la salida de pruebas:

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

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

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

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

Hooks asíncronos

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

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

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

Dispatchers en lugar de hooks independientes

Ejecutar siete hooks que se disparan en el mismo evento, cada uno leyendo stdin de forma independiente, crea condiciones de carrera. Dos hooks que escriben simultáneamente en el mismo archivo de estado de JSON truncarán JSON. Todos los hooks posteriores que analicen ese archivo fallarán.²

La solución: un dispatcher por evento que ejecute hooks secuencialmente desde stdin almacenado en caché:

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

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

Depuración de hooks

Cinco técnicas para depurar hooks que fallan de forma silenciosa:¹⁴

1. Prueba los scripts de forma independiente. Envía una muestra de JSON mediante una tubería: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Usa stderr para la salida de depuración. El stderr con código de salida 2 se devuelve a Claude como mensaje de error. El stderr no bloqueante (salida 1, 3, etc.) aparece solo en 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 los hooks rápidos. Los hooks se ejecutan de forma síncrona. Mantén todos los hooks por debajo de 2 segundos, idealmente por debajo de 500 ms.

Streaming de eventos de hooks del lado de SDK

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

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

La serie de julio de 2026 de TypeScript SDK (v0.3.205–v0.3.208) hizo que el protocolo de streaming fuera más contractual.⁷⁰ Las interrupciones ahora devuelven recibos tipados: una interrupción confirma qué mensajes en cola siguen pendientes mediante UUID still_queued, y las sesiones anuncian la capacidad interrupt_receipt_v1 en system/init, de modo que un coordinador puede distinguir entre «la interrupción llegó» y «la interrupción se cruzó con un mensaje que ya estaba en curso». Los marcos command_lifecycle informan queued/started/completed/cancelled/discarded por mensaje: la primera respuesta propia a «¿qué ocurrió con el mensaje que envié?» sin inferirlo a partir de la transcripción. También se incorporaron superficies menores: un tipo AgentToolCompletedOutput para cargas útiles de finalización de subagents, y los callbacks canUseTool ahora pueden devolver {behavior: 'allow'} sin un campo updatedInput.

Una línea de esa serie es un mínimo de seguridad, no una función: v0.3.208 corrigió el caso en que un aborto del llamador durante un hook pendiente se convertía en éxito del hook; esto significaba que una herramienta controlada por un hook PreToolUse podía ejecutarse después de que el llamador hubiera abortado.⁷⁰ Si tu harness usa hooks del lado de SDK como gate de permisos y depende de abortar para cancelar trabajo en curso, considera v0.3.208 como la versión mínima; por debajo de ella, «abortado» no significaba de forma fiable «bloqueado». Python v0.2.127 (24 de julio de 2026) es el segundo bypass de esta forma en un mes: query() cerraba stdin en el primer marco result mientras los subagents en segundo plano seguían ejecutándose, por lo que sus llamadas de herramientas SDK-MCP fallaban con "Stream closed" y omitían por completo los hooks PreToolUse.⁸⁵ Nombra el patrón y vigílalo: la aplicación de hooks del lado de SDK falla de forma abierta en los bordes del ciclo de vida —aborto, desmontaje, cierre del flujo—, donde el transporte muere antes de recopilar el veredicto del hook, y falla silenciosamente, porque un hook omitido se ve exactamente igual que uno que aprobó. Fija ambas versiones mínimas de SDK y conserva la capa de hooks de shell como la aplicación que puedes demostrar.

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

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

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

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

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

Claude Code v2.1.136 añadió un nuevo nivel de denegación estricta al modo automático y corrigió un grupo de problemas de plugins y MCP que afectaban a los harnesses de larga duración:⁴⁰ - settings.autoMode.hard_deny. Reglas del clasificador de modo automático que bloquean incondicionalmente, sin importar la intención del usuario ni las excepciones permitidas. Se ubica por encima de los comparadores allow/deny existentes como una palanca de gobernanza no negociable. Úsalo para reglas que nunca deben anularse (force-push a main, archivos con secretos, acceso a bases de datos de producción), incluso cuando un operador haya aprobado la categoría más amplia en su configuración personal. - autoMode.classifyAllShell (v2.1.193). De forma predeterminada, el clasificador de modo automático solo revisa los comandos de shell que coinciden con patrones de ejecución de código arbitrario. Esta configuración dirige todos los comandos de Bash/PowerShell a través del clasificador —la postura de máxima cobertura para un harness gobernado—, y la misma versión muestra los motivos de denegación en la transcripción, la notificación y /permissions, lo que convierte bloqueos silenciosos en decisiones auditables. Codex reforzó la superficie equivalente en 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 pasar silenciosamente.⁶⁶ - Hook ask establece un mínimo para el clasificador (v2.1.211). La cuestión de precedencia entre hooks y modo automático ya está resuelta: un hook PreToolUse que devuelve una decisión de permiso ask fija el resultado final en una solicitud —el modo automático no puede elevarlo nuevamente a allow para comandos Bash sin sandbox.⁶⁹ Para un harness gobernado, esta es la capa 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 totalmente automáticas. Usa ask (no solo bloques con exit-2) para las operaciones en las que quieres una decisión humana en lugar de una negativa. - El modelo del clasificador se fija por sesión (v2.1.210). El clasificador de modo automático usa Sonnet 5 de forma predeterminada y queda fijado para la sesión, de modo que los cambios de modelo a mitad de sesión ya no alteran qué modelo realiza las clasificaciones de permisos.⁶⁹ La consistencia de la clasificación es una propiedad de gobernanza; esto elimina una fuente silenciosa de desviación. - Los servidores MCP ya no desaparecen después de /clear. Los servidores configurados en .mcp.json, plugins y conectores de claude.ai desaparecían silenciosamente del conjunto activo después de un /clear en la extensión de VS Code, el plugin de JetBrains y Agent SDK. La corrección llega en v2.1.136. Si viste que “MCP server X disappeared mid-session”, esta era la causa. - Pérdida del refresh token de MCP OAuth durante una actualización simultánea. Los usuarios con varios servidores MCP remotos ya no deberían necesitar volver a autenticarse a diario. Las escrituras de actualización simultánea se sobrescribían entre sí. - El modo Plan ahora bloquea correctamente las escrituras de archivos. Una regla allow coincidente de Edit(...) estaba eludiendo la protección de escritura del modo Plan. El modo Plan ahora se aplica sin importar las reglas allow. - Los hooks Stop y UserPromptSubmit de plugins ya no fallan a mitad de sesión. La limpieza de caché eliminaba archivos de versiones de plugins que la sesión en ejecución todavía usaba, lo que rompía específicamente estos dos eventos de hook. La corrección mantiene fijadas las versiones en uso. - Entrada skills en plugin.json. Configurar skills ocultaba la carpeta skills/ predeterminada del plugin. Ahora la entrada se compone correctamente, y apuntarla a una ruta de archivo genera un error explícito en lugar de fallar silenciosamente. - Variables de entorno del hook SessionStart mediante CLAUDE_ENV_FILE que quedaban obsoletas. Las variables exportadas por hooks SessionStart a través de CLAUDE_ENV_FILE quedaban obsoletas después de /resume o /clear. Corregido en v2.1.136. Las sesiones ahora vuelven a cargar el archivo de entorno en estos eventos.

Para los harnesses de gobernanza, los elementos operativamente interesantes son autoMode.hard_deny (nueva palanca) y la corrección de desaparición de MCP (fallo silencioso que interrumpía sesiones largas). Todo lo demás es una limpieza de calidad de vida.

Argumentos estructurados de hooks y continuación tras bloqueos (11 de mayo de 2026)

Claude Code v2.1.139 añadió dos detalles de hooks importantes para 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. Genera el comando directamente sin un shell, lo que elimina toda una clase de errores de comillas e inyección.

Usa continueOnBlock cuando un hook PostToolUse deba devolver su motivo de rechazo a Claude y continuar el turno en lugar de finalizar el flujo. Trátalo como una función de experiencia del operador, no como una evasión de seguridad. Una puerta de bloqueo debe seguir bloqueando el resultado inseguro.

La misma versión pasa 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 rutas relativas al proyecto a partir de ese valor, en vez de hacerlo desde cualquier 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 de protocolo: roots/list de MCP ahora incluye los directorios de trabajo adicionales de la sesión, con notificaciones roots/list_changed cuando cambian; así, un servidor que respeta las raíces de MCP sigue la forma real del espacio de trabajo con múltiples directorios en lugar de asumir un único directorio de proyecto.⁶⁸

Claude Code v2.1.140 es principalmente una versión de confiabilidad para operadores de harnesses: corrige que los hooks ConfigChange no se activaran ante cambios de configuración, cierra casos límite en los que disableAllHooks y allowManagedHooksOnly no se componían correctamente entre niveles de configuración, e impide que los diálogos de permisos expongan variables de entorno no intencionadas devueltas por resultados de hooks.⁴⁹ Esto hace más fiables los patrones de gobernanza existentes en esta sección; no requiere una nueva arquitectura de hooks.

Claude Code v2.1.141 añade un campo terminalSequence en la salida de hooks para notificaciones de escritorio, títulos de ventana y campanas sin una terminal de control.⁵⁰ Trátalo como señalización para el operador, no como aplicación de reglas. Las puertas de seguridad y calidad deben seguir comunicando fallos mediante el contrato normal de bloqueo: salida estructurada del hook más el comportamiento de salida que impide la acción insegura. La misma versión añade claude agents --cwd <path> para delimitar Agent View a un directorio, CLAUDE_CODE_PLUGIN_PREFER_HTTPS para instalaciones de plugins en entornos sin claves de GitHub SSH, y ANTHROPIC_WORKSPACE_ID para reglas de federación de identidad de carga de trabajo que abarcan más de un espacio de trabajo.⁵⁰ Son detalles de arquitectura para harnesses de equipo: vistas operativas más acotadas, menos supuestos sobre la instalación de plugins y delimitación explícita de tokens empresariales.

Claude Code v2.1.142 es más importante para la orquestación de sesiones en segundo plano que para la semántica de hooks.⁵¹ claude agents ahora puede despachar sesiones en segundo plano con indicadores explícitos de directorio, configuración, MCP, plugin, permiso, modelo y esfuerzo, en lugar de depender del estado de un wrapper. El modo rápido usaba Opus 4.7 de forma predeterminada en esa versión, con CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 como fijación para un harness con dependencia medida del comportamiento de Opus 4.6; a partir de v2.1.219, Opus 4.7 ya no está en modo rápido y /fast se aplica a Opus 5 y Opus 4.8.⁸⁴ El descubrimiento de SKILL.md de plugins en el nivel raíz y la visibilidad de LSP proporcionada por plugins reducen la ambigüedad de empaquetado. Las correcciones para MCP_TOOL_TIMEOUT, worktrees preexistentes de sesiones en segundo plano, suspensión/reactivación de daemons y limpieza posterior a actualizaciones, así como limpieza de caché de plugins, cierran brechas de confiabilidad que de otro modo parecen errores de orquestación.

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

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

Los hooks Stop/SubagentStop obtuvieron un canal de dirección. A partir de Claude Code v2.1.163, un hook Stop o SubagentStop puede devolver hookSpecificOutput.additionalContext para dar retroalimentación a Claude y mantener el turno en curso, sin que la respuesta se etiquete como error del hook. Antes de esto, la única palanca real de un hook Stop era el bloque exit-2, que se interpreta como un error y cuenta para el límite de bloqueos consecutivos. Para un harness con puertas de calidad, esta es la primitiva más limpia: un hook Stop que detecta “dijiste que terminaste, pero las pruebas fallan” ahora puede inyectar “esto es lo que aún falla, continúa” en lugar de bloquear de forma rígida. Usa el bloqueo para condiciones de detención genuinas y additionalContext para “aún no has terminado; esta es la razón”.

La mensajería entre sesiones ya no transporta autoridad prestada. v2.1.166 reforzó el caso de múltiples sesiones: los mensajes retransmitidos mediante SendMessage desde otra sesión de Claude ya no llevan la autoridad del usuario de origen, por lo que una sesión receptora rechaza las solicitudes de permisos retransmitidas y el modo automático las bloquea. Si tu orquestación hace que los agentes se envíen mensajes entre sí, trata un mensaje entrante como datos no confiables, no como una instrucción autenticada. Es el mismo principio que aplica la sección de seguridad a la salida de herramientas, extendido a la mensajería entre agentes. A partir de v2.1.199, Claude Code también detecta y advierte cuando un SendMessage se enruta incorrectamente porque dos agentes comparten el mismo nombre; es un complemento de confiabilidad para este límite de autoridad, ya que un mensaje que llega al agente equivocado con el mismo nombre constituye su propia clase de error de orquestación. Las sesiones ahora son pares de primera clase (v2.1.224+). La mensajería entre sesiones evolucionó de reforzar los relés a una superficie completa: SendMessage/ListAgents permiten que tus sesiones se descubran y envíen mensajes entre sí desde tus máquinas (macOS/Linux), con controles crossSessionInbound de aceptar/mantener/rechazar del lado receptor; además, los runners autohospedados permiten que las sesiones web y móviles de Claude Code se ejecuten en hardware que controlas. Para la arquitectura del harness, esto convierte «una sesión» en un nodo direccionable: el descubrimiento, la política de entrada y el límite de autoridad anterior ahora son primitivas de la plataforma, no scripts de buzón de correo (la guía de Claude Code documenta el contrato completo).⁸⁷ Junto a ello llega un cambio de postura: el modo automático pasa a ser el modo de permisos predeterminado en los planes Pro, Max y Team el 14 de agosto de 2026; un harness que cuenta con las solicitudes del modo Manual como respaldo humano en el circuito debe fijar defaultMode explícitamente en lugar de asumirlo.⁸⁷

La resiliencia del modelo se convirtió en una configuración de primera clase. 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 un turno se vuelve a intentar automáticamente una vez con el respaldo ante errores inesperados no reintentables de API. Para un harness autónomo de larga duración, esto transforma una interrupción transitoria del modelo principal en una degradación gradual, en lugar de una ejecución perdida. claude agents --json también añadió un campo waitingFor (v2.1.162) que muestra qué espera una sesión en segundo plano bloqueada, como una solicitud de permiso: una mejora de observabilidad para cualquier coordinador que sondee una flota de agentes.

Modo seguro para gobernanza de sala limpia y diagnóstico. Claude Code v2.1.169 añade una 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 el inverso del harness: una sala limpia deliberada. Ú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 incorrectamente, una skill se activa cuando no debería o un servidor MCP contamina el contexto, --safe-mode te da una línea base conocida y vacía con la que comparar. También es una primitiva de gobernanza: una forma de ejecutar el modelo sin ninguna de las autorizaciones persistentes que normalmente concede tu harness, algo importante cuando necesitas reproducir un resultado sin que influya ningún andamiaje definido por el operador.

Una nota sobre los niveles de modelos. A partir de Claude Code v2.1.197 (30 de junio de 2026), Claude Sonnet 5 es el modelo predeterminado distribuido para sesiones nuevas —contexto nativo de 1M, precio promocional de $2/$10 por MTok hasta el 31 de agosto—, reemplazando a Opus 4.8 como la opción predeterminada. Esta guía considera Opus 5 (claude-opus-5) como el valor predeterminado recomendado para agentes: el modelo en el que ejecutar harnesses autónomos salvo que elijas deliberadamente otra opción, porque los ciclos de agentes de largo horizonte y alto riesgo 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 el Opus 4.8 al que reemplaza), modo rápido a $10/$50 para aproximadamente 2,5× la velocidad predeterminada; además, Anthropic informa que más que duplica a Opus 4.8 en Frontier-Bench v0.1 y queda a menos de 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 caracteriza como «mucho más fuerte al verificar su trabajo e iterar con cuidado» constituyen la rara actualización que no necesita un argumento de costo para el trabajo con harnesses; la migración desde 4.8 es un cambio de id. Baja a Sonnet 5 para trabajo sensible al costo o de alto rendimiento, donde su relación velocidad-inteligencia gana. Por encima de Opus está Claude Fable 5 (claude-fable-5), lanzado el 9 de junio de 2026: un nuevo nivel descrito como el modelo más potente de Anthropic, un sistema de «clase Mythos» seguro para uso general, seleccionable en Claude Code v2.1.170 mediante /model claude-fable-5.⁶⁰ Recurre deliberadamente al nivel superior en las decisiones donde la profundidad de razonamiento en bruto justifique el costo, no como una configuración general para una flota. El cambio a Opus 5 tiene dos consecuencias de mantenimiento: Opus 4.7 queda fuera del modo rápido (/fast ahora se aplica a Opus 5 y Opus 4.8), y el respaldo Fable-5 del clasificador de modo automático —«el mejor modelo Opus disponible» desde v2.1.176— ahora se resuelve en Opus 5.⁸⁴

Codex lanzó multiagente v2. Codex CLI v0.137.0 conserva la elección de runtime en cada hilo, ofrece valores predeterminados más limpios para los seguimientos y los metadatos de los agentes generados (hide_spawn_agent_metadata ahora tiene el valor predeterminado true) y propaga eventos sin procesar del padre a los listeners secundarios. Su modelo de subagents sigue siendo explícito: tipos de agentes integrados default/worker/explorer, agentes personalizados definidos en TOML y controles de concurrencia (agents.max_threads con valor predeterminado de 6, agents.max_depth con valor predeterminado de 1). La misma versión añade una extensión de skills v1 con resolución del catálogo de skills por turno y nuevos eventos contribuidores del ciclo de vida al inicio de hilo/error de turno, reduciendo la brecha con la superficie de hooks/skills de Claude Code mientras conserva la postura de sandbox del kernel como límite predeterminado. Codex v0.138.0–v0.139.0 luego reforzó multiagente v2 para producción: las cargas útiles de mensajes entre agentes ahora están cifradas, un catálogo de configuración de agentes v2 más un LRU de residencia de agentes gestionan qué agentes permanecen residentes, y la concurrencia se cuenta por ejecución activa en lugar de por hilos generados, de modo que los agentes inactivos ya no consumen 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 a un agente en ejecución en vez de simplemente cerrar un identificador, y las advertencias de inicio de MCP generadas por un subagente ahora permanecen limitadas al hilo propietario en lugar de duplicarse en la transcripción del padre.⁶¹ Para quien construya orquestación del lado de Codex, estas son las diferencias entre una demostración y una flota: transporte de mensajes cifrado, residencia acotada, concurrencia contada por ejecución y advertencias que no se filtran a través del límite entre hilos. Codex v0.140.0 abrió luego una unión entre herramientas: /import incorpora de forma selectiva la configuración inicial, la configuración del proyecto y chats recientes desde Claude Code a Codex, y las sesiones pasaron a poder eliminarse permanentemente (codex delete / /delete, con salvaguardas de confirmación).⁶⁴ /import es el primer reconocimiento oficial de que los operadores se mueven entre harnesses: la configuración que construyes para uno ya no queda atrapada 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 a contenido nuevo. La compresión implica pérdidas. Las decisiones arquitectónicas documentadas en el turno 3 quizá 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 captura errores, decisiones y patrones entre sesiones. Cuando descubres que ((VAR++)) falla con set -e en bash cuando VAR es 0, lo registras. Tres sesiones después, cuando te encuentras con un caso límite similar de enteros en Python, la entrada de MEMORY.md hace visible el patrón.¹⁵

Auto Memory (v2.1.32+): Claude Code registra y recupera automáticamente el contexto del proyecto. Mientras trabajas, Claude escribe observaciones en ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory carga las primeras 200 líneas en tu prompt del sistema al iniciar la sesión. Mantenlo conciso y enlaza archivos de temas separados para notas detalladas.⁶ Desde 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 aparece al momento de escribir, en vez de manifestarse como entradas de memoria que desaparecieron sin aviso. Si tu harness automatiza escrituras de memoria, maneja ese error; la plataforma te está indicando que el archivo necesita curación, no un reintento.

Curación de memoria por encima del volumen de memoria (mayo de 2026): Un preprint reciente de arXiv sobre cooperación entre agentes LLM plantea el recuerdo ampliado como un posible modo de falla: en los experimentos de los autores, un historial visible más extenso degradó la cooperación en 18 de 28 configuraciones de juegos de modelos.⁴⁸ Tómalo como una advertencia de diseño, no como una ley definitiva. La regla de producción ya es suficientemente clara: mantén MEMORY.md breve, enlaza los detalles y coloca resúmenes listos para tomar decisiones en los handoffs. Los volcados de transcripciones sin procesar, los registros de herramientas y las fuentes extensas de recuperación deben ir en almacenamiento consultable, no automáticamente en el prompt activo.

Estrategia 2: Compactación proactiva

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

Cuándo compactar: - Después de completar una subtarea diferenciada (función implementada, error corregido) - Antes de comenzar una nueva área de la base de código - Cuando Claude comienza a repetir u 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é de prompts. Mueve una sesión a un nuevo directorio de trabajo a mitad de la sesión sin romper la caché acumulada durante el turno.⁶⁰ Antes de esto, cambiar de directorio implicaba una sesión nueva y una caché fría. Para una sesión de larga duración que pasa de un repositorio a uno hermano —algo común en trabajos con monorepositorios y múltiples servicios—, /cd mantiene intacto el costoso prefijo almacenado en caché mientras redirige el contexto del sistema de archivos.

Estrategia 3: Handoffs de sesión

Para tareas que abarcan varias sesiones, crea documentos de handoff que capturen el estado completo:

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

La estructura Estado/Archivos/Decisión/Bloqueado/Siguiente proporciona a la sesión sucesora todo el contexto con un costo mínimo de tokens. Iniciar una nueva sesión con claude -c (continuar) o leer el documento de handoff permite pasar directamente a la implementación.¹⁵

Estrategia 4: Iteración con contexto nuevo (el bucle Ralph)

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

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

Compáralo con una única sesión larga:

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

El enfoque de contexto nuevo por iteración intercambia una sobrecarga del 15-20 % para el paso de orientación (leer archivos de estado, revisar el historial de git) por recursos cognitivos completos en cada iteración.¹⁶ El cálculo de costo-beneficio: para sesiones de menos de 60 minutos, una sola conversación es más eficiente. Más allá de los 90 minutos, el contexto nuevo produce resultados de mayor calidad pese a la sobrecarga.

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

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

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

Dreaming está en Research Preview, por lo que su comportamiento puede cambiar. Los patrones de handoffs de sesión y CLAUDE.md documentados anteriormente siguen siendo el mecanismo de memoria autorizado para harnesses autohospedados.

Antipatrones

Leer archivos completos cuando necesitas 10 líneas. Una sola lectura de un 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 extensos en el contexto. Después de depurar un error, tu contexto contiene más de 40 rastros de pila de iteraciones fallidas. Un solo /compact después de corregir el error libera ese peso muerto.

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

Patrones de subagents

Los subagents son instancias especializadas de Claude que gestionan tareas complejas de forma independiente. La mayoría comienza con un contexto limpio (sin contaminación de la conversación principal); la excepción es el tipo fork que se describe a continuación, que hereda todo deliberadamente. Operan con las herramientas especificadas y devuelven los resultados en forma de resúmenes. Los resultados de la exploración no saturan 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 git worktrees temporales, lo que proporciona una copia completa y aislada del repositorio:⁵

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

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

El aislamiento mediante worktree es esencial para el trabajo experimental que podría romper 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: precisamente el fallo que este mecanismo existe para evitar.⁶⁹ Si dependes de isolation: worktree como límite de seguridad y no como simple comodidad, considera v2.1.210 como la versión mínima. El cambio complementario de permisos actúa en sentido contrario: desde v2.1.211, las reglas de “permitir siempre” persisten en la raíz del repositorio entre distintos worktrees, por lo que una regla aceptada dentro de un worktree se aplica a los worktrees hermanos del mismo repositorio.⁶⁹ Esa es la ergonomía adecuada para agentes que trabajan en paralelo mediante worktrees, pero significa que un permiso concedido durante un experimento desechable sobrevive al experimento; concédelo teniendo en cuenta todo el repositorio, no solo el worktree que tienes delante.

v2.1.216 terminó el trabajo y llevó el aislamiento mediante worktree de una 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 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. Todas esas vías de escape ahora están cerradas. La misma versión corrigió que las sesiones de worktree terminaran ocasionalmente en el 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 duros. El patrón de las cuatro correcciones es el mismo: un límite de aislamiento debe resistir las redirecciones deliberadas —sobrescrituras del 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 relevante y devuelve un resumen. El contexto principal se mantiene limpio.

El Recursion Guard

Sin límites de generación, los agentes delegan en otros agentes que, a su vez, delegan en más 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 crítica: usa presupuestos de generación, no solo límites de profundidad. Los límites basados en profundidad rastrean las cadenas padre-hijo (bloqueadas al alcanzar una profundidad de 3), pero no detectan la amplitud: 23 agentes con profundidad 1 siguen teniendo una “profundidad de 1”. Un presupuesto de generación registra el total de hijos activos por padre y lo limita a un máximo configurable. El modelo de presupuesto 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 la profundidad de anidamiento ha cambiado 3 veces; no construyas sobre él. Claude Code v2.1.172 (10 de junio de 2026) permitió que los sub-agents generaran sus propios sub-agents, con hasta 5 niveles de profundidad, cuando antes la delegación estaba limitada, 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 límite a 1 y desactivó de forma predeterminada la generación anidada. Después, v2.1.219 (24 de julio de 2026) se quedó en 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.”⁸⁴ Primero 5, luego 1 y después 3; los 2 últimos cambios ocurrieron en un plazo de 3 días.

La interpretación útil no es que alguno de esos números sea el correcto, sino que la plataforma aún busca el valor predeterminado adecuado, lo que convierte “lo que venga de fábrica” en una mala opción para que un harness la herede. Trata la profundidad de anidamiento como una partida presupuestaria explícita: establece CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH en la profundidad que tu arquitectura realmente necesite —para la mayoría de las orquestaciones será 1 o 2—, de modo que una actualización no pueda cambiar silenciosamente hasta qué nivel delega tu flota. El argumento de fondo no cambia pese a toda 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 debe presupuestarse, no una capacidad que debas perseguir. El recursion guard anterior evita que un árbol profundo se ramifique hasta producir cientos de agentes activos, sin importar hacia dónde cambie después el valor predeterminado; además, un límite establecido por ti es el único número de profundidad que seguirá significando lo que crees después de la próxima versión.

El modo automático ahora evalúa las generaciones 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 generación de subagents antes de iniciar el subagent, no solo cuando comienza a realizar acciones.⁶³ Antes, se podía generar un subagent para solicitar una acción que la sesión principal no tenía permitido realizar; la propia generación servía como vía de elusión. La evaluación al generar significa que el recursion guard y el modelo de permisos por fin convergen: no se puede usar un hijo como paso de blanqueo para una acción prohibida por la política.

La plataforma ahora incluye un presupuesto de generación nativo. Claude Code v2.1.212 (julio de 2026) añadió mecanismos propios de protección contra bucles descontrolados: de forma predeterminada, las sesiones tienen un límite de 200 generaciones 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 generación que esta sección documenta como scripting de usuario desde v1.0 ahora forma parte de la plataforma, lo que valida el modelo de presupuesto por encima del modelo de profundidad. Sin embargo, observa la calibración: 200 generaciones es un orden de magnitud superior al presupuesto de 12 agentes de la configuración anterior. Los límites nativos son fusibles contra un bucle realmente descontrolado, no presupuestos ajustados a tu arquitectura. Conserva el mecanismo de protección de usuario para los presupuestos por padre, el seguimiento de profundidad y los límites que correspondan a lo que tu orquestación debería hacer; deja que el límite de la plataforma detenga lo que consiga escapar.

El conjunto propio de mecanismos de protección ahora abarca 4 ejes. Tres de ellos respaldan exactamente lo que rastrea el mecanismo de protección de usuario de esta sección: generaciones 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 cuya inestabilidad está demostrada) y ejecución simultánea (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 solo workflow planificado. Se distribuye con la pauta predeterminada de “intentar usar menos de 15 agentes” y puede configurarse desde cualquier archivo de configuración mediante workflowSizeGuideline (se aborda en la sección sobre la herramienta Workflow que aparece más adelante). El patrón de presupuesto de generación ahora cuenta con respaldo en cada eje para el que fue diseñado, además de uno para el que no lo fue.

La observación sobre la calibración sigue siendo válida, aunque de manera desigual. Las 200 generaciones y los 20 agentes simultáneos son fusibles: superan por un orden de magnitud el presupuesto de deliberación de 12 agentes de la configuración anterior y están dimensionados para detener un bucle descontrolado, no para dar forma a una arquitectura. La pauta de amplitud es el primer número nativo que se encuentra en el mismo rango que un presupuesto real: 15 agentes por workflow está justo al lado de los 12 de esta guía; es lo bastante cercano como para que adoptar el valor predeterminado de la plataforma no te cueste nada y para que discrepar de él exija una razón concreta. Configura los 3 fusibles con valores que puedas defender; ajusta la pauta de amplitud a la forma de la orquestación que pretendías construir.

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

Agent Teams coordina varias instancias de Claude Code que trabajan de manera 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 en lugar de subagents:

Agent View y Goal Loops (mayo de 2026)

Claude Code v2.1.139 añadió Agent View, una interfaz 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 distribuir y gestionar muchas sesiones, ver qué está haciendo cada una e identificar cuáles necesitan intervención del operador.⁴³ Esto proporciona al trabajo con múltiples agentes una vista operativa que los resúmenes finales no pueden ofrecer.

Usa Agent View cuando lleves un patrón de subagents o de equipo a producción: revisa qué sesiones están bloqueadas, cuáles siguen ejecutándose y si la distribución del trabajo coincide con la arquitectura prevista. No lo consideres una prueba de calidad. Es 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 que se cumpla, incluso en el uso interactivo, con -p y mediante Remote Control.⁴² Trata /goal como un completion loop limitado a la sesión, no como sustituto de gates deterministas. Resulta útil para mantener a un agente concentrado en un objetivo, pero las pruebas, las verificaciones de citas, las comprobaciones de despliegue y los hooks de seguridad deben seguir respaldados por comandos o scripts cuando un fallo deba bloquear el proceso.

Herramienta Workflow (v2.1.147+)

Los workflows dinámicos de Claude Code son una función disponible y activada de forma predeterminada: desde v2.1.154, orquestan decenas o cientos de agentes en segundo plano, se supervisan mediante /workflows y cuentan con un control “Dynamic workflow size” en /config (v2.1.202), además de una clave de configuración workflowSizeGuideline cuya pauta predeterminada es mediana: intenta usar menos de 15 agentes salvo que se indique lo contrario (v2.1.219). La función debutó una versión antes como la herramienta Workflow desactivada de forma predeterminada en v2.1.147 y protegida por CLAUDE_CODE_WORKFLOWS=1; la época de esa flag ya quedó atrás, pero la idea arquitectónica que planteó sigue vigente.⁵² Proporciona a Claude Code una primitiva de orquestación propia para flujos que antes requerían scripts de distribución personalizados, estado en un mailbox y convenciones de coordinación entre subagents.

No elimines el harness que la rodea. Un Workflow puede estructurar la ejecución, pero no sustituye tu modelo de seguridad. Conserva los hooks PreToolUse y PostToolUse como capa de bloqueo, mantén presupuestos de generación o 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.

Los workflows dinámicos ahora incluyen una postura sobre la amplitud (v2.1.219). De forma predeterminada, los workflows dinámicos usan una pauta de tamaño mediano —“intenta usar menos de 15 agentes”—, con otros tamaños y una opción sin restricciones disponibles en Dynamic workflow size dentro de /config; la pauta actual también 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 —incluidas las configuraciones administradas y las del proyecto, y desde v0.3.219 forma parte de los tipos de configuración de TypeScript SDK—, por lo que la amplitud de la orquestación se convierte en algo que un equipo o una organización puede estandarizar, en lugar de algo que cada operador debe redescubrir.⁸⁵ Configúrala a nivel del proyecto para representar 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 una configuración ausente si no sabes el motivo; además, como la pauta orienta al planificador en lugar de controlar la ejecución, pertenece a la columna de forma, no a la de seguridad. El límite de generación sigue siendo el responsable de contener una amplitud descontrolada.

Conviene conservar la idea de que este es un cuarto eje propio de protección —la amplitud de la orquestación, junto con el número de generaciones, la profundidad de anidamiento y la ejecución simultánea— y el primero que Anthropic ha calibrado con un tamaño de trabajo plausible, en lugar de tratarlo como un fusible contra desbordamientos. Quince agentes por workflow pertenece al 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 ofrecer estas cifras.

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

Claude Code v2.1.212 reformuló 2 primitivas de orquestación.⁶⁹ /fork ahora crea una nueva sesión en segundo plano a partir del estado actual de la conversación: la línea bifurcada se ejecuta de forma independiente mientras la original sigue trabajando, y el comportamiento anterior dentro de la sesión pasó a llamarse /subtask. La diferencia es importante para diseñar 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 una generación de un Ralph-loop que a un subagent. Si tus scripts del harness suponían que /fork permanecía dentro de la sesión, ahora distribuirán trabajo en segundo plano.

La misma versión envía automáticamente a segundo plano las llamadas lentas de MCP: una llamada a una herramienta de MCP que tarde más de 2 minutos pasa automáticamente a ejecutarse en segundo plano (ajusta el umbral con CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Un servidor lento de MCP ya no bloquea el agentic loop, pero esto también significa que “la herramienta devolvió un resultado” y “el turno continuó” ya no son el mismo evento, por lo que los hooks o scripts que suponían 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 headless, v2.1.211 añadió --forward-subagent-text (variable de entorno: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), que reenvía el texto del asistente de los subagents a la salida stream-json.⁶⁹ Ahora, un proceso coordinador que consuma el flujo del padre puede observar directamente el progreso de los subagents, en lugar de sondear transcripciones o esperar el resumen final: es el complemento de observabilidad para los subagents que se ejecutan en segundo plano de forma predeterminada. v2.1.219 lo extendió más allá del primer nivel: los subagents generados con una profundidad de 2 o superior ahora también aparecen en el flujo reenviado, identificados mediante el id de tool_use del Agent que los generó.⁸⁴ Esa clave es la parte sobre la que debes construir. Con el anidamiento nuevamente activado de forma predeterminada, un flujo plano de texto de subagents resulta ambiguo: el id indica al coordinador qué padre produjo cada hijo, por lo que el árbol de delegación puede reconstruirse a partir del flujo en lugar de inferirse. Si tu consumidor del flujo fue escrito para un solo nivel de subagents, ahora verá texto de agentes cuya existencia desconocía; agrupa por el id de tool_use que inició la generación, en lugar de suponer que cada línea reenviada pertenece a un hijo directo.

Orquestación Multi-Agent

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

Orquestación entre herramientas (abril de 2026): Google liberó como código abierto Scion el 7 de abril: un hipervisor multiagente que ejecuta Claude Code, Gemini CLI y otros “agentes profundos” como procesos simultáneos, cada uno con su contenedor, git worktree y credenciales aislados. Se ejecuta de forma local, en un hub o en Kubernetes. Su filosofía explícita es: “aislamiento por encima de restricciones”; los agentes operan con gran autonomía dentro de límites aplicados en la capa de infraestructura, no en el prompt.²⁵ Esto extiende directamente el argumento de aislamiento de subagents entre 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 subagents entre herramientas con aislamiento de worktree + credenciales por agente.

El debate no es una solución milagrosa: El grupo de investigación M3MAD-Bench (inicios de 2026) descubrió que el debate multiagente se estanca y puede ser manipulado mediante consensos engañosos: los argumentos válidos pierden cuando otros agentes afirman con seguridad una respuesta incorrecta.²⁶ Tool-MAD mejora esto al proporcionar a cada agente acceso heterogéneo a herramientas y usar puntuaciones de Fidelidad/Relevancia en la etapa de evaluación. Si estás creando una orquestación basada en debate, invierte en (a) heterogeneidad de herramientas por agente y (b) puntuación cuantitativa del evaluador, en lugar de asumir que más agentes = mejores respuestas.

Orquestación Multiagente Gestionada y Outcomes (beta pública)

Si no quieres crear 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 partes y delegue cada una a un especialista con su propio modelo, prompt y herramientas.”³⁵ Los especialistas “trabajan en paralelo en un sistema de archivos compartido y contribuyen al contexto general del agente líder.”³⁵

El trazado 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 es el éxito y el agente trabaja para lograrlo. Un evaluador independiente examina el resultado según tus criterios en su propia ventana de contexto, por lo que no recibe influencia del razonamiento del agente.”³⁵ Esta es la versión de servicio gestionado del patrón de validación de dos puertas documentado más adelante en esta sección: la rúbrica sustituye la puerta escrita a mano y el evaluador independiente sustituye al validador de consenso.

La deliberación autohospedada sigue siendo la respuesta adecuada cuando la validación debe integrarse con tu propia superficie de hooks (bloqueo PreToolUse, semántica de código de salida, dispatchers personalizados) o cuando el harness debe ejecutarse sin dependencias externas. Multiagent gestionado es la respuesta adecuada 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

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

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

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

El desencadenante de confianza

No todas las tareas necesitan 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 conocimientos especializados?
3. Riesgo - ¿La decisión es reversible?
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 en documentación solo necesitan 0,50. Esto evita sobrediseñar tareas simples y, al mismo tiempo, garantiza que las decisiones riesgosas reciban escrutinio.⁷

La máquina de estados

Siete fases, cada una condicionada por la anterior:⁷

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

RESEARCH: Agentes independientes investigan el tema. Cada agente recibe una persona diferente (arquitecto técnico, analista de seguridad, ingeniero de rendimiento y otras). El aislamiento de contexto garantiza que los agentes no puedan ver los hallazgos de los demás durante la investigación.

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

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

La arquitectura de validación de dos puertas

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

Puerta 1: validación de consenso (hook PostToolUse). Se ejecuta inmediatamente después de que cada agente de deliberación termina: 1. La fase debe haber alcanzado al menos RANKING 2. Deben haber terminado al menos 2 agentes (configurable) 3. La puntuación de consenso cumple el umbral adaptativo de la tarea 4. Si algún agente disintió, las inquietudes deben estar documentadas

Puerta 2: Pride Check (hook Stop). Se ejecuta antes de que la sesión pueda cerrarse: 1. Métodos diversos: se representan múltiples personas únicas 2. Transparencia de contradicciones: los disensos tienen motivos documentados 3. Gestión de complejidad: se generaron al menos 2 alternativas 4. Confianza del consenso: clasificada como sólida (por encima de 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 corresponden a cómo ocurren realmente los fallos: algunos son inmediatos (puntuación deficiente) y otros son graduales (baja diversidad, falta de documentación de disensos).⁷

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 personas disidentes toman mejores decisiones que los grupos que alcanzan acuerdos rápidos. La persona disidente no necesita tener razón. El acto de discrepar obliga a la mayoría a examinar suposiciones que, de otro modo, omitiría.¹⁸

Wu et al. probaron si los agentes LLM pueden debatir de verdad y descubrieron que, sin incentivos estructurales para discrepar, los agentes convergen hacia la respuesta inicial que parece más segura, 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 postura, la autorreflexión no puede generar contraargumentos novedosos, lo que hace estructuralmente necesaria la evaluación multiagente.²⁰

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

Detección de acuerdos falsos

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

Agrupamiento de puntuaciones: Que todos los agentes puntúen dentro de 0,3 puntos en una escala de 10 puntos indica contaminación de contexto compartido, en lugar de una evaluación independiente. Cuando cinco agentes que evaluaban una refactorización de autenticación calificaron el riesgo de seguridad entre 7,1 y 7,4, volver a ejecutar con aislamiento de contexto nuevo dispersó las puntuaciones entre 5,8 y 8,9.

Disenso estereotipado: Los agentes copian el lenguaje de inquietudes de los demás en lugar de generar objeciones independientes.

Ausencia de perspectivas minoritarias: Aprobación unánime de personas con prioridades en conflicto (un analista de seguridad y un ingeniero de rendimiento rara vez coinciden en todo).

El detector de conformidad detecta los casos evidentes (aproximadamente el 10-15% de las deliberaciones en las que los agentes convergen demasiado rápido). Para el 85-90% restante, las puertas de consenso y Pride Check proporcionan validación suficiente.

Lo que no funcionó en la deliberación

Rondas de debate de forma libre. Tres rondas de texto de ida y vuelta para una discusión sobre índices de base de datos produjeron 7.500 tokens de debate. Ronda 1: desacuerdo genuino. Ronda 2: posturas reformuladas. Ronda 3: argumentos idénticos con palabras distintas. La puntuación estructurada por dimensiones reemplazó el debate libre, reduciendo el costo en un 60% y mejorando la calidad de la clasificación.⁷

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

Costo de la deliberación

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

Con los precios actuales de Opus 5 ($5/$25 por MTok), una deliberación de 3 agentes cuesta aproximadamente $0,23-0,30. Una deliberación de 10 agentes cuesta $0,75-1,00. El sistema activa la deliberación en aproximadamente el 10% de las decisiones, por lo que el costo amortizado en todas las decisiones es de $0,08-0,10 por sesión. (Las ediciones anteriores indicaban 3 veces estas cifras, calculadas con los precios heredados de Opus 4.x de $15/$75). Que valga la pena 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 horizonte largo de Opus 4.7 (abril de 2026)

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

• Resiliencia ante fallos de herramientas: Opus 4.7 continúa tras fallos de herramientas que detenían sesiones de Opus 4.6. Puedes reducir —pero no eliminar— los wrappers defensivos de reintento en el código de subagents. Conserva las protecciones a nivel de hook; reduce la estructura de prompts de «si la herramienta falla, inténtalo de nuevo tres veces».
• Nivel de esfuerzo xhigh: Se introdujo junto con Opus 4.7 y ahora es compatible con los modelos Opus actuales (Opus 4.8 se lanzó con él como /effort xhigh en v2.1.154; Opus 5 lo hereda). Se sitúa entre high y max. Es el valor predeterminado recomendado para cargas de trabajo de programación y agentic. En subagents de larga duración, xhigh supera de forma significativa a high con un costo de tokens subproporcional. max sigue siendo la elección correcta para razonamiento difícil de una sola ejecución; xhigh es mejor para tareas sostenidas.
• Límite de presupuesto de tokens: Configurable por ejecución de agente mediante output_config.task_budget (encabezado beta task-budgets-2026-03-13). El modelo ve una cuenta regresiva en curso y ajusta el alcance del trabajo al presupuesto de forma elegante, en lugar de quedarse sin tokens inesperadamente. Úsalo en bucles agentic cuando busques un gasto de tokens predecible sin sacrificar calidad en prompts cortos.
• Conciencia de necesidades implícitas: El primer modelo Claude que superó las pruebas de «necesidad implícita»: reconoce cuándo la solicitud literal del usuario no especifica suficientemente lo que en realidad necesita. Esto hace menos necesaria la sección de «reglas de aclaración» de CLAUDE.md. Si tu CLAUDE.md tiene 200 líneas de barreras de protección tipo «considera también X cuando el usuario pida Y», elimina las que ahora están cubiertas de forma nativa.

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

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

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

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

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

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

Dos cambios de v2.1.207 importan para las implementaciones de producción.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permite que los entornos administrados inicien el proceso de Claude Code mediante un binario wrapper corporativo: el punto de integración para agentes de endpoint, verificaciones de políticas al iniciar y entornos donde cada proceso debe ejecutarse bajo un supervisor obligatorio. Si antes tu empresa simulaba esto con alias de shell o scripts de launcher bifurcados, esta es la integración compatible.

La misma versión redujo la sobrecarga de ejecución donde los harnesses más la perciben: hasta 7× más rápidas las rondas de uso de herramientas en sesiones con un alto número de herramientas MCP, y transcripciones de sesión 79× más pequeñas.⁶⁸ Esto suaviza —sin revertir— la guía de Costo como arquitectura: CLI-first sigue ganando para operaciones sin estado de una sola ejecución, pero un harness que lleva decenas de herramientas MCP ya no paga la penalización por ronda que pagaba en primavera, y el almacenamiento de transcripciones deja de ser un costo oculto de ejecuciones autónomas largas.

El quality loop

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

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

El evidence gate

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

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

Autoridad humana de merge

Un estudio de arXiv de mayo de 2026 sobre 29.585 ciclos de vida de pull requests de agentes de IA separa la autonomía operativa de la gobernanza de merge.⁴⁷ La lección arquitectónica útil es simple: los agentes pueden iniciar trabajo, continuar ramas, abrir PRs, revisar trabajo y resumir riesgos, mientras que la autoridad de merge sigue siendo 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 merges, lanzamientos y operaciones destructivas de repositorio, salvo que la organización cuente con una política de automatización auditada por separado. Cuando la automatización ejecute un merge, conserva registros que distingan al ejecutor de la persona o política que lo autorizó.

Patrones de manejo de errores

Escrituras atómicas de archivos. Varios agentes que escriben simultáneamente en el mismo archivo de estado corrompen JSON. Escribe en archivos .tmp y luego usa mv de forma atómica. El sistema operativo garantiza que mv es atómico en el mismo sistema de archivos.¹⁷

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

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

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

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

Clasificación de radio de impacto

Clasifica cada acción del agente según su radio de impacto y aplica la barrera correspondiente:²

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

Especificación de tareas para ejecuciones autónomas

Las tareas autónomas 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 ser verificables por máquina: aprobación o fallo de pruebas, salida de linter, códigos de estado HTTP y verificaciones de existencia de archivos. Una tarea inicial que pidió al agente «escribir pruebas que pasen» produjo assert True y assert 1 == 1. Técnicamente correcto. En la práctica, inútil.¹⁶

Modos de fallo que debes vigilar

Un rastro de sesión concreto

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

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

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

3. El agente llama a Bash para ejecutar pruebas. Se activa PreToolUse:Bash. Verificación de credenciales, validación de sandbox, detección de proyecto. 90 ms. Se ejecutan las pruebas. Se activa PostToolUse:Bash: se registra el heartbeat de actividad, verificación de desviación.

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

5. El agente termina la historia. Se activa Stop. Las comprobaciones de quality gate preguntan: ¿el agente citó evidencia? ¿Usó lenguaje evasivo? ¿Hay comentarios TODO en el diff? Si falla alguna comprobación, salida 2 y el agente continúa.

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

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

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

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

Caso de estudio: procesamiento nocturno de PRD

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

Las dos filtraciones de credenciales exigieron rotar claves de API y auditar servicios posteriores: aproximadamente 4 horas de respuesta a incidentes. La sobrecarga del harness que evitó el equivalente fue de 2,4 segundos de bash por historia. La tasa de finalización falsa bajó 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 son paralelos —y amplían— el enfoque de Evidence Gate de esta guía:

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

El turno sin estado y la identidad autodeclarada de MCP. La especificación de MCP completó su transición a un núcleo sin estado (SEP-2575) con la revisión del 28 de julio de 2026, ahora la especificación vigente, que elimina el intercambio de inicialización con estado que antes transportaba 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 la respuesta _meta, y clientInfo pasa a ser opcional en las solicitudes.⁷¹ La parte relevante para la seguridad es lo que la especificación dice sobre la confianza: esta identidad es autodeclarada y no verificada; solo para visualización y registro; y NO DEBERÍA impulsar decisiones de seguridad. Si tu harness basa allowlists, reglas de permisos o auditorías basadas en registros en el nombre declarado de un servidor MCP, ese nombre es una afirmación, no una credencial; vincula la confianza al transporte y la configuración (qué servidor configuraste tú en qué endpoint), nunca a lo que el servidor dice ser. La revisión sin estado se lanzó según lo previsto el 28 de julio de 2026 (server/discover obligatorio, negociación de versión del protocolo mediante _meta, encabezado Streamable HTTP); la guía de confianza anterior describe el comportamiento publicado.

Herramientas de sandbox para skills: Para los equipos que tratan las skills como una superficie de ataque, SandyClaw de Permiso (lanzado el 2 de abril de 2026) ejecuta skills en un sandbox dedicado y entrega veredictos respaldados por evidencia mediante detección 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 (habilitado mediante settings.json o el comando /sandbox) que restringe el acceso a la red y las operaciones del sistema de archivos mediante aislamiento a nivel de sistema operativo (seatbelt en macOS, bubblewrap en Linux). Cuando está habilitado, el sandbox evita que el modelo realice solicitudes de red arbitrarias o acceda a archivos fuera del directorio del proyecto. Sin sandboxing, Claude Code utiliza un modelo basado en permisos donde apruebas o deniegas llamadas individuales a herramientas.¹³

Nivel mínimo de seguridad de mayo de 2026. Claude Code v2.1.149 corrigió una omisión de permisos del directorio de trabajo en PowerShell, varias brechas en el análisis de permisos relacionadas con reglas de allow de PowerShell y variables obsoletas, y un error en la allowlist de escritura del sandbox para git worktree que cubría toda la raíz del repositorio principal en lugar de solo los elementos internos compartidos de git.⁵³ Si tu harness permite PowerShell o agentes aislados con worktree, considera v2.1.149+ como el mínimo y mantén las reglas de shell acotadas. Las excepciones amplias de PowerShell(*) y de escritura en todo el repositorio son atajos de orquestación, no límites de seguridad.

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

Nivel mínimo posterior de OpenAI Agents SDK (v0.17.3). La línea 0.17.1-0.17.3 añadió más refuerzo para sandbox y sesiones: límites de extracción de archivos, validación de subrutas de GitRepo, errores más claros del proveedor de sandbox, credenciales de puntos de montaje fuera de los comandos del sandbox, rechazo de raíces relativas del espacio de trabajo sandbox y manejo de estados terminales de Vercel-sandbox.⁵⁴ Si utilizas sandboxes alojados por OpenAI o respaldados por proveedores, en lugar de solo hooks de Claude Code, considera 0.17.3 como el mínimo 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 «How we contain Claude across products» (25 de mayo de 2026) es la propia articulación del proveedor de los principios que esta sección enseña de forma fragmentada: el sandbox a nivel de configuración anterior, el mínimo de aislamiento con worktree y la postura de tratar todo como no confiable.⁸¹ Su movimiento central consiste en asignar la fuerza de la contención a la superficie del producto, y ese mapeo es en sí la lección: no existe un único diseño de aislamiento correcto, solo un aislamiento adecuado para quién supervisa y qué puede salir mal.

• Contenedores gVisor efímeros (claude.ai). La ejecución del lado del servidor se realiza en contenedores gVisor sobre infraestructura aislada, con un sistema de archivos efímero por sesión. El modelo de amenazas es el aislamiento de infraestructura y tenants: la máquina del usuario nunca es accesible, así que no hay nada local que defender.
• Sandboxing del sistema operativo con intervención humana (Claude Code). El patrón descrito en el párrafo del sandbox anterior, expresado como política: Seatbelt en macOS y bubblewrap en Linux, con lecturas permitidas, escrituras limitadas al espacio de trabajo y red denegada por defecto; la persona aprueba lo que el límite no cubre. Anthropic liberó el runtime como código abierto (sandbox-runtime) para que el límite sea auditable. La publicación es franca sobre el eslabón débil: aproximadamente el 93% de los avisos de permisos se aprueban, y el clasificador de auto mode —que detecta aproximadamente el 83% de los comportamientos demasiado entusiastas antes de la ejecución y reduce los avisos de aprobación en un 84%— existe precisamente porque la fatiga de aprobación es una propiedad de seguridad, no una queja de UX. Esa es la postura de check-layer que esta guía ha seguido desde v2.1.193.
• VM selladas (Claude Cowork). Máquinas virtuales completas en hipervisores de la plataforma —Apple Virtualization framework en macOS, HCS en Windows— con solo el espacio de trabajo seleccionado y la carpeta .claude montados; nada más del host es visible. Las credenciales nunca entran en la VM: permanecen en el keychain del host y cada sesión recibe un token acotado y revocable de manera independiente. Un proxy MITM defensivo dentro de la VM lo aplica, dejando pasar solo solicitudes que llevan el propio token de sesión aprovisionado de la VM; una clave incorporada por un atacante se rechaza en el límite, porque solo la VM conoce su procedencia.

Los principios de diseño bajo la taxonomía son la parte transferible. Primero contiene en la capa de entorno; después dirige en la capa de modelo: toda defensa probabilística tiene una tasa de fallos distinta de cero, por lo que los límites deterministas deben capturar lo que la dirección a nivel de prompt no detecta; es el argumento de esta guía de que los hooks garantizan la ejecución, reformulado por el proveedor. Ajusta la fuerza del aislamiento a la capacidad de supervisión del usuario: un desarrollador puede evaluar un comando bash antes de aprobarlo; un trabajador del conocimiento no, por eso Code recibe un diálogo de permisos y Cowork recibe una VM sellada. Prefiere primitivas probadas en batalla antes que código de aislamiento personalizado: los hipervisores, seccomp y runtimes de contenedores sobrevivieron mejor al escrutinio adversarial que los propios proxies de allowlist y analizadores de configuración personalizados de Anthropic. Trata la configuración local del proyecto y las salidas de herramientas como no confiables: la instrucción de la publicación es tratar la apertura de proyectos y carga de configuración como cualquier solicitud entrante de internet, y la salida de herramientas como una superficie de ataque incluso cuando la herramienta es confiable; es la misma postura que esta guía aplica a mensajes entre agentes, contenido leído por subagents e identidad autodeclarada de MCP. Mantén las credenciales fuera del sandbox: tokens acotados, revocables y por sesión, en lugar de claves ambientales que el agente podría filtrar.

La superficie de configuración está alcanzando el primer principio (v2.1.219). «Primero contiene en la capa de entorno» es fácil de respaldar y ha sido incómodo de configurar realmente, porque el sandbox de Claude Code resolvía lo que sus reglas no cubrían preguntando; y un aviso de permisos es una defensa probabilística disfrazada de determinista, como reconoce la cifra de aprobación del 93% anterior. sandbox.network.strictAllowlist elimina la pregunta para el tráfico saliente: al configurarlo, la solicitud de un comando sandboxed a un host que no está en la allowlist se deniega directamente en lugar de solicitar confirmación.⁸⁴ Combínalo con sandbox.filesystem.disabled de v2.1.216 y ambas configuraciones conforman una postura, no una pila de interruptores: la contención del sistema de archivos y de red se puede seleccionar de manera independiente, y la contención de red ahora puede hacerse determinista. Para un harness sin supervisión, esta es la más importante de las dos, porque la salida de red es donde una instrucción inyectada se convierte en exfiltración, y el caso extremo de la fatiga de aprobación es que no hay nadie frente al teclado que pueda fatigarse. El costo es el costo normal de un límite determinista: la allowlist debe ser correcta, y un host que olvidaste falla como una denegación opaca en lugar de una pregunta. Enumera los hosts que tus agentes necesitan legítimamente y luego elimina el aviso.

Nada de esto reemplaza la capa de hooks; se sitúa por debajo de ella. Los patrones de contención son el nivel determinista, y el historial de aplicación de worktree en esta guía es la misma lección a pequeña escala: un límite solo cuenta si resiste una redirección deliberada, y las primitivas con más probabilidades de resistir son las que no se escribieron para la ocasión.

Límites de permisos

El sistema de permisos controla operaciones en varios niveles:

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

Claude Code v2.1.178 extendió las reglas de permisos desde el nivel de herramienta hasta el nivel de parámetro: Tool(param:value) coincide con los parámetros de entrada de una herramienta, usando * como comodín. El ejemplo canónico es Agent(model:opus): una regla que bloquea que se generen subagents en un nivel de modelo específico.⁶³ Desde el punto de vista arquitectónico, esto cierra una brecha que la tabla de cuatro niveles anterior no podía expresar: antes permitías o denegabas una herramienta en su totalidad, pero no podías restringir cómo se invocaba. Ahora una política de gobernanza puede decir «los subagents pueden generarse, pero no en el nivel Fable 5» o «Bash está permitido, pero no con este flag» como una regla determinista en lugar de una solicitud a nivel de prompt.

Una configuración administrada complementaria, enforceAvailableModels (v2.1.175), restringe la selección de modelos desde arriba: fija el modelo Default e impide que configuraciones de usuario o proyecto amplíen la allowlist administrada availableModels.⁶³ Ambas se combinan: la allowlist define qué niveles existen para la sesión, y las reglas a nivel de parámetro restringen cómo los usan los subagents. Desde v2.1.196, los administradores también pueden establecer un modelo predeterminado para toda la organización desde la consola de la organización, mostrado como «Org default» en /model, para que una flota herede un valor predeterminado gobernado sin que cada operador tenga que fijarlo; es un mínimo que complementa el máximo de la allowlist.

Las reglas allow con alcance de ruta se anclan al directorio de trabajo (julio de 2026)

Claude Code v2.1.214 corrigió una coincidencia excesiva silenciosa en las reglas de permisos con alcance de ruta: una regla allow con un patrón dir/** de un solo segmento —por ejemplo, Edit(src/**)— aprobaba automáticamente ediciones en cualquier directorio llamado src a cualquier profundidad, incluidos vendor/some-package/src/ y cualquier otro src/ anidado que el autor de la regla nunca quiso aprobar. Esas reglas ahora se anclan solo a <cwd>/dir; si realmente quieres coincidencias a cualquier profundidad, decláralo con **/dir/**.⁷⁴ Las reglas de denegación y consulta deliberadamente mantienen la anterior coincidencia a cualquier profundidad. Esa asimetría es el diseño correcto a prueba de fallos: una regla allow que coincide de forma demasiado estrecha falla de manera segura (recibes un aviso), mientras que una regla de denegación que coincide de forma demasiado estrecha falla abierta (se filtra una ruta que debía bloquearse); por ello, las reglas allow se volvieron más estrictas y las de denegación siguieron siendo amplias. Si tu configuración depende de patrones allow de un solo segmento para cubrir rutas anidadas, dejaron de hacerlo silenciosamente en v2.1.214; la corrección funciona como se esperaba, pero vale la pena revisar tus allowlists para volver a declarar el alcance que realmente deseas.

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

Claude Code v2.1.183 redujo el radio de impacto de auto mode para operaciones que hacen perder trabajo silenciosamente o destruyen entornos. Ahora auto mode bloquea estrictamente, salvo que las hayas solicitado explícitamente en la sesión: operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend cuando el commit no fue realizado por el agente en esta sesión; y destrucción de infraestructura (terraform destroy, pulumi destroy, cdk destroy) a menos que hayas nombrado el stack específico.⁶⁵ Desde el punto de vista arquitectónico, esto complementa las reglas de evaluación de generación y a nivel de parámetro anteriores: en lugar de controlar qué herramienta o cómo se genera, controla un pequeño conjunto de comandos irreversibles específicos por intención; el agente aún puede ejecutarlos, pero solo con una instrucción explícita, no por iniciativa propia. Para un harness autónomo, codifica el mismo principio en tus propios hooks PreToolUse: los comandos que destruyen estado merecen una regla de denegación por defecto que solo una señal explícita del operador levanta.

Julio de 2026: auto mode llega a empresas y un aviso no se puede omitir. Auto mode alcanzó disponibilidad general en Amazon Bedrock, Google Vertex AI y Microsoft Foundry en v2.1.207, con una configuración administrada disableAutoMode como opción de exclusión empresarial; la postura del clasificador como check-layer ahora está disponible en todas las plataformas empresariales propias, y desactivarla es una decisión de gobernanza explícita en lugar de una brecha de la plataforma.⁶⁸ Luego, v2.1.208 hizo absoluto el mecanismo contra eliminaciones catastróficas: los avisos de confirmación para eliminaciones catastróficas ahora atraviesan tanto --dangerously-skip-permissions como auto mode.⁶⁸ Es un precedente notable: la primera confirmación en Claude Code que ninguna postura de permisos, incluido el flag de omisión explícita, puede anular. Los diseños de harness autónomos que asumían que --dangerously-skip-permissions significaba literalmente cero avisos deben tener en cuenta esta excepción; se activa exactamente donde un ciclo sin supervisión puede causar el daño más irrecuperable.

Protecciones contra la fabricación (julio de 2026)

Las versiones v2.1.203–v2.1.206 cerraron dos vías por las que un agente podía fabricar su propio rastro de auditoría.⁶⁸ Primero, una regla de auto mode ahora bloquea la manipulación de archivos de transcripción: el registro de sesión ya no es algo que las propias llamadas a herramientas de la sesión puedan reescribir. Segundo, las notificaciones de tareas en segundo plano ahora indican explícitamente que no ocurrió ninguna entrada humana mientras se ejecutaba la tarea. La segunda medida apunta a una falla sutil: antes, un modelo que resumía una tarea en segundo plano podía presentar (o inventar) una «aprobación» en la transcripción que nunca ocurrió, y nada en la notificación lo contradecía. Ahora la propia notificación es la contraevidencia.

La lección arquitectónica se generaliza al Evidence Gate: las transcripciones, notificaciones y registros son superficies de auditoría, y las superficies de auditoría no deben poder ser escritas por aquello que auditan. La plataforma ahora aplica esta regla a su propia transcripción; aplica la misma regla a tu harness: los informes de evidencia, salidas de pruebas y registros de deliberación pertenecen fuera de la ruta con permisos de escritura del modelo.

Defensa contra inyección de prompts

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

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

allowed-tools: Read, Grep, Glob

Los hooks PreToolUse validan cada llamada a herramienta independientemente de cómo se haya dirigido 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 incluso si su prompt está comprometido.

El nivel mínimo de la plataforma aumentó en julio de 2026. Claude Code v2.1.210 reforzó la herramienta Agent contra la inyección indirecta de prompts transportada en contenido que leyó un subagent: un archivo, página web o resultado de herramienta envenenado que un subagent incorpora tiene menos capacidad para dirigir la propia superficie de delegación.⁶⁹ Y 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 un comando ya no puede diseñarse para mostrarse como inocuo en el diálogo de aprobación mientras ejecuta otra cosa.⁶⁹ La segunda corrección importa más para harnesses donde una persona aprueba vistas previas renderizadas bajo presión de tiempo: la visualización también era una superficie de inyección. Ninguno de estos cambios reemplaza las defensas a nivel de hooks anteriores; elevan el mínimo sobre el que estas se apoyan.

Los registros de agentes y las protecciones son superficies de seguridad

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

La regla de producción: trata las transcripciones de agentes, payloads de herramientas, registros SQLite y ejecución de guardrails como infraestructura sensible. Elimina información sensible antes de la persistencia, aplica límites de retención y mantén el código personalizado de guardrails en sandbox y revisable. Una regla a nivel de prompt de «no registres secretos» no es suficiente; la ruta de registro y guardrails necesita pruebas deterministas.

Seguridad de hooks

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

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

La división de responsabilidades entre humanos y agentes

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

El patrón: las personas poseen las decisiones que requieren contexto organizacional, juicio ético o dirección estratégica. Los agentes poseen las decisiones que requieren búsqueda computacional en grandes espacios de posibilidades. Los hooks aplican el límite.

Aplicación recursiva de hooks

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

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

El costo como arquitectura

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

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

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

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

Marco de decisión

Cuándo usar cada mecanismo:

Skills vs Hooks vs Subagents

Preguntas frecuentes

¿Cuántos hooks son demasiados?

El límite es el rendimiento, no la cantidad. Cada hook se ejecuta de forma síncrona, por lo que el tiempo total de ejecución de los hooks se suma a cada llamada de herramienta coincidente. 95 hooks entre la configuración de usuario y la del proyecto se ejecutan sin una latencia perceptible cuando cada hook termina en menos de 200 ms. El umbral que debes vigilar: si un hook PostToolUse añade más de 500 ms a cada edición de archivo, la sesión se siente lenta. Analiza tus hooks con time antes de implementarlos.¹⁴

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

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

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

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

¿Toda decisión necesita deliberación?

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

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

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

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

Una deliberación de 3 agentes añade entre 30 y 60 segundos de tiempo de reloj (este diseño de deliberación ejecuta sus agentes de forma secuencial mediante Agent tool; la plataforma ejecuta los subagents simultáneamente en segundo plano desde v2.1.198). Una deliberación de 10 agentes añade entre 2 y 4 minutos. Los hooks de consenso y pride check se ejecutan cada uno en menos de 200 ms. El principal cuello de botella es el tiempo de inferencia de LLM por agente, no la sobrecarga de orquestación.⁷

¿Qué extensión debe tener un archivo CLAUDE.md?

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

¿Puede funcionar esto con herramientas distintas de Claude Code?

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

Tarjeta de referencia rápida

Configuración de hooks

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

Frontmatter de Skill

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

Definición de Subagent

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

Instructions for the subagent.

Códigos de salida

Comandos clave

Ubicaciones de archivos

Registro de cambios

Referencias