As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Melhores práticas da política de raciocínio automatizado Esta página consolida as melhores práticas para criar e manter políticas de raciocínio automatizado. Leia isso antes de criar sua primeira política e consulte-a ao depurar problemas. Para obter os fundamentos conceituais por trás dessas práticas, consulte[O raciocínio automatizado verifica conceitos](automated-reasoning-checks-concepts.md). Para obter instruções de step-by-step criação, consulte[Criar uma política de raciocínio automatizado](create-automated-reasoning-policy.md). ## Comece de forma simples e repita O erro mais comum ao criar uma política de raciocínio automatizado é tentar capturar um documento complexo inteiro em uma única passagem. Em vez disso, comece com um subconjunto focado de suas regras e construa de forma incremental. 1. Escolha uma seção única e bem definida do seu documento fonte (por exemplo, elegibilidade para licença parental em um manual de RH). 1. Crie uma política a partir dessa seção e revise as regras e variáveis extraídas. 1. Escreva testes que cubram os principais cenários dessa seção. 1. Corrija qualquer problema antes de adicionar mais conteúdo. 1. Use a criação de políticas iterativas para mesclar seções adicionais, uma por vez. Para obter mais informações, consulte [Construção de políticas iterativas](create-automated-reasoning-policy.md#iterative-policy-building). Essa abordagem tem duas vantagens: facilita o isolamento dos problemas (você sabe qual seção introduziu um problema) e mantém a política gerenciável durante o desenvolvimento. Uma política com 10 regras bem testadas é mais útil do que uma com 100 regras não testadas. ## Pré-processe documentos com um LLM Para documentos que são longos, contêm prosa narrativa ou combinam regras com conteúdo não normativo (como avisos legais ou histórico organizacional), execute o documento por meio de um LLM antes de enviá-lo para verificações de raciocínio automatizado. Peça ao LLM que extraia o conteúdo como regras explícitas do tipo “se então”. Essa etapa de pré-processamento melhora significativamente a qualidade da política extraída porque as verificações de raciocínio automatizado funcionam melhor com declarações claras e declarativas do que com texto não estruturado. Ao escrever sua solicitação de pré-processamento, inclua as seguintes instruções para o LLM: + Extraia regras no formato if-then com condições e consequências claras. + Preserve todas as condições, operadores lógicos (AND, OR, NOT), quantificadores (“pelo menos”, “no máximo”) e cláusulas de exceção (“a menos que”, “exceto quando”). + Adicione regras de sanidade para restrições de bom senso, como “o saldo da conta não pode ser negativo” ou “a pontuação de crédito deve estar entre 300 e 850", que se traduzem em regras de limite em sua política (consulte). [Validar intervalos para valores numéricos](#bp-validate-ranges) **Importante** Sempre analise a saída do LLM em relação ao documento original antes de usá-lo como texto fonte. LLMs pode alucinar regras não presentes na fonte, interpretar mal as condições ou descartar exceções importantes. A etapa de pré-processamento é um ponto de partida — não um substituto para a revisão humana. Para obter modelos de solicitação detalhados e um fluxo step-by-step de trabalho de pré-processamento, consulte[(Opcional) Use um LLM para reescrever documentos como regras lógicas](create-automated-reasoning-policy.md#preprocess-with-llm). ## Use implicações (=>) para estruturar regras O formato if-then (usando o operador de `=>` implicação) é o padrão de redação de regras mais importante. Toda regra que expressa uma relação condicional deve usar esse formato. | Bom: Implicação | Ruim: afirmação pura | | --- | --- | | (=> (and isFullTime (> tenureMonths 12)) eligibleForParentalLeave) | eligibleForParentalLeave | | (=> (> loanAmount 500000) requiresCosigner) | requiresCosigner | Afirmações simples (regras sem uma estrutura if-then) criam axiomas — afirmações que são sempre verdadeiras. A afirmação `eligibleForParentalLeave` diz que o Automated Reasoning verifica se a elegibilidade da licença parental é sempre verdadeira, independentemente de quaisquer condições. Qualquer entrada que diga que o usuário *não* é elegível retornaria `IMPOSSIBLE` porque contradiz esse axioma. As afirmações simples são apropriadas somente para condições de limite que sempre devem ser válidas, como: ``` ;; Account balance can never be negative (>= accountBalance 0) ;; Interest rate is always between 0 and 1 (and (>= interestRate 0) (<= interestRate 1)) ``` Se você encontrar afirmações vazias na política extraída, reescreva-as como condicionais ou exclua-as. Para obter mais informações sobre como revisar sua política extraída, consulte. [Revise a política extraída](create-automated-reasoning-policy.md#review-extracted-policy) ## Escreva descrições abrangentes de variáveis As descrições das variáveis são o principal fator na precisão da tradução. Quando as verificações de raciocínio automatizado traduzem a linguagem natural em lógica formal, elas usam descrições de variáveis para determinar quais variáveis correspondem aos conceitos mencionados no texto. Descrições vagas ou incompletas são a principal causa dos `TRANSLATION_AMBIGUOUS` resultados. Uma boa descrição da variável deve responder a quatro perguntas: 1. **O que essa variável representa?** Explique o conceito em linguagem simples. 1. **Qual unidade ou formato ele usa?** Especifique unidades (meses, dólares, porcentagem como decimal) e quaisquer regras de conversão. 1. **Como os usuários podem se referir a esse conceito?** Inclua sinônimos, frases alternativas e formas comuns pelas quais os usuários expressam esse conceito na linguagem cotidiana. 1. **Quais são as condições de limite?** Descreva casos extremos, valores padrão e o que a variável significa quando definida para valores específicos. **Exemplo: antes e depois** | Vago (causa falhas de tradução) | Detalhado (traduz de forma confiável) | | --- | --- | | tenureMonths: “Há quanto tempo o funcionário trabalha.” | tenureMonths: “O número de meses completos em que o funcionário esteve empregado continuamente. Quando os usuários mencionarem anos de serviço, converta para meses (por exemplo, 2 anos = 24 meses). Defina como 0 para novas contratações que ainda não concluíram o primeiro mês.” | | isFullTime: “Status em tempo integral”. | isFullTime: “Se o funcionário trabalha em período integral (verdadeiro) ou em tempo parcial (falso). Defina como verdadeiro quando os usuários mencionarem ser “em tempo integral”, trabalhar em “horas inteiras” ou trabalhar mais de 40 horas por semana. Defina como false quando os usuários mencionarem ser “em tempo parcial”, trabalhar em “horas reduzidas” ou trabalhar menos de 40 horas por semana.” | | interestRate: “A taxa de juros.” | interestRate: “A taxa de juros anual expressa como um valor decimal, onde 0,05 significa 5% e 0,15 significa 15%. Quando os usuários mencionarem uma porcentagem como '5%', converta para a forma decimal (0,05).” | ## Use booleanos para estados não exclusivos Ao modelar estados que podem coexistir, use variáveis booleanas separadas em vez de uma única enumeração. Uma pessoa pode ser veterana e professora. Usar um enum `customerType = {VETERAN, TEACHER}` força a escolha entre eles, criando uma contradição lógica quando ambos se aplicam. | Bom: booleanos separados | Ruim: Enum para estados não exclusivos | | --- | --- | | `isVeteran`(bool): “Se o cliente é um veterano militar.” `isTeacher`(bool): “Se o cliente é professor.” | `customerType`(enum: VETERANO, PROFESSOR, ESTUDANTE): “O tipo de cliente”. Problema: um cliente que é ao mesmo tempo veterano e professor não pode ser representado. | Reserve enums para categorias verdadeiramente mutuamente exclusivas, nas quais somente um valor pode ser aplicado por vez, como `leaveType = {PARENTAL, MEDICAL, BEREAVEMENT}` (um funcionário só pode solicitar um tipo de licença por vez). Para obter mais informações sobre tipos personalizados, consulte[Tipos personalizados (enums)](automated-reasoning-checks-concepts.md#ar-concept-custom-types). ## Especifique unidades e formatos em descrições de variáveis A ambigüidade sobre as unidades é uma fonte comum de erros de tradução. Se um usuário disser “Trabalho aqui há 2 anos” e sua variável for`tenureMonths`, a tradução precisa saber como converter anos em meses. Se a descrição da variável não especificar a unidade, a tradução poderá atribuir `tenureMonths = 2` em vez de`tenureMonths = 24`. Sempre especifique: + A unidade de medida (meses, dias, dólares, porcentagem). + O formato (decimal versus porcentagem, formato de data, moeda). + Regras de conversão para expressões alternativas comuns (por exemplo, “2 anos = 24 meses”). **Exemplos:** + `loanAmount`: “O valor total do empréstimo em dólares americanos. Quando os usuários mencionarem valores em milhares (por exemplo, '500K'), converta para o número completo (500000).” + `submissionDate`: “O número de dias após a data de vencimento em que o envio foi feito. Um valor de 0 significa que o envio foi feito dentro do prazo. Valores positivos indicam envios tardios.” ## Validar intervalos para valores numéricos Para variáveis numéricas, adicione regras de limite que restrinjam o intervalo válido. Isso evita cenários logicamente impossíveis e ajuda as verificações automatizadas de raciocínio a produzir resultados mais significativos. ``` ;; Account balance cannot be negative (>= accountBalance 0) ;; Interest rate must be between 0 and 1 (0% to 100%) (and (>= interestRate 0) (<= interestRate 1)) ;; Credit score ranges from 300 to 850 (and (>= creditScore 300) (<= creditScore 850)) ;; Tenure in months cannot be negative (>= tenureMonths 0) ``` Sem essas regras de limite, as verificações de raciocínio automatizado podem considerar cenários com saldos de conta negativos ou pontuações de crédito acima de 1000, que não têm sentido em seu domínio. As regras de limite são um dos poucos casos em que afirmações simples (regras que não estão no formato if-then) são apropriadas. ## Use variáveis intermediárias para abstração Quando várias regras compartilham uma condição comum, extraia essa condição em uma variável booleana intermediária. Isso simplifica suas regras e facilita a manutenção da política. **Exemplo: níveis de associação** Em vez de repetir a condição de associação em todas as regras de benefícios: ``` ;; Without intermediate variable (repetitive) (=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForFreeShipping) (=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForPrioritySupport) (=> (and (> purchaseTotal 1000) (> accountAge 12)) eligibleForEarlyAccess) ``` Defina uma variável intermediária e faça referência a ela: ``` ;; With intermediate variable (cleaner) (=> (and (> purchaseTotal 1000) (> accountAge 12)) isPremiumMember) (=> isPremiumMember eligibleForFreeShipping) (=> isPremiumMember eligibleForPrioritySupport) (=> isPremiumMember eligibleForEarlyAccess) ``` Esse padrão facilita a atualização posterior dos critérios de associação — você só precisa alterar uma regra em vez de três. ## Use enums para categorização Quando uma variável representa uma categoria com um conjunto fixo de valores mutuamente exclusivos, use um tipo personalizado (enum) em vez de vários booleanos ou uma string. Os enums restringem os valores possíveis e tornam as regras mais claras. | Bom: Enum | Evite: vários booleanos para estados exclusivos | | --- | --- | | Tipo: `LeaveType = {PARENTAL, MEDICAL, BEREAVEMENT, PERSONAL}` Variável: `leaveType` (LeaveType) Regra: `(=> (= leaveType PARENTAL) (>= leaveDays 60))` | `isParentalLeave` (bool) `isMedicalLeave` (bool) `isBereavementLeave` (bool) Problema: nada impede que vários booleanos sejam verdadeiros simultaneamente. | **dica** Inclua um `NONE` valor `OTHER` ou em sua enumeração se for possível que a entrada não corresponda a nenhuma das categorias definidas. Isso evita problemas de tradução quando a entrada não se encaixa perfeitamente em um dos valores definidos. ## Mantenha a lógica declarativa, não processual As políticas de raciocínio automatizado descrevem *o que é verdade*, não *como computá-la*. Evite escrever regras que pareçam código com etapas sequenciais ou lógica de precedência. | Bom: Declarativo | Evitar: pensamento processual | | --- | --- | | “Se o funcionário trabalha em tempo integral e tem mais de 12 meses de mandato, ele é elegível para licença parental.” Isso afirma um fato sobre a relação entre condições e resultados. | “Primeiro verifique se o funcionário trabalha em tempo integral. Se sim, verifique a estabilidade. Se o mandato for superior a 12 meses, defina a elegibilidade como verdadeira.” Isso descreve um procedimento, não uma relação lógica. | Da mesma forma, evite codificar precedência ou prioridade entre as regras. Na lógica formal, todas as regras se aplicam simultaneamente. Se você precisar expressar que uma condição substitui outra, codifique-a explicitamente nas condições da regra: ``` ;; GOOD: Explicit exception handling ;; General rule: full-time employees with 12+ months get parental leave (=> (and isFullTime (> tenureMonths 12) (not isOnProbation)) eligibleForParentalLeave) ;; BAD: Trying to encode precedence ;; "Rule 1 takes priority over Rule 2" — this concept doesn't exist ;; in formal logic. Instead, combine the conditions into a single rule. ``` ## Convenções de nomenclatura A nomenclatura consistente facilita a leitura, a manutenção e a depuração das políticas. Siga estas convenções: + **Variáveis booleanas:** use o `has` prefixo `is` or. Por exemplo: `isFullTime`, `hasDirectDeposit`, `isEligibleForLeave`. + **Variáveis numéricas:** inclua a unidade no nome. Por exemplo: `tenureMonths`, `loanAmountUSD`, `creditScore`. + **Tipos de enumeração:** use PascalCase para nomes de tipos e UPPER\$1SNAKE\$1CASE para valores. Por exemplo: `LeaveType = {PARENTAL, MEDICAL, BEREAVEMENT}`. + **Variáveis:** Use CamelCase. Por exemplo: `tenureMonths`, `isFullTime`, `leaveType`. Evite abreviações que possam ser ambíguas. Use `tenureMonths` em vez `tenMo` de e `isFullTime` em vez de`ft`. Nomes claros ajudam tanto os revisores humanos quanto o processo de tradução. ## Antipadrões comuns Os padrões a seguir frequentemente causam problemas nas políticas de raciocínio automatizado. Se você encontrar resultados de teste inesperados, verifique se sua política contém algum desses antipadrões. ### Axiomas em vez de implicações Conforme descrito em[Use implicações (=>) para estruturar regras](#bp-use-implications), afirmações simples criam axiomas que são sempre verdadeiros. Esse é o antipadrão mais comum e o mais prejudicial — ele faz com que categorias inteiras de entradas retornem. `IMPOSSIBLE` **Sintoma:** testes que deveriam retornar `VALID` ou `INVALID` retornar `IMPOSSIBLE` em vez disso. **Correção:** encontre afirmações simples em suas regras e reescreva-as como implicações ou exclua-as se elas não representarem condições de limite. ### Variáveis sobrepostas Ter duas variáveis que representam conceitos iguais ou similares (por exemplo, `tenureMonths` e`monthsOfService`) confunde o processo de tradução. As verificações automatizadas de raciocínio não podem determinar qual variável usar para um determinado conceito, levando a traduções e `TRANSLATION_AMBIGUOUS` resultados inconsistentes. **Sintoma:** os testes retornam `TRANSLATION_AMBIGUOUS` mesmo com texto de entrada claro e inequívoco. **Correção:** mescle variáveis sobrepostas em uma única variável com uma descrição abrangente. Atualize todas as regras que fazem referência à variável excluída. ### Políticas excessivamente complexas Políticas com muitas variáveis, condições profundamente aninhadas ou aritmética não linear podem exceder os limites de processamento e retornar resultados. `TOO_COMPLEX` **Sintoma:** os testes retornam `TOO_COMPLEX` ou expiram. **Correção:** simplifique a política. Remova variáveis não utilizadas, divida regras complexas em regras mais simples usando variáveis intermediárias e evite aritmética não linear (expoentes, números irracionais). Se seu domínio for realmente complexo, considere dividi-lo em várias políticas focadas. ### Regras contraditórias Regras que se contradizem impossibilitam que as verificações automatizadas de raciocínio cheguem a uma conclusão. Por exemplo, uma regra diz que funcionários em tempo integral são elegíveis para licença, enquanto outra diz que funcionários no primeiro ano não são elegíveis, sem especificar o que acontece com funcionários em tempo integral no primeiro ano. **Sintoma:** Os testes retornam `IMPOSSIBLE` para entradas que envolvem regras conflitantes. **Correção:** verifique se há regras conflitantes no relatório de qualidade. Resolva conflitos mesclando as regras em uma única regra com condições explícitas ou excluindo uma das regras conflitantes. Para obter mais informações, consulte [Revise a política extraída](create-automated-reasoning-policy.md#review-extracted-policy). ### Variáveis não utilizadas Variáveis que não são referenciadas por nenhuma regra adicionam ruído ao processo de tradução. A tradução pode atribuir valores a variáveis não utilizadas, desperdiçando capacidade de processamento e potencialmente causando `TRANSLATION_AMBIGUOUS` resultados quando a variável não utilizada compete com uma variável ativa similar. **Sintoma:** `TRANSLATION_AMBIGUOUS` resultados inesperados ou traduções que atribuem valores a variáveis que não afetam nenhuma regra. **Correção:** exclua variáveis não utilizadas. No console, procure indicadores de aviso ao lado das variáveis. Por meio da API, verifique o relatório de qualidade em `GetAutomatedReasoningPolicyBuildWorkflowResultAssets` com`--asset-type QUALITY_REPORT`. ### Valores de enumeração ausentes Se sua enumeração não incluir um valor para cada categoria possível que os usuários possam mencionar, a tradução poderá falhar ou produzir resultados inesperados quando a entrada não corresponder a nenhum valor definido. **Sintoma:** Os testes retornam `TRANSLATION_AMBIGUOUS` ou `NO_TRANSLATIONS` quando a entrada menciona uma categoria que não está na enumeração. **Correção:** adicione um `NONE` valor `OTHER` ou à sua enumeração para lidar com entradas que não correspondem às categorias definidas. Atualize as descrições dos valores de enumeração para esclarecer quando cada valor se aplica.