Como documentar a taxonomia de categorias dentro de uma skill do Jev?

Agente que classifica sem taxonomia fechada inventa rótulo novo a cada execução, e aí o seu relatório vira uma salada de cobrança, financeiro, billing e pagamento apontando pra mesma coisa

Fala aí, beleza? O Jev é o modelo principal da TypeSafe AI e o primeiro modelo "System One", feito pra devolver decisão tipada que o software consome direto, em vez de texto gerado que você precisa parsear na esperança. E o lugar onde a sua taxonomia mora é a pergunta do tipo Choice: escolha única dentro de um conjunto fechado de opções, sem ordem entre elas

A sacada é que a saída fica constrangida ao conjunto que você declarou, o modelo não tem como devolver valor fora do schema

Ou seja: a variação não vem do modelo inventando rótulo, vem da sua taxonomia estar mal escrita

E é isso que a gente vai documentar aqui dentro da skill 🙂

O que você precisa antes de começar

Três coisas, nada de PC da Nasa

1. Conta com acesso ao Jev. O Jev saiu em early access limitado pela TypeSafe AI em 15/09/2026. Em 20/09/2026 a empresa removeu o waitlist e abriu pra todos, e em 22/09/2026 pausou temporariamente novos cadastros por excesso de demanda, mantendo as contas já criadas funcionando

Esse é o último estado confirmado, então se você já tem conta, tá tudo certo

2. A skill oficial da TypeSafe instalada no seu agente. Ela dá ao agente de código o contexto da API: os três tipos de pergunta, os padrões de arquitetura e boas práticas de estruturação. No Claude Code:

Pré-inscrição Curso Jev

Domine o Jev e coloque decisões de IA dentro do seu sistema

Você vai aprender a usar o Jev, o System One Model da TypeSafe AI, pra automatizar decisões com resposta tipada e confiança medida, sem depender de chat nem de alguém revisando cada passo. Entre na lista de espera para garantir a condição de lançamento!

Quero minha vaga

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Depois você invoca com /typesafe:typesafe-ai

Em outros agentes:

npx skills add typesafe-ai/skills --skill typesafe-ai

A instalação é project-local por padrão, e -g joga pra global. Prefere na mão? Copie o diretório skills/typesafe-ai inteiro, com os arquivos de referência, pro diretório de skills do seu agente. Tudo isso tá na página da agent skill oficial

3. Saber que skill, no Claude Code, é pasta no disco. Nada de menu escondido: cada skill é uma pasta com um SKILL.md dentro, em ~/.claude/skills/ pra skills pessoais ou .claude/skills/ pra skills de projeto

É nesse SKILL.md que a sua taxonomia vai morar

Como documentar a taxonomia passo a passo

1. Confirme que a pergunta é Choice, e não Score nem Noul

A TypeSafe expõe três primitivas, e escolher errado aqui estraga tudo que vem depois:

Se os seus rótulos têm ordem natural, é Score. Se é sim ou não, é Noul. Taxonomia de categorias sem hierarquia de valor entre elas? Choice, sempre

O erro comum deste passo: usar Choice pra algo ordenado tipo baixa, média, alta. Aí você perde a noção de ordem que o Score te daria de graça

2. Escreva a lista COMPLETA de rótulos, não uma lista curta

Esse é o passo que mais gente pula. A documentação do Choice orienta passar a lista completa de categorias em vez de uma amostra, porque cada opção extra custa poucos tokens

O teto é 255 opções por pergunta Choice, então sobra espaço pra caramba

O erro comum deste passo: declarar 5 categorias "principais" e esperar que o resto encaixe. Não encaixa, e aí vem a variação

3. Dê uma descrição curta a cada rótulo no campo criteria

As opções de um Choice são declaradas no campo criteria da pergunta, que é um mapa de opção pra descrição. Quando a opção é óbvia e não precisa de detalhe extra, você usa null

{
  "instructions": "Classifique o ticket no departamento que deve RESOLVER o caso, nao no assunto citado pelo cliente",
  "criteria": {
    "cobranca": "Fatura, reembolso, troca de plano e dados de pagamento",
    "suporte_tecnico": "Erro, bug, indisponibilidade e duvida de configuracao do produto",
    "comercial": "Pedido de proposta, upgrade de contrato e duvida de precificacao",
    "spam": null
  }
}

Regra de ouro: os rótulos de uma mesma pergunta são mutuamente exclusivos, exatamente um se aplica, e cada um carrega a sua descrição curta

O erro comum deste passo: exclusividade quebrada. Se cobranca e comercial podem descrever o mesmo ticket, o modelo vai alternar entre os dois e você vai jurar que ele é instável. Ele não é, a sua fronteira é que tá borrada

4. Afie as fronteiras migrando a descrição de string pra objeto

Tanto instructions quanto cada entrada de criteria aceitam string, objeto ou array. A recomendação é começar com string e migrar pra objeto quando a descrição precisa de vários tipos de orientação

E o objeto é onde a mágica acontece: ele pode dizer o que a opção cobre, o que pertence a outra opção e alguns exemplos

{
  "criteria": {
    "cobranca": {
      "cobre": "Fatura, reembolso, troca de plano e dados de pagamento",
      "nao_cobre": "Erro tecnico na tela de checkout, isso vai para suporte_tecnico",
      "exemplos": ["quero meu dinheiro de volta", "cobraram duas vezes no cartao"]
    },
    "suporte_tecnico": {
      "cobre": "Erro, bug, indisponibilidade e duvida de configuracao do produto",
      "nao_cobre": "Pedido de reembolso motivado por um erro, isso vai para cobranca",
      "exemplos": ["o app fecha ao salvar", "o webhook parou de disparar"]
    },
    "comercial": {
      "cobre": "Proposta, upgrade de contrato e duvida de precificacao de plano novo",
      "nao_cobre": "Duvida sobre uma fatura ja emitida, isso vai para cobranca",
      "exemplos": ["quanto fica para 50 usuarios", "quero migrar para o plano anual"]
    }
  }
}

Se liga nisso: use os MESMOS nomes de campo em todas as opções. É isso que permite ao modelo comparar uma opção com a outra no mesmo eixo

O erro comum deste passo: uma opção com cobre/nao_cobre/exemplos e a vizinha com descricao/quando_usar. Fica cada uma falando uma língua e a comparação se perde

5. Adicione a opção de escape

Quando a sua lista pode não cobrir toda entrada possível (e ela quase sempre pode), a orientação oficial é incluir uma opção tipo other ou none of the above

{
  "criteria": {
    "outro": "Nenhuma das outras categorias descreve este ticket"
  }
}

Parece detalhe bobo, mas é o que impede o modelo de empurrar um caso estranho pra dentro da categoria mais parecida só porque não tinha pra onde correr

O erro comum deste passo: esquecer o escape e depois culpar a taxonomia inteira por um outlier

6. Grave tudo no SKILL.md

Agora sai da API e vai pro disco. O SKILL.md usa frontmatter YAML com name e description, e a description é justamente o que diz ao modelo o que a skill faz e quando usá-la

As regras do frontmatter: name com no máximo 64 caracteres, só letras minúsculas, números e hífens, sem tags XML e sem as palavras reservadas "anthropic" e "claude". A description não pode ser vazia, vai até 1.024 caracteres e também não aceita tags XML

---
name: taxonomia-tickets
description: Taxonomia fechada de categorias de ticket para perguntas Choice. Use ao classificar ou rotear um ticket de suporte, para reaproveitar sempre os mesmos rotulos.
---

# Taxonomia de tickets

## Pergunta Choice: departamento

Rotulos (mutuamente exclusivos, exatamente um se aplica):

- cobranca
- suporte_tecnico
- comercial
- spam
- outro

Descricoes completas de cada rotulo em `criteria.json`, com os campos
cobre, nao_cobre e exemplos. Nao crie rotulo novo: se nada encaixa,
responda outro

O erro comum deste passo: frontmatter que não é lido. O Claude Code só interpreta o frontmatter quando o --- de abertura é a PRIMEIRA linha do arquivo. Uma linha em branco, um comentário, um título antes, e ele trata o arquivo inteiro (marcadores incluídos) como conteúdo da skill. Tome cuidado! É o tipo de coisa que você só descobre depois de meia hora achando que a skill não carrega

7. Use probabilities e confidence como limiar no seu código

Além do rótulo escolhido, a resposta traz uma probabilidade pra cada opção e um valor de confiança da opção selecionada, de 0 a 1. Isso serve de portão no fluxo:

# pseudo-codigo: o fluxo fica no codigo, o julgamento fica na pergunta tipada
r = perguntar_departamento(ticket)

rotulo, p = max(r["probabilities"].items(), key=lambda item: item[1])

if p >= 0.60:
    rotear(ticket, rotulo)
else:
    fila_de_revisao_humana(ticket)

A orientação oficial de arquitetura é exatamente essa: fluxo de controle, regras determinísticas e efeitos colaterais ficam no código, e o que vai pro modelo são julgamentos estreitos, quebrados em perguntas tipadas com instructions e criteria explícitos. Se essa divisão de papéis dentro do agente ainda tá nebulosa pra você, vale dar uma olhada antes de seguir

O erro comum deste passo: tratar confiança alta como garantia de acerto. Já volto nisso

Exemplos de taxonomia que funcionam bem em Choice

A documentação do Choice cita dois casos clássicos, e o cookbook oficial traz um terceiro bem mais agressivo

Roteamento de ticket para um departamento

Conjunto fechado, sem ordem, exatamente um departamento resolve. Perfeito pro Choice

A fronteira aqui quase sempre é intenção contra assunto. O cliente escreve "o checkout deu erro e eu quero meu dinheiro de volta": isso é cobranca ou suporte_tecnico?

A resposta não sai do modelo, sai da sua descrição. É por isso que o nao_cobre existe: "pedido de reembolso motivado por um erro vai para cobranca" resolve o caso pra sempre

Classificação de tipo de documento

Contrato, nota fiscal, procuração, comprovante. Também conjunto fechado e sem ordem

Aqui a fronteira é escrita com exemplos, porque documento real vem com nome errado e cabeçalho ambíguo. Dois ou três exemplos por opção fazem mais pela estabilidade do que um parágrafo de definição jurídica

Se você ainda tá decidindo onde esse tipo de decisão tipada compensa no seu produto, dá uma olhada nos casos de uso de automação com Jev

Catálogo grande: escolher no máximo uma skill por turno

Esse é o caso mais insano. Existe um cookbook oficial que usa Choice pra escolher no máximo 1 skill por turno dentro das 182 do catálogo Hermes da Nous Research

São duas requisições TypeSafe: uma pra ranquear candidatos e outra pra reverificar a escolha

O resultado reportado é redução de mais da metade nos carregamentos incorretos de skill

Repara no desenho: 182 opções em um único conjunto fechado, exatamente o oposto de "manda só as 5 mais prováveis". A fronteira, nesse volume, é escrita no criteria de cada skill descrevendo quando ela NÃO serve

Quando o agente ainda varia o rótulo: o que checar

Você documentou tudo, e ainda assim o mesmo caso limítrofe volta com rótulo diferente. Bora diagnosticar

Sintoma: o mesmo texto recebe rótulos diferentes em execuções separadas. Causa mais provável: duas opções cobrendo a mesma coisa. A exclusividade mútua tá no papel, mas não nas descrições. Solução: escrever nao_cobre nas duas apontando uma pra outra

Sintoma: a confiança vem baixa em uma família inteira de casos. Causa: descrição vaga, aquela que define a categoria repetindo o nome dela ("comercial: assuntos comerciais"). Solução: migrar de string pra objeto e botar exemplos reais

Sintoma: quase tudo caindo no outro. Causa: a lista de rótulos não cobre o seu domínio de verdade, ou o escape ficou descrito de forma atraente demais. Solução: olhar 20 casos que caíram no escape e ver se ali não tem uma categoria nova esperando pra nascer

Como medir isso sem achismo

Tem um cookbook oficial de autoconsistência para Choice que faz exatamente o que você deveria fazer: roda uma rubrica de perguntas várias vezes sobre o mesmo caso limítrofe e mede quanto o rótulo se repete

O setup é uma rubrica de 8 perguntas Choice, com 15 repetições por condição

Os números reportados pela TypeSafe:

• o rótulo de pluralidade se repetiu em 90,8% das respostas
• exigindo probabilidade máxima de ao menos 0,60, a concordância sobe pra 99,2%
• nesse regime, 74,2% das respostas recebem rótulo automático e o resto vai pra revisão humana

Isso é o desenho que você quer copiar: limiar no código, revisão humana pro que fica embaixo dele

E um detalhe que muita gente entende torto: confidence descreve o quanto a distribuição está concentrada em uma opção, e não uma medida de correção da resposta. Confiança alta em cima de uma taxonomia mal escrita é confiança alta no rótulo errado

Como prevenir

Rotina simples, sem mistério:

• guarde os casos de fronteira que apareceram na vida real em um arquivo junto do SKILL.md
• toda vez que mexer em uma descrição, rode a rubrica de novo nesses casos e compare a repetição
• quando criar rótulo novo, revise o nao_cobre dos vizinhos no mesmo commit, porque categoria nova sempre rouba território de alguém
• revise o que caiu no outro periodicamente, é ali que mora a próxima categoria

Vídeo: skills que leem seu código

Pra começar do zero com skills de agente e ver o que elas conseguem fazer lendo um projeto inteiro, este vídeo do canal mostra uma skill que lê o código e desenha a arquitetura sozinha:

Próximo passo

Taxonomia documentada é a versão prática daquela regra de arquitetura: fluxo de controle e regra determinística ficam no código, julgamento estreito fica na pergunta tipada

O modelo não inventa rótulo porque a saída é constrangida ao conjunto que você declarou

Quando ele varia, o problema é descrição vaga ou fronteira sobreposta, e isso você conserta escrevendo

Próximo passo sugerido: escreva a sua primeira rubrica Choice com a lista completa de rótulos e a opção de escape, junte 10 casos de fronteira e meça a repetição do rótulo antes de ligar isso no fluxo automático

Só depois que o número te agradar você liga o limiar no código =)

Até o próximo post!