LucioLiu/user-md

user-md: Disciplina del archivo de perfil de usuario

La comprensión que tu IA tiene de ti debería existir en un archivo que posees — no encerrado en la cuenta en la nube de algún proveedor. Este documento es la disciplina del archivo de perfil (enseña al agente cómo crear, mantener y usar este archivo), no es un sistema de memoria (no incluye tiempo de ejecución ni canalizaciones automáticas). Las reglas detalladas se leen bajo demanda en references/: reglas de mantenimiento en curation.md, criterios de capas y relación con el host en layering.md. El tamaño total del conjunto de archivos y los umbrales de frecuencia se definen solo una vez en la tabla de umbrales de references/curation.md; este documento y otros archivos solo lo referencian, sin duplicar números.

Postura central (cuatro frases)

1. El archivo es tuyo: Markdown en texto plano, legible, editable y eliminable en cualquier editor, se mueve con la carpeta.
2. Vías separadas: La sección escrita a mano pertenece al usuario; el agente solo puede sugerir, no reescribir. La sección de depósito pertenece al agente; solo se puede añadir, cada entrada deja rastro.
3. Sin reescrituras silenciosas: Cualquier reescritura deja rastro (una línea de registro de cambios). Todo el contenido es visible, editable y eliminable por el usuario.
4. Sin inventar hechos: La sección de depósito solo registra observaciones reales; cada observación única debe llevar una marca de "pendiente de verificación". No se escribe lo que no se ha observado.

I. Creación: Familia de archivos y cinco secciones

Familia de archivos (tres archivos)

Archivo	¿Qué contiene?	Características
USER.md	Perfil de usuario válido entre máquinas y proyectos	Migrable; se inyecta completo en cada sesión, debe mantener un tamaño pequeño (umbrales en references/curation.md)
USER.local.md	Contenido que pierde validez al cambiar de máquina: entorno/rutas/herramientas/punteros a credenciales	Local a la máquina; debe estar en .gitignore
user/*.md Archivos auxiliares de desbordamiento	Detalles movidos cuando el área de depósito supera la línea de hundimiento	El archivo principal deja una línea de índice, se carga bajo demanda

Cinco secciones de USER.md (estructura definitiva, plantilla en templates/USER.md)

1. ## Who I am — Hechos de identidad: rol/antecedentes/cómo referirse. Hechos y preferencias se almacenan por separado (esta es una práctica común en varios sistemas de memoria de nivel de producto).
2. ## How I work — Preferencias y estilo: forma de comunicación/estándares de entrega/hábitos de revisión/límites de autorización predeterminados.
3. ## Our relationship — Relación y colaboración: qué preguntar, qué hacer directamente, cómo dar retroalimentación.
4. ## What I'm up to — Capa de cognición dinámica: objetivos actuales y tareas en curso — suposiciones explícitamente revisables, se actualizan con evidencia, se eliminan cuando caducan.
5. ## Learned by your agent — Área de depósito del agente (reglas en la siguiente sección sobre el sistema de doble carril).

Disciplina de nombres: Los nombres de las secciones siguen el espectro facts / preferences; la palabra "persona" está completamente prohibida en todo el documento — en el contexto de UX se refiere a un usuario ficticio de prototipo, en el contexto de agente se refiere a la personalidad del propio agente, doble ocupación, uso seguro de ambigüedad.

Inicio: Copia dos plantillas de templates/ a la raíz del espacio de trabajo, añade USER.local.md a .gitignore, dedica cinco minutos a llenar las primeras cuatro secciones. Dejarlas vacías también funciona, pero el agente tendrá cero conocimiento de ti en cada sesión.

II. Mantenimiento: Sistema de doble carril y disciplina de depósito

Sistema de doble carril

• Área escrita a mano (primeras cuatro secciones): Escrito por el usuario. Si el agente descubre contenido desactualizado o contradictorio, solo puede sugerir (proporcionar texto sugerido + razón). El usuario debe hacer el cambio por sí mismo o dar su consentimiento explícito, luego dejar una línea en el registro de cambios al final del archivo.

• Área de depósito (quinta sección): Añadido por el agente. Formato de cada entrada:

  - 【YYYY-MM-DD · Evento de origen】Texto de la regla.【Observación única pendiente de verificación】

  Fecha+origen es el certificado de nacimiento de cada entrada; las observaciones únicas deben llevar una marca de pendiente de verificación. Cuando una observación del mismo tipo se repite y alcanza el umbral de ascenso (umbral en references/curation.md), se puede iniciar una propuesta de ascenso. Solo después de la confirmación del usuario se mueve al área escrita a mano. Formato completo y flujo en references/curation.md.

Señales y falsos positivos

• Tres tipos de señales que se pueden depositar: Corrección (el usuario corrigió tu acción o comprensión), Preferencia repetida (la misma exigencia aparece en diferentes contextos), Expresión explícita (el usuario dice directamente "recuerda", "a partir de ahora siempre...").
• Regla dura de agregar en el momento: Cuando se detectan los tres tipos de señales y pasan el filtro de falsos positivos → agregar inmediatamente al área de depósito — no acumular en lotes, no esperar al final de la sesión para escribir de memoria. Si se identifica pero no se escribe, es como si esta disciplina no existiera.
• Filtro de falsos positivos: Contexto único de la tarea no se deposita (exigencia específica de esta tarea ≠ preferencia a largo plazo); mensajes muy cortos se ignoran por defecto (línea de filtro en references/curation.md); expresiones en momentos emocionales reducen la confianza; instrucciones fuertemente vinculadas a la tarea pertenecen a la tarea, no al perfil.

Integración y tamaño

• Integración y deduplicación periódica (periodicidad en la tabla de umbrales de references/curation.md): fusionar entradas sinónimas, limpiar entradas caducadas; La integración y el traslado por ascenso son los únicos dos escenarios legales para reescribir el área de depósito, ambos deben dejar rastro en el registro de cambios.
• Si el archivo principal supera el objetivo de tamaño o el área de depósito supera la línea de hundimiento (umbrales en references/curation.md) → los detalles se hunden en archivos auxiliares user/*.md, el archivo principal deja una línea de índice.

III. Uso: Inyección y derivación

Inyección por sesión

Aquí radica la importancia de mantener el archivo principal pequeño: lo suficientemente pequeño para inyectarlo completo en cada sesión. El método de conexión se elige según el host (detalles de cada host en la sección de Compatibilidad del README):

• Línea de referencia en el archivo de instrucciones: Por ejemplo, en Claude Code añadir una línea @USER.md en CLAUDE.md;
• Hosts sin mecanismo de referencia: Añadir una frase en el prompt del sistema o archivo de reglas "Al inicio de la sesión, lee USER.md";
• Hook de inicio de sesión disponible (opcional — este skill no incluye ningún tiempo de ejecución; la disciplina sigue siendo válida sin el hook). Ejemplo de configuración para Claude Code:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "cat USER.md" } ] }
    ]
  }
}

(Ejemplo POSIX; en Windows u otros hosts usar el comando equivalente. Colgar o no colgar, cómo colgarlo lo decide el usuario.)

Tres criterios de derivación (respaldo para modelos débiles, ver detalles en references/layering.md)

1. Pierde validez al cambiar de máquina → USER.local.md;
2. Pierde validez al cambiar de proyecto/rol → archivo local de ese proyecto;
3. Resto → USER.md.

Disciplina de punteros: No se duplican hechos que ya tienen una fuente autorizada, solo se pone una línea de puntero ("ver archivo X") — para evitar desviación de fuentes duales. Casos de ejemplo en references/layering.md.

Línea roja de privacidad

• Esta familia de archivos es inherentemente PII — trátala según el contenido más sensible que manejes.
• USER.local.md debe estar en .gitignore, nunca subir al repositorio.
• Antes de subir USER.md a un repositorio público, debes revisarlo manualmente: nombre real, información de contacto, detalles del empleador, punteros a credenciales, ítem por ítem.
• Contraseñas en texto plano / API keys / tokens nunca se escriben en esta familia de archivos — solo se escribe un puntero a "dónde están las credenciales, cómo invocarlas".
• Las plantillas nunca se rellenan con contenido real — las plantillas incluidas en este skill son todas marcadores de posición + ejemplos ficticios.

Ejemplos breves

• El usuario dice otra vez "responde primero con la conclusión" → la entrada de tipo de observación repetida en el área de depósito ha alcanzado el umbral de ascenso (ver references/curation.md) → redactar propuesta de ascenso (fusionar en una frase, proponer incluirla en How I work), esperar confirmación del usuario antes de migrar.
• El usuario dice "en esta máquina usa pnpm, no npm" → pierde validez al cambiar de máquina → registrar en USER.local.md.
• El usuario dice en un repositorio "en este proyecto los mensajes de commit en español" → pierde validez al cambiar de proyecto → registrar en el archivo local de ese proyecto, no en USER.md.
• El usuario se queja a altas horas de la noche "estoy harto, no me muestres respuestas largas" → momento emocional → depositar como observación única con baja confianza, no modificar directamente el área escrita a mano, mucho menos como regla fija.
• El usuario escribió en el área escrita a mano "estoy trabajando en el proyecto X" pero no lo ha mencionado en tres meses → el agente sugiere actualizar la sección What I'm up to, adjuntando razón; no mover una palabra hasta que el usuario asienta.

Versión y autocomprobación de actualizaciones

• Versión actual: 1.0.0 (consistente con plugin.json).
• Repositorio: https://github.com/LucioLiu/user-md
• Autocomprobación: Si está instalado como plugin, el mecanismo de actualización del host seguirá el número de versión; si es clonado manualmente / copia de plantilla, comparar este archivo con la rama main del repositorio para saber si está atrasado. Tu propia familia de archivos USER.md no se ve afectada por las actualizaciones del skill — son tus datos, no parte del skill.