Arquitectura de Agent Harness 2026: Referencia con Diagramas

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

Andrej Karpathy acuñó un término para lo que crece alrededor de un agente LLM: claws (garras). Los hooks, scripts y orquestación que permiten al agente 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 siguen adelante. Ese enfoque limita la productividad a lo que puedas supervisar personalmente.

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

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

Conclusiones clave

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

Cómo usar esta guía

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

La ruta dorada de cinco minutos

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

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

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

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

Conéctalo en .claude/settings.json:

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

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

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

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

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

Paso 3: genera un subagent (30 segundos)

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

Lo que ahora tienes

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

Por qué importa la arquitectura de agentes

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

Tres fuerzas hacen que la arquitectura de agentes sea necesaria:

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

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

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

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

El patrón Harness

El harness no es un framework. Es un patrón: un conjunto componible de archivos, scripts y convenciones que envuelven a un agente de codificación con IA en una 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 que se activa automáticamente según el contexto. Los hooks ofrecen puertas deterministas que se disparan en cada llamada de herramienta coincidente. Los archivos de memoria conservan el estado entre sesiones. Los agentes personalizados proporcionan configuraciones especializadas de subagents.

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

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

Harnesses gestionados vs. autogestionados (abril de 2026)

Durante los primeros meses de 2026, la ruta de “construye tu propio harness” era la única opción real. En abril de 2026, eso cambió. Anthropic lanzó Claude Managed Agents en beta pública (8 de abril): bucle del harness + ejecución de herramientas + contenedor sandbox + persistencia de estado como una API REST, facturada a tokens estándar más $0,08/hora-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 nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) y snapshot/rehidratación para sobrevivir a la pérdida de contenedores.²³²⁴

La bifurcación arquitectónica ya es real:

Cuándo elegir cada uno: el autogestionado sigue siendo la opción adecuada para equipos que ya tienen músculo de infraestructura, quieren skills/hooks bajo su control o están optimizando profundamente un flujo de trabajo específico. El gestionado es adecuado para equipos sin ingenieros de plataforma dedicados, cuando el tiempo hasta obtener valor importa más que la personalización, o cuando las ejecuciones del agente necesitan sobrevivir de forma fiable al cierre de la laptop sin que tú construyas esa capa de persistencia. Los dos son compatibles: puedes ejecutar un harness autogestionado que delegue tareas específicas de larga duración a Managed Agents a través de su API REST.

Cómo se ve el harness en disco

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

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

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

Sistema de skills

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

Cuándo construir una skill

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

Crear una skill

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

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

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

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

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

Referencia de Frontmatter

El Campo Description Lo Es Todo

Al iniciar la sesión, Claude Code extrae el name y description de cada skill y los inyecta en el contexto de Claude. Cuando envías un mensaje, Claude usa razonamiento de modelo de lenguaje para decidir si alguna skill es relevante. El 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 utiliza comprensión estándar del lenguaje para seleccionar las skills relevantes.¹⁰

Descripción deficiente:

description: Helps with code

Descripción efectiva:

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

La descripción efectiva incluye: qué hace (revisa código en busca de tipos específicos de problemas), cuándo usarla (al examinar cambios, PRs, análisis de calidad) y frases disparadoras (review, audit, check) que los usuarios escriben de forma natural.

Presupuesto de Contexto

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

Archivos de Apoyo y Organización

Las skills pueden referenciar archivos adicionales en el mismo directorio:

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

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

Compartir Skills mediante Git

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

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

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

Skills como Biblioteca de Prompts

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

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

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

Las Skills se Componen con Hooks

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

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

Las skills de filosofía se autoactivan mediante hooks SessionStart, inyectando restricciones de calidad en cada sesión sin invocación explícita. La skill en sí es conocimiento. El hook es la aplicación. Juntos, forman una capa de polí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 ajustar la descripción o añadir disable-model-invocation: true y exigir la invocación explícita con /skill-name.⁴

Demasiadas skills compitiendo por el presupuesto. Más skills significa más descripciones compitiendo por el 2% del presupuesto de contexto. Si notas que las skills no se activan, revisa /context para ver las excluidas. Prioriza pocas skills bien descritas sobre muchas vagas.

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

Arquitectura de Hooks

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

Eventos Disponibles

Claude Code expone más de 26 eventos del ciclo de vida en siete categorías (la lista de eventos crece con cada versión — consulta la hoja de referencia para ver la tabla completa actual):¹³

Semántica de los Códigos de Salida

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

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

Configuración de Hooks

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

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

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

Protocolo de Entrada/Salida de Hooks

Los hooks reciben JSON en stdin con el contexto completo:

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

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

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

Tres Tipos de Garantías

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

Las garantías de formato aseguran la consistencia después del hecho. Los hooks PostToolUse sobre 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 sobre Bash inspeccionan comandos y bloquean patrones destructivos con código de salida 2:

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

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

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

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

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

Tipos de Hooks Más Allá de los Comandos de Shell

Claude Code admite cuatro tipos de hooks:¹³

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

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

Los hooks de agente (type: "agent") generan un subagente con acceso a herramientas (Read, Grep, Glob) para verificación de múltiples turnos. Úsalos cuando la verificación requiera 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
          }
        ]
      }
    ]
  }
}

Los hooks HTTP (type: "http") envían la entrada JSON del evento como una solicitud POST a una URL y reciben JSON de vuelta. Úsalos para webhooks, servicios externos de notificación o validación basada en API (v2.1.63+). No se admiten para 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. Añade 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 copias de seguridad. Nunca uses async para formateo, validación o cualquier cosa que deba completarse antes de la siguiente acción.

Dispatchers Sobre Hooks Independientes

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

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

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

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

Depuración de Hooks

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

1. Prueba los scripts de forma independiente. Canaliza JSON de muestra: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Usa stderr para la salida de depuración. El stderr del código de salida 2 se envía de vuelta a Claude como mensaje de error. El stderr no bloqueante (exit 1, 3, etc.) solo aparece en modo verbose (Ctrl+O).
3. Está atento a los fallos de jq. Las rutas JSON incorrectas devuelven null silenciosamente. Prueba las expresiones jq contra la entrada real de la herramienta.
4. Verifica los códigos de salida. Un hook PreToolUse que usa exit 1 no proporciona ninguna aplicación mientras aparenta 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.

Memoria y contexto

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

Los tres mecanismos del colapso multiturno

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

Estrategia 1: el sistema de archivos como memoria

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

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

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

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

Estrategia 2: compactación proactiva

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

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

Instrucciones personalizadas de compactación en CLAUDE.md:

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

Estrategia 3: handoffs entre sesiones

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

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

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

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

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

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

Compara con una única sesión larga:

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

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

Los antipatrones

Leer archivos completos cuando solo necesitas 10 líneas. La lectura de un único archivo de 2.000 líneas consume entre 15.000 y 20.000 tokens. Usa offsets de línea: Read file.py offset=100 limit=20 ahorra la mayor parte de ese coste.¹⁵

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

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

Patrones de Subagentes

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

Tipos de Subagentes Integrados

Creación de Subagentes Personalizados

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Campos de Configuración del Subagente

Aislamiento por Worktree

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

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

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

El aislamiento por worktree es esencial para el trabajo experimental que podría romper el código base.

Subagentes Paralelos

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

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

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

La Protección contra Recursión

Sin límites de generación, los agentes delegan a agentes que delegan a agentes, cada uno perdiendo contexto y consumiendo tokens. El patrón de protección contra recursión impone presupuestos:¹⁶

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

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

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

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

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

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

Equipos de Agentes (Vista Previa de Investigación)

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

Habilítalo con: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Cuándo usar equipos de agentes vs. subagentes:

Orquestación multiagente

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

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

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

Deliberación mínima viable

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

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

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

El disparador de confianza

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

1. Ambigüedad - ¿La consulta tiene múltiples interpretaciones válidas?
2. Complejidad del dominio - ¿Requiere conocimiento especializado?
3. Riesgo - ¿La decisión es reversible?
4. Dependencia del contexto - ¿Requiere entender 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 la documentación solo necesitan 0,50. Esto evita la sobreingeniería en tareas simples mientras se garantiza que las decisiones arriesgadas 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 distinta (Arquitecto Técnico, Analista de Seguridad, Ingeniero de Rendimiento, entre otros). El aislamiento de contexto garantiza que los agentes no puedan ver los hallazgos de los demás durante la investigación.

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

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

La arquitectura de validación de dos puertas

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

Puerta 1: Validación de consenso (hook PostToolUse). Se ejecuta inmediatamente después de que cada agente de deliberación termine: 1. La fase debe haber llegado al menos a RANKING 2. Mínimo de 2 agentes completados (configurable) 3. La puntuación de consenso alcanza 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: múltiples personas únicas representadas 2. Transparencia en las contradicciones: los disensos tienen razones documentadas 3. Manejo de complejidad: al menos 2 alternativas generadas 4. Confianza del consenso: clasificada como fuerte (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 puntos distintos del ciclo de vida coinciden con la forma en que realmente ocurren los fallos: algunos son instantáneos (puntuación baja) y otros son graduales (poca diversidad, falta de documentación de disensos).⁷

Por qué el acuerdo es peligroso

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

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

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

Detectar el acuerdo falso

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

Agrupación de puntuaciones: Cuando cada agente puntúa dentro de un rango de 0,3 puntos en una escala de 10, esto señala contaminación de contexto compartido en lugar de evaluación independiente. Cuando cinco agentes que evaluaban un refactor de autenticación puntuaron el riesgo de seguridad entre 7,1 y 7,4, al volver a ejecutar con aislamiento de contexto fresco las puntuaciones se dispersaron entre 5,8 y 8,9.

Disensos de plantilla: Agentes que copian el lenguaje de preocupación de los demás en lugar de generar objeciones independientes.

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

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

Lo que no funcionó en la deliberación

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

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

Costo de la deliberación

Cada agente de investigación procesa aproximadamente 5.000 tokens de contexto y genera entre 2.000 y 3.000 tokens de hallazgos. Con 3 agentes, eso 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, una deliberación con 3 agentes cuesta aproximadamente entre $0,68 y $0,90. Una deliberación con 10 agentes cuesta entre $2,25 y $3,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,23 a $0,30 por sesión. Si eso vale la pena depende de cuánto cuesta una mala decisión.

Cuándo deliberar

Diseño de CLAUDE.md

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

La jerarquía de precedencia

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

Lo que se ignora

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

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

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

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

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

Lo que funciona

Instrucciones basadas en comandos:

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

Definiciones de cierre:

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

Secciones organizadas por tarea:

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

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

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

Reglas de escalamiento:

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

Orden de escritura

Si partes desde cero, añade secciones en este orden de prioridad:²¹

1. Comandos de build y test (el agente los necesita antes de poder hacer algo útil)
2. Definición de hecho (previene falsas finalizaciones)
3. Reglas de escalamiento (previene soluciones destructivas)
4. Secciones organizadas por tarea (reduce el análisis de instrucciones irrelevantes)
5. Delimitación por directorio (monorepos: mantiene aisladas las instrucciones de cada servicio)

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

Importación de archivos

Referencia otros archivos dentro de CLAUDE.md:

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

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

Compatibilidad de instrucciones entre herramientas

AGENTS.md es un estándar abierto reconocido por todas las herramientas principales de codificación con IA.²¹ Si tu equipo usa varias herramientas, escribe AGENTS.md como fuente canónica y replica las secciones relevantes a archivos específicos de cada herramienta:

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

Probar tus instrucciones

Verifica que el agente realmente lee y sigue tus instrucciones:

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

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

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

Patrones de Producción

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

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

• Resiliencia ante fallos de herramientas: Opus 4.7 continúa a pesar de fallos de herramientas que detenían las sesiones de Opus 4.6. Puedes reducir — pero no eliminar — los wrappers defensivos de reintentos en el código de los subagents. Conserva las protecciones a nivel de hook; recorta el andamiaje dentro del prompt del tipo “si la herramienta falla, inténtalo tres veces”.
• Nivel de esfuerzo xhigh (solo en Opus-4.7): Se sitúa entre high y max. Predeterminado recomendado para cargas de trabajo de codificación y agentic. En subagents de larga duración, xhigh supera notablemente a high con un costo de tokens sub-proporcional. max sigue siendo la opción correcta para razonamiento difícil de un solo disparo; xhigh es mejor para tareas sostenidas.
• Techo de presupuesto de tokens: Configurable por ejecución de agent mediante output_config.task_budget (encabezado beta task-budgets-2026-03-13). El modelo ve una cuenta regresiva activa y ajusta el trabajo al presupuesto con elegancia, en lugar de quedarse sin tokens inesperadamente. Úsalo en bucles agentic donde quieras un gasto de tokens predecible sin sacrificar calidad en prompts cortos.
• Conciencia de necesidad implícita: Primer modelo Claude que aprueba pruebas de “necesidad implícita” — reconocer cuándo la solicitud literal del usuario subespecifica lo que realmente necesita. Esto hace menos necesaria la sección de “reglas de aclaración” en CLAUDE.md. Si tu CLAUDE.md tiene 200 líneas de guardarraíles del tipo “considera también X cuando el usuario pida Y”, poda los que ahora están cubiertos de forma nativa.

El Quality Loop

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

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

El Evidence Gate

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

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

Patrones de Manejo de Errores

Escrituras atómicas de archivo. Múltiples agents escribiendo al mismo archivo de estado simultáneamente corrompen JSON. Escribe a archivos .tmp, luego haz mv atómicamente. El SO garantiza que mv es atómico en el mismo sistema de archivos.¹⁷

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

Recuperación de corrupción de estado. Si el estado se corrompe, el patrón de recuperación lo recrea con 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 bash de ((VAR++)). ((VAR++)) devuelve código de salida 1 cuando VAR es 0 porque 0++ evalúa a 0, que bash trata como falso. Con set -e activado, esto mata el script. Usa VAR=$((VAR + 1)) en su lugar.¹⁶

Clasificación del Radio de Impacto

Clasifica cada acción del agent por radio de impacto y establece controles en consecuencia:²

Remote Control (conectarse al Claude Code local desde cualquier navegador o app móvil) convierte el control “Externo” de una espera bloqueante en una notificación asíncrona. El agent sigue trabajando en la siguiente tarea mientras tú revisas la anterior desde tu teléfono.²

Especificación de Tareas para Ejecuciones Autónomas

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

Los criterios deben ser verificables por máquina: aprobado/reprobado de pruebas, salida del linter, códigos de estado HTTP, comprobaciones de existencia de archivos. Una tarea inicial que pidió al agent “escribir pruebas que pasen” produjo assert True y assert 1 == 1. Técnicamente correcto. Prácticamente inútil.¹⁶

Modos de Fallo a Vigilar

Un Rastro de Sesión Concreto

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

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

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

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

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

5. El agent termina la historia. Se dispara Stop. El quality gate verifica: ¿el agent citó evidencia? ¿Lenguaje de reserva? ¿Comentarios TODO en el diff? Si alguna verificación falla, sale con 2 y el agent continúa.

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

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

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

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

Caso de Estudio: Procesamiento Nocturno de PRD

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

Las dos fugas de credenciales requirieron rotar claves de API y auditar servicios descendentes: aproximadamente 4 horas de respuesta a incidentes. La sobrecarga del harness que previno el equivalente fue 2,4 segundos de bash por historia. La tasa de falsa finalización bajó del 35% al 4% porque el hook Stop ejecutó pruebas de forma independiente antes de permitir que el agent reportara 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 extienden — el pensamiento del Evidence Gate de esta guía:

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

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

El Sandbox

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

Límites de Permisos

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

Defensa contra Inyección de Prompts

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

Los skills con restricciones de herramientas impiden 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 prompteado al modelo:

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

El aislamiento de subagentes limita el radio de impacto. Un subagente con permissionMode: plan no puede hacer cambios aunque su prompt esté comprometido.

Seguridad de los Hooks

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

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

La División de Responsabilidad entre Humano y Agente

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

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

Aplicación Recursiva de Hooks

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

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

El Costo como Arquitectura

El costo es una decisión arquitectónica, no una ocurrencia operacional de último momento.² Tres niveles:

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

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

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

Marco de Decisión

Cuándo usar cada mecanismo:

Skills vs Hooks vs Subagentes

Preguntas frecuentes

¿Cuántos hooks son demasiados?

La restricción 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 distribuidos entre la configuración a nivel de usuario y a nivel de proyecto se ejecutan sin latencia perceptible cuando cada hook se completa 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. Perfila tus hooks con time antes de desplegarlos.¹⁴

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

Sí. Los hooks PreToolUse bloquean cualquier acción de herramienta al salir con código 2. Claude Code cancela la acción pendiente y muestra la salida stderr del hook al modelo. Claude ve la razón del rechazo y sugiere una alternativa más segura. Salir con código 1 es una advertencia no bloqueante en la que la acción igualmente 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 (incluidos en tu repositorio, compartidos con tu equipo) o en ~/.claude/settings.json para hooks a nivel de usuario (personales, aplicados a cada proyecto). Los hooks a nivel de proyecto tienen prioridad cuando ambos existen. Usa rutas absolutas para los archivos de script para evitar problemas con el directorio de trabajo.¹⁴

¿Cada decisión necesita deliberación?

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

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

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

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

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

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

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

¿Puede funcionar esto con herramientas distintas a Claude Code?

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

Changelog

Referencias