ubiquitous-language

Visão geral da skill ubiquitous-language

A skill ubiquitous-language transforma uma discussão confusa sobre um domínio em um glossário estruturado no estilo DDD, com termos canônicos, definições e aliases a evitar. O trabalho central dela não é “escrever um glossário” de forma genérica. Ela ajuda equipes a padronizar a linguagem quando produto, engenharia e redação técnica usam termos sobrepostos ou inconsistentes para os mesmos conceitos.

Quando a ubiquitous-language funciona melhor

Use a skill ubiquitous-language quando a conversa já contém linguagem de domínio e você precisa formalizar isso em algo reutilizável. Ela é especialmente adequada para:

• trabalho com domain-driven design
• revisão e limpeza de terminologia de API e produto
• alinhamento de nomenclatura em plataformas internas
• documentação de onboarding
• modelagem de conteúdo
• ubiquitous-language para Technical Writing, quando a documentação precisa usar um termo canônico de forma consistente

O problema real que ela resolve

A maioria dos usuários está tentando resolver um destes problemas:

• “Continuamos usando vários nomes para a mesma coisa.”
• “Um termo significa coisas diferentes dependendo do contexto.”
• “Nossa documentação, a UI do produto e as discussões de engenharia estão se afastando.”
• “Precisamos de uma primeira versão de glossário de domínio a partir de discussões existentes, não começar do zero.”

Essa skill examina a conversa atual, identifica terminologia ambígua ou duplicada, propõe termos canônicos com posicionamento claro e grava o resultado em UBIQUITOUS_LANGUAGE.md.

O que diferencia isso de um prompt comum

Um prompt comum pode pedir um glossário. O fluxo da ubiquitous-language é mais específico e, por isso, mais útil na hora de decidir pela adoção:

• procura ambiguidades, sinônimos e termos sobrecarregados
• força uma direção de nomenclatura canônica, em vez de apenas extrair termos
• gera um artefato markdown reutilizável
• segue uma estrutura previsível baseada em tabelas, fácil de revisar e editar

Isso a torna melhor para consolidar terminologia do que um pedido genérico como “resuma nossos termos de domínio”.

Como é o resultado gerado

A skill cria UBIQUITOUS_LANGUAGE.md com seções temáticas, como ciclo de vida do pedido ou pessoas, e tabelas contendo:

• termo canônico
• definição
• aliases a evitar

Esse formato é especialmente útil para revisão porque torna divergências visíveis rapidamente.

Quando esta skill não é uma boa escolha

Evite usar essa skill se:

• a conversa ainda não tem material de domínio suficiente
• você precisa de uma ontologia completa, modelo de dados ou saída de event storming
• seu objetivo é naming de marca, e não clareza de domínio
• o domínio ainda está especulativo demais para escolher termos canônicos

Nesses casos, reúna exemplos primeiro e rode a skill depois.

Como usar a skill ubiquitous-language

Contexto de instalação da ubiquitous-language

Se você usa o ecossistema de skills de mattpocock/skills, instale a skill ubiquitous-language pelo seu carregador de skills habitual. Um padrão comum é:

npx skills add mattpocock/skills --skill ubiquitous-language

Se o seu ambiente carrega skills de outra forma, use esse método. O requisito principal é que o agente consiga acessar a definição da skill ubiquitous-language e gravar UBIQUITOUS_LANGUAGE.md no diretório de trabalho.

Leia este arquivo primeiro antes de usar

Comece por:

• SKILL.md

O caminho neste repositório é incomumente simples: a lógica principal de uso está nesse único arquivo. Você não precisa sair procurando scripts auxiliares ou referências profundas antes de decidir se vale testar.

Qual entrada a skill realmente precisa

A skill funciona melhor quando a conversa atual já contém:

• substantivos de domínio: order, invoice, account, shipment
• verbos de processo: approve, fulfill, cancel
• nomes de papéis: customer, operator, reviewer
• exemplos de uso confuso: “às vezes chamamos de subscription, às vezes de contract”
• contexto sobre limites: área de produto, público, sistema ou processo de negócio

Sem esse material, a saída tende a ficar superficial ou especulativa demais.

Como acionar a ubiquitous-language do jeito certo

Um pedido fraco seria:

• “Faça um glossário.”

Um pedido mais forte seria:

• “Use the ubiquitous-language skill on this discussion. Extract domain terms, identify synonyms and overloaded words, propose canonical terms, and write UBIQUITOUS_LANGUAGE.md. Group terms by business area.”

Essa formulação orienta o agente a usar a skill como ela foi pensada, em vez de improvisar um glossário qualquer.

Como transformar um objetivo vago em um prompt de alta qualidade

Um bom prompt de uso da ubiquitous-language normalmente inclui quatro partes:

1. o domínio
2. o material de origem
3. os conflitos ou pontos de dor
4. a expectativa de saída

Exemplo:

“Use the ubiquitous-language skill for our order-management domain. Based on the conversation so far, extract core terms, flag where we use the same word for different concepts, and propose canonical terms with aliases to avoid. Separate customer-facing terms from internal operational terms where needed. Save the result to UBIQUITOUS_LANGUAGE.md.”

Fluxo prático recomendado

Um fluxo confiável é:

1. discutir o domínio primeiro de forma natural
2. deixar os termos colidirem na conversa
3. rodar ubiquitous-language
4. revisar os termos canônicos propostos
5. corrigir erros de negócio
6. usar o glossário aprovado em docs, APIs, textos de UI e templates de issues

A skill entrega mais valor depois de alguma discussão real, não antes.

Dicas práticas para melhorar a qualidade da saída

Para obter resultados melhores:

• inclua exemplos concretos, não só categorias abstratas
• cite conflitos de termos explicitamente
• diga qual público importa mais: engenheiros, usuários, suporte, redatores
• indique se um termo é apenas interno ou voltado ao público externo
• peça ao modelo para preservar distinções relevantes, em vez de colapsar tudo em um único rótulo

Esses detalhes melhoram materialmente o glossário porque reduzem fusões incorretas de sinônimos.

O que technical writers devem fazer de diferente com ubiquitous-language

Para ubiquitous-language para Technical Writing, acrescente restrições como:

• vocabulário preferido do leitor
• jargão interno proibido
• restrições de rótulos de UI
• restrições de termos de API
• se a documentação deve espelhar a linguagem do produto ou normalizá-la

Exemplo:

“Use the ubiquitous-language skill, but optimize for external documentation. Prefer terms users will recognize, keep internal code names in aliases to avoid, and note any term that should not appear in public docs.”

Isso torna a saída mais aproveitável do ponto de vista editorial.

Arquivo esperado e padrão de revisão

O arquivo gerado é UBIQUITOUS_LANGUAGE.md. Revise-o com estas perguntas:

• A skill fundiu conceitos distintos por engano?
• Ela manteve termos ambíguos sem alertar?
• Os “aliases to avoid” são realistas?
• As definições refletem o comportamento real do sistema, e não só uma preferência de redação?

Trate a primeira versão como um rascunho para decisão, não como verdade final.

FAQ da skill ubiquitous-language

A ubiquitous-language é amigável para iniciantes?

Sim, desde que já exista uma conversa sobre o domínio. Você não precisa de conhecimento profundo em DDD para se beneficiar. A saída é um markdown legível, e as tabelas deixam divergências visíveis. O que iniciantes costumam subestimar é que a qualidade depende muito da especificidade da discussão de origem.

Por que isso é melhor do que pedir um glossário diretamente?

A skill ubiquitous-language é mais focada e, por isso, mais confiável para alinhamento terminológico. Ela foi desenhada para detectar ambiguidades, sinônimos e termos sobrecarregados, e então forçar escolhas canônicas. Um prompt genérico de glossário costuma listar termos sem resolver conflitos.

Ela só ajuda equipes que usam DDD?

Não. O vocabulário de DDD é a moldura, mas a skill é útil em qualquer contexto em que deriva de terminologia gere atrito: documentação técnica, APIs, operações de suporte, design de produto ou ferramentas internas. Ela é especialmente útil quando várias equipes descrevem o mesmo fluxo de maneiras diferentes.

Quando não devo instalar a ubiquitous-language?

Não priorize a instalação da ubiquitous-language se sua principal necessidade for uma destas:

• brainstorming de nomes de produto
• geração de documentação para usuário final a partir do zero
• criação de schema de banco de dados
• mapeamento detalhado de todas as regras de negócio

Essa skill serve para normalizar linguagem, não para modelagem completa de domínio.

Ela funciona com uma conversa curta?

Funciona, mas os resultados são mais fracos. A skill extrai a partir da conversa atual, então entrada escassa leva a definições genéricas e menos detecção de conflitos relevantes. Se você só tem um chat curto, adicione exemplos, casos de borda e termos concorrentes antes.

Ela se encaixa em fluxos de documentação?

Sim. O arquivo de saída é fácil de versionar, revisar em pull requests e reaproveitar em style guides, architecture docs, materiais de onboarding e referências de API. Isso torna o uso da ubiquitous-language prático para equipes que querem manter decisões terminológicas ao lado do código e da documentação.

Como melhorar a skill ubiquitous-language

Dê à ubiquitous-language evidências de domínio mais ricas

A maior alavanca de qualidade da saída é a qualidade do material de origem. Antes de rodar a ubiquitous-language, inclua:

• termos reais voltados ao usuário
• abreviações ou atalhos internos
• etapas de processo
• casos de borda
• exemplos em que duas pessoas usaram palavras diferentes para a mesma coisa

A skill só consegue normalizar o que ela consegue enxergar.

Separe sinônimos reais de distinções importantes

Um modo comum de falha é colapsar dois conceitos relacionados, mas distintos. Evite isso declarando os contrastes de forma direta, por exemplo:

• “Order is the customer request; invoice is the billing artifact.”
• “Account is the legal entity; workspace is the product container.”

Isso ajuda a skill a preservar os limites do domínio em vez de simplificar demais.

Diga qual linguagem deve prevalecer

Nomenclatura canônica envolve escolha. Se você não explicitar sua preferência, a skill pode optar por termos tecnicamente corretos, mas inadequados para o seu fluxo de trabalho. Melhore os resultados especificando:

• vocabulário externo vs interno
• terminologia de engenharia vs de negócio
• rótulos de UI vs rótulos de back-office
• termos que precisam permanecer por compatibilidade

Essa orientação torna o glossário mais utilizável depois de gerado.

Use prompts mais fortes em domínios ambíguos

Se o seu domínio é carregado de ambiguidades, peça explicitamente uma análise de ambiguidade. Exemplo:

“Use the ubiquitous-language skill and be strict about ambiguity. If the same term refers to multiple concepts, split them into separate entries and call out the conflict clearly instead of picking one silently.”

Isso reduz o risco de uma falsa sensação de clareza.

Revise os aliases to avoid com cuidado extra

A coluna “aliases to avoid” é onde muitas equipes extraem mais valor, mas também onde erros podem gerar confusão. Verifique se os aliases banidos são:

• realmente enganosos
• ainda necessários em documentação legada
• aceitáveis para um público, mas não para outro

Uma segunda revisão melhor costuma manter o termo canônico, mas suavizar a orientação sobre aliases.

Itere depois da primeira versão

O melhor guia de ubiquitous-language é iterativo:

1. rode a skill
2. marque os termos contestados
3. adicione exemplos esclarecedores à conversa
4. rode a skill novamente
5. aprove o glossário
6. aplique-o em toda a documentação e linguagem do produto

Não espere que a primeira passada resolva toda decisão de nomenclatura.

Estenda o resultado para dentro do seu sistema de documentação

Quando UBIQUITOUS_LANGUAGE.md estiver estável, aumente o valor da skill ubiquitous-language conectando-o ao trabalho editorial real:

• faça link a partir do style guide da documentação
• use durante revisão de PR
• alinhe headings e referências de UI aos termos canônicos
• audite docs antigas em busca de aliases banidos

É assim que o glossário deixa de ser decorativo e passa a ser operacional.