Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

Equipe tirou 203 KB de prompts do código PHP para YAML — isso é um terço de todo o código

A equipe de um projeto PHP mantém 203 KB de prompts — cerca de um terço de todo o código PHP — em arquivos YAML no Git, e não no código. Antes, os prompts eram editados no painel administrativo, e a produção saía de sincronia com o staging sem nenhum histórico de alterações. Agora um único arquivo guarda texto, modelo, temperatura e formato da resposta, e o código chama essa "capacidade" pelo nome. A conclusão: versione o prompt como código, junto com os parâmetros de geração.

Processado por IA de Habr AI; editado por Hamidun News
Equipe tirou 203 KB de prompts do código PHP para YAML — isso é um terço de todo o código
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1Os dados do usuário são substituídos com str_replace depois do Blade
Dado-chave #2Retry semântico — 2 tentativas; retry de rede — 3, com pausa crescente
Dado-chave #3Em produção, o log registra apenas erros, porque os requests contêm conversas

Onde guardar os prompts é uma questão que, mais cedo ou mais tarde, surge para toda equipe que constrói um produto com LLM. Um projeto PHP respondeu a ela de forma radical: o repositório tem 203 kilobytes de prompts, o que equivale a cerca de um terço de todo o código PHP. Ao mesmo tempo, não há nenhum prompt no próprio código.

Todos eles estão em arquivos YAML (um formato de texto simples para configurações), que passam por revisão, são versionados no Git e publicados junto com a release. O projeto está sob NDA, por isso o autor inventou exemplos de prompts para um cenário de bot de suporte, mas a estrutura dos arquivos, o código de processamento e as armadilhas são reais. No caminho, ficou claro que "mover o prompt para um arquivo de configuração" não é uma decisão única, e sim uma dezena de pequenas decisões, cada uma fácil de tomar errada.

Por que não no código nem no painel administrativo

Prompt no código significa deploy por causa de uma vírgula. Mas os prompts têm uma especificidade: quem os ajusta não é o desenvolvedor, e sim quem responde pela qualidade das respostas do modelo. Muda-se a redação, observa-se a saída, desfaz-se a mudança, tenta-se de outro jeito. O ciclo se mede em horas, não em sprints.

A resposta óbvia é um campo editável no painel administrativo. A equipe fez isso na primeira versão e teve o resultado típico: o prompt em produção difere do de staging, ninguém lembra quem alterou e por quê o parágrafo sobre o formato da resposta mudou, e reverter só é possível de memória. Não há revisão, não há histórico, não há diff para consultar. O Git resolve todos esses quatro problemas ao custo de um só: para alterar um prompt, é preciso saber fazer um commit. Para essa equipe, a troca foi aceitável.

A unidade de armazenamento deixou de ser uma string de texto e passou a ser a "capacidade", por exemplo summarize-ticket. Um único arquivo reúne o provedor, o modelo, os parâmetros de geração, os templates de sistema e de usuário para cada idioma e o formato esperado da resposta. A razão é simples: o mesmo texto com temperatura 0,2 e com temperatura 0,9 produz dois comportamentos diferentes. Se a temperatura fica no código e o texto no arquivo, o resultado de ontem não pode ser reproduzido. O código chama a capacidade pelo nome e não sabe nada sobre o modelo ou o provedor.

Templates, segurança e pequenas armadilhas

O prompt quase nunca é uma constante: nele são inseridos o histórico de mensagens e o contexto. A equipe não escreveu um template engine próprio e conectou o Blade com uma única linha. O custo é claro: o Blade compila o template em PHP e o executa, ou seja, o conteúdo do arquivo YAML é código executável. Enquanto os arquivos passam por revisão, isso é aceitável. Mas, se o time de produto quiser editar prompts diretamente no painel, não se deve liberar um template engine completo ali: é preciso um motor restrito, sem execução de código e sem acesso ao sistema de arquivos.

A segunda proteção é a ordem da substituição. Primeiro é renderizado o template confiável do repositório e só depois as strings enviadas pelo usuário, como o nome, são inseridas no texto final com um str_replace comum. Se esses dados fossem passados para dentro do template engine, quem se identificasse como {{ config('app.key') }} receberia a chave da aplicação na resposta.

Alguns outros detalhes práticos:

  • Cinco idiomas não são apenas tradução. Em russo, por exemplo, o modelo mantém o formato de outra maneira e erra mais vezes ao responder em outro idioma, por isso os templates não ingleses ganham complementos como a exigência de responder no idioma correto. O teste "o significado confere" não serve para nada; o que funciona é verificar se existe template em todas as localidades e se o conjunto de substituições é o mesmo, porque um tradutor pode muito bem transformar {user} na palavra "usuário".
  • Na capacidade, o modelo é indicado por um alias curto, e a descrição completa fica no arquivo do provedor. Quando o provedor renomeia um modelo, altera-se um arquivo, e não nove.
  • No YAML é guardado o nome de uma variável de ambiente, como ${FAST_CLOUD_KEY}, e não a chave em si. Uma chave real colada "só por um minuto" permanece no histórico do Git para sempre, por isso isso é verificado separadamente na revisão.
  • Aspas em volta de números no YAML os transformam em strings, e o provedor responde com erro de validação. A equipe converte os parâmetros para números no código.

Respostas estruturadas, retries e logs

Os provedores diferem na capacidade de devolver respostas estruturadas, por isso a configuração tem três níveis: um JSON Schema completo, apenas o modo "JSON válido" e nenhum dos dois. O sistema degrada de acordo com essa escada. Se o provedor entende o schema, ele vai para response_format.

Se só suporta o modo JSON, o schema é acrescentado como texto ao final do prompt de sistema, no idioma do usuário. Mas isso é um pedido, não uma garantia, então existe uma terceira camada: do texto da resposta é extraído tudo o que está entre o primeiro { e o último }, porque o modelo gosta de acrescentar "Claro! Aqui está sua resposta:".

O resultado é parseado e validado contra o schema. O autor admite que resistiu a essa função por muito tempo, até checar quantas respostas ela salva.

Os retries se dividem em dois tipos. Uma falha de rede (timeout, 502, conexão interrompida) é resolvida com uma nova tentativa comum, com pausa exponencial, em até três tentativas. Já uma falha semântica (código 200, mas string vazia, JSON inválido ou estrutura que não passa no schema) exige repetir a requisição inteira, e essas tentativas são exatamente duas. Cada uma custa dinheiro e segundos de espera do usuário, e se o modelo falhou duas vezes com o mesmo prompt, o problema está no prompt ou no modelo, não no azar. É mais honesto mostrar o erro e registrar o caso no log.

Em produção, só os erros são registrados em log. Primeiro, o corpo da requisição, ou seja, o prompt de sistema mais o histórico de mensagens, com dezenas de kilobytes por linha, o que faz essa tabela crescer mais rápido que as outras. Segundo, nele está a conversa do usuário, isto é, dados pessoais com prazos de retenção e exclusão sob solicitação. Ainda assim, os erros devem ser registrados obrigatoriamente: status, provedor, modelo, tempo de execução e detalhes. Sem isso, a reclamação "o bot respondeu besteira" teria de ser investigada apenas pela descrição do usuário.

Sobre testes, o autor observa que a resposta do modelo é não determinística e não pode ser verificada com um assert comum, mas isso não significa que não haja nada a testar. A conclusão prática para quem constrói produtos com LLM: trate os prompts como código, mantenha os parâmetros de geração ao lado do texto, insira os dados do usuário depois do template engine e decida com antecedência o quão poderoso pode ser o template engine que você está disposto a liberar para quem edita os prompts.

História

Perguntas frequentes sobre a notícia

Por que não no código nem no painel administrativo?

Prompt no código significa deploy por causa de uma vírgula. Mas os prompts têm uma especificidade: quem os ajusta não é o desenvolvedor, e sim quem responde pela qualidade das respostas do modelo. Muda-se a redação, observa-se a saída, desfaz-se a mudança, tenta-se de outro jeito. O ciclo se mede em horas, não em sprints. A resposta óbvia é um campo editável no painel administrativo.

O que se sabe sobre Templates, segurança e pequenas armadilhas?

O prompt quase nunca é uma constante: nele são inseridos o histórico de mensagens e o contexto. A equipe não escreveu um template engine próprio e conectou o Blade com uma única linha. O custo é claro: o Blade compila o template em PHP e o executa, ou seja, o conteúdo do arquivo YAML é código executável. Enquanto os arquivos passam por revisão, isso é aceitável.

O que se sabe sobre Respostas estruturadas, retries e logs?

Os provedores diferem na capacidade de devolver respostas estruturadas, por isso a configuração tem três níveis: um JSON Schema completo, apenas o modo "JSON válido" e nenhum dos dois. O sistema degrada de acordo com essa escada. Se o provedor entende o schema, ele vai para response_format. Se só suporta o modo JSON, o schema é acrescentado como texto ao final do prompt de sistema, no idioma do usuário.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
O que você acha?
Carregando comentários…