Anatomía de un patrón

Un patrón es simple a propósito. Es un pequeño conjunto de piezas tipadas, más los metadatos necesarios para mostrarlo, versionarlo y asociarlo a un proyecto. Entender su forma deja claro qué obtienes cuando importas uno.

Un patrón es un conjunto de piezas

Todo patrón incluye una lista de piezas. Cada pieza es exactamente una memoria, una regla o una skill, y sabe dónde debe quedar.

Una pieza declara:

• kind: memory, rule o skill. Determina en qué tipo de contenido se convierte al importarla.
• nodePath: la ruta, relativa al espacio de trabajo, a la que pertenece; por ejemplo /app, /services/billing o / para la raíz. Es el alcance con el que se entrega la pieza.
• title: el título de la memoria, el nombre de la regla o el nombre de la skill.
• summary: una descripción de una línea que se muestra en la lista del conjunto, independiente del cuerpo.
• body: el contenido completo en Markdown. Es exactamente lo que se escribe en tu espacio de trabajo, sin ninguna transformación.

Como cada pieza indica su propia ruta, un patrón está vinculado a rutas por construcción. El conjunto no es un único documento que haya que archivar en algún sitio; es un grupo de piezas que ya saben adónde van.

Metadatos específicos de cada tipo

Algunas piezas llevan campos adicionales propios de su tipo de contenido, y estos se conservan intactos al importar.

• Las piezas de tipo regla definen un tipo de alcance (folder, file_type o project) y una prioridad (high, medium, low). Una regla que los omite se importa como regla de proyecto con prioridad media. Una regla importada conserva ambos, así que una regla de carpeta de prioridad alta proveniente de un patrón aparece exactamente igual que una que hayas escrito tú.
• Las piezas de tipo skill llevan un nombre de skill y etiquetas opcionales, y su resumen de una línea se convierte en la descripción de la skill. Al importarla, la skill también se etiqueta como pattern:<slug>, para que puedas encontrar como grupo todas las skills que trajo un patrón. Después de importarla, la skill se puede descubrir e invocar por su nombre, igual que cualquier otra skill del espacio de trabajo.
• Las piezas de tipo memoria no necesitan metadatos adicionales; el cuerpo y la ruta bastan.

Las piezas de tipo regla también llevan un modo de aplicación (advisory o strict), y la copia manual etiqueta cada regla con uno de ellos. La importación no lo conserva: una regla importada llega como regla orientativa que acompaña como contexto, sin importar cómo la etiquete el catálogo. Para bloquear una edición hace falta una restricción ejecutable que una persona haya aprobado, igual que con cualquier regla, como se describe en Reglas como barreras de protección. Así, bloquear sigue siendo una decisión que toma una persona de tu equipo, no algo que active un catálogo.

Para el significado de fondo del alcance, la prioridad y la aplicación, consulta Conceptos clave.

Los conteos y las rutas se derivan

Un patrón nunca mantiene a mano su propio resumen. La línea "4 Rules, 2 Memories, 1 Skill" y la lista de rutas de destino de cada página del catálogo y del README del paquete se calculan a partir de las piezas. Eso significa que el contenido mostrado nunca puede desfasarse de lo que el conjunto contiene realmente. Si agregas una regla a un patrón, su conteo se actualiza solo.

Versionado y vigencia

Cada patrón tiene versión y fecha para que sepas qué estás adoptando y cuándo cambió por última vez:

• version es una versión de visualización, como 1.0.1. Se muestra en la página del catálogo y en la vista previa de importación. El token de importación no la incluye: ::pathrule:package:<slug> siempre se refiere a la versión que incluye tu cliente.
• updatedAt es la fecha del último cambio de contenido. Es la fecha "Updated" de la página del catálogo y la fecha de última modificación en el sitemap.
• changelog es una lista de entradas legibles, de la más reciente a la más antigua, que registra qué cambió entre versiones. Todos los patrones del catálogo tienen uno, que puedes leer en el paquete abierto.

El versionado importa porque la importación es una siembra única (consulta Importar un patrón). Tu copia nunca cambia sin que lo sepas, y Pathrule no registra qué versión importaste ni te avisa cuando se publica una más reciente. Compara la versión y la fecha de actualización de la página del catálogo con el momento en que importaste, y lee el registro de cambios para ver qué se movió. Importar un patrón explica cómo incorporar una versión más reciente.

Metadatos de presentación

Además de las piezas, un patrón incluye lo que el catálogo necesita para presentarlo: un nombre, un lema de una línea, una descripción más extensa, una categoría (una de Framework, Frontend, Backend, Billing, Infra, Workflow, AI y Security) y un ícono. Cada patrón del catálogo también se explica a sí mismo con el problema que resuelve, el público para el que está pensado y una lista de los errores que evita que cometa tu asistente. La página del catálogo muestra los tres en "Why this pattern".

Metadatos de coincidencia

Un patrón puede declarar a qué tipo de proyecto se ajusta, dentro de un bloque appliesTo: rutas relevantes, etiquetas de stack (por ejemplo nextjs, react) y nombres de dependencias. Todos los patrones del catálogo declaran uno. El catálogo web usa las etiquetas de stack para la búsqueda. La vista previa de importación le pasa ese mismo bloque a tu asistente, que lo compara con el árbol y el stack de tu proyecto antes de escribir nada y te pide confirmación cuando el patrón no parece encajar.

El paquete abierto

El catálogo se apoya en un único paquete abierto, @pathrule/patterns, publicado en npm bajo Apache-2.0. El paquete es puro y serializable: contiene las definiciones de los patrones, sus tipos y algunas funciones auxiliares, sin depender de ningún código de interfaz ni de la nube. Eso permite leerlo como datos simples y que todas las superficies consuman exactamente los mismos conjuntos.

Agregar un patrón consiste en registrar una nueva entrada en ese paquete. Como el paquete es la única fuente de verdad, el catálogo del sitio web, las herramientas de importación y las vistas en Markdown muestran el mismo contenido. El servidor MCP de Pathrule incluye su propia copia del paquete, y por eso un patrón recién publicado se puede importar en cuanto la versión de Pathrule que usas lo incluye.

Qué leer a continuación

• Importar un patrón muestra cómo se escribe un conjunto en tu espacio de trabajo y cómo quitarlo.
• Introducción a los patrones ofrece la visión de conjunto, por si te la saltaste.
• Escribir reglas y Escribir skills tratan a fondo los tipos de piezas.