Arquiteto de sistema Jev

Arquiteto de Sistemas Jev

Propósito

Use esta skill para determinar:

1. Se o Jev deve fazer parte de um sistema
2. Exatamente onde o limite do Jev deve ficar
3. Quais julgamentos devem se tornar perguntas Choice, Score ou Noul
4. Qual estado cada julgamento deve ver
5. Quais perguntas devem ser executadas juntas
6. Como o código comum deve compor os resultados
7. Como a incerteza deve alterar o comportamento do sistema
8. Como a integração deve ser avaliada antes do uso em produção

Esta é principalmente uma skill de arquitetura e decomposição.

Para sintaxe exata do SDK, campos de requisição/resposta, modelos, limites ou comportamento específico de versão da API, leia a documentação atual do TypeSafe e, quando disponível, use a skill de agente oficial do TypeSafe.

Não invente campos de API.

---

Modelo Mental Central

Jev não é a aplicação.

Jev não é o mecanismo de fluxo de trabalho.

Jev não é um agente autônomo.

A arquitetura preferida é:

ESTADO DA APLICAÇÃO
      ↓
perguntas semânticas limitadas
      ↓
     JEV
      ↓
julgamentos tipados + probabilidades
      ↓
CÓDIGO DETERMINÍSTICO DA APLICAÇÃO
      ↓
rotear / classificar / verificar / perguntar / escalar / executar

O modelo fornece julgamento programável.

O código possui:

• fluxo de controle
• permissões
• cálculos
• regras determinísticas
• persistência
• transações
• efeitos colaterais
• execução de ferramentas
• autorização
• imposição de políticas

Use Jev somente onde o software comum precisa de compreensão semântica de informações não estruturadas ou ambíguas.

---

Condições de Acionamento

Considere Jev quando o sistema contiver um limite com a seguinte forma:

informação não estruturada ou contextual
                ↓
     um julgamento limitado é necessário
                ↓
 o software precisa de um valor tipado para continuar

Fortes candidatos incluem:

• classificação de intenção
• roteamento semântico
• decisões de moderação
• classificação de documentos
• verificação de evidências
• verificação de citações
• barreiras de segurança semânticas
• sinais de risco
• interpretação de mensagens
• seleção de candidatos
• dimensões de classificação
• julgamentos de relevância
• sentimento ou urgência
• interpretação de solicitações do usuário
• seleção de ferramentas/funções
• extração de um conjunto conhecido de candidatos
• filtragem de passagens RAG
• triagem de fluxo de trabalho
• julgamentos de qualidade
• comparação política-para-caso
• correspondência aproximada
• alinhamento de entidades
• decisões de escalonamento

Inspecione também o código em busca de sintomas como:

LLM → prosa → analisador → JSON → validação → nova tentativa

ou:

árvore de regex grande
classificador if/else semântico enorme
classificador baseado em prompt retornando JSON arbitrário
loop de agente usado apenas para tomar uma decisão limitada
modelo de raciocínio caro usado para uma classificação trivial

Esses são pontos potenciais de inserção do Jev.

---

Não Use Jev Por Padrão

Prefira código comum para:

• aritmética
• datas exatas já representadas estruturalmente
• consultas a banco de dados
• correspondências exatas de string
• permissões
• autorização
• validação de esquema
• regras de negócio determinísticas
• transformações conhecidas
• ordenação de números conhecidos
• operações criptográficas
• analisadores exatos que já resolvem o problema de forma confiável

Prefira um modelo generativo quando a saída necessária for fundamentalmente aberta:

• escrita
• sumarização
• explicação
• brainstorming
• geração de código
• síntese de formato longo
• pesquisa aberta
• raciocínio de múltiplas etapas

Jev pode apoiar esses sistemas tomando decisões limitadas ao redor deles, mas não deve ser forçado a um papel generativo.

---

Etapa 1 — Encontre os Limites dos Julgamentos

Inspecione o fluxo de trabalho da entrada ao resultado.

Marque cada ponto onde o software efetivamente pergunta:

"Eu tenho informações, mas preciso entender o que elas significam antes de saber qual caminho determinístico seguir."

Para cada limite candidato, escreva:

ESTADO DE ENTRADA: Que informações existem?

JULGAMENTO: Que determinação semântica é necessária?

SAÍDA: Qual valor limitado permitiria ao código continuar?

AÇÃO: O que o código fará com a resposta?

IMPLICAÇÕES: O que acontece se o julgamento estiver errado?

Não implemente Jev imediatamente.

Primeiro determine se o código determinístico pode resolver o problema de forma mais confiável.

---

Etapa 2 — Aplique o Teste de Adequação ao Jev

Um julgamento é um forte candidato a Jev quando a maioria destas condições for verdadeira:

• A entrada contém linguagem natural ou dados contextuais.
• A saída necessária pode ser limitada.
• O software precisa da resposta programaticamente.
• Um humano conhecedor poderia fazer o julgamento rapidamente.
• O julgamento pode ser descrito explicitamente.
• A incerteza é informação útil.
• O resultado pode ser testado contra exemplos ou rótulos.
• O código pode ser dono da ação após o julgamento.

Seja cético quando a tarefa exigir:

• deliberação profunda
• longas cadeias de raciocínio
• muitas conclusões intermediárias dependentes
• geração aberta
• planejamento autônomo

Decomponha primeiro.

---

Etapa 3 — Torne as Perguntas Atômicas

Uma pergunta Jev deve representar um julgamento coerente.

RUIM:

Analise este cliente e determine se devemos reembolsá-lo, o quão irritado ele está, se há probabilidade de fraude e qual departamento deve lidar com o caso.

MELHOR:

• tópico → Choice
• reembolso_solicitado → Noul
• sinal_fraude → Noul
• frustração → Score

Depois componha essas respostas em código.

O objetivo é:

comportamento complexo = muitos pequenos julgamentos + composição determinística

Não esconda a política da aplicação dentro de uma pergunta semântica gigante quando o código poderia expressar essa política explicitamente.

---

Etapa 4 — Selecione o Primitivo Correto

Choice

Use quando exatamente uma resposta deve ser selecionada de um conjunto definido.

Forma: Qual?

Exemplos:

• cobrança | técnico | vendas | conta
• reembolso | reagendamento | informação
• python | javascript | rust | outro

Adicione um resultado "outro", "desconhecido" ou "nenhum" quando as opções fornecidas podem não cobrir a entrada.

Noul

Use para uma proposição cuja probabilidade de ser verdadeira é útil.

Forma: Isso é verdade?

Exemplos:

• O cliente solicita um reembolso?
• Esta passagem responde à pergunta do usuário?
• Esta mensagem solicita uma credencial?
• O currículo declara experiência profissional em Python?

Interprete a saída como a probabilidade de sim.

Não interprete ~0.5 como "intensidade média".

Significa que sim/não são aproximadamente igualmente plausíveis.

Score

Use quando o julgamento existe em uma dimensão ordenada.

Forma: Onde neste espectro definido o estado se enquadra?

Exemplos:

• calmo / preocupado / muito frustrado
• irrelevante / parcialmente relevante / fortemente relevante / resposta direta

Cada nível deve descrever uma condição semântica concreta.

Evite rótulos indefinidos como ruim / ok / bom / ótimo, a menos que seu significado seja explicitamente definido.

---

Etapa 5 — Projete o Estado Deliberadamente

Envie o menor estado que contenha as evidências necessárias para as perguntas.

Prefira estado estruturado:

{
  "ticket": {
    "mensagem": "...",
    "remetente": {}
  },
  "cliente": {
    "plano": "...",
    "pedidos": []
  },
  "politica": {
    "politica_reembolso": "..."
  }
}

em vez de um grande bloco de prosa.

Princípios:

• relevante > abrangente
• estruturado > achatado
• fatos observados > conhecimento de modelo assumido
• informação atual > conhecimento integrado desatualizado

Mantenha fatos observados distinguíveis de julgamentos inferidos.

Quando as perguntas se referirem a campos de estado específicos, aponte explicitamente para esses campos.

---

Etapa 6 — Distribua Perguntas Independentes

Se várias perguntas podem ser respondidas a partir do mesmo estado existente, prefira fazê-las juntas.

                    ┌── tópico
                    ├── urgência
ESTADO ── JEV ───────┼── reembolso_solicitado
                    ├── frustração
                    └── sinal_fraude

Não crie chamadas seriais desnecessárias como:

Jev → resposta → Jev → resposta → Jev → resposta

quando todas as três perguntas poderiam ter sido avaliadas a partir do estado original.

Faça perguntas especulativas quando forem baratas e puderem ser úteis mais tarde.

Exemplo: categoria, gravidade_bug, qualidade_reproducao, reembolso_solicitado, frustração

Se categoria = cobrança, o código simplesmente ignora as respostas específicas do bug.

---

Etapa 7 — Use Múltiplos Estágios Jev Apenas para Dependências Reais

Uma segunda requisição Jev é justificada quando a primeira resposta é necessária para:

• buscar novas evidências
• construir novo estado
• escolher o próximo conjunto de candidatos
• determinar quais perguntas podem ser feitas de forma significativa
• percorrer uma hierarquia
• recuperar documentos necessários para o próximo julgamento

Exemplo:

ETAPA 1  Qual família de produtos?
   ↓
código recupera produtos dessa família
   ↓
ETAPA 2  Qual produto exato corresponde melhor?

Não serialize perguntas meramente porque o fluxo de trabalho contém conceitualmente várias etapas.

---

Etapa 8 — Mantenha a Composição no Código

Jev produz sinais semânticos.

O código decide o que esses sinais significam operacionalmente.

Exemplo:

tópico = cobrança
reembolso_solicitado = 0.94
frustração = alto

O código da aplicação pode decidir:

se tópico == cobrança:
    rotear_para_cobranca()

se reembolso_solicitado > LIMIAR_SINAL_REEMBOLSO:
    adicionar_sinal_reembolso()

se frustração > LIMIAR_PRIORIDADE:
    aumentar_prioridade()

A lógica de negócio deve permanecer inspecionável.

Não pergunte ao Jev "O que nossa aplicação inteira deve fazer?" quando a resposta pode ser construída a partir de julgamentos menores.

---

Etapa 9 — Trate a Incerteza como um Sinal de Primeira Classe

Nunca trate a saída tipada como equivalente à verdade.

Saída tipada significa que a interface é restrita.

Não significa que o julgamento semântico não pode estar errado.

Para Choice e Score, inspecione probabilidades e confiança.

Para Noul, inspecione diretamente a probabilidade de sim.

Projete comportamento como:

• ALTA CERTEZA → caminho automático
• CERTEZA MÉDIA → peça confirmação / reúna mais evidências / modelo mais forte / sinalize para revisão
• BAIXA CERTEZA → não adivinhe / escale

Limiares são política da aplicação.

Eles devem refletir o custo de falsos positivos/negativos, reversibilidade, impacto no usuário/financeiro/segurança/regulatório.

Um limiar copiado de um exemplo não é evidência de que seja apropriado para este sistema.

---

Etapa 10 — Corresponda Portões de Confiança ao Risco

Não use um limiar de confiança universal.

Exemplo:

• mostrar_artigo_ajuda — baixa consequência
• rotear_ticket_suporte — consequência moderada
• cancelar_assinatura — consequência maior
• mover_dinheiro — consequência muito alta

O julgamento semântico pode ser idêntico enquanto a certeza necessária e o caminho de confirmação diferem.

Para ações consequentes, Jev deve geralmente informar um limite de decisão controlado em vez de autorizar independentemente o efeito colateral.

---

Etapa 11 — Projete a Avaliação Antes da Automação

Antes de colocar em produção um limite Jev, identifique casos representativos.

Inclua: positivos fáceis, negativos fáceis, casos ambíguos, casos sem evidências, casos de borda, casos adversariais, falhas raras, mas custosas.

Registre: estado, pergunta, comportamento esperado, resposta Jev, probabilidades/confiança, ação da aplicação, resultado real quando disponível.

Avalie o comportamento do sistema, não meramente se o rótulo principal parecia razoável.

Para sistemas com limiares, meça o comportamento em vários limiares.

Meça especialmente: cobertura / taxa de automação, taxa de falsos positivos, taxa de falsos negativos, taxa de revisão humana, custo de erros, latência, custo.

Ajuste limiares usando dados reais do domínio alvo.

---

Etapa 12 — Centralize a Política Jev

Mantenha perguntas Jev, critérios, pesos e constantes de limiar fáceis de encontrar e revisar.

Prefira uma estrutura como:

ai/
  jev/
    perguntas.*
    limiares.*
    avaliacao/
    cliente.*

ou a estrutura equivalente apropriada para o projeto.

Não espalhe política semântica por dezenas de manipuladores de rota.

Revisores humanos devem poder inspecionar:

• O que o Jev está julgando?
• Que definições demos a ele?
• Que limiares causam ações?
• Quais ações são reversíveis?
• O que acontece quando a confiança é baixa?

---

Etapa 13 — Preserve Julgamentos Brutos

Quando prático, mantenha as saídas úteis brutas separadas da ação derivada delas.

Por exemplo:

probabilidade_reembolso = 0.91
pontuacao_frustracao = 1.72
tópico = cobrança
confianca_topico = 0.88

em vez de armazenar apenas prioridade = alto.

Isso permite reavaliar limiares, alterar pesos, auditar comportamento, comparar versões de modelo, investigar falhas e análises downstream.

Não retenha dados sensíveis além dos requisitos legítimos da aplicação.

---

Etapa 14 — Procure Jev ao Redor de IA Generativa

Jev é frequentemente valioso ao redor de um LLM, em vez de substituí-lo.

Exemplos:

ENTRADA → barreira Jev → LLM → verificação de citação/qualidade Jev → código decide se retorna

ou:

consulta → recuperação → julgamentos de relevância/injeção Jev → contexto selecionado → modelo de raciocínio

ou:

solicitação do usuário → seleção de intenção/função Jev → função tipada determinística → resultado

Isso pode reduzir a quantidade de controle da aplicação confiada a um modelo generativo aberto.

---

Procedimento de Revisão de Arquitetura

Quando solicitado a revisar um sistema existente em busca de oportunidades Jev:

1. Mapeie o fluxo de trabalho

Identifique: entradas, etapas determinísticas, decisões semânticas, chamadas de modelo, analisadores, roteadores, chamadas de ferramentas, efeitos colaterais, pontos de revisão humana.

2. Produza um mapa de oportunidades Jev

Para cada candidato:

• LOCALIZAÇÃO: Código/módulo/fluxo de trabalho atual
• MÉTODO ATUAL: Como o julgamento é feito hoje
• CANDIDATO JEV: Sim / Não / Talvez
• PORQUÊ: Por que uma decisão semântica limitada é ou não apropriada
• ESTADO: Evidência mínima necessária
• PRIMITIVO: Choice / Score / Noul
• PERGUNTAS: Julgamentos atômicos propostos
• COMPOSIÇÃO: Como o código deve usá-los
• INCERTEZA: O que acontece quando a resposta não é clara
• RISCO: Consequência de um julgamento errado
• AVALIAÇÃO: Como validá-lo

3. Priorize por alavancagem

Prefira oportunidades onde Jev poderia substituir código semântico frágil, análise repetida de LLM, chamadas de raciocínio trivial caras, loops de agente ilimitados, classificadores duplicados ou revisão manual de casos óbvios — mantendo o comportamento do sistema limitado e testável.

4. Recomende a menor versão v

…