La mayoría de equipos tratan a Claude Code como un único agente. Eso es la mitad del valor.

El verdadero desbloqueo son los sub-agentes — personas especializadas con sus propios system prompts, herramientas permitidas y reglas. No hablas con "Claude". Hablas con code-reviewer, luego con test-writer, luego con migration-runner. Cada uno se mantiene en su carril y hace bien una sola cosa.

Aquí están los 11 sub-agentes que ejecuto en cada base de código seria, lo que dominan y las definiciones .claude/agents/<nombre>.md que los hacen funcionar.

¿Por qué sub-agentes?

Un agente monolítico es generalista. Los generalistas son geniales con problemas pequeños. En una base real quieres:

• Un reviewer que solo revise y nunca escriba código.
• Un test-writer que nunca modifique código de aplicación.
• Un migration-runner que solo corra migraciones y se detenga.

La restricción es la feature. Cada sub-agente está acotado por un system prompt y una allowlist de herramientas. Esa cota es lo que los hace fiables.

Los 11 que mantengo en cada proyecto

1. code-reviewer

Domina: revisión post-implementación. Lee diffs, nunca los escribe.

# system
Revisas diffs. No modificas archivos. Devuelves:
1. Bugs (con archivo:línea)
2. Áreas de riesgo (seguridad, rendimiento, cambios incompatibles)
3. Violaciones de estilo/convención frente a CLAUDE.md
4. Veredicto en 1 línea: SHIP, FIX-FIRST o REWRITE.

# tools
allow: ["git diff *", "rg *", "cat *"]
deny:  ["edit", "shell-write"]

2. test-writer

Escribe tests nuevos. Nunca edita código de producción. Si el test falla, reporta el fallo — no lo "arregla".

3. test-fixer

La imagen espejo. Lee tests fallidos, modifica código de producción para hacerlos pasar, nunca edita el test salvo que sea demostrablemente erróneo.

4. migration-runner

Ejecuta migraciones de DB. Permitido: pnpm db:migrate, psql -c "...". Denegado: cualquier otro comando shell.

5. dependency-auditor

pnpm outdated, pnpm audit, npm-check-updates. Devuelve una tabla markdown de upgrades + riesgo. No ejecuta upgrades sin supervisión.

6. release-bot

Genera changelogs, bumps de versión, tags. Nunca hace push — el push es humano.

7. docs-writer

Toca README.md, docs/, comentarios JSDoc. Prohibido en src/ y app/.

8. refactor-surgeon

Refactors puros. Restricción: cero cambio de comportamiento, todos los tests deben pasar antes y después. Si un test falla, el refactor no fue puro — revierte.

9. incident-responder

Al que solo invocas durante una caída. Lee logs, escribe esqueleto de postmortem, sugiere comandos de rollback. Nunca ejecuta comandos de producción.

10. architect

Read-only. Mira la base, produce un borrador de ADR (architecture decision record) cuando preguntas "¿deberíamos añadir X?"

11. ci-fixer

Lee .github/workflows/, los logs de CI fallidos y propone cambios mínimos. Permitido empujar ramas, nunca a main.

Lo que va en .claude/agents/<nombre>.md

Cada agente es un archivo. Esta es la forma canónica:

---
name: code-reviewer
model: claude-sonnet-4
---

# system
<persona + alcance + formato de salida>

# tools
allow: [...]
deny: [...]

# Respeto a CLAUDE.md
Lee el CLAUDE.md del proyecto antes de actuar.

Eso es todo. Commitea esa carpeta; todo el equipo recibe el mismo plantel.

Cómo colaboran (sin llamarlo "multi-agente")

Esto todavía no son pipelines multi-agente (eso es el artículo 7). Es la coreografía más simple:

Tú → /agents → eliges test-writer → "escribe tests para lib/cache.ts"
  → /agents → eliges test-fixer    → "haz que pasen"
  → /agents → eliges code-reviewer → "revisa el diff"
  → /release-notes

Cada paso está acotado. Cada paso es revisable. Nunca tienes un único agente que "escribió los tests, arregló el código, se autorrevisó y empujó a main". Esa autorrevisión es justo el modo de fallo que quieres diseñar para evitar.

La regla de naming

Los sub-agentes se nombran por roles, no por herramientas. code-reviewer, no claude-con-rg. migration-runner, no psql-runner. Los roles componen; las herramientas no.

Cuando alguien nuevo se une, lee .claude/agents/ una vez y entiende inmediatamente el modelo operativo. Eso es documentación por configuración.

Ejemplo en vivo: enviar una feature con el equipo

Tú: /agents test-writer
> Escribe casos vitest para lib/cache.ts cubriendo expiración TTL y desalojo LRU.
test-writer: <escribe 2 tests, ambos fallan, reporta>

Tú: /agents test-fixer
> Haz que esos tests pasen sin cambiar lib/cache.test.ts.
test-fixer: <implementa TTL + LRU en lib/cache.ts, tests verdes>

Tú: /agents code-reviewer
> Revisa el diff.
code-reviewer: SHIP.

Tú: /release-notes
release-bot: <escribe changelog>

Tú: git checkout -b feat/cache-lru && git commit && gh pr create

Escribiste ~20 líneas en lenguaje natural. Tres especialistas distintos escribieron / verificaron / aprobaron el código real. Ese es el flujo.

Construye los tuyos

Empieza con dos: code-reviewer y test-writer. Úsalos en cada PR durante una semana. Descubrirás dónde está la fricción y añadirás el tercero orgánicamente — normalmente ci-fixer o migration-runner.

Para el segundo mes, todo equipo que he onboardeado tiene 6-8 sub-agentes commiteados en .claude/agents/, tratados como infraestructura.

---

Próximo artículo: Seguridad en bases de código de producción — permisos, salvaguardas y las cosas que ningún sub-agente debería tocar sin supervisión.