Módulo 8: Proyecto — Sistema Multi-Agente Completo

5. Retrospectiva — Análisis, Optimización, y Cierre de la Guía

5. Retrospectiva — Análisis, Optimización, y Cierre de la Guía

Descripción

La ejecución terminó. El equipo de 5 agentes completó el task board, los hooks validaron cada paso, el SDK generó métricas, y tienes un reporte de ejecución completo. Ahora toca hacer lo que todo equipo profesional hace después de un sprint: una retrospectiva.

Esta cápsula no tiene ejercicios tradicionales. Es una retrospectiva estructurada donde analizas qué funcionó, qué no, dónde estuvieron los cuellos de botella, y qué cambiarías para la próxima ejecución. También cierra la guía completa — conecta lo que aprendiste con las guías #10 y #11 del path, y te deja con un plan de acción concreto.

Parte 1: Análisis de Resultados

Qué produjo cada agente

Después de la ejecución, revisa los entregables de cada agente:

Backend Agent:

echo "=== Backend Deliverables ==="
find src/api src/models src/services src/schemas src/types -type f 2>/dev/null

Esperado:

  • src/schemas/task.py — Pydantic models (TaskCreate, TaskUpdate, TaskResponse)
  • src/api/routes/tasks.py — 5 CRUD endpoints
  • src/types/task.ts — Tipos compartidos para frontend
  • Posiblemente: src/services/task_service.py — Business logic layer

Preguntas de análisis:

  • ¿Los schemas son completos? ¿Faltan campos?
  • ¿Los endpoints siguen el patrón definido en CLAUDE.md?
  • ¿Los tipos publicados en src/types/ son exactos respecto a los schemas?
  • ¿El business logic está en services o en los route handlers?

Frontend Agent:

echo "=== Frontend Deliverables ==="
find src/components src/pages src/hooks -type f 2>/dev/null

Esperado:

  • src/components/TaskList/index.tsx — Lista de tareas
  • src/components/TaskCard/index.tsx — Tarea individual con toggle
  • src/components/CreateTaskForm/index.tsx — Formulario de creación
  • src/hooks/useTasks.ts — Hook para fetch de datos (posible)

Preguntas de análisis:

  • ¿Los componentes importan tipos de src/types/ o los definen inline?
  • ¿Tienen loading, error, y empty states?
  • ¿Las props están tipadas con TypeScript interfaces?
  • ¿Los nombres de campos coinciden con lo que el backend publicó?

Testing Agent:

echo "=== Testing Deliverables ==="
find tests -type f -name "*.py" 2>/dev/null

Esperado:

  • tests/test_tasks_api.py — Tests de endpoints
  • tests/test_components.py — Tests de componentes (si aplica)
  • tests/conftest.py — Fixtures compartidos (si no existía)

Preguntas de análisis:

  • ¿Los tests cubren happy path, error cases, y edge cases?
  • ¿Usan fixtures o hardcodean datos?
  • ¿Todos los tests pasan?
  • ¿Hay tests que son triviales (test que nada nuevo valida)?

Docs/Review Agent:

echo "=== Docs Deliverables ==="
find docs -type f 2>/dev/null

Esperado:

  • docs/api/tasks.md — Documentación API
  • Quality review integrado en el reporte final del team lead

Preguntas de análisis:

  • ¿La documentación API es completa? (endpoints, schemas, ejemplos)
  • ¿El quality review identificó issues reales?
  • ¿Las recomendaciones del review son actionables?

Matriz de entregables

Completa esta matriz con tus resultados reales:

| Agente            | Archivos creados | Archivos esperados | Match? |
|-------------------|------------------|--------------------|--------|
| backend-agent     |                  | 3-5                |        |
| frontend-agent    |                  | 3-4                |        |
| testing-agent     |                  | 2-3                |        |
| docs-review-agent |                  | 1-2                |        |
| TOTAL             |                  | 9-14               |        |

Parte 2: Análisis de Performance

Métricas del dashboard

Si ejecutaste el monitor (cápsula 04), revisa el dashboard:

python scripts/monitor/team-monitor.py --summary

Analiza:

1. ¿Qué agente tardó más?

Típicamente el backend-agent o el testing-agent. El backend-agent tiene más tareas (schemas, types, endpoints, error handling). El testing-agent tarda porque ejecuta la suite de tests además de escribirlos.

2. ¿Qué agente fue más eficiente?

Eficiencia = output producido / tiempo invertido. Un agente que crea 3 archivos en 15 segundos es más eficiente que uno que crea 1 archivo en 20 segundos.

3. ¿Hubo tiempo idle?

Revisa el timeline de actividad. Si el frontend-agent tuvo largos períodos sin actividad mientras esperaba al backend, hay oportunidad de optimización (agregar tareas frontend independientes del backend).

4. ¿Cuánto fue el overhead de coordinación?

El team lead usa turns para leer, planificar, asignar, y forwardear contexto. Ese tiempo es overhead. Si el team lead usó 30 turns y los agentes usaron 60 en total, el overhead de coordinación es ~33%.

Template de análisis de performance

PERFORMANCE ANALYSIS
═══════════════════

Total execution time:     ___________
Total agent time:         ___________
Coordination overhead:    ___________%

Agent Rankings (by total time):
1. _____________ — _____s (___ tasks)
2. _____________ — _____s (___ tasks)
3. _____________ — _____s (___ tasks)
4. _____________ — _____s (___ tasks)

Most efficient agent:     _____________
Bottleneck agent:         _____________
Most idle agent:          _____________

Parallelism achieved:
- Tasks that ran in parallel: ___/___
- Potential parallelism:      ___/___
- Parallelism utilization:    ___%

Parte 3: Análisis de Conflictos

Tipos de conflictos

Revisa la ejecución y documenta cada conflicto que ocurrió:

1. Type Mismatches

¿Los tipos que el backend publicó coincidieron exactamente con lo que el frontend consumió?

Conflicto de tipos encontrado:
- Backend publicó: status como string enum ("pending" | "completed")
- Frontend interpretó: status como boolean
- Resolución: team lead instruyó al frontend-agent a usar el tipo del backend
- Causa raíz: context forwarding insuficiente

2. Naming Inconsistencies

¿Los nombres de campos, funciones, y archivos fueron consistentes?

Inconsistencia de naming:
- Backend usa: created_at (snake_case)
- Frontend usa: createdAt (camelCase)
- Resolución: los tipos en src/types/ usan camelCase (convención JS)
- Causa raíz: CLAUDE.md no especificaba la convención de naming para src/types/

3. Boundary Violations

¿Algún agente tocó archivos fuera de su territorio?

Violación de boundaries:
- frontend-agent creó un helper en src/utils/api.ts
- src/utils/ no está en su territorio definido
- Resolución: mover a src/hooks/ o agregar src/utils/ como territorio compartido
- Causa raíz: el agent file no incluía src/utils/ en los boundaries

4. Dependency Violations

¿Alguna tarea se ejecutó antes de que sus dependencias se completaran?

Violación de dependencias:
- T7 (CreateTaskForm) se asignó antes de que T3 (endpoints) terminara
- El frontend-agent no tenía los endpoint URLs
- Resolución: team lead re-asignó con contexto completo
- Causa raíz: team lead no verificó dependencias antes de asignar

Template de análisis de conflictos

CONFLICT ANALYSIS
═════════════════

Type mismatches:      ___
Naming issues:        ___
Boundary violations:  ___
Dependency violations:___

Most problematic area:    _____________
Root cause pattern:       _____________
Suggested fix:            _____________

Parte 4: Optimización

10 optimizaciones concretas

Basándote en tu análisis, identifica qué cambiarías. Aquí tienes las 10 optimizaciones más comunes:

1. Mejorar el context forwarding del team lead

Si el frontend-agent no recibió suficiente contexto:

# Agregar al team-lead.md:
## Context Forwarding Checklist (MANDATORY)
Before assigning ANY frontend task that depends on backend:
□ Endpoint URLs with full paths
□ Request schemas with ALL fields and types
□ Response schemas with ALL fields and types
□ Error response format with example
□ File path of published types (exact path)
□ Authentication requirements (if any)

2. Agregar tareas frontend independientes

Si el frontend-agent estuvo idle:

Agregar al task board:
- T2b: "Create reusable Button, Input, Card components" (no dependencies)
- T2c: "Create useFetch custom hook" (no dependencies)
- T2d: "Create base CSS/theme variables" (no dependencies)

3. Reducir maxTurns donde sea seguro

Si los agentes terminan con turns sobrantes:

# Reducir de 25 a 20 para agentes rápidos
maxTurns: 20  # frontend-agent, docs-review-agent

# Mantener alto para agentes que ejecutan comandos
maxTurns: 30  # testing-agent (ejecuta pytest)

4. Especificar naming conventions en CLAUDE.md

Si hubo inconsistencias de naming:

## Naming Conventions
- Python: snake_case for variables, functions, files
- TypeScript: camelCase for variables/functions, PascalCase for components
- src/types/: camelCase (JavaScript convention — frontend consumes these)
- API endpoints: kebab-case in URLs, snake_case in JSON bodies

5. Agregar un hook de boundary enforcement

Si hubo violaciones de territorio:

#!/bin/bash
# pre-tool-boundary.sh
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
AGENT=$(echo "$INPUT" | jq -r '.agent_name // empty')

if [[ "$AGENT" == "frontend-agent" ]]; then
  if echo "$FILE" | grep -qE "^src/(api|models|services|schemas)/"; then
    echo "BLOCKED: frontend-agent cannot modify $FILE"
    exit 2
  fi
fi

if [[ "$AGENT" == "backend-agent" ]]; then
  if echo "$FILE" | grep -qE "^src/(components|pages|hooks|styles)/"; then
    echo "BLOCKED: backend-agent cannot modify $FILE"
    exit 2
  fi
fi

exit 0

6. Hacer el task board más granular para backend

Si el backend-agent tardó mucho:

En lugar de:
  T3: "CRUD endpoints" (una tarea para 5 endpoints)

Dividir en:
  T3a: "POST /api/tasks endpoint"
  T3b: "GET /api/tasks and GET /api/tasks/{id} endpoints"
  T3c: "PUT /api/tasks/{id} endpoint"
  T3d: "DELETE /api/tasks/{id} endpoint"

7. Agregar pre-checks al testing-agent

Si los tests fallaron por falta de infraestructura:

# Agregar al testing-agent.md:
## Before Writing Tests
1. Verify the source files exist (Glob)
2. Verify the project can import the modules (Bash: python -c "import src.api")
3. Check if conftest.py exists; create if not
4. Check if pytest is installed (Bash: python -m pytest --version)

8. Consolidar el quality review

Si el docs-review-agent no produjo un review útil:

# Agregar al docs-review-agent.md:
## Review Template (MANDATORY)
Your review MUST include ALL of these sections:
1. Files Reviewed (list with quality grade A-D)
2. Critical Issues (must fix before merge)
3. Warnings (should fix soon)
4. Suggestions (nice to have)
5. Positive Patterns (what was done well)
Do NOT produce generic reviews. Be specific with file:line references.

9. Mejorar error messages del team lead

Si los mensajes de error no fueron útiles:

# Agregar al team-lead.md:
## Error Reporting Format
When reporting errors to the user:
1. WHAT failed (task ID, agent, specific error)
2. WHY it failed (dependency missing, timeout, boundary violation)
3. IMPACT (which downstream tasks are blocked)
4. RECOMMENDATION (retry with X, manual intervention needed, skip)

10. Agregar métricas de costo al SubagentStop hook

Si quieres tracking de costos:

#!/bin/bash
# subagent-stop-log-v2.sh
INPUT=$(cat)
AGENT=$(echo "$INPUT" | jq -r '.agent_name // "unknown"')
DURATION=$(echo "$INPUT" | jq -r '.duration_ms // 0')
COST=$(echo "$INPUT" | jq -r '.cost_usd // 0')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

LOG_DIR="logs/agents"
mkdir -p "$LOG_DIR"

echo "[$TIMESTAMP] Agent: $AGENT | Duration: ${DURATION}ms | Cost: \$${COST} | Status: completed" \
  >> "$LOG_DIR/agent-activity.log"

exit 0

Parte 5: Template de Retrospectiva

Usa este template para documentar tu retrospectiva. Puedes guardarlo en docs/retrospective.md:

# Multi-Agent System Retrospective

**Date:** [fecha]
**Feature:** [qué se implementó]
**Team:** 5 agents (team lead + frontend + backend + testing + docs/review)

## What Went Well (Liked)
1. [algo que funcionó bien]
2. [algo que funcionó bien]
3. [algo que funcionó bien]

## What Was Challenging (Learned)
1. [algo que fue difícil pero aprendiste]
2. [algo que fue difícil pero aprendiste]
3. [algo que fue difícil pero aprendiste]

## What Didn't Work (Lacked)
1. [algo que no funcionó]
2. [algo que no funcionó]
3. [algo que no funcionó]

## What to Change (Longed For)
1. [algo que cambiarías para la próxima vez]
2. [algo que cambiarías para la próxima vez]
3. [algo que cambiarías para la próxima vez]

## Metrics
- Total execution time: ___
- Tasks completed: ___/___
- Tasks blocked: ___
- Agent with most time: ___
- Agent with most tasks: ___
- Total cost (estimated): ___

## Action Items for Next Run
- [ ] [acción concreta]
- [ ] [acción concreta]
- [ ] [acción concreta]
- [ ] [acción concreta]

La metodología 4Ls

Este template usa la metodología 4Ls (Liked, Learned, Lacked, Longed For), que es estándar en retrospectivas ágiles:

  • Liked — ¿Qué funcionó bien y quieres mantener?
  • Learned — ¿Qué aprendiste durante la ejecución?
  • Lacked — ¿Qué faltó o no funcionó?
  • Longed For — ¿Qué deseas que hubiera existido o funcionado diferente?

Parte 6: Planificando la Próxima Ejecución

Checklist de mejoras para V2

Basándote en tu retrospectiva, crea un plan para la siguiente ejecución del sistema:

V2 IMPROVEMENTS CHECKLIST
══════════════════════════

Agent Files:
- [ ] Actualizar boundaries del frontend-agent (agregar src/utils/ si es necesario)
- [ ] Agregar naming conventions explícitas al team lead
- [ ] Reducir maxTurns de agentes rápidos
- [ ] Agregar pre-checks al testing-agent

Task Board:
- [ ] Agregar 2-3 tareas frontend independientes del backend
- [ ] Dividir tareas de backend grandes en subtareas
- [ ] Ajustar dependencias basándote en el flujo real

Hooks:
- [ ] Agregar boundary enforcement hook
- [ ] Agregar métricas de costo al SubagentStop hook
- [ ] Ajustar sensibilidad del PreToolUse hook (si fue demasiado estricto)

CLAUDE.md:
- [ ] Agregar naming conventions para src/types/
- [ ] Agregar Architecture Decision Records
- [ ] Clarificar ownership de directorios compartidos

Monitoring:
- [ ] Agregar cost tracking al dashboard
- [ ] Agregar notificaciones de completion
- [ ] Agregar comparison entre ejecuciones

Patrones de iteración

Iteración 1 (lo que hiciste): 5 agentes, 10 tareas, feature de CRUD básica.

Iteración 2 (mejorada): Mismos 5 agentes con system prompts mejorados, hooks de boundary enforcement, task board optimizado con tareas paralelas adicionales.

Iteración 3 (expandida): 6 agentes (agregar security-agent), 12 tareas, feature más compleja (CRUD + auth + rate limiting).

Iteración 4 (producción): Plugin publicado, pipeline de CI/CD (Guía #10), security audit integrado (Guía #11), ejecución en CI automático.

Parte 7: Conexión con el Resto del Path

Lo que completaste

Has terminado la Guía #9: Advanced Claude Code Workflows. Aquí está todo lo que dominaste:

Guía #9 — Complete ✅
├── M1: Custom Subagents ────────── Crear agentes con identidad propia
├── M2: Agent Memory ────────────── Memory scopes para contexto compartido
├── M3: Parallel Delegation ─────── Frontend + backend simultáneo
├── M4: Agent Teams ─────────────── Team lead + task board + dependencias
├── M5: Plugins ─────────────────── Empaquetar y distribuir configuraciones
├── M6: Hooks + SDK ─────────────── Quality gates + ejecución programática
├── M7: Remote + CLAUDE.md ──────── Gobernanza + aprobaciones remotas
└── M8: Proyecto Integrador ─────── Sistema multi-agente funcional

Guía #10: Claude Code in CI/CD Pipelines

La siguiente guía toma lo que construiste aquí y lo integra en pipelines de integración continua:

  • SDK headless en GitHub Actions — Los scripts Python que escribiste en M6 y M8 se ejecutan como CI steps
  • Hooks como CI checks — Los hooks PreToolUse y PostToolUse se convierten en quality gates en el pipeline
  • Agentes en CI — Los agent files se empaquetan en el repositorio y se ejecutan en cada PR
  • Code review automático — El docs-review-agent se ejecuta automáticamente en cada pull request
  • Test automation — El testing-agent corre la suite completa y reporta en el PR

Conexión directa: el orchestrator.py que creaste en la cápsula 04 se convierte en el script que GitHub Actions ejecuta.

Guía #11: Security Deep Dive

La guía de seguridad profundiza en aspectos que aquí mencionamos superficialmente:

  • Boundary enforcement — De reglas en system prompts a enforcement técnico real
  • Secrets management — Los hooks PreToolUse que bloquean .env se extienden con scanning de secrets
  • Agent permissions — --allowedTools y --disallowedTools como modelo de seguridad
  • Audit trails — Los logs de SubagentStop se extienden con audit logs completos
  • CLAUDE.md security policies — Políticas de seguridad como parte de la constitución del equipo

Conexión directa: el hook pre-tool-validate.sh que creaste aquí se convierte en la base del security scanning en la Guía #11.

Parte 8: Resumen de la Guía Completa

Lo que sabías antes de esta guía

  • Usabas Claude Code como herramienta interactiva
  • Habías experimentado con subagents básicos
  • Conocías hooks a nivel introductorio
  • CLAUDE.md era un archivo de instrucciones

Lo que sabes ahora

  • Custom Subagents (M1): Crear agentes con identidad propia — roles, restricciones de herramientas, system prompts especializados, output formats definidos. Cada agente es un especialista con boundaries claros.

  • Agent Memory (M2): Configurar memory scopes (session, project, global) para que los agentes compartan contexto y recuerden decisiones entre sesiones. La memoria convierte agentes stateless en agentes con historia.

  • Parallel Delegation (M3): Delegar tareas a múltiples agentes simultáneamente, gestionar dependencias entre ellos, y resolver conflictos de merge. El paralelismo multiplica la velocidad sin multiplicar los errores.

  • Agent Teams (M4): Organizar agentes en equipos con un team lead coordinador, task board con dependencias formales, y protocolos de comunicación. El team lead no ejecuta — coordina, forwardea contexto, y resuelve conflictos.

  • Plugins (M5): Empaquetar agent files, skills, y hooks en paquetes npm distribuibles. Un npm install configura un equipo completo de agentes. Versionado semver para control de cambios.

  • Hooks + SDK (M6): Hooks como sistema nervioso (7 eventos: SessionStart, PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop, PermissionRequest) y SDK headless como control programático (Python y TypeScript).

  • Remote Control + CLAUDE.md (M7): CLAUDE.md como constitución del equipo — estándares compartidos que todos los agentes respetan. Remote control para aprobar operaciones desde el celular. Governance sin micromanagement.

  • Sistema Multi-Agente (M8): 5 agentes trabajando coordinados con task board, ejecución paralela, quality gates automáticos, monitoring via SDK, y retrospectiva de mejora continua. De herramienta a sistema.

El salto mental

ANTES:  Yo → prompt → Claude → resultado → yo reviso → siguiente prompt

AHORA:  Yo diseño el sistema → 5 agentes ejecutan → hooks validan →
        SDK monitorea → reportes se generan → yo analizo resultados →
        optimizo para la siguiente ejecución

El cambio no es cuantitativo (más rápido, más código). Es cualitativo: pasaste de operar una herramienta a diseñar un sistema de automatización. La diferencia entre un piloto que vuela un avión y un ingeniero que diseña el sistema de navegación autónoma.

Parte 9: Entregables Finales

Checklist de completitud

Verifica que tienes todos los entregables del módulo:

MÓDULO 8 — ENTREGABLES
═══════════════════════

Agent Files:
✅ .claude/agents/team-lead.md
✅ .claude/agents/backend-agent.md
✅ .claude/agents/frontend-agent.md
✅ .claude/agents/testing-agent.md
✅ .claude/agents/docs-review-agent.md

Hooks:
✅ scripts/hooks/post-edit-lint.sh
✅ scripts/hooks/pre-tool-validate.sh
✅ scripts/hooks/subagent-stop-log.sh

Configuration:
✅ .claude/settings.json (hooks configurados)
✅ CLAUDE.md (constitución del equipo)

Plugin:
✅ multi-agent-plugin/package.json
✅ multi-agent-plugin/agents/ (5 agent files)
✅ multi-agent-plugin/skills/team-conventions.md

Monitoring:
✅ scripts/monitor/team-monitor.py
✅ scripts/monitor/orchestrator.py
✅ scripts/monitor/metrics.py
✅ scripts/run-team.sh

Documentation:
✅ docs/reports/ (execution reports)
✅ docs/retrospective.md (retrospective template filled)

Logs:
✅ logs/agents/agent-activity.log (generated by execution)

Checklist de habilidades

HABILIDADES DOMINADAS
═════════════════════

Custom Subagents:
✅ Crear agent files con frontmatter YAML
✅ Definir roles, boundaries, y output formats
✅ Restringir herramientas por agente

Agent Teams:
✅ Configurar team lead como coordinador (no ejecutor)
✅ Diseñar task board con dependencias
✅ Gestionar ejecución paralela

Hooks:
✅ PreToolUse para validación y bloqueo
✅ PostToolUse para auto-linting
✅ SubagentStop para logging

SDK:
✅ Ejecutar Claude Code desde Python
✅ Parsear resultados JSON
✅ Monitoring en tiempo real

Governance:
✅ CLAUDE.md como constitución del equipo
✅ Plugins para distribución
✅ Remote control para aprobaciones

System Design:
✅ Diseñar arquitectura multi-agente
✅ Analizar performance y cuellos de botella
✅ Optimizar para la siguiente iteración

Parte 10: ¿Qué Sigue?

Siguiente paso inmediato

Elige UNA cosa de tu retrospectiva y aplícala. No intentes hacer las 10 optimizaciones a la vez. Elige la que tenga más impacto con menos esfuerzo:

  • Si el context forwarding fue el problema → actualiza el team lead
  • Si los boundaries se violaron → agrega el hook de enforcement
  • Si el task board fue ineficiente → rediseña con más paralelismo
  • Si el testing fue insuficiente → mejora el testing-agent

Siguiente guía: CI/CD Pipelines

Cuando estés cómodo con el sistema multi-agente local, pasa a la Guía #10: Claude Code in CI/CD Pipelines. Ahí integrarás este sistema en GitHub Actions para que se ejecute automáticamente en cada PR.

Siguiente guía después: Security Deep Dive

Después de CI/CD, la Guía #11: Security Deep Dive profundiza en todo lo que aquí tratamos superficialmente: permissions model, secrets scanning, audit trails, y security policies en CLAUDE.md.

El ciclo de mejora

Ejecutar → Monitorear → Analizar → Optimizar → Ejecutar de nuevo
    ↑                                                    │
    └────────────────────────────────────────────────────┘

Este ciclo no termina. Cada ejecución te da datos. Cada retrospectiva te da insights. Cada optimización mejora la siguiente ejecución. El sistema multi-agente no es un producto terminado — es un sistema vivo que mejoras continuamente.

Resumen de la Cápsula

  • La retrospectiva analiza resultados por agente: ¿qué produjo cada uno? ¿coincide con lo esperado?
  • El análisis de performance identifica agentes lentos, idle time, y overhead de coordinación
  • El análisis de conflictos documenta type mismatches, naming inconsistencies, boundary violations, y dependency violations
  • Las 10 optimizaciones cubren: context forwarding, tareas paralelas, maxTurns, naming conventions, boundary enforcement, task granularity, pre-checks, review templates, error reporting, y cost tracking
  • El template 4Ls (Liked, Learned, Lacked, Longed For) estructura la retrospectiva
  • La V2 checklist prioriza mejoras para la siguiente ejecución
  • La guía se conecta con CI/CD (Guía #10) para automatización en pipelines y Security (Guía #11) para hardening del sistema

Parte 11: Anti-Patterns — Qué NO Hacer

Los 7 anti-patterns más comunes

Después de múltiples ejecuciones del sistema multi-agente, estos son los errores que más se repiten:

1. Team lead que ejecuta código

El team lead tiene Read y Glob para entender el contexto, no para implementar. Si le das Write o Edit, tarde o temprano decidirá que es "más rápido hacerlo él mismo" y producirá código que no sigue las convenciones del agente especializado.

2. Agentes sin boundaries explícitos

"Trabaja en el frontend" no es un boundary. "Trabaja en src/components/, src/pages/, src/hooks/, src/styles/" sí lo es. La vaguedad produce solapamiento, y el solapamiento produce conflictos.

3. Task board sin dependencias

Un task board donde todas las tareas son "none" en dependencias es un todo-list, no un task board. Las dependencias son lo que permite paralelismo y previene errores.

4. Context forwarding implícito

Asumir que el frontend-agent "verá" los tipos que el backend publicó no es suficiente. El team lead debe forwardear explícitamente qué archivos, qué tipos, y qué endpoints están disponibles.

5. Testing antes de que exista código

El testing-agent que arranca antes de que las tareas de implementación terminen produce tests que no compilan, fixtures que asumen código inexistente, y errores falsos que desperdician turns.

6. Hooks demasiado estrictos

Un hook PreToolUse que bloquea todo rm sin contexto bloqueará operaciones legítimas como borrar archivos de test obsoletos. Los hooks deben ser específicos: bloquear rm -rf / pero permitir rm tests/test_old.py.

7. No mantener running summary

Sin un running summary, el team lead pierde el contexto de las primeras tareas cuando llega al reporte final. El context window no es infinito — el summary compensa esa limitación.

Resumen de la Guía Completa

Advanced Claude Code Workflows — Guía #9 de 11

8 módulos · 3 phases · 8-10 horas

MóduloAprendizaje CoreEntregable
M1Crear agentes con identidad propia3 custom subagent files
M2Memory scopes para contexto compartidoJerarquía de memoria configurada
M3Delegación paralela con mergeRefactor ejecutado en paralelo
M4Agent Teams con task boardEquipo de 3 agentes funcional
M5Plugins distribuiblesPlugin npm publicado
M6Hooks + SDK headlessPipeline automatizado end-to-end
M7Remote control + CLAUDE.mdGobernanza de equipo
M8Sistema multi-agente completo5 agentes + hooks + monitoring

El arco de la guía:

Individual (M1-M3)     → Team (M4-M5)     → System (M6-M8)
"Un agente hace X"     → "Agentes coordinan" → "El sistema se auto-opera"

El resultado: Un sistema de desarrollo multi-agente que puedes adaptar a cualquier proyecto. Los agentes son plantillas — cambia los roles y el sistema funciona igual. Los hooks son gates — cambia las reglas y la calidad se mantiene. El monitoring es observabilidad — cambia las métricas y sigues teniendo visibilidad.

No construiste un proyecto — construiste una capacidad.

Recursos Adicionales

  1. Create Custom Subagents (Anthropic Docs) — Referencia base de todo el sistema de agentes
  2. Claude Code Hooks — Hooks como quality gates y sistema nervioso
  3. Claude Code CLI Reference — SDK headless, flags, y modos de ejecución
  4. Claude Code Settings — Configuración de hooks y preferencias
  5. Claude Code Best Practices — Buenas prácticas de automatización
  6. Multi-Agent Orchestration — Patrones de orquestación multi-agente
  7. Prompt Engineering: System Prompts — System prompts para agentes especializados
  8. Claude Code Overview — Contexto general de Claude Code como plataforma

Nota Final

Terminaste la guía más avanzada del path. Lo que construiste no es un demo — es un sistema funcional. Los agent files, hooks, scripts de monitoring, y el plugin son artefactos reales que puedes usar mañana en tu proyecto. Adapta los roles, ajusta los boundaries, cambia el stack tecnológico, pero mantén la arquitectura: coordinación por task board, quality gates automáticos, monitoring por SDK, y gobernanza por CLAUDE.md.

El sistema multi-agente no reemplaza tu criterio. Lo amplifica. Tú diseñas, los agentes ejecutan, los hooks validan, y tú analizas los resultados. El ciclo de mejora continua es lo que convierte un buen sistema en un sistema excelente.

Siguiente guía: La Guía #10 (Claude Code in CI/CD Pipelines) integra todo lo que construiste aquí en GitHub Actions. Los agent files se versionan en el repo, los hooks se convierten en CI checks, el SDK orchesta ejecuciones en cada PR, y el sistema multi-agente se convierte en parte de tu pipeline de desarrollo. Lo que hoy corre en tu terminal, mañana corre en la nube.

← Anterior4. Monitoring — SDK para Observabilidad, Remote Control para Aprobaciones