Documente regras de negócio para apps de IA em linguagem simples

Por que regras vagas criam apps pouco confiáveis

Regras de negócio dizem a um app o que fazer em situações reais. Elas respondem a perguntas como quem pode aprovar uma solicitação, como um total é calculado e o que acontece quando um caso foge do padrão.

Se essas regras são vagas, o app ainda precisa escolher um caminho. Só que pode não ser o caminho que você esperava.

Pense numa regra como "despesas grandes precisam de aprovação do gerente." Uma pessoa pode achar que parece clara. Um construtor não. O que conta como grande: $500, $5.000 ou qualquer valor acima do orçamento da equipe? Qual gerente: o gerente direto, o chefe do departamento ou o financeiro? Se ninguém responde em dois dias, a solicitação espera, expira ou vai para outra pessoa?

É por isso que regras vagas levam a apps pouco confiáveis. O construtor só pode ser tão consistente quanto as instruções que recebe. Quando a redação deixa margem para suposições, o app pode agir de um jeito hoje e de outro amanhã, quando aparece um caso um pouco diferente.

Os maiores problemas normalmente aparecem em algumas áreas:

• cálculos com detalhes faltando, como arredondamento, impostos, descontos ou intervalos de datas
• exceções que todo mundo pressupõe, mas ninguém escreve
• etapas de aprovação sem dono claro, ordem ou plano de contingência

Um exemplo simples mostra o problema. Um fundador cria um app interno de despesas na Koder.ai e escreve: "Reembolsar custos de viagem, a menos que pareçam incomuns." Isso soa razoável, mas o app não tem uma forma confiável de julgar o que é incomum. O táxi de um funcionário é aprovado, o de outro similar é sinalizado, e ninguém sabe por quê.

Comportamento confiável começa com regras que podem ser seguidas da mesma forma todas as vezes. Palavras como "grande", "urgente" e "caso especial" precisam ser trocadas por limites, condições e ações exatas. Se duas pessoas diferentes aplicariam a regra da mesma forma, é muito mais provável que o app faça o mesmo.

Como é uma regra de negócio clara

Uma regra clara cobre uma decisão ou uma ação, não um processo inteiro. Isso importa mais do que a maioria das equipes espera. Quando uma regra tenta cobrir aprovação, precificação, exceções e notificações de uma vez, o construtor tem que adivinhar qual parte é mais importante.

Uma boa regra é fácil de ler em voz alta. Alguém fora da sua equipe deve entendê-la sem precisar do seu jargão interno. Substitua termos como "via rápida", "caso padrão" ou "assinatura do gerente" por linguagem simples que diga exatamente o que acontece.

A maioria das regras claras responde quatro perguntas básicas:

• Quem toma a decisão ou realiza a ação?
• Quando a regra se aplica?
• O que muda no app?
• O que acontece em seguida?

Essa estrutura mantém a regra ligada ao comportamento real. Em vez de escrever "Pedidos grandes precisam de revisão", escreva: "Se um pedido for superior a $5.000, o gerente de vendas deve aprová-lo antes de ser enviado para cumprimento." Uma frase, uma decisão, um resultado.

Também ajuda manter regras relacionadas separadas. A regra de aprovação deve existir sozinha. A regra de envio de e-mail deve ser separada. A regra de bloquear o envio também. Isso torna cada regra mais fácil de testar, atualizar e corrigir.

A diferença é fácil de ver:

"Clientes premium recebem atendimento prioritário" é vago.

"Se o cliente tem um plano premium, a solicitação de suporte é marcada como Alta Prioridade quando o ticket for criado" é claro.

A segunda versão nomeia o gatilho, a condição e a mudança dentro do app. Ela diz ao construtor como o comportamento confiável deve ser.

Se você usa um construtor baseado em chat, esse tipo de redação faz grande diferença. Regras claras não precisam de linguagem jurídica. Precisam de palavras simples, uma ideia por vez e um resultado esperado que caiba numa única frase.

Escrevendo cálculos em linguagem simples

Cálculos costumam parecer simples até alguém tentar construí-los. A abordagem mais segura é começar com uma frase simples que diga exatamente o que o app deve fazer.

Uma boa regra soa assim: "O valor do reembolso é igual às milhas aprovadas multiplicadas pela taxa por milha." Isso é muito mais claro do que "calcular pagamento de viagem" ou "aplicar reembolso padrão."

Depois dessa primeira frase, defina cada entrada que o app deve usar. Seja específico o suficiente para que o construtor não tenha que adivinhar.

O que definir para cada cálculo

Para cada cálculo, especifique:

• as entradas, com nomes simples e unidades
• de onde vem cada valor
• regras de arredondamento
• qualquer valor mínimo ou máximo
• o que acontece se um valor estiver faltando

Pequenos detalhes importam. "Arredonde o valor final para 2 casas decimais" dá um resultado diferente de arredondar cada item da linha primeiro. Se há um teto, diga se o app deve limitar ao teto ou apenas mostrar um aviso.

Uma regra escrita em linguagem simples pode ficar assim: "O reembolso de viagem é igual a milhas aprovadas x $0,67. Arredonde o valor final para 2 casas decimais. O reembolso máximo é $300 por viagem. Se milhas aprovadas estiver em branco, não calcule o valor. Marque a solicitação como incompleta e peça ao usuário para inserir as milhas."

Depois adicione um ou dois exemplos com números reais. Exemplos expõem lacunas mais rápido do que fórmulas abstratas.

Example 1: "If approved miles is 120, reimbursement is 120 x $0.67 = $80.40. Because this is below the $300 cap, the final amount is $80.40."

Example 2: "If approved miles is 500, reimbursement is 500 x $0.67 = $335.00. Because the maximum is $300, the final amount is $300.00."

Esse estilo é mais fácil de revisar para pessoas e mais fácil para um construtor transformar em comportamento do app.

Capturando exceções sem confusão

A maioria dos apps não falha no caminho principal. Falham nos casos de borda.

O caminho normal pode ser simples, mas o trabalho real inclui reembolsos após prazo, clientes VIP, documentos faltantes e aprovações pontuais. Se as exceções são omitidas, o app preenche a lacuna por conta própria, e é aí que começam os resultados inconsistentes.

Uma forma simples de escrever exceções é usar regras curtas do tipo if-then. Mantenha cada uma focada em uma condição e um resultado.

• Se a despesa for inferior a $100, então aprovar automaticamente.
• Se a despesa for inferior a $100 mas for submetida após 30 dias, então enviar para revisão manual.
• Se o funcionário faz parte da equipe executiva, então ignorar o limite de $100 e direcionar para o financeiro.
• Se um admin financeiro marcar a reivindicação como urgente, então aplicar override manual e mover a reivindicação para o topo da fila.

Esse formato torna a lógica oculta visível. Também ajuda a detectar sobreposições antes que virem bugs.

Igualmente importante, diga qual regra vence quando duas conflitam. Um cliente pode se qualificar para um desconto, mas o pedido pode estar em um período de blackout de feriado. Escreva a prioridade em linguagem simples: "Se uma regra de blackout de feriado conflitar com uma regra de desconto ao cliente, a regra de blackout prevalece."

Seja exato sobre limites. Datas, tipos de usuário, localizações, status de conta e overrides manuais frequentemente mudam o resultado. Em vez de escrever "submissões tardias precisam de aprovação", escreva "Se uma solicitação for submetida mais de 14 dias corridos após o evento, então a aprovação do gerente é necessária."

Diga também o que o app deve mostrar ao usuário em cada exceção. Uma boa regra não para na decisão. Define também a mensagem, como "Submetido após 14 dias. Aprovação do gerente necessária" ou "Override manual aplicado pelo admin financeiro."

Quando exceções são escritas desse jeito, casos incomuns deixam de parecer incomuns. Tornam-se comportamento normal e testável.

Descrevendo a lógica de aprovação passo a passo

A lógica de aprovação funciona melhor quando é escrita como uma sequência de decisões, não como uma política vaga. Cada passo deve responder cinco perguntas: quem age, o que desencadeia a revisão, quais limites se aplicam, quanto tempo eles têm e qual status a solicitação recebe após a decisão.

Comece nomeando o cargo, não apenas a equipe. Em vez de escrever "o financeiro revisa solicitações grandes", escreva "o Gerente Financeiro pode aprovar, rejeitar ou devolver qualquer solicitação acima de $5.000." Isso elimina ambiguidade e facilita a construção.

Depois defina o gatilho para cada etapa. Um gatilho é a condição que envia a solicitação para a próxima pessoa. Pode ser baseado em valor, departamento, nível de risco, tipo de solicitação ou uma combinação.

Por exemplo:

• Se a solicitação for inferior a $500, o líder de equipe a revisa.
• Se a solicitação for de $500 a $5.000, o gerente do departamento a revisa após aprovação do líder de equipe.
• Se a solicitação for acima de $5.000, o financeiro a revisa após aprovação do gerente do departamento.
• Se a solicitação for marcada como alto risco, o compliance deve revisar antes da aprovação final.

Os limites precisam de fronteiras exatas. Não diga "grande" ou "sensível." Diga "acima de $5.000", "do departamento de Vendas" ou "pontuação de risco 8 ou mais." Se dois limites puderem se aplicar ao mesmo tempo, diga qual vence. Por exemplo: "Alto risco sempre vai para compliance, mesmo que o valor seja baixo."

Você também precisa de uma regra de timeout. Se ninguém responder, o app não deve ficar em limbo para sempre. Diga o que acontece após um tempo definido, como 48 horas ou 3 dias úteis. A solicitação pode ser escalada para o gerente do aprovador, reatribuída a um aprovador reserva ou automaticamente cancelada.

Por fim, defina o status após cada decisão. Mantenha os rótulos curtos e consistentes:

• Aprovado: a solicitação avança ou é concluída.
• Rejeitado: a solicitação é encerrada e nenhuma ação adicional é tomada.
• Devolvido: o solicitante deve editar e reenviar.
• Escalado: a solicitação vai para um aprovador reserva ou superior.

Quando a lógica de aprovação é escrita assim, o construtor tem menos espaço para adivinhar e o fluxo se torna muito mais confiável.

Um modelo simples de regra que você pode reaproveitar

Se você quer comportamento consistente, dê a cada regra a mesma forma. Estilos de escrita mistos costumam criar resultados mistos.

Um formato simples funciona bem na maioria dos casos: gatilho, condições, ação, resultado. É curto o suficiente para escrever rápido e claro o bastante para outra pessoa revisar depois.

Use uma regra, uma unidade

Mantenha cada regra em sua própria linha, cartão ou bloco. Não junte várias ideias num parágrafo. Se uma regra cobre preço, aprovação e uma exceção ao mesmo tempo, fica difícil testar e fácil de interpretar errado.

Um modelo prático fica assim:

Trigger: When [event happens]
Conditions: If [facts must be true]
Action: Then [the app does this]
Result: So [expected outcome]
Assumption: [anything not yet confirmed]
Example: [short sample input and output]

Você não precisa de todos os campos sempre. Mas manter a mesma ordem ajuda as pessoas a escanear as regras rapidamente.

Por exemplo:

Trigger: When an employee submits an expense claim
Conditions: If the total is over $500 and no receipt is attached
Action: Then send the claim back for correction
Result: So incomplete claims are not forwarded to a manager
Assumption: Receipt is required for all claims above $500
Example: A $620 taxi claim without a receipt is returned to the employee

Observe que o exemplo fica abaixo da regra, não dentro dela. Isso mantém a regra limpa. O exemplo apenas demonstra como a regra deve se comportar.

Marque suposições claramente em vez de escondê‑las na frase. Uma nota pequena como "Suposição" ou "Precisa de confirmação" torna perguntas em aberto fáceis de revisar antes do momento da construção.

Também ajuda manter sua redação consistente. Sempre comece gatilhos com "When", condições com "If" e ações com "Then." Pequenos padrões assim reduzem confusão, especialmente quando as regras estão sendo transformadas em lógica do app.

Um teste rápido funciona bem aqui: alguém consegue testar essa regra e alguém pode interpretá‑la mal? Se a resposta para o primeiro for não, ou para o segundo for sim, aperte a redação.

Exemplo: um app de aprovação de despesas

Um app de despesas de funcionários é um bom caso de teste porque a política é familiar e os casos de borda aparecem rápido. A equipe pode reclamar refeições, táxis, hotéis e pequenos custos com clientes, mas cada reivindicação tem limites, exceções e etapas de aprovação. É exatamente o tipo de processo onde linguagem simples importa.

Política de exemplo

Escreva a regra de refeições assim: funcionários podem reclamar até $40 por dia para refeições em dias normais de trabalho. O app deve somar todos os recibos de refeição na mesma data e comparar esse total com o limite diário, não cada recibo isoladamente.

Se o funcionário gastar $12 no café da manhã e $22 no almoço na terça, o total é $34, então a reivindicação passa. Se adicionar um jantar de $15 no mesmo dia, o total vira $49, então o app deve sinalizar a reivindicação como acima do limite.

Agora adicione uma exceção. Se a refeição aconteceu durante viagem de negócios aprovada ou reunião com cliente, o limite diário para refeições aumenta para $75. Essa exceção só se aplica quando o funcionário seleciona Viagem = Sim ou Reunião com cliente = Sim e adiciona uma nota curta com o nome do cliente ou o propósito da viagem.

Isso é mais confiável do que redações vagas como "casos especiais podem ser permitidos" porque a exceção está vinculada a condições claras.

Etapas de aprovação

A lógica de aprovação pode permanecer igualmente simples:

• Solicitações abaixo de $100 são aprovadas pelo gerente do funcionário.
• Solicitações de $100 a $500 precisam de aprovação do gerente e depois do financeiro.
• Solicitações acima de $500 precisam de aprovação do gerente, do financeiro e do chefe do departamento.
• Qualquer solicitação marcada como "viagem" também precisa de revisão do financeiro, mesmo que o valor esteja abaixo de $100.

Você pode testar a regra com alguns casos simples. Uma reivindicação de refeição de $36 num dia normal deve ser aprovada se os recibos estiverem anexados. Uma reivindicação de $60 num dia de viagem deve passar se viagem estiver marcada e a nota preenchida. Uma reivindicação de $60 num dia normal deve ser rejeitada ou devolvida para correção. Uma reivindicação de hotel de $650 deve passar por todas as três etapas de aprovação.

Esse é o objetivo: a regra deve produzir o mesmo resultado toda vez que alguém testá‑la com casos reais.

Erros comuns que levam a resultados ruins

Uma regra pode soar clara para uma pessoa e ainda confundir um construtor. Isso geralmente acontece quando o documento é vago, reúne várias ideias ou é inconsistente de uma linha para outra.

Um erro comum é amontoar várias regras em um parágrafo longo. Por exemplo: "Gerentes aprovam viagens a menos que o total seja alto, o financeiro verifica recibos e solicitações urgentes podem pular a revisão." Isso pode parecer eficiente, mas esconde várias decisões separadas. Separe em regras distintas para que cada ação tenha um gatilho e um resultado.

Outro problema é linguagem imprecisa. Palavras como normal, grande, urgente ou recente só funcionam se estiverem definidas. Se "despesa grande" significa qualquer valor acima de $2.000, diga isso. Se "urgente" significa necessário em 24 horas, escreva essa condição exata.

Dados faltantes são outra grande fonte de resultados ruins. Equipes costumam descrever o caminho feliz e esquecer de dizer o que fazer quando a informação está incompleta ou errada. Se uma solicitação não tem valor, departamento ou recibo, a regra deve dizer o que acontece em seguida.

Os erros que mais causam problemas geralmente são:

• combinar múltiplas regras num único parágrafo
• usar termos indefinidos para tamanho, tempo ou prioridade
• esquecer casos de erro e campos faltantes
• deixar a autoridade final de aprovação ambígua
• mudar nomes para a mesma coisa no meio do documento

A autoridade final importa mais do que muitas equipes imaginam. Se um gerente e um revisor financeiro discordam, quem toma a decisão final? Se ninguém é dono do passo final, o app pode travar ou enviar trabalho em círculos.

Mudanças de termos criam erros silenciosos. Se você começa com "solicitação" e depois chama de "submissão" ou "ticket", os leitores podem presumir que são itens diferentes. Escolha um termo e mantenha ao longo do documento.

Isso importa ainda mais em um construtor baseado em chat, onde linguagem simples impulsiona o comportamento. Regras claras não precisam soar formais. Precisam ser específicas, consistentes e completas.

Lista rápida de verificação antes de construir

Antes de transformar requisitos em telas, fluxos ou prompts, faça uma última revisão. Uma checagem curta agora pode poupar horas corrigindo comportamentos estranhos depois.

Torne cada regra testável. Cada regra deve terminar com um resultado claro como sim ou não, aprovar ou rejeitar, aplicar taxa ou não aplicar taxa. Se duas pessoas puderem ler a mesma frase e dar respostas diferentes, a regra precisa ser aperfeiçoada.

Descreva cada cálculo. Nomeie as entradas, a fórmula e quando o cálculo ocorre. Adicione arredondamento, moeda, tratamento de datas e o que ocorre se um valor estiver faltando ou for zero.

Mantenha exceções separadas. Escreva a regra padrão primeiro e depois adicione exceções à parte. O limite principal de gasto não deve ficar escondido dentro de um caso especial para contratados, compras urgentes ou viagens pré‑aprovadas.

Mapeie todo o caminho de aprovação. Para cada limite, declare quem aprova e o que acontece em seguida. Seja exato também nas bordas: diga se uma regra começa acima de $500 ou em $500 e acima.

Depois faça o teste do novo colega. Dê a regra a alguém que não trabalhou nela e peça que a explique com as próprias palavras. Se precisar de contexto extra, a regra ainda é vaga.

Um exemplo pequeno mostra por que isso importa. "Gerente aprova despesas grandes" parece claro até alguém perguntar se $500 conta como grande. "Gerente aprova despesas acima de $500. Diretor aprova despesas acima de $2.000. Despesas de $500 ou menos são aprovadas automaticamente" deixa muito menos margem para erro.

Transformando regras em um app funcional

Uma vez que as regras estão claras, reveja‑as com as pessoas que usam o processo todo dia. Gerentes, coordenadores, equipe financeira e aprovadores costumam perceber detalhes pequenos que nunca entram no documento de política. Esses detalhes costumam ser o que faz um app ser fluido ou frustrante.

Trate o documento de regras como instruções de trabalho, não como um rascunho descartável. Ele deve explicar o que acontece, quem decide, quais são as exceções e o que o app faz quando faltar informação.

Antes de construir o app completo, teste alguns cenários reais do trabalho recente. Use casos limpos e casos bagunçados: uma solicitação padrão que deve passar, uma sem informação, uma exceção que precisa de revisão manual e um caso que ultrapassa um limite de gasto ou aprovação.

Essa etapa detecta lacunas cedo. Uma regra pode soar clara no papel, mas falhar quando uma solicitação real não se encaixa no padrão esperado.

Quando esses cenários funcionarem, leve‑os para seu construtor. Se você usa uma plataforma baseada em chat como a Koder.ai, um conjunto de regras claro torna a construção muito mais rápida porque você está traduzindo um processo definido em telas, ações e aprovações em vez de tomar decisões na hora.

Após o lançamento, mantenha o documento como fonte da verdade. Quando uma política muda, um novo aprovador é adicionado ou um limite é atualizado, altere primeiro o documento e depois o app. Isso mantém edições futuras mais simples e reduz a chance de pessoas lembrarem a regra de maneiras diferentes.

Um pequeno hábito ajuda aqui: revise as regras sempre que o processo mudar, não apenas quando o app quebrar. Pequenas atualizações feitas cedo são muito mais fáceis do que consertar comportamento confuso depois.

Se o documento se mantiver atualizado, o app fica mais fácil de testar, melhorar e confiar com o tempo.