Anatomia di un pattern

Un pattern è volutamente semplice. È un piccolo insieme di elementi tipizzati, più i metadati necessari per mostrarlo, versionarlo e abbinarlo a un progetto. Una volta capita questa struttura, è chiaro che cosa ottieni quando ne importi uno.

Un pattern è un insieme di elementi

Ogni pattern contiene un elenco di elementi. Ogni elemento è esattamente una memoria, una regola o una skill, e sa dove deve finire.

Un elemento dichiara:

• kind: memory, rule o skill. Determina il tipo di contenuto in cui si trasforma all'importazione.
• nodePath: il percorso relativo al workspace a cui appartiene, per esempio /app, /services/billing o / per la radice. È l'ambito con cui l'elemento viene fornito.
• title: il titolo della memoria, il nome della regola o il nome della skill.
• summary: una descrizione di una riga mostrata nell'elenco del pacchetto, separata dal corpo.
• body: il contenuto Markdown completo. È esattamente ciò che viene scritto nel tuo workspace, senza alcuna trasformazione.

Poiché ogni elemento indica il proprio percorso, un pattern è legato ai percorsi per costruzione. Il pacchetto non è un unico documento da archiviare da qualche parte: è un insieme di elementi che sanno già dove andare.

Metadati specifici per tipo

Alcuni elementi hanno campi aggiuntivi legati al loro tipo di contenuto, e questi vengono conservati intatti all'importazione.

• Gli elementi di tipo regola impostano un tipo di ambito (folder, file_type o project) e una priorità (high, medium, low). Una regola che li omette viene importata come regola di progetto con priorità media. Una regola importata li mantiene entrambi, quindi una regola di cartella ad alta priorità proveniente da un pattern emerge esattamente come una che hai scritto tu.
• Gli elementi di tipo skill hanno un nome di skill e tag facoltativi, e il loro riepilogo di una riga diventa la descrizione della skill. All'importazione la skill riceve anche il tag pattern:<slug>, così puoi trovare come gruppo tutte le skill portate da un pattern. Dopo l'importazione la skill è individuabile e invocabile per nome, come qualsiasi altra skill del workspace.
• Gli elementi di tipo memoria non richiedono metadati aggiuntivi: bastano il corpo e il percorso.

Gli elementi di tipo regola hanno anche una modalità di applicazione (advisory o strict), e la copia manuale indica per ogni regola quale delle due. L'importazione non la trasferisce: una regola importata arriva come regola consultiva che accompagna il contesto, qualunque sia l'etichetta nel catalogo. Per bloccare una modifica serve un vincolo eseguibile approvato da una persona, come per qualsiasi regola, secondo quanto descritto in Le regole come guardrail. In questo modo il blocco resta una decisione presa da una persona del tuo team, non qualcosa che attiva un catalogo.

Per il significato di fondo di ambito, priorità e applicazione, vedi Concetti fondamentali.

Conteggi e percorsi sono ricavati

Un pattern non mantiene mai a mano il proprio riepilogo. La riga "4 Rules, 2 Memories, 1 Skill" e l'elenco dei percorsi di destinazione in ogni pagina del catalogo e nel README del pacchetto vengono calcolati dagli elementi. Questo significa che il contenuto mostrato non può mai discostarsi da ciò che il pacchetto contiene davvero. Se aggiungi una regola a un pattern, il conteggio si aggiorna da solo.

Versionamento e aggiornamento

Ogni pattern ha una versione e una data, così puoi sapere che cosa stai adottando e quando è cambiato l'ultima volta:

• version è una versione di visualizzazione come 1.0.1. Compare nella pagina del catalogo e nell'anteprima di importazione. Il token di importazione non la contiene: ::pathrule:package:<slug> indica sempre la versione inclusa nel tuo client.
• updatedAt è la data dell'ultima modifica del contenuto. È la data "Updated" nella pagina del catalogo e la data di ultima modifica nella sitemap.
• changelog è un elenco di voci leggibili, dalla più recente, che registra cosa è cambiato tra una versione e l'altra. Ogni pattern del catalogo ne ha uno, consultabile nel pacchetto aperto.

Il versionamento conta perché l'importazione è un'inizializzazione una tantum (vedi Importare un pattern). La tua copia non cambia mai a tua insaputa, e Pathrule non tiene traccia di quale versione hai importato né ti avvisa quando ne viene pubblicata una più recente. Confronta la versione e la data di aggiornamento nella pagina del catalogo con il momento in cui hai importato, e leggi il changelog per vedere che cosa è cambiato. Importare un pattern spiega come portare dentro una versione più recente.

Metadati di visualizzazione

Oltre agli elementi, un pattern contiene ciò che serve al catalogo per presentarlo: un nome, uno slogan di una riga, una descrizione più lunga, una categoria (una tra Framework, Frontend, Backend, Billing, Infra, Workflow, AI e Security) e un'icona. Ogni pattern del catalogo spiega inoltre il problema che risolve, il pubblico per cui è pensato e un elenco degli errori che evita al tuo assistente. La pagina del catalogo mostra tutti e tre sotto "Why this pattern".

Metadati di corrispondenza

Un pattern può dichiarare a quale tipo di progetto si adatta, in un blocco appliesTo: percorsi rilevanti, tag dello stack (per esempio nextjs, react) e nomi delle dipendenze. Ogni pattern del catalogo ne dichiara uno. Il catalogo web usa i tag dello stack per la ricerca. L'anteprima di importazione passa lo stesso blocco al tuo assistente, che lo confronta con la struttura e lo stack del tuo progetto prima di scrivere qualsiasi cosa e ti chiede conferma quando il pattern non sembra adatto.

Il pacchetto aperto

Il catalogo si basa su un unico pacchetto aperto, @pathrule/patterns, pubblicato su npm con licenza Apache-2.0. Il pacchetto è puro e serializzabile: contiene le definizioni dei pattern, i loro tipi e alcune funzioni di supporto, senza dipendenze da codice di interfaccia o cloud. Questo lo rende leggibile come semplici dati e permette a ogni superficie di usare esattamente gli stessi pacchetti.

Aggiungere un pattern significa registrare una nuova voce in quel pacchetto. Poiché il pacchetto è l'unica fonte di verità, il catalogo del sito, gli strumenti di importazione e le viste Markdown mostrano tutti lo stesso contenuto. Il server MCP di Pathrule include una propria copia del pacchetto, ed è per questo che un pattern appena pubblicato diventa importabile quando la release di Pathrule che usi lo include.

Cosa leggere dopo

• Importare un pattern mostra come un pacchetto viene scritto nel tuo workspace e come rimuoverlo.
• Panoramica dei pattern offre il quadro generale, se l'hai saltata.
• Scrivere regole e Scrivere skill approfondiscono i tipi di elemento.