Los defaults de Claude Code te llevan lejos. Pero hay un punto — normalmente alrededor del tercer mes de uso serio — donde se te quedan pequeños. Quieres un efecto colateral determinista después de cada llamada de herramienta. Quieres que el agente lea tu wiki interna. Quieres enviar una herramienta custom que hable con la API a medida de tu empresa.

Para eso es este artículo. Cuatro patrones:

1. Hooks — pegamento determinista entre los pasos del agente.
2. Servidores MCP — datos de empresa que el agente puede leer.
3. Herramientas custom — tus propios comandos cableados al agente.
4. Cirugía de system prompt — cuando los prompts solos no te llevarán allí.

1. Hooks — pegamento determinista

Un hook es un script que se dispara en un evento conocido: onFileEdit, onShellRun, onSessionStart, onSessionEnd, etc. No son "IA"; son shell puro.

Por qué importan: te permiten añadir garantías deterministas alrededor de un agente que de otro modo es probabilístico.

Ejemplos que corro en cada proyecto:

{
  "hooks": {
    "onSessionStart": "scripts/claude-onstart.sh",
    "onFileEdit": "scripts/claude-onedit.sh",
    "onSessionEnd": "scripts/claude-onend.sh"
  }
}

scripts/claude-onstart.sh:

#!/usr/bin/env bash
# Snapshot del working tree antes de que arranque el agente.
git stash push -u -m "claude-pre-session-$(date +%s)" --keep-index || true

scripts/claude-onedit.sh:

#!/usr/bin/env bash
# Después de cada edición, prettier solo en el archivo cambiado.
file="$1"
if [ -f "$file" ]; then
  pnpm prettier --write "$file" --log-level silent
fi

scripts/claude-onend.sh:

#!/usr/bin/env bash
# Al final de la sesión, enviamos el transcript.
cp ~/.claude/sessions/last.jsonl /var/log/claude/$(date +%F-%H%M).jsonl

Tres hooks. Cada sesión ahora es snapshot-able, formateada y auditada. Ninguno es IA; todos son infraestructura.

2. Servidores MCP — tus datos dentro del agente

Model Context Protocol (MCP) es el estándar para permitir que un agente lea fuentes de datos externas en tiempo de sesión. En lugar de pegar una página de Confluence, conectas el servidor MCP y el agente puede navegar bajo demanda.

Los patrones que he visto rendir:

• MCP para el bug tracker. El agente lee el ticket, comentarios incluidos, antes de empezar a implementar.
• MCP para el esquema de la BD de staging. El agente puede introspeccionar tablas en lugar de adivinar.
• MCP para los runbooks. El agente lee docs/runbooks/<incident-type>.md automáticamente.

La configuración vive en .claude/mcp.json:

{
  "servers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
    },
    "company-docs": {
      "command": "node",
      "args": ["./mcp/company-docs.js"]
    }
  }
}

Dos advertencias:

• Los servidores MCP corren con tus privilegios. Trátalos como CLIs; revisa su código antes de enchufarlos.
• MCP puede filtrar. Si conectas un servidor que expone datos de cliente, cada sesión puede leerlos. Acota fino.

3. Herramientas custom — tus propios verbos

Los sub-agentes y slash commands te dejan reutilizar texto. Las herramientas custom te dejan añadir verbos invocables.

Ejemplo: una herramienta deploy-preview. El agente no debería ejecutar shell para desplegar un preview — demasiadas formas de que eso salga mal. En su lugar, expón una herramienta:

{
  "tools": {
    "deploy-preview": {
      "description": "Despliega un preview environment para la rama actual.",
      "schema": {
        "type": "object",
        "properties": {
          "branch": { "type": "string" }
        },
        "required": ["branch"]
      },
      "command": "scripts/deploy-preview.sh"
    }
  }
}

Ahora el agente ve un verbo llamado deploy-preview con una entrada tipada. El script que tú escribes decide qué hace. El agente no puede escapar del contrato.

Este es el mismo patrón que usaría para:

• run-load-test
• migrate-staging
• tail-prod-logs (solo lectura)
• notify-pager-duty

Cada uno es una baranda que dice "el agente puede hacer esto, exactamente así, nunca más profundo".

4. Cirugía de system prompt

A veces el comportamiento de un sub-agente está casi bien y un retoque del system prompt cierra la brecha. Tres patrones:

4a. El bloque "rules"

Pon siempre los no-negociables bajo un header llamado rules:

# rules
- Nunca añadas @ts-ignore.
- Nunca modifiques archivos en /infra/.
- Siempre corre `pnpm test` antes de declarar éxito.

El agente las trata como más duras que meras instrucciones porque parecen una lista de leyes.

4b. Esquema de salida primero

Si quieres salida estructurada (handoffs, JSON, YAML), pon el esquema antes de la explicación en prosa. Los agentes se anclan en los primeros 200 tokens.

# esquema de salida (siempre arriba del system prompt)
status: ok | needs-human | failed
artifacts: [path: string]
notes: string
next: code-reviewer | release-bot | done

# rationale (debajo del esquema, jamás arriba)
# Emites esto para que el siguiente agente del pipeline sepa exactamente dónde estás.

4c. Contraejemplos

Muestra qué NO hacer:

# salida mala
"Listo. La caché está implementada."

# salida buena
status: ok
artifacts: [{path: "lib/cache.ts"}]
notes: "LRU + TTL implementados. Todos los tests verdes."
next: code-reviewer

Los contraejemplos son raramente más efectivos que los ejemplos positivos para conseguir cumplimiento. No tengo una teoría profunda del porqué; empíricamente, funciona.

Cuando necesitas los cuatro juntos

El workflow avanzado que enciende a los equipos de verdad:

hook (onSessionStart)              → snapshot stash
el agente lee CLAUDE.md            → contexto
el agente llama un servidor MCP    → lee el ticket de Linear
el agente llama una tool custom    → run-load-test
hook (onFileEdit)                  → prettier
el agente emite handoff estructurado → code-reviewer
hook (onSessionEnd)                → envía el transcript

Cada capa añade determinismo, trazabilidad o capacidad. Ninguna es "el agente". Todas son andamio.

Esa es la lección, cuatro artículos adentro de los patrones avanzados: el agente es la parte pequeña. El andamio es el trabajo de ingeniería.

---

Último artículo de la serie: El futuro del desarrollo agéntico — hacia dónde va esto en 2026, a qué le apostaría y la línea más allá de la cual sería escéptico.