ubiquitous-language

Visão geral do skill de linguagem ubíqua

O que a linguagem ubíqua faz

O skill ubiquitous-language transforma uma conversa confusa em um glossário no estilo DDD: ele extrai termos de domínio, identifica ambiguidade e deriva de sinônimos e, depois, escreve um arquivo canônico UBIQUITOUS_LANGUAGE.md. Se você precisa de um vocabulário compartilhado para produto, engenharia ou Technical Writing, este skill de linguagem ubíqua ajuda a explicitar a terminologia em vez de deixar o modelo improvisar.

Quem deve instalar

Instale este skill de linguagem ubíqua se você estiver definindo um modelo de domínio, documentando uma área do produto, alinhando equipes sobre termos ou limpando uma linguagem confusa em specs e documentos. Ele é especialmente útil quando você já tem uma conversa em andamento, uma transcrição de entrevista ou um thread de requisitos e quer normalizar a terminologia rapidamente.

Por que ele é útil

O trabalho real a ser feito não é “escrever um glossário”; é “evitar a deriva de significado”. Este skill funciona muito bem quando o maior risco é nomenclatura inconsistente, termos sobrecarregados ou vários nomes para a mesma coisa. Ele serve menos para gerar texto corrido e mais para escolher um termo canônico e explicar o que deve ser evitado.

Como usar o skill de linguagem ubíqua

Instale e localize os arquivos do skill

Use o fluxo ubiquitous-language install no seu gerenciador de skills, ou instale pelo caminho do repositório mattpocock/skills em skills/deprecated/ubiquitous-language. Comece por SKILL.md; aqui não há scripts auxiliares, referências nem pastas de recursos, então o comportamento principal fica concentrado nesse único arquivo.

Forneça o material de origem certo

Para usar bem a linguagem ubíqua, entregue ao skill uma conversa, anotações, um thread de ticket ou um rascunho de spec que contenha linguagem real do domínio. Um prompt forte nomeia o contexto e a superfície de decisão, por exemplo: “Extraia o glossário de linguagem ubíqua desta conversa de discovery de produto para um app de gestão de pedidos. Priorize os termos customer, order, invoice, shipment e refund, e sinalize qualquer palavra que pareça sobrecarregada.”

Formule o prompt para melhorar a qualidade da saída

O skill funciona melhor quando você diz quais termos importam e para quem o glossário serve. Se você quer linguagem ubíqua para Technical Writing, deixe isso explícito e peça terminologia que possa ser reutilizada em docs, rótulos de UI e docs de API. Inclua restrições como “prefira termos canônicos com opinião”, “aponte aliases a evitar” ou “foque em termos com impacto para o usuário”.

Siga um fluxo simples

Primeiro, cole a conversa ou as notas de origem. Depois, peça o glossário e as ambiguidades encontradas. Em seguida, revise o UBIQUITOUS_LANGUAGE.md gerado à luz da realidade do produto: confirme se cada termo é realmente distinto, se sinônimos devem ser unificados e se algum termo precisa ser renomeado para refletir o vocabulário real do time.

FAQ do skill de linguagem ubíqua

Isso é melhor do que um prompt normal?

Sim, quando você quer uma limpeza de terminologia repetível, e não um resumo pontual. Um prompt normal pode gerar uma lista de termos, mas o skill de linguagem ubíqua foi feito para identificar ambiguidade, propor formulações canônicas e salvar o resultado em um formato de arquivo reutilizável.

O que ele não faz?

Ele não substitui a validação do domínio com stakeholders. Ele pode inferir e organizar termos a partir da conversa, mas não tem como saber qual rótulo o seu time adotou oficialmente. Se o material de origem for raso ou contraditório, a saída deve ser tratada como rascunho para revisão, e não como fonte de verdade.

Ele é amigável para iniciantes?

Sim, desde que você consiga fornecer um texto de origem claro e um domínio-alvo definido. O erro mais comum de quem está começando é pedir “um glossário” sem dar contexto de domínio suficiente. Quanto mais específica for a conversa e mais explícito for o público, melhor o guia de linguagem ubíqua vai funcionar.

Quando devo pular este skill?

Pule este skill se você só precisa de uma definição curta de marketing, de uma página de glossário genérica ou de uma taxonomia ampla sem conflitos reais de termos. Ele é mais valioso quando a escolha das palavras afeta implementação, documentação ou alinhamento entre áreas.

Como melhorar o skill de linguagem ubíqua

Traga mais evidências do domínio, não mais enrolação

A maior melhoria vem de linguagem de origem mais rica: user stories, tickets de suporte, textos de onboarding e discussões de produto ajudam bastante. No uso de linguagem ubíqua, termos cercados por exemplos são mais fáceis de normalizar do que listas abstratas de funcionalidades.

Peça as decisões que realmente importam

Diga ao skill o que deve ser otimizado: consistência entre docs, menos sinônimos na UI, nomenclatura de API mais clara ou alinhamento mais forte com DDD. Se você estiver usando linguagem ubíqua para Technical Writing, peça que ele prefira termos que funcionem bem em headings, labels, linhas de tabela e reutilização entre documentos.

Revise os modos de falha mais comuns

Fique atento a unir demais conceitos distintos, inventar termos que o time jamais usaria ou achatar nuances do domínio em uma linguagem genérica. Se o primeiro rascunho parecer abstrato demais, responda com exemplos de casos-limite e peça ao skill para refazer o glossário em torno dessas distinções.

Itere com correções específicas

A forma mais rápida de melhorar a saída é marcar exatamente quais escolhas de termos estão erradas e por quê. Por exemplo: “Use customer em vez de account, mantenha order separado de purchase e trate refund e credit como conceitos distintos.” Esse tipo de feedback deixa a próxima passagem do skill de linguagem ubíqua muito mais precisa.