3. Compartir Memoria entre Subagents

Descripción

En la cápsula anterior configuraste memoria en tres scopes: user, project, y local. Cada subagent tiene su propio MEMORY.md en su propio directorio. Esto resuelve la amnesia individual — el reviewer recuerda patrones, el implementer recuerda convenciones. Pero crea un nuevo problema: memorias independientes que pueden contradecirse.

El reviewer registra "el proyecto usa camelCase para funciones." El implementer, en otra sesión, observa snake_case en un módulo diferente y registra "la convención es snake_case." Cuando el reviewer reporta "naming inconsistency" y el implementer "corrige" según su propia memoria, el resultado es código que sigue dos convenciones diferentes. La memoria individual sin coordinación produce exactamente el tipo de inconsistencia que la memoria debería evitar.

Esta cápsula te enseña estrategias para compartir contexto entre subagents de forma controlada: memoria complementaria, convenciones compartidas, CLAUDE.md como fuente de verdad, y patrones prácticos para sistemas de 3+ subagents. Al terminar, sabrás diseñar una estrategia de memoria que escala sin contradicciones — el prerequisito para la cápsula 05.

El Problema: Memorias Aisladas

Por qué la memoria individual no basta

Cuando habilitas memory: project en el reviewer y en el implementer, cada uno tiene su propio directorio:

.claude/agent-memory/
├── reviewer/
│   └── MEMORY.md       ← el reviewer lee y escribe aquí
└── implementer/
    └── MEMORY.md       ← el implementer lee y escribe aquí

Son dos archivos independientes. Ningún subagent lee el MEMORY.md del otro por defecto. Cada uno construye su propia versión de la verdad:

reviewer/MEMORY.md:
  "Team uses repository pattern for all DB access"
  "Error handling: raise HTTPException directly in routes"

implementer/MEMORY.md:
  "DB access through direct SQLAlchemy queries in routes"
  "Error handling: custom AppError hierarchy with middleware"

Ambos observaron patrones reales, pero de módulos diferentes o momentos diferentes. Sin coordinación, el implementer aplica convenciones que el reviewer marcará como inconsistentes.

El costo en un flujo multi-agente

reviewer → "routes/orders.py: uses direct queries,
            should use repository pattern per convention"

implementer → lee su propia memoria, no la del reviewer
           → "my memory says direct queries are the convention"
           → no corrige el issue

tester → ejecuta tests, todo pasa
       → el anti-pattern queda en el código

El pipeline completó sin errores, pero la inconsistencia arquitectural sobrevivió porque los agentes trabajan con versiones diferentes de la realidad.

Estrategia 1: Memoria Complementaria

El concepto

En lugar de que cada subagent mantenga una copia independiente de la verdad, asignas roles de memoria complementarios. El reviewer se especializa en recordar ciertos aspectos, el implementer en otros. Ninguno duplica la información del otro.

reviewer/MEMORY.md    → Patrones del codebase, issues, decisiones de diseño
implementer/MEMORY.md → Convenciones de código, library patterns, file map
tester/MEMORY.md      → Test results, flaky tests, coverage trends

Implementación: system prompts especializados

System prompt del reviewer — especialización en observaciones:

## Memory Management — Specialization: Observations
Your MEMORY.md tracks:
- Architecture patterns observed across the codebase
- Design decisions found in code comments or PR descriptions
- Recurring issues and their resolution status
You DO NOT track:
- Code conventions (implementer's responsibility)
- Test results (tester's responsibility)

System prompt del implementer — especialización en convenciones:

## Memory Management — Specialization: Conventions
Your MEMORY.md tracks:
- Naming conventions observed and enforced
- Library-specific patterns (how the project uses SQLAlchemy, etc.)
- Implementation patterns that should be consistent
You DO NOT track:
- Architecture decisions (reviewer's responsibility)
- Test results (tester's responsibility)

Cross-reading: leer la memoria de otros

La clave: cada subagent lee la memoria de los demás al inicio, pero solo escribe en la suya.

## Cross-Memory Reading

Before starting your work, read other agents' memories:
1. Read `.claude/agent-memory/reviewer/MEMORY.md` for architecture
   decisions and known issues
2. Read `.claude/agent-memory/implementer/MEMORY.md` for code
   conventions and library patterns

Use this context to inform your work, but ONLY write to YOUR
memory directory: `.claude/agent-memory/[your-name]/`

Subagent completo con lectura cruzada

---
name: implementer
description: Implements code changes following project conventions
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
maxTurns: 30
memory: project
---

## Role
You are a senior developer implementing code changes in src/.

## Cross-Memory Reading
Before implementing, read context from team agents:
1. Read `.claude/agent-memory/reviewer/MEMORY.md` for:
   - Architecture decisions (inform your approach)
   - Known issues (avoid reintroducing fixed bugs)
2. Your own memory (auto-injected) provides:
   - Code conventions to follow
   - Library patterns to apply

## Memory Management — Specialization: Conventions
Update YOUR memory with:
- New conventions you observe during implementation
- Library usage patterns discovered
- File/module purposes clarified

Do NOT write architecture decisions — that's the reviewer's domain.
If you discover an architectural pattern, note it in your report
so the reviewer captures it in their next run.

## Constraints
- ONLY modify files inside src/
- NEVER modify other agents' MEMORY.md
- When conventions conflict between memories, prefer the reviewer's
  (broader project visibility)

## Output Format
### Implementation Report
**Cross-memory context applied:**
- From reviewer memory: [patterns/decisions applied]
- From own memory: [conventions applied]
**Changes made:**
1. **[file]** — Description
**Suggested memory updates for reviewer:**
- [architectural patterns observed that reviewer should capture]

Estrategia 2: Directorio de Memoria Compartido

El concepto

En lugar de memorias separadas, un directorio común con archivos temáticos. Requiere un curator designado que controle la escritura:

.claude/agent-memory/reviewer/
├── MEMORY.md           ← memoria propia del reviewer
├── architecture.md     ← reviewer escribe, todos leen
├── conventions.md      ← reviewer escribe, todos leen
└── known-issues.md     ← reviewer escribe, todos leen

Implementación

El reviewer actúa como curator principal:

## Shared Memory Management (Reviewer as Curator)
You are the PRIMARY writer of shared memory files:
1. Update `architecture.md` with architectural patterns observed
2. Update `conventions.md` with coding conventions confirmed
3. Update `known-issues.md` with new issues found or resolved

Los demás subagents leen pero no editan estos archivos:

## Cross-Memory Reading (for implementer)
Before implementing, read the shared memory files:
1. `.claude/agent-memory/reviewer/architecture.md`
2. `.claude/agent-memory/reviewer/conventions.md`
3. `.claude/agent-memory/reviewer/known-issues.md`

If you discover information for these files, include it in your
report under "Suggested memory updates" — the reviewer captures it.

Cuándo usar esta estrategia

• ✅ Equipos pequeños (2-3 agentes) donde un curator natural existe
• ✅ Proyectos donde la consistencia de la memoria es crítica
• ❌ No escala bien con muchos agentes — el curator es bottleneck

Estrategia 3: CLAUDE.md como Fuente de Verdad

El concepto

CLAUDE.md es leído por todos los agentes, incluyendo subagents. Pon la verdad fundamental ahí y usa memorias para contexto específico del agente.

CLAUDE.md           → Verdad compartida: arquitectura, convenciones, stack
MEMORY.md (reviewer) → Contexto específico: issues encontrados, patrones
MEMORY.md (implementer) → Contexto específico: library patterns, file map
MEMORY.md (tester)   → Contexto específico: resultados, flaky tests

Implementación

CLAUDE.md — verdad del proyecto:

# CLAUDE.md

## Architecture
- FastAPI + SQLAlchemy + Alembic + PostgreSQL
- Routes in src/routes/, models in src/models/
- Repository pattern for ALL database access

## Code Conventions
- Snake_case for all Python identifiers
- Type hints required on all public functions
- Custom AppError hierarchy for error handling (src/exceptions.py)

System prompt — jerarquía de verdad:

## Context Hierarchy
Your sources of truth, in priority order:
1. **CLAUDE.md** — Project truth. NEVER contradict CLAUDE.md.
2. **Your MEMORY.md** — Your accumulated observations.
   Use for context that complements CLAUDE.md.
3. **Code inspection** — Current state.
   If code contradicts CLAUDE.md, report the deviation.

If your MEMORY.md contradicts CLAUDE.md, update your MEMORY.md
to align — the team source takes priority.

Cuándo usar esta estrategia

• ✅ Cualquier proyecto con CLAUDE.md bien mantenido
• ✅ Combina naturalmente con las otras dos estrategias
• ❌ No reemplaza la necesidad de memoria específica del agente

Comparación: Estrategias de Memoria

Recomendación práctica

Combina la Estrategia 3 (CLAUDE.md como verdad) con la Estrategia 1 (memoria complementaria):

CLAUDE.md → Verdad compartida (arquitectura, convenciones)
                 ↑ todos los agentes leen

reviewer/MEMORY.md → Observaciones (issues, anti-patterns)
                       ↑ implementer lee al inicio

implementer/MEMORY.md → Convenciones prácticas (library patterns)
                          ↑ reviewer lee para contexto

tester/MEMORY.md → Resultados de tests (privado, scope local)
                     ↑ solo el tester lee/escribe

Read-Only vs Read-Write: Ownership

El problema de la escritura sin coordinación

En sesiones diferentes, dos subagents pueden llegar a conclusiones opuestas. Si ambos escriben en archivos compartidos, el último en ejecutarse gana.

Patrón: ownership claro

Asigna un solo writer por archivo:

Para el owner (read-write):

## Memory: MEMORY.md (OWNER)
You own your MEMORY.md. Keep it current and accurate.

Para los lectores (read-only):

## Cross-Memory: reviewer/MEMORY.md (READER)
Read `.claude/agent-memory/reviewer/MEMORY.md` for context.
You MUST NOT write to this file — the reviewer owns it.
If you discover relevant info, include it in your output
under "Suggested memory updates for reviewer."

Las herramientas de escritura activadas por memory están scoped al directorio del agente. Para leer archivos de otros agentes, usa Read (no restringido por scope de memoria).

Naming Conventions

Reglas recomendadas

1. El nombre del directorio = el name del frontmatter (automático)
2. Archivos adicionales siguen kebab-case: known-issues.md, library-patterns.md
3. Prefijo de contexto cuando tienes variantes del mismo agente:

name: reviewer-security    # → .claude/agent-memory/reviewer-security/
name: reviewer-performance # → .claude/agent-memory/reviewer-performance/

4. Nombres descriptivos, no genéricos:

✅ reviewer, implementer, tester, doc-generator
❌ agent-1, agent-2, helper, worker

Qué Compartir vs Qué Mantener Privado

La regla simple

¿Si un colega ve esto, le ayuda o le perjudica?
→ Le ayuda: compartir (project scope o CLAUDE.md)
→ Le es indiferente: privado (local scope)
→ Le perjudica o es riesgoso: privado (local scope)

Patrones Prácticos: Sistema de 3 Agentes

Diagrama de flujo de memoria

CLAUDE.md (fuente de verdad del proyecto)
    ↑ todos leen
    │
    ├── reviewer (memory: project)
    │   ├── MEMORY.md → Patrones, issues, decisiones
    │   └── Lee: implementer/MEMORY.md para convenciones
    │
    ├── implementer (memory: project)
    │   ├── MEMORY.md → Convenciones, library patterns
    │   └── Lee: reviewer/MEMORY.md para arquitectura
    │
    └── tester (memory: local)
        ├── MEMORY.md → Test results, flaky tests, coverage
        └── Lee: reviewer/MEMORY.md para issues a verificar

Flujo de información en el pipeline

Sesión 1 — reviewer ejecuta:
  1. Lee CLAUDE.md (verdad del proyecto)
  2. Lee su MEMORY.md (inyectado auto)
  3. Lee implementer/MEMORY.md (convenciones)
  4. Analiza código
  5. Actualiza su MEMORY.md con hallazgos
  6. Produce reporte

Sesión 2 — implementer ejecuta:
  1. Lee CLAUDE.md
  2. Lee su MEMORY.md (inyectado auto)
  3. Lee reviewer/MEMORY.md (issues y decisiones)
  4. Implementa fixes
  5. Actualiza su MEMORY.md con convenciones descubiertas
  6. Produce reporte

Sesión 3 — tester ejecuta:
  1. Lee CLAUDE.md
  2. Lee su MEMORY.md (inyectado auto)
  3. Lee reviewer/MEMORY.md (issues a verificar)
  4. Ejecuta tests
  5. Actualiza su MEMORY.md con resultados
  6. Produce reporte con comparación vs sesión anterior

System prompt template para lectura cruzada

Usa este patrón en cualquier subagent que necesite leer la memoria de otros:

## Cross-Memory Context

Before starting work, gather context from team memory:

### Required Reading
1. **CLAUDE.md** — Project truth
2. **Your MEMORY.md** — Auto-injected, your accumulated context
3. **`.claude/agent-memory/reviewer/MEMORY.md`** — Architecture,
   known issues, design patterns

### Priority Order (for conflicts)
1. CLAUDE.md wins (team-agreed truth)
2. Reviewer memory (broadest visibility)
3. Your own memory (your domain expertise)
4. Code inspection (current state)

### Report Conflicts
If sources contradict each other, include them in your output
under "Memory Conflicts Detected" for human resolution.

Conexión con el Proyecto

Hacia la cápsula 05: Memory Hierarchy para 3 Subagents

En la cápsula 05 implementarás la jerarquía completa:

CLAUDE.md → verdad del proyecto (editable solo por humanos)
     ↓
reviewer  (project) → observaciones, issues, decisiones
     ↕ lectura cruzada
implementer (project) → convenciones, library patterns
     ↕ lectura cruzada
tester (local) → resultados, flaky tests, coverage

La cápsula 05 te pedirá: configurar los 3 subagents con memoria, ejecutar el pipeline completo, cerrar y reabrir la sesión, ejecutar de nuevo y verificar que la memoria influyó en los resultados, e inspeccionar los 3 archivos MEMORY.md para confirmar consistencia.

Troubleshooting

"El subagent no lee la memoria de otros agentes"

Causa: Las instrucciones de lectura cruzada no son explícitas o el path es incorrecto.

Fix: Verifica que el subagent tiene Read en sus tools (Read no está restringida al directorio de memoria) y que el path en las instrucciones es correcto: .claude/agent-memory/reviewer/MEMORY.md, no reviewer/MEMORY.md.

"Las memorias se contradicen"

Causa: Dos agentes observaron aspectos diferentes del codebase y sacaron conclusiones opuestas.

Fix: Implementa la jerarquía de verdad: CLAUDE.md > reviewer > implementer. El agente que detecta la contradicción la reporta en su output para resolución humana.

"Un subagent sobrescribe la memoria de otro"

Causa: El subagent tiene Write habilitado y no sabe qué directorio es suyo.

Fix: Las herramientas de escritura por memory están scoped al directorio del agente. Pero si tiene Write en herramientas generales (como el implementer), puede escribir en cualquier archivo. Refuerza en el system prompt: "NEVER write to any memory directory except your own."

"MEMORY.md de un agente está vacío pero los demás tienen contenido"

Causa: El subagent no se ejecutó aún, o su system prompt no incluye instrucciones de memoria.

Fix: Ejecuta cada subagent al menos una vez para inicializar su MEMORY.md. Agrega ## Memory Management al system prompt de cada subagent.

Ejercicios

Ejercicio 1: Identificar contradicciones (Fácil)

El reviewer anotó "services usan inyección de dependencias" (observó src/services/). El implementer anotó "funciones son puras, sin inyección" (observó src/utils/). Se pide al implementer crear un nuevo servicio en src/services/. ¿Qué contradicción surge?

Ejercicio 2: Diseñar ownership de archivos (Fácil)

Tienes 3 agentes y 5 tipos de información. Asigna quién escribe y quién lee cada uno:

1. Patrones arquitecturales
2. Convenciones de naming
3. Resultados de test suite
4. Bugs conocidos y su estado
5. Library versions y compatibilidades

Ejercicio 3: Escribir instrucciones de lectura cruzada (Medio)

Escribe la sección ## Cross-Memory Context para un doc-generator que genera documentación de API. Debe leer: reviewer (arquitectura), implementer (convenciones), tester (endpoints verificados). Define qué busca en cada memoria y la prioridad de conflictos.

## Cross-Memory Context

Before generating documentation, gather context:

### Required Reading
1. **CLAUDE.md** — Project truth: architecture, stack, conventions
2. **Your MEMORY.md** — Documentation style, templates, glossary
3. **`.claude/agent-memory/reviewer/MEMORY.md`** —
   Module purposes, design patterns, architectural decisions
4. **`.claude/agent-memory/implementer/MEMORY.md`** —
   Endpoint signatures, response formats, library patterns
5. **`.claude/agent-memory-local/tester/MEMORY.md`** —
   Which endpoints have passing tests (mark as "verified")

### Priority for Conflicts
1. CLAUDE.md → 2. Reviewer → 3. Implementer → 4. Tester → 5. Code

### What to Extract
From reviewer: module purposes, architecture overview
From implementer: endpoint signatures, request/response schemas
From tester: verification status per endpoint

Ejercicio 4: Implementar CLAUDE.md como fuente de verdad (Medio)

Tienes información dispersa en 3 memorias. Extrae lo que debería estar en CLAUDE.md:

reviewer: "FastAPI 0.104, SQLAlchemy 2.0 async, repository pattern since abc123" implementer: "snake_case, type hints required, {data, error, meta} response format" tester: "pytest, test_[action]_[scenario] naming, 80% min coverage"

# CLAUDE.md

## Architecture
- FastAPI 0.104.0 + SQLAlchemy 2.0 (async)
- Repository pattern for ALL database access
- All API responses: {data, error, meta} format

## Code Conventions
- Snake_case for all Python identifiers
- Type hints required on all public functions

## Testing
- Framework: pytest
- Test naming: test_[action]_[scenario]
- Minimum coverage: 80%

Ejercicio 5: Resolver una contradicción (Difícil)

El reviewer tiene: "Error handling: raise HTTPException directly." El implementer tiene: "Error handling: use AppError hierarchy, never HTTPException." Diseña un plan de 4 pasos: investigar, decidir, actualizar fuentes, y prevenir futuras contradicciones.

grep -r "raise HTTPException" src/routes/
grep -r "raise AppError\|raise.*Error" src/routes/

# En CLAUDE.md:
## Error Handling
- Use custom AppError hierarchy (src/exceptions.py)
- Legacy: some routes still use HTTPException — migrate when touched

# En reviewer/MEMORY.md:
- OFFICIAL: AppError hierarchy (confirmed with team)
- LEGACY: HTTPException in some routes — flag as WARNING

# En implementer/MEMORY.md:
- AppError is standard (confirmed in CLAUDE.md)
- Migrate old HTTPException routes to AppError when touched

## Conflict Prevention (add to all system prompts)
When you observe a pattern inconsistent with your memory or CLAUDE.md:
1. Do NOT update memory with the new pattern
2. Report it as "Potential convention conflict" in your output
3. Let the human resolve — only update memory after confirmation

Ejercicio 6: Diseñar memoria para 4 agentes (Difícil)

Proyecto con 4 subagents: reviewer, implementer, tester, deployer (verifica readiness para deploy). Diseña: scope, categorías, qué lee de otros, y ownership.

CLAUDE.md (verdad compartida — solo humanos escriben)
    │
    ├── reviewer (project)
    │   ├── MEMORY.md → Architecture, issues, design decisions
    │   └── Lee: implementer, deployer memories
    │
    ├── implementer (project)
    │   ├── MEMORY.md → Conventions, library patterns
    │   └── Lee: reviewer memory
    │
    ├── tester (local)
    │   ├── MEMORY.md → Test results, flaky tests, coverage
    │   └── Lee: reviewer memory (issues to verify)
    │
    └── deployer (project)
        ├── MEMORY.md → Deploy checklist, env requirements
        └── Lee: reviewer, implementer memories

Resumen

• Memorias individuales aisladas pueden contradecirse — cada agente construye su propia versión de la verdad
• Estrategia 1 (Complementaria): Cada agente se especializa en un dominio de memoria y lee las memorias de los demás
• Estrategia 2 (Directorio compartido): Un curator designado escribe archivos temáticos, los demás leen
• Estrategia 3 (CLAUDE.md + memoria): CLAUDE.md es la fuente de verdad compartida; las memorias complementan con contexto específico del rol
• La combinación recomendada: CLAUDE.md como verdad + memorias complementarias
• Ownership claro evita conflictos: cada archivo tiene un solo writer y múltiples readers
• Naming conventions: name del frontmatter = directorio, kebab-case para archivos adicionales
• Compartir: arquitectura, convenciones, decisiones. Mantener privado: credenciales, preferencias, resultados locales
• La jerarquía de verdad (CLAUDE.md > reviewer > implementer) resuelve contradicciones
• Reportar conflictos es mejor que resolverlos silenciosamente — el humano decide
• Esta estrategia coordinada es el building block del proyecto de la cápsula 05

Recursos Adicionales

1. Subagents — Persistent Memory (Anthropic Docs) — Documentación oficial del campo memory y scopes
2. Create Custom Subagents — Referencia completa de frontmatter YAML
3. CLAUDE.md Documentation — Cómo CLAUDE.md funciona como fuente de verdad compartida
4. Claude Code Best Practices — Organización de contexto y memoria
5. Prompt Engineering: System Prompts — Principios aplicables a instrucciones de memoria
6. Claude Code Tips and Tricks — Estructuración de contexto
7. Git Best Practices — Versionar configuración compartida como memory scopes
8. Claude Code Overview — Contexto general del sistema de agentes

Siguiente cápsula: En la cápsula 04 abordarás Memory Management — cómo curar MEMORY.md para que se mantenga útil. Un archivo de 200 líneas lleno de ruido es peor que uno vacío. Aprenderás rotación de contenido, consolidación, priorización dentro del límite de 200 líneas, y estrategias para mantener la memoria limpia a lo largo de semanas de uso.