CLAUDE.md para equipos: cómo convertimos los recuerdos de IA de cinco personas en reglas compartidas

Cada desarrollador que trabaja con un agente de programación basado en IA va elaborando, sin darse cuenta, un manual de normas. La memoria automática de Claude Code guarda notas de sus correcciones a medida que trabaja, su perfil personal ~/.claude/CLAUDE.mdrecopila las preferencias que se ha cansado de repetir y se desarrollan algunas habilidades personales en torno a las tareas que realiza cada semana. Todo ello es privado. La memoria automática es local en la máquina y específica de cada repositorio: los agentes de sus compañeros de equipo nunca la ven.

Así pues, cinco personas aprenden la misma lección por separado, cada una en un archivo privado. Las normas que más necesita su equipo ya están por escrito. Simplemente no figuran en ningún documento compartido.

En septiembre, cinco de nosotros llevamos a cabo una «cosecha de recuerdos»: reunimos esos archivos privados y nos preguntamos qué normas merecían convertirse en normas del equipo. Así es como lo hicimos, qué normas fueron seleccionadas, dónde se ubicó cada una de ellas y qué descubrimos, incluidas las normas en las que nos equivocamos.

¿Qué es una «cosecha de recuerdos»?

Una «recogida de recuerdos» es un ejercicio en equipo que consta de tres pasos. Cada persona exporta los recuerdos de su agente privado y sus reglas personales. Un revisor agrupa las entradas de todas las exportaciones. Las reglas que varias personas han redactado de forma independiente se proponen para los archivos compartidos: el proyectoCLAUDE.md``AGENTS.md, una habilidad compartida o una comprobación en CI.

Es el paso de mantenimiento que la ingeniería de contexto suele omitir. Ya hemos señalado anteriormente que los archivos de contexto necesitan un ciclo de retroalimentación impulsado por los agentes que los utilizan. Una «cosecha» es ese mismo ciclo aplicado a las personas en lugar de a las sesiones: se trata de la fase 4 del ciclo de vida de la retroalimentación de los agentes, dirigida a las notas que ya se encuentran abandonadas en la memoria privada.

Las herramientas disponibles para ello son escasas. De las diez herramientas de programación de IA que hemos analizado, solo Devin ofrece un bucle que supervisa una sesión, propone una regla compartida y espera a que un usuario la apruebe. El resto se basa en archivos que los usuarios escriben y envían manualmente, o en conjuntos de instrucciones que un administrador distribuye. Ninguna de ellas analiza los recuerdos personales de varias personas en busca de posibles normas para el equipo.

Lo que hicimos

El 17 de septiembre de 2026, cinco desarrolladores ejecutaron cada uno un script de exportación sobre sus propias memorias de Claude Code, su «global» personal yCLAUDE.md sus habilidades personales. El script no transmite nada. Cada persona leyó su propio paquete, eliminó todo aquello que no debía transmitirse y, solo entonces, lo envió.

Los cinco paquetes contenían 444 entradas de memoria, 5 CLAUDE.mdarchivos globales, 13 habilidades personales y 194 filas que describían las habilidades instaladas en cada repositorio. Un revisor, un agente de IA que trabajaba junto a un humano, agrupó las entradas de los cinco paquetes y redactó una propuesta para cada grupo. El 22 de septiembre, cuatro de nosotros votamos en dos páginas de revisión. Las promociones se implementaron como solicitudes de incorporación de cambios (pull requests) ordinarias en tres repositorios: nuestro repositorio principal de productos, un repositorio de juegos y nuestro complemento compartido de habilidades.

Los paquetes se alojan en una rama que nunca se fusiona. Solo se publican las promociones, cada una de ellas como una solicitud de incorporación de cambios (PR) independiente en el repositorio al que se refiere, y se revisan como cualquier otro cambio.

Qué determina el ascenso: se tienen en cuenta los autores, no las entradas

Una regla se considera válida cuando dos o más personas la han anotado de forma independiente. Se deben contar los autores distintos, nunca las entradas. Esta única regla fue la que hizo la mayor parte del trabajo, y fue necesario realizar tres ajustes antes de que resultara fiable.

Tenga en cuenta al usuario más activo. Un paquete contenía 251 de las 444 entradas, repartidas en 10 repositorios. El resto aportaba entre 37 y 68 entradas repartidas en entre 1 y 4 repositorios. Por lo tanto, «dos autores» solía significar «nuestro usuario más activo del agente más uno», y un clúster que no incluyera al usuario más activo constituía una prueba más escasa y sólida. Marcamos esos clústeres por separado.

Una persona equivale a un autor. Un desarrollador que ha exportado desde dos equipos. Eso equivale a un autor. Que una persona repita la misma regla tres veces es una forma de enfatizarla. Para que haya corroboración, se necesita una segunda persona.

Las fuentes compartidas no son independientes. Los archivosCLAUDE.md globales de ambas personas eran idénticos byte a byte en sus cuatro primeras secciones, ya que ambas habían adoptado el mismo texto publicado: las directrices de codificación de Andrej Karpathy para agentes de IA. Ambas citaban un único documento de origen, por lo que se consideró una sola fuente. Cualquier clúster futuro que se base únicamente en ese par se comparará primero con la redacción original.

Para clasificar cada grupo, hemos tomado prestados los cuatro operadores de ExpeL, un método de investigación para agentes que aprenden reglas a partir de la experiencia: AÑADIR una nueva regla, VOTAR A FAVOR de una que ya figure en los documentos compartidos, VOTAR EN CONTRA de una que se contradiga con las pruebas, EDITAR una que se acerque pero sea errónea. El voto negativo y la edición son tan importantes como la adición. Un proceso de recopilación que solo pueda añadir reglas hace que sus archivos de contexto sean más largos, pero nunca más correctos.

El umbral determina lo que propone el revisor, no lo que el equipo pueda aprobar. En una segunda página de revisión se enumeraban los datos de un solo autor que parecían merecer la pena compartir, y los presentes votaron sobre cada uno de ellos. Se incluyeron porque la gente los leyó y estuvo de acuerdo.

Dónde debe ubicarse cada regla

Acordar una norma es la mitad de la decisión. La otra mitad es su «altitud»: el nivel en el que realmente se leerá y se aplicará. (En el capítulo de nuestra guía dedicado a dónde debe situarse una corrección se aborda este tema en profundidad). En el caso de las normas recopiladas, esta es la tabla de enrutamiento que utilizamos:

La norma es	Su lugar está en	¿Por qué?
Un hecho que se da en cada sesión de este repositorio es que se necesita	El proyecto CLAUDE.md	Se carga al inicio de cada sesión
Lo mismo ocurre con todas las herramientas de IA que utiliza el equipo	AGENTS.md, importado de CLAUDE.md	Un archivo que todas las herramientas pueden leer
Solo es relevante para una parte del código fuente	Una regla con ámbito de ruta en .claude/rules/	Solo se carga cuando el agente detecta archivos coincidentes
Un procedimiento que se utiliza en varios repositorios	Una habilidad en un complemento compartido	Los complementos aportan habilidades, no CLAUDE.md
Un procedimiento específico para un repositorio	Una habilidad de reposición	Se carga cuando la tarea lo requiere
Los detalles de la referencia son demasiado extensos para cada sesión	Un documento, además de un indicador de una línea en CLAUDE.md	Un documento que no se carga es un documento que el agente nunca lee
Comprobable mecánicamente	Una regla de Lint, una prueba o una comprobación de CI	La prosa advierte; un freno lo detiene
Una preferencia en cuanto a sus propias herramientas, su máquina o su presupuesto	Su experiencia personal CLAUDE.mdo recuerdo	No se trata de un dato relativo al código fuente

Hay dos puntos que merecen especial atención. En primer lugar, un complemento de Claude Code puede incluir habilidades, agentes y ganchos, pero no procedimientosCLAUDE.md. Los procedimientos se aplican a varios repositorios dentro de un complemento; las reglas fijas deben incluirse en cada repositorio que las necesite.

En segundo lugar, solo se debe borrar la memoria privada una vez que el destino se haya cargado automáticamente. Si se traslada una regla a un documento que no se carga, el agente simplemente la olvida. Cuando una regla se trasladaba a documentos de referencia, la memoria privada se reducía a un puntero en lugar de desaparecer.

¿Qué hacer ante las contradicciones?

Los recuerdos agrupados presentan discrepancias. Resuelva las contradicciones por ámbito siempre que sea posible, sustituya el dato obsoleto y deje las discrepancias relacionadas con las preferencias en un grupo explícito de elementos sin resolver.

Compruebe primero el ámbito de aplicación. Una de las contradicciones se refería a cómo configurar las dependencias en una segunda copia de trabajo de un repositorio: dos personas habían escrito reglas opuestas. Ambas eran válidas en su propio repositorio. Un cambio posterior en una habilidad compartida había resuelto la cuestión para ambos, y resultó que la memoria de nuestro usuario más activo era la que estaba desactualizada, por lo que es esa la que debe sustituirse, en lugar de eliminarse sin más.

Reemplace, nunca sobrescriba. Cuando cambie una regla compartida, añada la nueva regla indicando la fecha y mantenga la antigua legible, del mismo modo que un registro de decisiones de arquitectura sustituye a una decisión anterior. De este modo, el siguiente revisor podrá ver qué ha cambiado y por qué.

Mantener una cuestión sin resolver. La segunda contradicción se refería a qué modelo de IA debían utilizar los subagentes. Dos personas querían un modelo de primer nivel para cada subagente; otra elegía los modelos en función de la tarea. La votación se dividió en dos votos a favor de «debatir» y dos a favor de «aceptar». Se dejó sin resolver a propósito, ya que se trata de cuánto está dispuesta a gastar cada persona por su cuenta, y no de un aspecto relacionado con el código fuente. Queda en las reglas privadas de cada persona.

Lo que se descubrió durante la cosecha

Se aprobaron quince promociones procedentes de la primera página de revisión: once para nuestro repositorio principal de productos (dos de ellas también se aplicaban al repositorio de juegos), tres para el complemento de habilidades compartidas y una que corregía el propio exportador de Harvest. Se aprobaron otras diecisiete de la segunda página: datos de un solo autor que el grupo acordó compartir, además de dos grupos que en el primer recuento se habían registrado erróneamente como de un solo autor. En la segunda página, se rechazó una propuesta, tres quedaron en suspenso a la espera de más debate o de un lugar más adecuado, y tres fueron aceptadas, aunque requieren código o una habilidad en lugar de una simple línea de documentación. La cuestión del modelo quedó pendiente.

El grupo de comentarios más recurrente se refería a los comentarios. Tres autores, uno de los cuales lo había anotado cuatro veces: los comentarios exponen hechos duraderos sobre el código; nunca narran el cambio ni su historia. Un autor señaló que los subagentes son los que suelen cometer esta falta.

La más general se refería a las pruebas. Cuatro de los cinco autores habían redactado una versión de «verifique antes de afirmar; una búsqueda fallida no es prueba de ausencia». Las afirmaciones de los revisores son hipótesis, y el hecho de que no se pueda reproducir un error no demuestra que este no pueda producirse. Era lo más parecido que tenía el equipo a una norma interna compartida, y no constaba por escrito en ningún documento común.

Un grupo de casos relacionados, de dos autores, versaba sobre un estado obsoleto de Git: una rama local muy desfasada respecto a la remota, una búsqueda realizada en una copia incorrecta. Cada uno de sus cinco incidentes dio lugar a una afirmación falsa, pero expresada con seguridad, que llegó a figurar en el mensaje de una confirmación o en la descripción de una solicitud de incorporación de cambios.

La recopilación se centró en corregir las orientaciones erróneas, no solo en las que faltaban. Tres de los hallazgos consistían en solicitudes de «votar en contra» o «editar» respecto a orientaciones de las que ya disponíamos:

• Nuestro grupo de trabajo indicóAGENTS.md a los agentes que aplicaran el cambio a todo el repositorio allint:fix modificar las reglas de lint. Tres personas habían advertido por separado de que no se hiciera: el repositorio no pasa la comprobación de lint en su estado inicial, por lo que una corrección aplicada a todo el repositorio oculta su diferencia entre versiones tras cambios de formato ajenos al asunto.
• Se trata de una función compartida que, según se indica, recurre a la API en caso de fallogh pr edit. Sin embargo, no falla: muestra un aviso no crítico, devuelve un valor de salida 0 y deja la solicitud de incorporación de cambios sin modificar. Una opción de recurso basada en un fallo que nunca se produce nunca se ejecuta. Tres autores se habían topado con este problema en tres repositorios distintos.
• En una advertencia ya existente de la documentación de nuestro agente se calificaba de «seguro» un error de base de datos porque generaba un error de forma inmediata. Tres personas lo habían cometido en tres tablas diferentes. En uno de los casos, el error superó la revisión, superó la integración continua (CI) y solo provocó un fallo en tiempo de ejecución.

Algunas reglas acordadas debían incluirse en una comprobación automática. La advertencia de la base de datos mencionada anteriormente se puede comprobar de forma automática: una prueba que lea el esquema pondría fin a toda la clase, mientras que la documentación solo advierte al respecto. Se acordó que «Nunca edite manualmente el archivo de esquema generado» era cierto y aún se mantiene pendiente, ya que la redacción no es la forma adecuada de garantizar su cumplimiento. Otros dos puntos acordados ya se habían redactado como procedimientos paso a paso, lo que los convierte en habilidades. Varios puntos salieron de la votación como tickets en lugar de como documentación.

Una norma puede ser un comportamiento predeterminado y, aun así, es necesario plasmarla por escrito. Dos personas habían escrito, de forma independiente, «nunca realice un commit ni envíe cambios a menos que se le solicite». Uno de ellos lo expresó de la mejor manera: «el hecho de escribir archivos no supone un permiso para realizar un commit con ellos». Cualquier agente ya debería comportarse de esta manera. Dos personas lo pusieron por escrito porque, a pesar de todo, seguía ocurriendo, lo cual es el argumento a favor de hacerlo explícito.

Se detectó un error en el proceso de recopilación. Cada paquete incluía un sello de versión, por lo que el proceso de revisión se negaba a comparar paquetes generados mediante reglas de recopilación diferentes. El sello procedía de la versión del complemento, no del exportador. Los cinco paquetes se generaron mediante scripts idénticos al nivel de byte y se marcaron con tres versiones diferentes. La barrera de seguridad nunca se activaría ante un cambio real en las reglas, pero sí lo haría ante cualquier actualización del complemento que no guardara relación con ello. Esa corrección fue una de las quince.

Con qué frecuencia debe ejecutarse

La primera recopilación es la más laboriosa: meses de notas personales, resumidas en una sola sesión delimitada. A partir de ahí, mantenga una revisión rápida de cinco minutos durante las reuniones periódicas de sincronización del equipo: ¿hay alguna novedad que haya anotado más de una persona?

Cinco modos de fallo que deben tenerse en cuenta en el diseño:

• Solo escritura: las reglas se aplican y nadie comprueba si el comportamiento del agente ha cambiado.
• Obsoleta y sin propietario: una regla compartida sigue vigente después de que el código al que hace referencia haya dejado de existir.
• Promovido en n=1: la firme opinión de una persona se convierte en una norma del equipo por el mero hecho de haber sido la primera en expresarla.
• Un documento que recoge cuatro tipos de contenido: normas generales, procedimientos, información de referencia e historial, todo ello en un único archivo que nadie lee de principio a fin.
• Abstraída hasta el punto de resultar inútil: una norma tan alejada del incidente que la originó que ya no indica al agente qué debe hacer.

Ejecute uno manualmente

No necesita herramientas especiales. Nuestra exportación consistía en un pequeño script, pero cada paso se puede realizar manualmente:

1. Exportar de forma privada. Cada persona debe copiar su carpeta de memoria automática (en Claude Code, ~/.claude/projects/<project>/memory/), sus y~/.claude/CLAUDE.md cualquier habilidad personal en una carpeta individual por persona.
2. Revise el contenido antes de compartirlo. Cada persona debe eliminar cualquier información que no deba difundirse: credenciales, datos de clientes, cualquier dato sobre un compañero de trabajo identificado. No se debe enviar nada sin que su autor lo haya leído previamente.
3. Agrupar por significado. Un revisor, ya sea una persona o un agente, agrupa las entradas que expresan lo mismo con palabras diferentes y registra quién ha redactado cada una de ellas.
4. Cuente los autores distintos. Se considera candidato cualquier grupo que cuente con dos o más autores independientes. Agrupe los equipos de una misma persona, descarte el texto compartido de fuentes superiores y anote qué grupos se mantienen sin tener en cuenta a su usuario más activo.
5. Clasifique y desvíe. Etiquete cada elemento candidato como «AÑADIR», «VOTO A FAVOR», «VOTO EN CONTRA» o «EDITAR» y, a continuación, asígnele un destino según la tabla de enrutamiento anterior.
6. Enumere las contradicciones por separado. Resuélvalas según su ámbito de aplicación siempre que sea posible; deje el resto sin resolver e indíquelo.
7. Que la sala vote. Ponga las propuestas en una página y los datos del autor en otra, y decidan juntos.
8. Trate cada promoción como una campaña de relaciones públicas independiente respecto al repositorio al que se refiere. Mantenga los paquetes sin procesar fuera del repositorio principal.

Preguntas frecuentes

¿Qué es una «cosecha de recuerdos»?

Una «cosecha de memorias» es una práctica de equipo para los agentes de programación de IA: cada desarrollador exporta las memorias de su agente privado y sus reglas personales; un revisor agrupa las entradas de todas las exportaciones, y las reglas que varias personas han escrito de forma independiente se transfieren a archivos compartidos, como oCLAUDE.md AGENTS.md. Se trata de la etapa de mantenimiento a nivel de equipo de la ingeniería de contexto.

¿Cuántas personas deben dar su visto bueno para que una norma se incorpore a CLAUDE.md?

Recurrimos a dos o más autores independientes. Se deben contar personas distintas, no entradas: una persona que repita una norma tres veces, o que realice una exportación desde dos equipos, sigue siendo un solo autor. Dos personas que hayan copiado el mismo texto publicado tampoco se consideran independientes. El umbral determina qué se propone; el equipo sigue votando cada promoción.

¿Qué forma parte del equipo CLAUDE.md y qué forma parte de la memoria personal?

Es un hecho indiscutible que, en cada sesión, todo lo que se encuentre en ese repositorio debe pertenecer al proyectoCLAUDE.md, ya que se carga automáticamente. Los procedimientos deben incluirse en «skills», los detalles de referencia deben incluirse en «docs» con un enlace, y todo aquello que una máquina pueda comprobar debe incluirse en una regla de lint o en una prueba. Las preferencias relativas a sus propias herramientas, su equipo informático o su presupuesto son de carácter personal.

¿Deberían incluirse las normas del equipo en CLAUDE.md o en AGENTS.md?

Las reglas que debe seguir toda herramienta de IA se incluyen en AGENTS.md; las instrucciones específicas de Claude se mantienen en CLAUDE.md. Claude Code puede leer AGENTS.mddirectamente o mediante una importación@AGENTS.md, por lo que un único archivo puede servir para todas las herramientas que utilice su equipo.

¿Qué se hace cuando los recuerdos de dos desarrolladores se contradicen entre sí?

Compruebe primero el alcance: ambas opciones pueden ser válidas en distintos repositorios, y es posible que un cambio posterior en la herramienta haya resuelto la cuestión. Si una de las partes está desactualizada, sustitúyala en lugar de sobrescribirla. Si la discrepancia se debe a una preferencia y no a un aspecto concreto del código, déjela sin resolver y manténgala en las reglas privadas de cada persona.

¿Con qué frecuencia debería un equipo llevar a cabo una «recogida de recuerdos»?

Realice una sesión limitada para liquidar el trabajo pendiente y, a continuación, mantenga una revisión rápida de cinco minutos durante la reunión periódica de sincronización del equipo para detectar nuevos candidatos. La primera ronda es la más costosa; a partir de ahí, el volumen debería ser reducido.

Que sea una decisión de equipo

En una recopilación de recuerdos, el equipo decide qué reglas se comparten; el revisor solo hace propuestas. La exportación, la agrupación y el recuento pueden automatizarse. La votación no puede automatizarse, ni debe hacerlo. Qué reglas son vinculantes para todos, cuáles siguen siendo personales y qué desacuerdos quedan abiertos son decisiones que deben tomar las personas que tendrán que convivir con ellas. Es lo mismo que señalamos en el informe «Existe, la sala no existe»: una visión global solo resulta útil cuando las personas responsables de las correcciones toman una decisión conjunta.

Se trata de una retrospectiva con diferentes fuentes de información. Cuando nuestros agentes de IA presentaron sus propios puntos para la retrospectiva, los datos procedían de sus sesiones. En esta ocasión, procedían de nuestras propias notas privadas, y la sala desempeñó la misma función: identificar el patrón, determinar el nivel de importancia y asignar un responsable a cada punto. Si su equipo ya celebra una retrospectiva periódica, la recopilación de recuerdos puede incluirse como un punto más del orden del día. La práctica completa se describe en nuestra guía sobre retrospectivas de agentes de IA.

¿Ha realizado usted mismo un análisis de cosecha o cree que nuestro umbral es incorrecto? Háganoslo saber: ai-discussion@teamretro.com.