Prompt engineering em 10 princípios: o que me salvou horas

Durante meses escrevi prompts por instinto. Às vezes funcionava, às vezes não. Quando não funcionava, repetia o mesmo prompt com umas palavras trocadas e esperava um resultado diferente. Que é praticamente a definição de insanidade.

O ponto de viragem foi perceber que os modelos de linguagem não são caixas mágicas. São sistemas com comportamentos previsíveis. E quando percebes os padrões, começas a trabalhar com eles em vez de contra eles.

Estes são os 10 princípios que uso hoje, com exemplos concretos. Nenhum deles é teoria: todos vieram de tentativa, erro, e de construir o Descomplicai peça a peça.

1. Contexto antes de instrução

O maior erro que vejo é começar o prompt com o que queres que o modelo faça, sem lhe dizer quem ele é ou o que está a acontecer.

Fraco:

Escreve um email de vendas para o meu produto.

Melhor:

És um copywriter experiente a trabalhar para uma PME portuguesa de software de gestão.
O produto é uma plataforma de faturação para freelancers.
O destinatário é um designer gráfico a fazer a transição para o trabalho independente.
Escreve um email de apresentação com foco no tempo que poupa, não nas funcionalidades.

O contexto não é decorativo. É o filtro através do qual o modelo interpreta tudo o resto.

2. Persona com propósito

Pedir ao modelo que assuma uma persona funciona. mas só se a persona for útil para a tarefa. Não uses personas genéricas ("és um especialista em X"). Usa personas com perspectiva específica.

Actua como um director financeiro de uma empresa de 15 pessoas que acabou de passar
por uma auditoria. Analisa este orçamento e diz-me o que te preocuparia.

A persona não muda o que o modelo sabe. Muda o ângulo de análise.

3. Formato explícito, não implícito

Se queres bullet points, pede bullet points. Se queres três parágrafos, diz três parágrafos. Se queres JSON, mostra o schema.

Os modelos inferem formato pelo contexto e frequentemente inferem mal. Poupar esse trabalho de inferência é poupar variabilidade no output.

# Exemplo: forçar output estruturado
prompt = """
Analisa o seguinte texto e extrai:
- Tom (positivo / neutro / negativo)
- Principais temas (lista de até 5)
- Acção recomendada (1 frase)

Responde APENAS em JSON com as chaves: tom, temas, accao.

Texto: {texto}
"""

4. Exemplos valem mais que explicações

Few-shot prompting é a técnica com melhor retorno por esforço que conheço. Mostrar dois ou três exemplos do que queres é mais eficaz do que escrever três parágrafos a explicar.

Converte as seguintes descrições de tarefas num título curto e accionável.

Descrição: "Preciso de verificar se os contratos dos fornecedores foram todos renovados para 2026"
Título: "Validar renovação de contratos de fornecedores"

Descrição: "Há um bug no formulário de contacto que não deixa enviar quando o nome tem acento"
Título: "Corrigir validação de acentos no formulário de contacto"

Descrição: {tua_descrição}
Título:

O modelo aprende o padrão dos exemplos e aplica-o.

5. Cadeia de raciocínio para problemas complexos

Para tarefas que envolvem análise, raciocínio ou decisão, pede ao modelo que pense passo a passo antes de dar a resposta final. Não é um truque. É dar ao modelo espaço para processar.

Antes de responder, pensa passo a passo:
1. Que informação tenho?
2. O que está em falta?
3. Quais são as hipóteses razoáveis?
4. Qual é a conclusão mais defensável?

Só depois de percorrer estes passos, dá a tua resposta final.

A qualidade do output em tarefas analíticas melhora visivelmente com esta instrução simples.

6. Restrições negativas

Dizer ao modelo o que não deve fazer é tão importante como dizer o que deve. Os modelos têm tendências: para ser excessivamente positivos, para adicionar disclaimers, para generalizar quando deveriam ser específicos.

Analisa este plano de negócio. 
NÃO faças elogios genéricos.
NÃO uses frases como "é um plano ambicioso" ou "há oportunidades interessantes".
Foca-te exclusivamente nos riscos e nos pontos fracos.

As restrições negativas cortam o ruído e forçam o modelo a ir onde não iria por defeito.

7. Temperatura conceptual por tarefa

Para outputs criativos e variados: usa linguagem aberta, pede múltiplas hipóteses, encoraja divergência.

Dá-me 5 formas completamente diferentes de enquadrar esta mensagem.
Quero perspectivas contrastantes, não variações do mesmo ângulo.

Para outputs precisos e reproduzíveis: usa linguagem fechada, define critérios claros, pede uma única resposta justificada.

Com base apenas na informação que te dei, qual é a única acção mais prioritária?
Justifica em duas frases.

8. Iteração estruturada, não aleatória

Quando um prompt não funciona, a tentação é mudar tudo. O problema é que não sabemos o que causou o mau resultado.

A abordagem que uso: muda uma variável de cada vez.

• Mudei o contexto. mantive a instrução e o formato.
• Mudei o formato. mantive o contexto e a instrução.
• Adicionei exemplos. mantive tudo o resto.

Em dois ou três ciclos sabes exactamente o que estava a falhar.

9. Prompts como código: versionamento e reutilização

Se usas o mesmo prompt mais de duas vezes, ele merece ser tratado como código: documentado, versionado, testado.

No Descomplicai tenho um ficheiro de prompts base que evolui como qualquer outro componente do sistema. Quando mudo um prompt, registo o porquê. Quando encontro uma versão melhor, a anterior fica acessível.

PROMPTS = {
    "analise_sentimento_v2": """
        Analisa o sentimento do seguinte texto sobre uma marca portuguesa.
        Classifica como: muito positivo / positivo / neutro / negativo / muito negativo.
        Indica as 2-3 expressões que mais influenciaram a tua classificação.
        Responde em JSON: {sentimento: str, expressoes: list[str]}
    """,
}

Não é burocracia. É a diferença entre um sistema que melhora e um sistema que fica sempre no mesmo sítio.

10. O modelo não sabe o que não lhe disseste

O mais simples e o que mais frequentemente esqueço. O modelo não tem acesso ao teu contexto, às tuas intenções, ao que aconteceu antes desta conversa. Se algo é importante para o resultado, tem de estar no prompt.

Quando um output decepciona, a primeira pergunta que faço a mim mesmo é: que informação dei como garantida que não está aqui?

Quase sempre há algo.

O que isto representa na prática

Estes 10 princípios não são regras absolutas. São heurísticas que resultam na maioria dos casos. O trabalho é perceber quando aplicar o quê.

O que mudou para mim foi deixar de tratar os prompts como pedidos e começar a tratá-los como especificações. Um bom prompt é um documento de trabalho: tem contexto, instrução clara, formato definido, restrições relevantes.

Quando chegas a esse ponto, a qualidade do output deixa de ser uma surpresa e passa a ser uma consequência.

Se trabalhas com IA no teu negócio e queres estruturar isto de forma sistemática, o Descomplicai tem projectos nessa área em /projetos.

Construído com tentativa e erro. Se um destes princípios te salvar tempo, já valeu a pena escrever.