El error más común al armar sistemas multi-agente: dar a cada subagente su propio contexto aislado. Resultado: duplican trabajo, contradictorios entre sí, pierden info clave. Patrón alternativo: una memoria compartida que todos consultan y actualizan.
Te entusiasmás con la idea de "equipos de agentes" y armás algo así:
Agente Investigador → busca info
Agente Planificador → hace plan
Agente Implementador → ejecuta
Agente Revisor → validaCada uno con su prompt de sistema, su contexto, sus tools. Suena bien. No funciona bien en la práctica.
Lo que pasa en realidad:
Cada agente vive en su burbuja. La info viaja entre ellos por el cuello de botella del orquestador. Se pierde el 60% del contexto.
En lugar de subagentes con contextos aislados, un solo proceso con acceso a una memoria estructurada compartida.
┌─────────────────────────┐
│ Memoria Compartida │
│ (archivos versionados) │
└────────────┬────────────┘
│ lee/escribe
┌────────────┴────────────┐
│ │
┌────▼─────┐ ┌────▼─────┐
│ Tarea A │ │ Tarea B │
│ (Claude) │ │ (Claude) │
└──────────┘ └──────────┘La memoria es una carpeta .memory/ (o el nombre que elijas) con archivos estructurados. Cualquier "agente" (= invocación de Claude) lee y escribe ahí. No hay info en burbujas.
Ejemplo concreto para un proyecto de "armar feature de notificaciones":
.memory/
├── README.md ← cómo navegar esta memoria
├── goals.md ← objetivo de alto nivel
├── decisions/ ← decisiones tomadas con fecha y porqué
│ ├── 2026-05-15-arquitectura.md
│ └── 2026-05-16-stack-email.md
├── research/ ← lo investigado
│ ├── libs-evaluadas.md
│ └── benchmarks.md
├── plan/
│ ├── tasks.md ← lista viva de tareas con estado
│ └── current-task.md ← qué se está haciendo ahora
├── learnings/ ← cosas descubiertas durante la implementación
│ └── ...
└── open-questions.md ← lo que falta decidirReglas de la memoria:
open-questions.md, es un blocker explícitoEn vez de "orquestador que llama subagentes", un loop que:
Esto se puede implementar como:
# pseudocódigo
def loop():
while True:
state = load_memory('.memory/')
if state.has_blockers():
ask_user(state.blockers)
continue
next_task = state.pick_next_task()
if not next_task:
break # nada que hacer
result = run_claude(
system_prompt=AGENT_PROMPT,
context=state.relevant_context(next_task),
task=next_task,
)
update_memory(result)AGENT_PROMPT no cambia entre iteraciones. Lo que cambia es el contexto que se le pasa: filtrado de la memoria según la tarea actual.
Si no querés montar un loop con código, podés implementarlo a mano dentro de Claude Code usando skills.
---
name: context-load
description: Carga el contexto relevante de .memory/ para la tarea actual.
Activala con "cargá contexto" o "leé la memoria".
---
Leé los siguientes archivos de .memory/ y resumime el estado:
1. .memory/goals.md (objetivo general)
2. .memory/plan/current-task.md (qué se está haciendo)
3. .memory/decisions/ (todas las decisiones tomadas)
4. .memory/open-questions.md (blockers)
Devolveme un resumen estructurado en 4 párrafos:
- Objetivo
- Tarea actual
- Decisiones relevantes que aplican
- Blockers (si hay)
NO leas archivos no listados a menos que sean explícitamente relevantes.---
name: context-save
description: Actualiza .memory/ con los cambios hechos. Activala al final
de una sesión con "guardá lo hecho" o "actualizá la memoria".
---
Actualizá los archivos relevantes de .memory/ con lo trabajado en la sesión:
1. Si tomaste decisiones, agregalas a .memory/decisions/<fecha>-<topic>.md
2. Si avanzaste tareas, actualizá .memory/plan/tasks.md (marcar como done lo terminado)
3. Si descubriste algo importante, agregalo a .memory/learnings/
4. Si surgió un blocker, agregalo a .memory/open-questions.md
Sé conciso. La memoria es para futuro yo, no un diario.Ahora cada sesión empieza con "cargá contexto" y termina con "guardá lo hecho". El estado vive en archivos versionados, no en el contexto de Claude.
El único caso donde subagentes-en-burbuja gana es cuando necesitás paralelismo extremo y los agentes son realmente independientes (ej. procesar 1000 imágenes en paralelo, cada agente trabaja sobre 1). Pero ese no es "agentes colaborando" — es "workers paralelos".
✅ Tareas de varios pasos con dependencias (research → plan → implementar → revisar) ✅ Trabajo que se extiende en varias sesiones / días ✅ Equipos donde varios humanos también colaboran (la memoria es legible) ✅ Cuando querés trazabilidad (qué se decidió, cuándo, por qué)
❌ Tareas one-shot triviales ❌ Workers realmente paralelos sin info compartida ❌ Cuando el proceso es totalmente exploratorio y no querés estructura
Si querés probar este patrón hoy, copiate esto a tu repo:
mkdir -p .memory/{decisions,research,plan,learnings}
touch .memory/{goals.md,open-questions.md,README.md}
touch .memory/plan/{tasks.md,current-task.md}.memory/README.md:
# Memoria del proyecto
Esta carpeta es la "fuente de verdad" del estado del trabajo. Cualquier sesión
de Claude (o humano) debería:
1. **Leer** esta memoria al empezar
2. **Actualizarla** al terminar
## Archivos clave
- `goals.md`: objetivo de alto nivel
- `plan/tasks.md`: lista de tareas con estado [todo|wip|done]
- `plan/current-task.md`: descripción detallada de la tarea actual
- `decisions/`: decisiones técnicas (formato: YYYY-MM-DD-topic.md)
- `research/`: investigaciones y benchmarks
- `learnings/`: cosas descubiertas durante implementación
- `open-questions.md`: blockers que necesitan decisión humanaY en tu CLAUDE.md agregale:
## Memoria del proyecto
Antes de tocar código, leé `.memory/README.md` y los archivos relevantes para
la tarea pedida. Al terminar, actualizá la memoria con decisiones y aprendizajes.Eso solo ya cambia cómo Claude opera en sesiones futuras.