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
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.
- 12 de out. de 2026T-Bank ensinou um agente de IA a escrever testes unitários de iOS com AGENTS.md e SKILL.md
- 16 de jun. de 2026IA no desenvolvimento: como um LLM detecta conflitos entre microsserviços
- 18 de nov. de 2026Kub Tri deu ao agente de IA uma memória do projeto: o review fica mais simples, mas o modelo custa quase um terço a mais
- 2 de mai. de 2026Framework zymi propõe montar agentes de IA como um projeto dbt, com YAML e event sourcing
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.
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.
O essencial da IA — uma vez por semana
Sete histórias que realmente importaram, escolhidas a dedo. Sem ruído nem releases.
Pronto! Verifique seu e-mail para a confirmação.