01 El problema: cada subagente empieza en blanco
Montas un equipo de subagentes (uno investiga, otro ejecuta, otro revisa) y el resultado decepciona: el segundo repite la búsqueda del primero y el revisor señala como problema algo que ya estaba resuelto y justificado. No es que los roles estén mal escritos; es lo que cada subagente recibe al arrancar.
| Un subagente sí recibe | Un subagente no recibe |
|---|---|
| Su propio prompt de sistema (el cuerpo de su archivo de definición) | Tu conversación con Claude ni tus mensajes anteriores |
| El mensaje de encargo que Claude redacta al delegar | Los archivos que ya leyó la conversación principal |
| Tus archivos CLAUDE.md (salvo Explore y Plan, que los omiten) | La memoria automática de la conversación principal |
| Una instantánea del estado de git | Lo que averiguó otro subagente, salvo que esté escrito en algún archivo |
Este aislamiento es deliberado: permite que un subagente lea veinte archivos sin llenar tu conversación. El precio es que todo lo que no deje escrito desaparece al terminar. La solución es darle un sitio donde escribir y la obligación de leerlo.
02 Tres memorias que no son la misma
| Memoria | Dónde vive | Quién la ve |
|---|---|---|
| Memoria automática de Claude Code | ~/.claude/projects/proyecto/memory/ en tu equipo | Tus sesiones en ese ordenador; no viaja a git ni a la nube, y no se carga en subagentes |
| Memoria propia de un subagente (campo memory) | .claude/agent-memory/nombre/ o la carpeta de usuario | Solo ese subagente, entre sesiones |
| Cuaderno compartido del repositorio | Una carpeta memory/ versionada en git | Todos los agentes y todas las personas que clonen el repositorio |
03 Montar el cuaderno
memory/INDICE.md
Qué archivo contiene qué y las últimas entradas importantes. Es lo primero que lee cualquier agente.
memory/decisiones.md
Decisiones tomadas, con fecha, autor y motivo. Solo escribe el orquestador.
memory/hallazgos.md
Datos verificados: qué se encontró, dónde y con qué fuente. Escribe el investigador.
memory/trabajo.md
Qué se ha hecho, en qué archivos y qué queda pendiente. Escribe el ejecutor.
memory/revisiones.md
Problemas detectados, gravedad y estado. Escribe el revisor.
memory/conflictos.md
Contradicciones entre agentes que debe resolver el orquestador o una persona.
Crea en este repositorio una carpeta memory/ con estos archivos: INDICE.md, decisiones.md, hallazgos.md, trabajo.md, revisiones.md y conflictos.md. Cada uno con un encabezado que explique su propósito, quién puede escribir en él y el formato de entrada: ### [AAAA-MM-DD] [agente] título, seguido de contenido, fuente y estado.
Después añade a CLAUDE.md una sección «Cuaderno del equipo» con estas reglas:
1. Antes de trabajar, todo agente lee memory/INDICE.md y los archivos que afecten a su tarea.
2. Cada agente escribe solo en su archivo; nunca edita entradas de otros.
3. Se añade, no se reescribe: las correcciones son entradas nuevas que citan la anterior.
4. Todo dato lleva su fuente (archivo, URL o comando).
5. Si un agente contradice una entrada, lo anota en conflictos.md y no actúa sobre ello.
6. Al terminar, el agente actualiza INDICE.md con una línea por entrada nueva.
No toques nada más de CLAUDE.md.04 Definir los agentes
Los subagentes de proyecto viven en .claude/agents/ como archivos Markdown con frontmatter. Solo name y description son obligatorios; con tools limitas lo que puede hacer, con model eliges el modelo y con effort ajustas cuánto razona ese rol. Claude Code detecta los cambios en esa carpeta sin reiniciar.
---
name: investigador
description: Investiga código, documentación o fuentes externas y registra hallazgos verificados. Úsalo antes de cambios que dependan de información que aún no tenemos.
tools: Read, Grep, Glob, WebFetch, WebSearch, Edit
model: sonnet
effort: medium
---
Antes de empezar, lee memory/INDICE.md y memory/hallazgos.md. No repitas búsquedas ya registradas.
Escribe únicamente en memory/hallazgos.md, siguiendo el formato del archivo, con la fuente de cada dato. Si algo contradice una entrada existente, anótalo en memory/conflictos.md.
Tu trabajo no cuenta si no queda escrito. Devuelve al terminar: qué has añadido, qué no pudiste verificar y qué recomiendas investigar después.-
1
Investigador
Lee y busca; escribe solo en hallazgos.md. Herramientas de lectura y búsqueda, sin Bash.
-
2
Ejecutor
Implementa a partir de decisiones y hallazgos; registra en trabajo.md qué archivos cambió y qué queda.
-
3
Revisor
Comprueba el resultado contra decisiones.md; registra problemas en revisiones.md sin corregirlos él.
-
4
Orquestador
Reparte el trabajo, resuelve conflictos y es el único que escribe en decisiones.md. Es donde más compensa un nivel de esfuerzo alto.
05 Qué subir a git
- ✓Sube .claude/agents/, la sección del cuaderno en CLAUDE.md y la carpeta memory/: así quien clone el repositorio hereda el equipo completo.
- ✓No subas CLAUDE.local.md ni .claude/settings.local.json, que son personales.
- ✓Si das memoria propia a un agente con memory: project, esa carpeta también se versiona; usa local si no quieres compartirla.
- ✓No guardes en el cuaderno datos personales de clientes, claves ni contraseñas: está en el repositorio.
- ✓Si trabajas con varias sesiones en worktrees separados, cada uno tiene su copia del cuaderno; fusiona los cambios de memory/ como cualquier otro archivo.
06 Probarlo con una tarea real
Actúa como orquestador del equipo definido en .claude/agents/. Tarea: [por ejemplo, preparar el correo de lanzamiento del nuevo servicio con datos verificados de la web y las tarifas].
1. Lee memory/INDICE.md y decisiones.md.
2. Planifica el reparto y anótalo como decisión.
3. Delega en el investigador, luego en el ejecutor y después en el revisor, recordando a cada uno qué archivos debe leer.
4. Resuelve lo que aparezca en conflictos.md.
5. Al final, resume qué se hizo, qué decisiones se tomaron y qué queda pendiente.Revisa la carpeta memory/ tras la última tarea y dime: si cada agente escribió solo en su archivo, si hay datos sin fuente, si algún agente repitió trabajo ya registrado y si INDICE.md está al día. Propón ajustes a las reglas de CLAUDE.md si detectas fallos repetidos.Preguntas frecuentes
No. El mismo patrón funciona para marketing, ventas o contenidos: cambia los roles (por ejemplo, documentalista, redactor y editor) y los archivos, y mantén las reglas de lectura y escritura.
Para tus preferencias personales, sí. Pero la memoria automática vive en tu equipo, no se comparte por git y no se carga en los subagentes, así que no sirve para coordinar un equipo.
Crecerá. Archiva periódicamente las entradas cerradas en una carpeta aparte y deja en INDICE.md solo lo vigente. Pide al orquestador que haga esa limpieza cada cierto tiempo.
Sí, Claude puede reanudar un subagente con su historial completo. Es útil para continuar una tarea, pero no sustituye a un registro compartido que lean otros agentes y otras personas.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.