Anatomia de um padrão

Um padrão é simples de propósito. Ele é um pequeno conjunto de peças tipadas, mais os metadados necessários para exibi-lo, versioná-lo e associá-lo a um projeto. Entender esse formato deixa claro o que você recebe ao importar um.

Um padrão é um conjunto de peças

Todo padrão traz uma lista de peças. Cada peça é exatamente uma memória, uma regra ou uma skill, e sabe onde deve ser colocada.

Uma peça declara:

• kind: memory, rule ou skill. Define em qual tipo de conteúdo ela se transforma na importação.
• nodePath: o caminho, relativo ao espaço de trabalho, ao qual ela pertence, por exemplo /app, /services/billing ou / para a raiz. É com esse escopo que a peça é entregue.
• title: o título da memória, o nome da regra ou o nome da skill.
• summary: uma descrição de uma linha exibida na lista do conjunto, separada do corpo.
• body: o conteúdo completo em Markdown. É exatamente isso que é gravado no seu espaço de trabalho, sem nenhuma transformação.

Como cada peça indica o próprio caminho, um padrão já nasce vinculado a caminhos. O conjunto não é um documento único que precisa ser arquivado em algum lugar; é um grupo de peças que já sabem para onde vão.

Metadados específicos de cada tipo

Algumas peças trazem campos extras de acordo com o tipo de conteúdo, e eles são preservados intactos na importação.

• Peças de regra definem um tipo de escopo (folder, file_type ou project) e uma prioridade (high, medium, low). Uma regra que omite esses campos é importada como regra de projeto com prioridade média. Uma regra importada mantém os dois, então uma regra de pasta de alta prioridade vinda de um padrão aparece exatamente como uma que você mesmo escreveu.
• Peças de skill trazem um nome de skill e tags opcionais, e o resumo de uma linha vira a descrição da skill. Na importação, a skill também recebe a tag pattern:<slug>, para que você encontre em grupo todas as skills que um padrão trouxe. Depois da importação, a skill pode ser encontrada e invocada pelo nome, como qualquer outra skill do espaço de trabalho.
• Peças de memória não precisam de metadados extras; o corpo e o caminho bastam.

Peças de regra também trazem um modo de aplicação (advisory ou strict), e a cópia manual identifica cada regra com um deles. A importação não leva esse campo: uma regra importada chega como regra consultiva, que acompanha o contexto, independentemente do rótulo que tem no catálogo. Bloquear uma edição exige uma restrição executável aprovada por uma pessoa, como acontece com qualquer regra, conforme descrito em Regras como guardrails. Assim, bloquear continua sendo uma decisão de alguém da sua equipe, e não algo que um catálogo ativa.

Para entender o significado de escopo, prioridade e aplicação, veja Conceitos principais.

Contagens e caminhos são derivados

Um padrão nunca mantém o próprio resumo à mão. A linha "4 Rules, 2 Memories, 1 Skill" e a lista de caminhos de destino em cada página do catálogo e no README do pacote são calculadas a partir das peças. Por isso, o conteúdo exibido nunca fica defasado em relação ao que o conjunto realmente contém. Adicione uma regra a um padrão e a contagem se atualiza sozinha.

Versionamento e atualização

Cada padrão tem versão e data, para que você saiba o que está adotando e quando ele mudou pela última vez:

• version é uma versão de exibição, como 1.0.1. Ela aparece na página do catálogo e na prévia de importação. O token de importação não a inclui: ::pathrule:package:<slug> sempre se refere à versão que vem com o seu cliente.
• updatedAt é a data da última alteração de conteúdo. É a data "Updated" na página do catálogo e a data de última modificação no sitemap.
• changelog é uma lista de entradas legíveis, da mais recente para a mais antiga, que registra o que mudou entre versões. Todo padrão do catálogo tem um, que pode ser lido no pacote aberto.

O versionamento importa porque a importação é uma semente aplicada uma única vez (veja Importando um padrão). Sua cópia nunca muda por baixo dos panos, e o Pathrule não registra qual versão você importou nem avisa quando uma nova é publicada. Compare a versão e a data de atualização na página do catálogo com a data em que você importou, e leia o changelog para ver o que mudou. Importando um padrão explica como trazer uma versão mais nova.

Metadados de exibição

Além das peças, um padrão traz o que o catálogo precisa para apresentá-lo: um nome, um slogan de uma linha, uma descrição mais longa, uma categoria (uma entre Framework, Frontend, Backend, Billing, Infra, Workflow, AI e Security) e um ícone. Todo padrão do catálogo também se explica com o problema que resolve, o público para o qual foi feito e uma lista dos erros que ele evita que o seu assistente cometa. A página do catálogo mostra os três em "Why this pattern".

Metadados de correspondência

Um padrão pode declarar a que tipo de projeto se aplica, em um bloco appliesTo: caminhos relevantes, tags de stack (por exemplo nextjs, react) e nomes de dependências. Todo padrão do catálogo declara um. O catálogo web usa as tags de stack na busca. A prévia de importação entrega esse mesmo bloco ao seu assistente, que o compara com a árvore e a stack do seu projeto antes de gravar qualquer coisa e pede sua confirmação quando o padrão não parece se encaixar.

O pacote aberto

O catálogo se apoia em um único pacote aberto, @pathrule/patterns, publicado no npm sob a licença Apache-2.0. O pacote é puro e serializável: contém as definições dos padrões, seus tipos e algumas funções auxiliares, sem depender de nenhum código de UI ou de nuvem. Isso o mantém legível como dados simples e permite que todas as superfícies consumam exatamente os mesmos conjuntos.

Adicionar um padrão é registrar uma nova entrada nesse pacote. Como o pacote é a única fonte da verdade, o catálogo do site, as ferramentas de importação e as visualizações em Markdown renderizam o mesmo conteúdo. O servidor MCP do Pathrule carrega sua própria cópia do pacote, e é por isso que um padrão recém-publicado só passa a ser importável quando a versão do Pathrule que você usa o inclui.

O que ler em seguida

• Importando um padrão mostra como um conjunto é gravado no seu espaço de trabalho e como removê-lo.
• Visão geral dos padrões traz o panorama geral, caso você tenha pulado essa parte.
• Como escrever regras e Como escrever skills tratam dos tipos de peça em detalhes.