Produto não tem essa pessoa. Produto tem mil execuções por dia, sem ninguém olhando, e uma resposta ruim vira registro no banco, e-mail enviado ou cobrança errada. A distância entre esses dois mundos é onde mora todo o trabalho de engenharia — e é a parte que quase nunca aparece na demo.

Texto livre é dívida técnica

O primeiro erro estrutural é deixar o modelo devolver prosa e depois tentar entender essa prosa com regex. Já vi parser de trinta linhas para extrair um valor monetário de uma frase que o modelo escrevia de quatro jeitos diferentes dependendo do dia.

A saída de um LLM dentro de um sistema precisa ser um contrato, exatamente como qualquer outra integração. Hoje isso se resolve com saída estruturada: você declara o schema, o modelo responde dentro dele, e o que chega no seu código é um objeto validável.

{
  "categoria": "reembolso",
  "urgencia": "alta",
  "valor_centavos": 12990,
  "resumo": "Cliente pede estorno de cobrança duplicada em 12/07.",
  "confianca": 0.82
}

Repare no último campo. confianca não é enfeite: é o que permite rotear. Acima de um limiar, o fluxo segue automático; abaixo, cai numa fila de revisão humana. Sem esse número, você só tem duas opções ruins — confiar em tudo ou revisar tudo.

E, mesmo com schema, valide de novo do seu lado. O schema garante a forma, não o sentido. valor_centavos: 999999999 passa em qualquer validação de tipo e ainda assim é absurdo para o seu domínio.

A chamada é lenta, então trate como sistema externo

Um LLM é uma dependência de rede com latência variável, limite de taxa e indisponibilidade eventual. Ou seja: é exatamente igual a um gateway de pagamento, e merece o mesmo tratamento arquitetural.

Na prática, isso significa que a chamada raramente deve acontecer dentro do request HTTP. No pipeline de vídeo que mantenho, tudo que envolve modelo — transcrição do áudio, seleção dos melhores trechos, geração de título e descrição — está em jobs separados, com retentativa e backoff. O usuário do painel vê um status mudando, não uma tela travada por quarenta segundos.

Fila também é o que torna a falha barata. Quando a API responde 529 num pico, o job volta pra fila e roda dez minutos depois. Sem fila, isso vira um erro 500 na cara do cliente e um chamado no suporte.

Cache é a diferença entre viável e inviável

A conta que ninguém faz na fase de protótipo é o custo por operação em escala real. Um pipeline que processa duzentos itens por dia e chama o modelo três vezes por item faz dezoito mil chamadas por mês. Se você não mediu isso antes de aprovar a feature, vai descobrir na fatura.

Duas coisas cortam esse custo de forma quase gratuita:

• Cache de resultado por hash da entrada. Se o input é idêntico, a resposta pode ser reaproveitada. Em classificação de tickets, chamado repetido é regra, não exceção — vi taxa de acerto de cache passar de 30% só com isso.
• Escolher o modelo por tarefa. Classificar em cinco categorias não precisa do modelo mais caro do catálogo. Redação final para o cliente talvez precise. Tratar "o modelo" como uma escolha única para o produto inteiro é desperdício.

E tem a economia que é só disciplina: não mande o documento inteiro quando três parágrafos resolvem. Contexto é o item de linha mais caro da conta.

Sem avaliação, você está chutando

Essa é a parte que mais separa protótipo de produto. Como você sabe que mexer no prompt melhorou alguma coisa?

A resposta útil é chata: um conjunto de casos com o resultado esperado, rodado a cada mudança. Não precisa de ferramenta sofisticada — comecei com um arquivo de casos e um comando Artisan cuspindo uma taxa de acerto no terminal. Cinquenta casos reais, tirados do que já aconteceu em produção, incluindo os feios: texto truncado, mensagem em duas línguas, cliente irritado escrevendo tudo em caixa alta.

Sem isso, cada ajuste de prompt é superstição. Alguém troca uma frase, testa em dois exemplos, acha que melhorou, e ninguém percebe que quebrou um caso que funcionava desde março.

Projete para o erro, não para o acerto

A pergunta que eu faço em toda reunião de escopo de IA é: o que acontece quando o modelo erra?

Se a resposta for "o cliente recebe um e-mail errado" ou "a cobrança sai com o valor errado", a funcionalidade não pode ser automática. Ela pode sugerir, pré-preencher, ordenar por prioridade, rascunhar — tudo com uma pessoa apertando o botão final. Se a resposta for "o item fica na categoria errada e alguém arrasta de volta", aí sim automatize.

Essa distinção define o produto muito mais do que a escolha do modelo. E ela é uma decisão de negócio, não técnica.

O resumo

A parte de IA de uma feature de IA costuma ser dez linhas de código. O resto — schema, validação, fila, cache, avaliação, fallback e desenho do momento em que o humano entra — é engenharia comum, do tipo que todo dev sênior já sabe fazer. A boa notícia é que a experiência anterior conta. A má é que ninguém escapa dessa parte.

O problema é que muito time escreve código de 2013 dentro de um framework de 2026. A stack evoluiu; o hábito, não.

O sintoma: array como contrato

O primeiro cheiro é sempre o mesmo. Um método de service que recebe array $data, mexe em dez chaves e devolve outro array. Ninguém sabe o que entra, ninguém sabe o que sai, e o autocomplete da IDE vira decoração. Aí o time compensa isso com documentação em Notion, que envelhece em duas sprints.

PHP tem tipagem forte o suficiente para acabar com isso desde a 7.4, e desde a 8.x ficou confortável de verdade. Um objeto de valor com readonly resolve mais do que um bloco de PHPDoc:

final readonly class NovaAssinatura
{
    public function __construct(
        public int $clienteId,
        public PlanoAssinatura $plano,
        public Carbon $inicioEm,
        public ?string $cupom = null,
    ) {}
}

Agora o contrato existe no código, não na cabeça de quem escreveu. Se alguém tentar passar um cupom como int, o erro aparece no CI, não no suporte.

Enum é a ferramenta mais subaproveitada da linguagem

Máquina de estados em string solta é a causa de bug mais chata que já depurei. 'pending', 'PENDING', 'pendente', 'aguardando' — todos no mesmo banco, todos escritos por pessoas diferentes ao longo de dois anos. Enums nativos, que chegaram no PHP 8.1, matam essa categoria inteira de problema.

enum StatusDemanda: string
{
    case Aberta = 'aberta';
    case EmVisita = 'em_visita';
    case Orcada = 'orcada';
    case Concluida = 'concluida';

    public function podeAvancarPara(self $proximo): bool
    {
        return in_array($proximo, $this->proximosPassos(), strict: true);
    }
}

O Eloquent faz o cast direto no model, o Filament monta o select sozinho a partir do enum, e a regra de transição fica no mesmo arquivo que define os estados. Num marketplace de serviços que eu mantenho, esse único movimento cortou a maior fonte de chamado do suporte: pedido que "pulava" etapa porque alguém escreveu a string errada numa migration de correção.

Fila não é otimização, é design

A outra herança do PHP antigo é achar que tudo tem que acontecer dentro do request. Envio de e-mail, geração de PDF, chamada de gateway, processamento de imagem — tudo empurrado no ciclo do HTTP porque "é rápido". Até o dia em que o gateway demora oito segundos e o cliente clica duas vezes no botão de pagar.

Filas mudam a forma de modelar a operação, não só o tempo de resposta. Quando o job é a unidade de trabalho, você ganha de graça três coisas que dificilmente ia implementar na mão: retentativa com backoff, isolamento de falha e visibilidade. Eu tenho pipeline de vídeo em produção onde cada etapa — baixar, transcrever, selecionar trecho, cortar, publicar — é um job separado. Quando a transcrição falha por limite de API, só aquela etapa volta para a fila. O resto do pipeline não sabe e não precisa saber.

A regra prática que uso: se a operação depende de um sistema que eu não controlo, ela não roda no request.

Teste que você escreve porque quer

A objeção clássica contra teste em PHP era a ergonomia. PHPUnit funciona, mas escrever suíte nele nunca foi prazeroso. Pest resolveu isso de um jeito quase injusto — a barreira caiu tanto que hoje é mais rápido escrever o teste do que abrir o Postman e reproduzir o cenário na mão.

it('bloqueia checkout quando a loja está fechada', function () {
    $loja = Loja::factory()->fechada()->create();

    postJson('/api/checkout', payloadValido($loja))
        ->assertStatus(422)
        ->assertJsonPath('erro', 'loja_fechada');
});

Não é sobre cobertura de 100%. É sobre ter uma rede embaixo das regras que dão dinheiro: pagamento, cupom, zona de entrega, transição de status. Essas eu testo sempre. Layout de e-mail, não.

O que eu não faço mais

Duas coisas que já defendi e abandonei.

A primeira é encher o projeto de camada. Repository que só faz proxy pro Eloquent, DTO para toda ação, interface com uma implementação só. Isso não é arquitetura limpa, é imposto de indireção. O Eloquent já é a camada de dados; brigar com ele custa caro e não devolve nada.

A segunda é perseguir a última versão de tudo no dia do lançamento. Laravel tem ciclo previsível e política de suporte clara justamente para você planejar a atualização. Subir versão major numa sexta porque saiu no Twitter é escolha, não obrigação.

O ponto

PHP moderno é uma linguagem tipada, com enums, com atributos, com um ecossistema que resolve fila, painel, teste e deploy sem você escrever nada disso do zero. A linguagem cumpriu a parte dela. Falta o hábito acompanhar — e isso não se resolve trocando de stack, se resolve lendo a documentação da versão que você está usando e parando de escrever array $data.