Estrutura Profissional de Prompts

Objetivos

• Criar prompts reutilizáveis em equipe
• Tratar mudança de prompt como mudança de código (review, diff, rollback)

O prompt que mora na cabeça de um dev

Cenário clássico: o bot funciona bem porque o João escreveu um prompt genial no Notion. João sai de férias. Ninguém sabe o que mudar. Um colega "melhora" uma frase e o bot passa a inventar código de rastreio.

Prompt profissional não vive na cabeça — vive no repositório, com versão, changelog e testes. Mudou o prompt? Pull request, review, deploy — como qualquer feature.

Modelo PCORS

PCORS é uma checklist para o time inteiro falar a mesma língua — dev, produto e suporte.

Exemplo completo — agente de pedidos

PAPEL
Você é o assistente de pedidos da TechParts. Não é advogado nem médico.

CONTEXTO
Canal: chat do site. Usuário pode informar número de pedido.
Ferramentas disponíveis: buscar_pedido(id) — você NÃO inventa status.

OBJETIVO
Responder status de entrega ou orientar como encontrar o número do pedido.

REGRAS
- Português BR, tom cordial, frases curtas
- Se pedido não encontrado: peça CPF ou e-mail cadastrado
- Nunca invente código de rastreio
- Se pergunta for sobre produto novo: diga que pode buscar no catálogo

SAÍDA
Texto plano, máximo 120 palavras. Sem markdown pesado.

Conversa simulada com este prompt:

Usuário: "Cadê meu pedido?"
Assistente: "Claro! Qual o número do pedido? Você encontra no e-mail de confirmação."
Usuário: "8842"
Assistente: [chama buscar_pedido] "Seu pedido 8842 foi enviado. Rastreio: BR123."

Sem PCORS, a mesma pergunta vira: "Seu pedido está a caminho!" — sem número, sem dado real, sem confiança.

Arquivo no repositório

/prompts
  order-agent.system.v1.txt
  order-agent.system.v2.txt
  faq-agent.system.v1.txt

import { readFileSync } from 'fs';

const SYSTEM_PROMPT = readFileSync('./prompts/order-agent.system.v2.txt', 'utf8');

export function buildMessages(userMessage, history) {
  return [
    { role: 'system', content: SYSTEM_PROMPT },
    ...history,
    { role: 'user', content: userMessage },
  ];
}

Separar prompt do código permite que produto revise texto sem tocar na lógica do servidor.

Testes de prompt (sem framework)

const CASES = [
  { input: 'Pedido 9912', expectIncludes: ['9912'] },
  { input: 'Quero processo judicial', expectIncludes: ['Não posso'] },
];

for (const c of CASES) {
  const out = await chat(buildMessages(c.input, []));
  assert(out.includes(c.expectIncludes[0]));
}

Rode no CI com mock da API ou snapshot em staging. Prompt é código — merece teste.

Casos que todo agente de pedidos deveria passar:

"Qual meu pedido?" → pede número
"Pedido 99999" (inexistente) → orienta, não inventa
"Quero processo judicial" → recusa com educação

Variáveis dinâmicas

Substitua placeholders no deploy:

CONTEXTO
Empresa: {{companyName}}
Horário suporte: {{supportHours}}

const prompt = template.replace('{{companyName}}', config.companyName);

Nunca deixe usuário final editar system prompt sem sanitização — isso é porta aberta para jailbreak e vazamento de instruções internas.

Changelog de prompt

Documente no topo do arquivo:

# v2 — 2025-06-01
# - Proíbe inventar rastreio
# - Limite 120 palavras
# v1 — 2025-05-15 — versão inicial

Quando suporte disser "o bot piorou na sexta", você olha o changelog e o diff do Git — não adivinha.

Resumo

• PCORS = estrutura que times inteiros entendem
• Prompt vive no Git, não na cabeça do dev
• Testes manuais/automáticos antes de produção
• Versionar permite rollback quando qualidade cai

Prompts prontos, API dominada — hora de montar algo que usuário final enxerga: um chatbot de verdade. A próxima matéria começa pela interface e pelo fluxo completo até o backend.