Gestión de Memoria

Cómo escribir en la memoria automática de Claude Code y en CLAUDE.md para que la biblioteca se mantenga buscable a medida que el proyecto crece.

Referencia Rápida

El usuario dice...	Haz esto
"记一下" (ambiguo, múltiples candidatos)/ "复盘"/ "开发完了看有什么值得记的"	→ Modo 1: Evaluación de Candidatos (filtrado de múltiples candidatos)
"记一下今天那个 X 坑" (ítem específico único)/ Después de corregir un bug importante/ Después de manejar un incidente de seguridad/ Decisión única con conclusión no obvia	→ Modo 2: Crear nueva memoria (directo)
"更新这个 memory / 修正 X 的结论"	→ Modo 3: Actualizar memoria existente (prioritario sobre crear nueva)
El párrafo a añadir supera 100 líneas o el archivo ya tiene > 4 temas H2	→ Regla 6: Dividir en lugar de actualizar
"改 schema / 加新 type / 改记忆结构"	→ Modo 4: Cambio estructural (leer obligatoriamente la lista de errores ya cometidos)
"新项目零记忆起步" / "怎么开始"	→ Modo 5: Bootstrap sin memoria
"记忆系统看起来乱了 / audit"	→ Si existe `scripts/audit-memory.sh` en la raíz del proyecto, ejecútalo; si no, consulta `templates/audit-memory.template.sh` para crearlo

Reglas Importantes

Regla 1: Hechos en la memoria, métodos en el skill

El archivo de memoria contiene "tropiezos con X", "datos de la industria Y", "estado del proyecto Z"; este skill contiene "cómo decidir qué registrar / cómo escribirlo / cómo organizarlo". No pongas las reglas del esquema en la memoria (error de categoría).

Regla 2: Primero juzga "si vale la pena registrar", luego juzga "dónde registrarlo"

No todo hallazgo merece ser registrado. Árbol de decisión:

Señal	¿Debe registrarse?
El mismo tropiezo ocurre por segunda vez	✅ Obligatorio
Juicio no obvio descubierto durante una revisión adversarial	✅ Registrar el "Por qué" de la decisión
Comparación con la industria / cifras medidas (línea base reutilizable)	✅ Registrar
Debug puntual ya corregido sin valor de sedimentación	❌ No registrar (basta con el mensaje de commit)
Estado temporal que cambiará	⚠️ Depende de la persistencia, solo si es a largo plazo
Baja frecuencia pero crítico (no se ha leído en 6 meses pero sigue siendo la única verdad)	✅ Mantener — 30 días sin tocar ≠ obsoleto; el criterio para eliminar es "el tema ha desaparecido/ha sido reemplazado", no "cuánto tiempo sin leer"

Juzgar "dónde registrar" — Enrutamiento de cuatro niveles por localidad (locality):

Primero hazte una pregunta ortogonal: "Cuando en el futuro se necesite este hecho, ¿se estará mirando una ubicación de código específica, o se estará tomando una decisión entre archivos / diagnosticando un tipo de error?"

Condición de disparo	Destino	Mecanismo
Mirando una línea/bloque específico, el POR QUÉ se explica en una frase	Comentario en línea de código (justo encima de esa línea)	Se encuentra 100% al modificar el archivo, costo de índice 0
Contrato/punto de control que abarca un conjunto específico de archivos	`.claude/rules/<x>.md` + frontmatter `paths:`	Inyección automática de contexto cuando se coincide con la ruta
El disparo es un escenario/error/tipo de problema, o abarca múltiples archivos, o no pertenece a un solo archivo del repositorio (tropiezo con plataforma/SDK)	memoria (este sistema)	Coincidencia por description
Reglas que deben cumplirse en cada sesión (comandos, pila tecnológica, preferencias de colaboración)	CLAUDE.md	Permanente

El feedback vinculado a un archivo se DIVIDE por defecto: el núcleo local del archivo → comentario en línea (antes de escribir, haz grep de ese código, a menudo ya hay un comentario equivalente); la memoria solo retiene "el principio reutilizable entre archivos + un puntero a ese archivo".

Tres barreras contra la migración excesiva (por defecto a memoria, mejor migrar de menos):

Si al quitar el archivo específico aún queda una lección general → queda en memoria (ej. "no uses campos opcionales para decisiones en rutas críticas", el archivo específico es solo un ejemplo, el principio es migrable)
Comportamiento de plataforma/SDK que se repite en múltiples archivos → queda en memoria, incluso si tiene significado de código
Tumbas (X ya retirado → mirar Y)/ SOP de investigación / razonamiento económico del negocio → queda en memoria (el disparo está en el nivel de arquitectura/escenario)

Evidencia empírica (auditoría completa de una base de producción de 175 archivos): solo ~15% de las entradas están vinculadas a un solo archivo, y la mayoría de esos archivos ya tenían el núcleo en comentarios de código — "migrar" es principalmente eliminar copias redundantes de la memoria, no un verdadero traslado.

Escritura de .claude/rules/*.md (colocar en .claude/rules/ del proyecto, incluir en git → compartir entre máquinas/worktrees):

---
description: Una frase sobre qué gestiona esta regla
paths:
  - src/components/SomeDialog.tsx
  - src/lib/providers/*.ts          # soporta glob
---

Contrato / lista de verificación (puntos gotcha múltiples) que se inyecta automáticamente cuando se tocan las rutas anteriores.

⚠️ Límites conocidos de la inyección nativa de reglas (verificado en 2026-07, anthropics/claude-code issues): las reglas con paths: solo se inyectan en Lectura cuando se coincide con un archivo, no se inyectan en Escritura/creación de archivos nuevos (#23478); los paths: en ~/.claude/rules/ a nivel de usuario se ignoran, solo funcionan a nivel de proyecto (#21858). Los contratos que "deben aplicarse también al crear archivos nuevos" deben permanecer en CLAUDE.md, no solo en rules.

Regla 3: Priorizar actualizar existente, no crear nuevo

Si ya existe un archivo relacionado con el tema → actualiza ese archivo (añade un párrafo o una sección de changelog). Solo crea uno nuevo si el tema es completamente ortogonal. Crear uno nuevo fragmenta los temas → dificulta encontrar cosas → pérdida de memoria.

Regla 4: La memoria no se carga automáticamente; el description determina el acierto

Los archivos de tema (memory/*.md) no se cargan al inicio de la sesión. Claude se basa en el description del índice MEMORY.md para decidir si leerlos. El description debe ser una mezcla de palabras clave de escenario + conclusión central, de lo contrario Claude decidirá qué leer basándose en la impresión.

Verificación del mecanismo nativo (2026-07, docs oficiales en/memory): no hay recuperación semántica/vectorial automática — el descubrimiento depende completamente de "la línea de índice de MEMORY.md + el nombre de archivo", Claude usa Lectura para leer bajo demanda; al leer, el harness inyecta una sugerencia de actualidad "Esta memoria tiene N días de antigüedad". La calidad del gancho de la línea de índice = toda la tasa de acierto, esto es comportamiento nativo, no una convención de este skill.

Regla 5: El skill mismo debe cumplir con lo que enseña

Si este skill pide al usuario escribir una sección ## Why, entonces este skill también debería explicar el Por qué de cada una de sus reglas (todas están inline en este archivo).

Nota de alcance: La Regla 5 se aplica a "métodos/forma de escribir/formato de Referencia Rápida, etc.", no se aplica recursivamente a las reglas del esquema. El esquema (nombre/frontmatter/sección Why) es para archivos de memoria, no se aplica al skill mismo. El skill no es un archivo de memoria.

Regla 6: Cuándo dividir en lugar de actualizar (evitar sobrecarga de un solo archivo/grupo)

La Regla 3 prioriza la actualización, pero hay umbrales. Señales para dividir (a nivel de archivo único):

Señal	Acción
El archivo ya tiene > 100 líneas y el nuevo contenido es ortogonal al tema original	Crear un nuevo archivo, no meterlo
El archivo ya tiene ≥ 4 secciones H2 de nivel superior y el nuevo contenido pertenece a un quinto tema independiente	Crear un nuevo archivo
Al añadir el párrafo, la longitud total supera las 150 líneas	Evaluar si dividir (dependiendo de la independencia del tema)
El contenido añadido no coincide con el título/description del archivo original	Crear un nuevo archivo (el original debe centrarse en su tema declarado)

Sobrecarga de un solo grupo (a nivel de índice):

Señal	Acción
Número de entradas en un grupo grande de MEMORY.md ≥ 15	Considerar crear un hub memory (índice de secciones) en lugar de índice plano, las nuevas entradas se cuelgan del hub
La suma de las descripciones de un grupo supera las 25 líneas al revisarlas	Lo mismo que arriba
MEMORY.md > 23,000 caracteres (`wc -m`) o > 190 líneas	🔴 Límite duro nativo = primeras 200 líneas o 25K caracteres, lo que llegue primero (la redacción de los docs oficiales dice "25KB", pero en la práctica se mide por string length=caracteres: un índice de 27,972 caracteres/37.9KB se truncó exactamente en el carácter 25,000; por bytes debería haber sido ~35% antes). La parte que excede no se carga en silencio. ⚠️ No uses `wc -c` (bytes) para estimar: en chino UTF-8 cada carácter son 3 bytes, sobreestimarías el margen ~35%. Cerca del límite, el harness inyecta una advertencia; si ves "Only part of it was loaded" = ya se está perdiendo índice
Una sola línea de índice > ~160 caracteres	Hay demasiados detalles en el description → moverlos al archivo de tema o hundirlos en comentarios de código, el índice solo deja "palabras clave de escenario + conclusión central"

Por qué también hay que gestionar la sobrecarga de un solo grupo: Claude escanea las descripciones del índice MEMORY.md para acertar; 20+ descripciones en un grupo tienen tasa de omisión en un solo escaneo. Después de crear un hub, el índice del grupo solo tiene una línea que apunta al hub, y el hub contiene un mapa de temas.

Por qué la sobrecarga del índice general es la más peligrosa: la sobrecarga de un solo archivo/grupo solo "reduce la capacidad de acierto"; pero el truncamiento del índice completo = toda la parte final no se carga = capacidad de acierto cero, y ocurre en silencio sin error. Por lo tanto, ⭐⭐⭐ las entradas de la corona deben colocarse cerca de la parte superior de MEMORY.md (seguro contra truncamiento).

Prioridades de adelgazamiento cuando se superan los límites / es demasiado grande (comprimir description es el peor primer paso, perjudica la capacidad de acierto):

Primero migrar: entradas locales de archivo → comentarios en línea / .claude/rules (el índice se vuelve más pequeño y la tasa de acierto aumenta, ver Regla 2 enrutamiento de cuatro niveles)
Luego eliminar: verdaderas tumbas (temas que han desaparecido/sido reemplazados y sin valor de resurrección)
Luego reordenar: mover ⭐⭐⭐ a la parte superior de MEMORY.md
Luego jerarquizar: asignar presupuesto de longitud a las líneas de índice según importancia — entradas de la corona ≤160 caracteres, entradas normales ≤110, entradas de cola de baja frecuencia agregadas en una sola línea con múltiples enlaces (subtema → [a](f1.md) · [b](f2.md), una línea para 5-10 archivos). Además: usar nombres cortos sin prefijo de tipo para las etiquetas de enlace ([foo-bar](feedback_foo_bar.md)), no repetir el nombre completo del archivo, ahorrando 12-45 caracteres por línea
Por último comprimir la cantidad de información de una sola descripción

Casos históricos de tropiezo (referencia, no forman parte de las reglas)

Sobrecarga de un solo archivo: un archivo de referencia creció hasta 130+ líneas, metiendo 7-8 subtemas independientes (infraestructura, lista de cron, manual de fallos, etc.), la descripción del índice MEMORY.md no abarcaba bien, Claude no acertaba el subtema específico. Al dividirlo en 5 memorias independientes, cada tema se acertó con precisión.
Sobrecarga de un solo grupo: un grupo acumuló 20+ entradas; en una nueva sesión, Claude omitió algunas al escanear el índice, y al procesar una tarea reinventó la rueda. Crear un hub memory que agregara las entradas relacionadas → solucionado.
Sobrecarga del índice general: MEMORY.md creció a 43KB bytes (≈31K caracteres, superando el límite de 25K caracteres), 93 descripciones de 400-900 caracteres cada una; al iniciar se truncó en silencio, las entradas ⭐⭐⭐ del final no se leyeron → en una investigación se malinterpretó un mecanismo que funcionaba según diseño como un error. Lección: description no es cuanto más detallado mejor; demasiado detalle hincha el índice y perjudica el acierto.
Calibración errónea por confundir bytes/caracteres: al gestionar la sobrecarga, se estableció la línea de advertencia en bytes (wc -c) en 32KB, pero el harness ejecuta por caracteres (cada carácter chino son 3 bytes) → la línea de bytes hacía pensar que aún había margen, y el índice se truncó de nuevo. Lección: para comparar con el harness, usa la misma unidad; monitorea con wc -m.

Modos de Trabajo

Modo 1: Evaluación de Candidatos (múltiples candidatos, requiere filtrado)

Escenario de disparo (múltiples candidatos → requiere filtrado del Modo 1):

Después de completar una funcionalidad / después de un largo debug / después de una revisión adversarial
Después de manejar un abuso (pueden haber múltiples puntos de juicio + lecciones)
Después de manejar un incidente de seguridad / después de localizar una falla
El usuario dice "记一下" (ambiguo, sin especificar qué tropiezo)

Contenido específico único va directamente al Modo 2: el usuario dice "记一下今天那个 wildcard bug" / "记一下连接泄漏的故障手册" → ya está claro que es un ítem único → Modo 2, no Modo 1.

Pasos:

Revisar los puntos clave de esta sesión (correcciones del usuario, hallazgos de revisión adversarial, bugs inesperados, consultas de comparación con la industria, conclusiones no obvias de decisiones únicas)
Aplicar el árbol de decisión de la Regla 2 a cada uno, filtrar los que merecen registrarse
Para cada candidato, juzgar:
- ¿Ya hay un archivo de memoria que lo cubra? (grep del índice MEMORY.md) → si sí, ir al Modo 3 de actualización; si no, ir al Modo 2 de creación
- ¿El contenido a añadir supera la línea de división de la Regla 6? → crear un nuevo archivo
- ¿Debería ir a CLAUDE.md en lugar de a la memoria? (ver tabla abajo)
Confirmar la lista con el usuario: enumerar los candidatos "sugerido crear nuevo / sugerido actualizar / sugerido dividir", esperar confirmación del usuario antes de escribir

Límite entre memoria y CLAUDE.md:

Naturaleza del contenido	Dónde colocarlo
Tropiezos concretos aprendidos (bug de SDK, limitación de plataforma, datos de la industria)	memoria `feedback_*`
Referencia profunda de tema / método estándar / documento de proceso	memoria `reference_*`
Hechos de estado (trabajo en curso, configuración temporal, instantánea de arquitectura actual)	memoria `project_*`
Reglas que deben cumplirse en cada sesión (comandos, pila tecnológica, preferencias de colaboración)	CLAUDE.md
Reglas que solo se necesitan al operar archivos específicos	`.claude/rules/*.md` con frontmatter paths

Modo 2: Crear nueva memoria (proceso estándar)

Paso 0: Primero pasar por el enrutamiento de localidad (Regla 2, cuatro niveles)

Antes de escribir, confirma que realmente debe ir a la memoria: si se trata de un solo archivo → comentario en línea; si es un contrato de un conjunto de archivos → .claude/rules+paths; si es un escenario/cruce de archivos/tropiezo de plataforma → entonces va a la memoria. El feedback vinculado a un archivo se DIVIDE por defecto (el núcleo va al comentario, la memoria solo retiene el principio transversal + puntero). Ver Regla 2 para más detalles.

Paso 1: Determinar el tipo

Tipo	Cuándo usarlo	Información obligatoria
feedback	Tropiezos aprendidos (bug de SDK / limitación de plataforma / preferencia de usuario)	Causa (por qué esta conclusión) + Cuándo reutilizar (escenario de disparo)
reference	Referencia profunda de tema / método estándar / comparación con la industria / pipeline reutilizable	No es obligatorio el segmento de causa (descriptivo)
project	Hechos de estado (instantánea de arquitectura, trabajo en curso, análisis económico)	No es obligatorio el segmento de causa (estado)

Forma de presentación de la información obligatoria en feedback (cualquiera de las siguientes):

Sección separada: ## Why o sinónimos en chino ## 根因 / ## 原因 / ## 教训 / ## 为什么 (la auditoría los acepta todos)
Negrita inline: **Why**: / **根因**: (también válido para conclusiones cortas)
Inline en el description o en el título ## (si la conclusión en sí ya implica la causa + cuándo reutilizar, como una tabla comparativa ❌/✅)

Información de cuándo reutilizar: puede ser una sección separada ## How to apply, o el description puede contener palabras clave de escenario (ej. cambio de tab / mutation ya sugiere el escenario de disparo).

Paso 2: Nombrar el archivo

<tipo>_<tema>[_<modificador>].md todo en minúsculas y guiones bajos:

✅ feedback_supabase_from_deadlock.md
✅ reference_supabase_egress_favorites_refactor.md
❌ feedback-supabase-deadlock.md (usó guiones)
❌ FeedbackSupabaseDeadlock.md (camelCase)
❌ _schema.md (comienza con guion bajo, se trataría como archivo oculto, y Claude no lo leería activamente)

Paso 3: Escribir el frontmatter

---
name: kebab-case-slug
description: Palabras clave de escenario + conclusión central
type: feedback | reference | project       # Plano (recomendado)
# o:
# metadata:
#   type: feedback | reference | project   # Anidado (escritura compatible)
---

Ubicación del campo type: type: plano (recomendado) o metadata.type: anidado, ambos aceptados. El script de auditoría reconoce ambos. Al crear archivos nuevos, prioriza el plano, alineado con la mayoría existente.

Criterio de estilo para description:

✅ Buen description	❌ Mal description
`mutación de supabase.from() en el lado del navegador causa deadlock tras cambiar de tab, usar fetch() para llamar a la REST API`	`Problemas relacionados con Supabase`
`CF Image Transformations falla con caché de 7 días / cf-resized err= / patrón de reintento en FavoriteCard`	`A veces las imágenes no se muestran`
`Las políticas RLS deben envolverse con (SELECT auth.uid()), de lo contrario se evalúan repetidamente por fila`	`Optimización de rendimiento de RLS`

Criterio de juicio: ¿Puede Claude saber inmediatamente al leer el description "esta es la conclusión Y que se debe consultar en el escenario X"?

Paso 4: Escribir el cuerpo

Para clase feedback (obligatorio incluir causa + cuándo reutilizar):

# Título (Qué — una frase)

[Conclusión central + 1-2 párrafos de contexto]

## Why (o sinónimos: ## 根因 / ## 原因 / ## 教训 / ## 为什么)

[Por qué se llegó a esta conclusión — el tropiezo concreto encontrado, hallazgo de revisión adversarial, preferencia del usuario]
**Por qué es obligatorio**: sin la sección de causa, la próxima vez que se discuta la misma decisión, a menudo se llegará a la misma conclusión errónea.

## How to apply (opcional, si el description ya contiene palabras clave de escenario)

[Cuándo reutilizar esta línea — escenario de disparo, lista de verificación, pasos para evitar el tropiezo]

Para clases reference / project: no hay estructura de sección obligatoria, organizar naturalmente según el tema.

Paso 5: Agregar al índice MEMORY.md

Elegir un grupo grande existente, no crear un nuevo grupo
Agregar el description en la posición correspondiente dentro del grupo (alta importancia usar ⭐⭐ / ⭐⭐⭐ en negrita)
Temas transversales: añadir (también ver [[otro-archivo]]) al final del description

Modo 3: Actualizar memoria existente (prioritario sobre crear nueva)

Paso 1: Confirmar la pertenencia al tema existente con grep

grep -l "<palabra clave>" memory/*.md

Paso 2: Decidir la forma de actualización

Situación	Cómo actualizar
Nuevos datos / nuevo caso que complementan una conclusión existente	Agregar un párrafo o una sección de changelog en el cuerpo
Conclusión existente refutada	Agregar al principio del archivo antiguo `⚠️ Reemplazado por [[nuevo-slug-de-archivo]]`, y en el cuerpo del nuevo archivo escribir "reemplaza la parte X de [[viejo]]"
Solo la descripción no es lo suficientemente clara	Modificar el índice MEMORY.md, no modificar el archivo en sí (a menos que también se añada contenido)

Paso 3: Sincronizar MEMORY.md

Si se modificó el description, también se debe modificar la línea correspondiente en MEMORY.md.

Modo 4: Cambio estructural (cambiar esquema / añadir nuevo tipo / cambiar agrupación)

Lista obligatoria de errores ya cometidos:

No intentar usar la sintaxis glob if: "Write(memory/*.md)" — if: es una regla de permiso, no un glob de archivo; ya se verificó que no funciona
No usar exit 2 para bloquear hooks — ya se verificó que rompe el flujo de lotes de pre-deploy (Claude no tiene mecanismo de reintento automático)
No poner la fuente autoritativa del esquema en un archivo que comience con guión bajo como _schema.md — Claude no lee archivos de tema activamente
No configurar hooks en .claude/settings.json del proyecto — ese directorio suele estar en .gitignore, no entra en git ni se comparte entre worktrees
Al añadir un campo obligatorio nuevo, sincronizar 3 lugares: (a) la sección "Modo 2 → Paso 3" de este skill (b) la sección de resumen rápido al inicio de MEMORY.md (c) la lista de campos del script audit-memory.sh
Antes de modificar hooks / añadir restricciones, ejecutar bash scripts/audit-memory.sh para ver la tasa de cumplimiento actual — solo se necesitan medidas duras si <95%; si ≥95%, mantener advertencia suave
El monitoreo del tamaño de MEMORY.md debe hacerse en caracteres (wc -m), no en bytes (wc -c) — el límite nativo de 200 líneas/25K caracteres se mide en caracteres; cada carácter chino son 3 bytes, calibrar por bytes causa truncamiento silencioso (ver caso histórico en Regla 6)

Proceso para cambiar el esquema:

Ejecutar auditoría para obtener la línea base actual
Diseñar el cambio (modificar este skill + hub del proyecto)
Verificar si la memoria existente viola masivamente la nueva regla (>10% → posponer, migrar primero según nueva regla)
Actualizar la sección de resumen de MEMORY.md sincronizada
Modificar la lista de campos del script de auditoría
Volver a ejecutar la auditoría para ver la nueva tasa de cumplimiento

Modo 5: Bootstrap sin memoria (proyecto nuevo)

Cuando el usuario dice "comenzar a construir memoria" en un proyecto sin sistema de memoria:

Paso 1: Confirmar la ruta del directorio de memoria automática

Claude Code crea automáticamente ~/.claude/projects/<slug-del-proyecto>/memory/, donde <slug-del-proyecto> = la ruta absoluta del proyecto reemplazando / por -. Ejemplo:

Proyecto /Users/alice/Project/myapp → slug -Users-alice-Project-myapp

Si Claude Code ya ha creado memoria automática para ese proyecto, el directorio existirá. Verificar: ls ~/.claude/projects/ | grep <nombre del proyecto>.

Paso 2: Crear el índice MEMORY.md

Plantilla para la parte superior (se puede comprimir a ~25 líneas):

# Memoria del proyecto <nombre del proyecto>

## ⭐⭐⭐ Consulta rápida para escribir memoria (reglas duras)
- Nombre de archivo: `<tipo>_<tema>.md` todo en minúsculas y guiones bajos; tipo ∈ {feedback, reference, project}
- Frontmatter obligatorio: name / description / type
- feedback debe contener sección ## Why (o sinónimos en chino ## 根因 / ## 教训 / ## 原因)
- Estilo de description: palabras clave de escenario + conclusión central (una línea ≤160 caracteres)
- Si ya existe archivo sobre el mismo tema → actualizar, no crear nuevo (si supera el umbral de la Regla 6, dividir)
- Límite duro de este índice: primeras 200 líneas o 25K caracteres (lo que llegue primero), el exceso no se carga en silencio
- Método detallado: skill memory-management

## ⭐ Lista de temas del proyecto
(ninguno por ahora — agregar grupos por tema más adelante)

Paso 3: Umbral de evolución de grupos (estructura determinada por número de archivos)

Número de archivos de memoria	Estructura recomendada
< 15 ítems	Lista plana, sin grupos (una sola lista es suficiente, agrupar fragmentaría)
15-25 ítems	Introducir 3-5 grupos grandes (agregar por tema)
> 25 ítems	Agrupación madura, congelar grupos prohibiendo crear nuevos; las nuevas entradas se cuelgan de grupos existentes (temas transversales usar `(también ver X)`)

Paso 4: Agregar el protocolo de memoria al inicio de CLAUDE.md (3-5 líneas)

## Gestión de Memoria
Al involucrar escritura/actualización de memoria / ajuste de esquema → usar el skill `memory-management`.
- Reglas de consulta rápida: sección ⭐⭐⭐ al inicio de MEMORY.md
- Tasa de cumplimiento de revisión: `bash scripts/audit-memory.sh` (opcional, ver skill templates/)

Paso 5: Reutilizar los métodos generales de este skill

No copiar el contenido del skill al proyecto. El skill está a nivel de usuario, todos los proyectos comparten un mismo método. En el proyecto solo se colocan estados específicos del proyecto (lista de grupos / pendientes / tropiezos propios del proyecto).

Esquema Normativo (fuente autoritativa)

Nombrado de archivos

<tipo>_<tema>[_<modificador>].md todo en minúsculas y guiones bajos, tipo ∈ {feedback, reference, project}

Frontmatter obligatorio

---
name: kebab-case-slug
description: Palabras clave de escenario + conclusión central
type: feedback | reference | project       # Plano (recomendado)
# o:
# metadata:
#   type: feedback | reference | project   # Anidado (compatible)
---

El script de auditoría reconoce ambos. Al crear archivos nuevos, prioriza el plano.

Información obligatoria en feedback

Sección de causa (cualquiera de las siguientes):

## Why o títulos sinónimos en chino ## 根因 / ## 教训 / ## 原因 / ## 为什么 / ## Root cause (puede llevar : en inglés o : en chino)
Negrita inline **Why**: / **Why**: / **根因**:, etc.

Cuándo reutilizar (cualquiera de las siguientes):

Sección separada ## How to apply
El description contiene palabras clave de escenario (implica el escenario de disparo)

Estilo de description

Mezcla (palabras clave de escenario + conclusión central), para que Claude acierte con el description "consulta la conclusión Y en el escenario X". Una línea ≤ ~160 caracteres — los detalles van al archivo de tema o a comentarios de código (límite duro del índice = 200 líneas/25,000 caracteres, lo que llegue primero; el exceso no se carga en silencio)

Formato de la línea de índice

- [etiqueta corta](nombre completo del archivo.md) — hook. Etiqueta corta = nombre con guiones sin prefijo de tipo (ej. [supabase-from-deadlock](feedback_supabase_from_deadlock.md)); entradas de cola de baja frecuencia usar línea agregada (subtema → [a](f1.md) · [b](f2.md))

Congelación de grupos

Elegir de grupos grandes existentes, prohibido crear nuevos grupos. Para pertenencia ambigua usar (también ver hub-X) como referencia cruzada.

Errores Comunes

Mal	Bien
Escribir description por impresión "Problema de Supabase"	Escribir palabras clave de escenario + conclusión "supabase.from() deadlock al cambiar de tab, usar fetch"
feedback solo escribe "qué es"	feedback debe llevar ## Why, protegiendo contra futuras re-discusiones
Crear un segundo archivo sobre el mismo tema	Priorizar actualizar el existente, crear uno nuevo fragmenta
Crear un grupo "Problemas de red" para poner 1 entrada	Usar un grupo existente, temas transversales usar `(también ver X)`
Poner las reglas del esquema en un archivo de memoria	El esquema está en este skill, la memoria contiene hechos
Usar hook exit 2 para bloquear forzosamente	Usar advertencia suave (stderr + exit 0) o auditoría posterior

Autoverificación (después de escribir)

Integración de Herramientas

El script de auditoría es una herramienta opcional del proyecto.

Si existe scripts/audit-memory.sh en la raíz del proyecto → ejecutar:

bash scripts/audit-memory.sh  # Ver tasa de cumplimiento / listar infracciones / listar no tocado en 30 días

Salida: total de archivos / falta frontmatter / falta Why / enlaces rotos en MEMORY.md / no tocado en 30 días / tamaño de MEMORY.md (caracteres + líneas, comparado con el límite nativo de 200 líneas/25K caracteres) / tasa de cumplimiento %. Tasa de cumplimiento objetivo ≥ 95%.

Si no hay script de auditoría → crear desde la plantilla:

# El skill a nivel de usuario trae una plantilla genérica
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
   <tu proyecto>/scripts/audit-memory.sh
# Modificar MEMORY_DIR para que apunte al directorio de memoria automática de tu proyecto
chmod +x <tu proyecto>/scripts/audit-memory.sh
bash <tu proyecto>/scripts/audit-memory.sh

Ruta predeterminada de referencia para memoria automática: ~/.claude/projects/<slug-del-proyecto>/memory/, ver Modo 5 Paso 1.

Preguntar en tu IA favorita

Documentación