Prompt Espalhado

Como reconhecer

Um SDR automático escreve a primeira mensagem para leads. O prompt final é montado por concatenação em quatro arquivos (anonimizado):

# persona.py
BASE = "Você é Júlia, consultora da Empresa. "

# tone.py
def tone(segment):
    return "Seja formal. " if segment == "industria" else "Seja descontraída! "

# campaigns/q3.py
CAMPAIGN = "Mencione o desconto de lançamento. "

# writer.py
prompt = BASE + tone(lead.segment) + CAMPAIGN + f"Lead: {lead.name}, {lead.company}. " \
         + ("Não mencione preço. " if lead.is_enterprise else "")

Um lead enterprise do varejo monta isto, em tempo de execução, e ninguém revisou este texto:

Você é Júlia, consultora da Empresa. Seja descontraída! Mencione o
desconto de lançamento. Lead: Ana, Loja Norte. Não mencione preço.

“Mencione o desconto” e “não mencione preço” no mesmo parágrafo. A mensagem sai oscilando: um dia cita 12% de desconto, no outro diz que o comercial informa. Leads do varejo comum só recebem o tom descontraído e o desconto. Ninguém vê o prompt enviado sem rodar o código com aquele lead.

Sinais de Prompt Espalhado:

• O prompt é montado com +, f-strings ou join em vários arquivos.
• Pedaços do prompt dependem de condições espalhadas pelo código.
• Não existe um lugar onde se possa ler o prompt completo.
• Combinações de condições geram instruções contraditórias.
• O tom ou o conteúdo muda conforme o caminho de código que montou a mensagem.

flowchart LR
  A["persona.py"]:::tool --> J["1. Concatenação"]:::tool
  B["tone.py"]:::tool --> J
  C["campaigns/q3.py"]:::tool --> J
  D["writer.py com ifs"]:::tool --> J
  J --> M(["2. Prompt que ninguém leu inteiro"]):::llm
  M --> OUT(["3. Mensagem com tom variável"]):::io

1. Pedaços de texto vêm de vários arquivos e condições.
2. O prompt final existe só em tempo de execução.
3. A saída varia conforme a combinação, às vezes com instruções que se contradizem.

Uma variável ou duas, declaradas, num arquivo só, não é este smell. O cheiro começa quando o texto inteiro não cabe na cabeça sem executar.

O jeito mais rápido de confirmar: logue o prompt montado em toda requisição, por um dia. Se você não consegue apontar um arquivo e dizer “é isto que o modelo viu”, o texto está espalhado. No SDR da Júlia, o log de Ana seria a primeira vez que alguém leria as duas frases opostas na mesma tela.

Checagem +20 XP de primeiraAna é enterprise no varejo. O prompt montado pede desconto e proíbe preço ao mesmo tempo. Qual é o primeiro diagnóstico?

O modelo é ruim de seguir instrução e precisa de um maior

Pedaços de arquivos diferentes se combinaram num prompt que ninguém leu

Falta um few-shot de mensagem enterprise boa

Por que acontece

• Reaproveitar pedaços parece bom design. A persona é a mesma em vários lugares, então vira uma constante. A constante ganha um if, o if ganha um arquivo.
• Cada campanha acrescenta um pedaço. O código cresce por adição, como o prompt. Q3 entra em campaigns/q3.py sem ninguém abrir o texto final.
• Prompt tratado como string comum. Não há uma ferramenta de template, então se usa o que a linguagem oferece: + e f-string.
• Condição no código, instrução no texto. if lead.is_enterprise mistura controle de fluxo com prosa. As combinações crescem em produto, não em soma.

Quanto custa ignorar

• Comportamento imprevisível. Combinações raras geram prompts contraditórios. O SDR promete desconto e recusa preço na mesma frase.
• Impossível revisar. Ninguém aprova um prompt que só existe montado. O PR de tone.py parece inofensivo e muda todos os segmentos.
• Impossível versionar. Uma mudança em tone.py altera todos os prompts que o usam, sem registro de qual combinação saiu.
• Depuração lenta. Para entender uma resposta, é preciso reconstruir o prompt daquele caso, com aquele lead, naquela campanha.

Em atendimento de banco no WhatsApp, o mesmo padrão aparece: um arquivo de tom “formal”, outro de produto “Pix”, outro de compliance “não promete prazo”. O cliente enterprise de Pix recebe três políticas ao mesmo tempo, e uma delas contradiz a outra.

Tratamento

Refatoração	Escolha quando
Extrair Template Versionado	Sempre. Os pedaços viram um template único, com nome, versão e variáveis declaradas. As condições viram variáveis ou templates separados. Destino: Registro de Templates.

O template declara o que pode variar. O que não está na lista não entra por concatenação:

# sdr.primeira_mensagem@3
Você é {{persona_nome}}, consultora da {{empresa}}.
Tom: {{tom}}.
Campanha: {{campanha}}.
Lead: {{lead_nome}}, {{lead_empresa}}.
Preço: {{politica_preco}}.

Duas campanhas incompatíveis viram dois templates (sdr.varejo@3 e sdr.enterprise@3), não um if que cola frases opostas. O trace guarda nome e versão. Na revisão, a pessoa lê o arquivo inteiro.

Um teste que o concatenador nunca teve: renderize o template com um lead enterprise de varejo e cole o texto no PR. Se a revisão não consegue dizer “sim, é isto que o modelo vê”, ainda falta juntar algum pedaço.

Checagem +20 XP de primeiraO time extraiu um template com variáveis nome, empresa e segmento. Um if em writer.py ainda concatena 'Não mencione preço.' para enterprise. O smell saiu?

Sim, o grosso do prompt está num arquivo só

Não: a condição ainda injeta prosa fora do template

Sim, se o if estiver comentado no template

O que você ganha

• O prompt completo legível num lugar só.
• Cada versão registrada, com quem mudou e por quê.
• Variáveis declaradas, sem combinações escondidas.
• O trace guarda nome e versão do template de cada mensagem.

Quando ignorar

• Uma ou duas variáveis simples. Um prompt com o nome do cliente inserido não está espalhado.
• Protótipo de um arquivo só. Se todo o prompt está num lugar, mesmo montado com f-string, o problema é menor.

É esse smell?

Checagem +20 XP de primeiraO prompt fica num arquivo de template com três variáveis: nome, empresa e segmento. O código só preenche as variáveis. É Prompt Espalhado?

Sim, há variáveis

Não

Sim, porque segmento ainda decide o tom

Checagem +20 XP de primeiraO template está num lugar só, mas ninguém sabe qual versão gerou a mensagem de que um lead reclamou. Qual smell?

Prompt Espalhado

Prompt Sem Versão

Prompt Sem Eval

Checagem +20 XP de primeiraTrês serviços diferentes montam prompts para o mesmo assistente, cada um com sua cópia da persona, e as cópias divergiram. O que fazer?

Sincronizar as cópias manualmente

Um registro de templates compartilhado

Mandar os três serviços concatenarem a partir do mesmo persona.py

Checagem +20 XP de primeiraUm script de uma página só faz prompt = BASE + f'Cliente: {nome}', com BASE no mesmo arquivo. É Prompt Espalhado?

Sim, há concatenação

Não, e não há nada a fazer nunca

Não é o caso; uma ou duas variáveis num arquivo só não espalham o prompt