Pontos-chave
- Todo prompt de produção precisa no mínimo de um Cartão One-Liner (propósito, modelo, data, autor)
- Todo prompt modificado precisa de um Bloco de Versão (o que mudou, por que, resultado do teste)
- Todo prompt testado precisa de um Cabeçalho de Suite de Testes (critérios de sucesso, exemplos golden, modos de falha)
- Armazene a documentação no mesmo sistema que o prompt — os docs separados ficam abandonados
- A justificativa da mudança ("por que") é o campo mais importante: as equipes que a omitem voltam aos padrões anteriores quando o autor sai
- O PromptHub oferece a estrutura de documentação incorporada mais completa; o Git funciona para equipes de engenharia com boa disciplina de commits
Por que os prompts sem documentação quebram as equipes
📍 In One Sentence
Os prompts sem documentação quebram as equipes por meio de regressão silenciosa, duplicação e perda de conhecimento — cada um prevenível com 5–10 minutos de documentação por prompt.
💬 In Plain Terms
Quando um prompt não tem registro do que faz nem por que foi escrito assim, a equipe não pode alterá-lo com segurança, recuperá-lo após uma edição nem entregá-lo a um novo membro sem contexto.
Os prompts sem documentação quebram as equipes de três maneiras: regressão silenciosa (sem registro do que mudou), duplicação (as equipes reescrevem prompts existentes porque não os encontram) e perda de conhecimento (os prompts se tornam impossíveis de manter quando o autor sai). Cada falha é prevenível com 5–10 minutos de documentação por prompt.
A falha mais custosa é a regressão silenciosa. Uma equipe modifica um prompt de produção para resolver um problema, inadvertidamente quebra outro, e não tem uma linha de base para comparar. Sem histórico de versões e um cabeçalho de suite de testes, diagnosticar a regressão requer comparação manual e suposições.
Use documentação para todo prompt utilizado mais de uma vez, armazenado em infraestrutura compartilhada ou implantado em produção. Omita para prompts exploratórios de uso único em uma única sessão.
⚠️ Risco de regressão silenciosa
Sem um Bloco de Versão e exemplos golden, uma equipe que modifica um prompt de produção não tem linha de base. Cada edição é uma suposição sobre qual era o estado anterior.
6 modelos de documentação de prompts
Seis modelos cobrem o ciclo de vida completo do prompt desde o primeiro rascunho até a aposentadoria em produção. Cada modelo foi projetado para ser concluído em menos de 10 minutos e fornecer as informações mínimas necessárias para cada etapa do ciclo de vida.
- 1Cartão One-Liner
Why it matters: Propósito: capturar o registro mínimo para qualquer prompt reutilizado. Campos: nome do prompt, propósito (1 frase), modelo alvo, data de criação, autor. Use quando: um prompt é salvo pela primeira vez. Armazenamento: qualquer ferramenta compartilhada (Notion, Git, PromptHub). - 2Bloco de Versão
Why it matters: Propósito: rastrear o histórico de prompts que mudam com o tempo. Campos: número de versão, data de modificação, autor, o que mudou (1 frase), razão da mudança (1 frase), resumo do resultado do teste. Use quando: um prompt é modificado. Armazenamento: mensagem de commit do Git ou entrada de versão no PromptHub. - 3Cabeçalho de Suite de Testes
Why it matters: Propósito: definir os critérios de aceitação antes de escrever os testes. Campos: objetivo do teste (o que o prompt deve fazer), critérios de sucesso (quais características de saída definem o sucesso), exemplos golden (2–3 pares entrada/saída), modos de falha conhecidos. Use quando: um prompt entra na suite de testes. Armazenamento: junto ao arquivo de teste no Git ou no projeto do Braintrust. - 4Registro de Decisões
Why it matters: Propósito: registrar decisões de design que não são óbvias no texto do prompt. Campos: decisão tomada, alternativas consideradas, razão pela qual esta opção foi escolhida, data. Use quando: uma decisão de design não óbvia é tomada (por exemplo, por que uma temperatura específica foi definida). Armazenamento: doc vinculado ao bloco de versão. - 5Justificativa de Mudança
Why it matters: Propósito: explicar por que um prompt foi alterado em termos que permitem reverter ou replicar a mudança. Campos: descrição do problema (o que estava errado), mudança realizada, melhoria esperada, resultado medido. Use quando: um prompt é modificado em resposta a uma falha ou regressão. Armazenamento: corpo do commit do Git ou nota de mudança no PromptHub. - 6Bloco de Config API
Why it matters: Propósito: registrar os parâmetros do modelo usados em produção. Campos: modelo (por exemplo, GPT-5.5, Claude 4.6 Sonnet), temperatura, max tokens, top_p, stop sequences, versão do system prompt, versão do user prompt. Use quando: um prompt é implantado em produção. Armazenamento: arquivo de configuração de implantação, referenciado no bloco de versão.
📌 Guia de seleção de modelo
Novo prompt → Cartão One-Liner. Prompt modificado → Bloco de Versão. Prompt testado → Cabeçalho de Suite de Testes. Decisão de design tomada → Registro de Decisões. Alterado após uma falha → Justificativa de Mudança. Implantado em produção → Bloco de Config API.
Onde armazenar a documentação de prompts
Armazene a documentação de prompts no mesmo sistema que o prompt. Se o prompt está no código, armazene os docs no Git. Se está em uma ferramenta GUI, armazene os docs nas notas dessa ferramenta ou em um doc vinculado.
- Git: melhor para equipes de engenharia com prompts armazenados como arquivos. As mensagens de commit servem como blocos de versão. Gratuito. Requer disciplina. Sem fluxo de trabalho de revisão incorporado.
- PromptHub: gerenciamento de prompts com histórico de versões, assinaturas de revisores e armazenamento de resultados de testes. $0–$49/mês. Melhor para equipes com 3+ pessoas escrevendo prompts.
- Notion: funciona para equipes que gerenciam prompts como documentos em vez de código. Fácil de configurar. Carece de controle de versões e integração de testes — trate-o como camada de documentação, não como fonte da verdade.
- Braintrust: armazena cabeçalhos de suite de testes e resultados de avaliação junto às versões do prompt. Melhor para equipes que executam avaliações automatizadas regulares.
- PromptQuorum: plataforma de otimização de prompts para despachar prompts documentados para mais de 25 provedores de IA simultaneamente. Use-a para validar que os prompts documentados generalizam entre modelos antes de confirmar uma versão. Nível gratuito.
💡 Co-localize a documentação
A documentação armazenada em um sistema separado (Notion, Confluence, Google Docs) do prompt ficará desatualizada em dias. A única documentação que se mantém atualizada é a que vive com o prompt.
Erros comuns de documentação
❌ Sem documentação alguma
Why it hurts: Os prompts não podem ser recuperados após edições, a equipe não consegue entender por que um prompt foi escrito de determinada forma
Fix: Use no mínimo o modelo Cartão One-Liner — 3 campos, menos de 2 minutos
❌ Documentação armazenada separadamente do prompt
Why it hurts: A documentação fica desatualizada à medida que os prompts mudam; as equipes esquecem de atualizá-la
Fix: Armazene a documentação no mesmo arquivo ou commit do Git que o prompt
❌ Campo "por que" ausente — apenas descreve o que o prompt faz
Why it hurts: Os editores futuros não conhecem as restrições, não conseguem refatorar com segurança
Fix: Adicione um campo "justificativa" a cada modelo: 1-2 frases sobre por que esta estrutura foi escolhida
❌ Sem bloco de versão
Why it hurts: Sem forma de saber se o prompt que está rodando em produção corresponde à versão documentada
Fix: Adicione versão e dateModified a cada arquivo de prompt de produção
Perguntas frequentes
Por que os prompts precisam de documentação?
Os prompts sem documentação não podem ser revisados, auditados nem reproduzidos. Quando o autor altera o prompt e não deixa nenhum registro, a equipe não consegue diagnosticar regressões, não consegue voltar a uma versão conhecida como boa nem consegue integrar novos membros.
Qual é a documentação mínima que um prompt precisa?
O mínimo é um cartão one-liner: propósito do prompt (uma frase), modelo alvo, data de criação e autor. Isso leva 2 minutos para escrever e previne a falha de documentação mais comum — prompts cujo propósito é desconhecido 6 meses depois.
Onde deve ser armazenada a documentação de prompts?
Armazene a documentação de prompts na mesma localização que o prompt. O Git funciona para prompts armazenados como arquivos de código. O PromptHub fornece armazenamento estruturado com histórico de versões e assinaturas de revisores incorporadas. O Notion funciona para equipes que gerenciam prompts como documentos, mas carece de controle de versões.
Quão detalhada deve ser uma justificativa de mudança?
Três linhas: o que mudou (uma frase), por que (o problema que a mudança resolve) e que teste confirmou que funcionou. As equipes que omitem o "por que" invariavelmente voltam ao padrão anterior quando o autor sai.
Qual modelo devo usar para um novo prompt?
Comece com o Cartão One-Liner. Se o prompt vai para produção, atualize para um Bloco de Versão. Se tem vários casos de teste, adicione um Cabeçalho de Suite de Testes. Se exigiu uma decisão de design não óbvia, adicione um Registro de Decisões.
Com que frequência devo atualizar a documentação de prompts?
Atualize sempre que o texto do prompt mudar. Adicione um incremento de versão e uma entrada de Justificativa de Mudança para cada edição substancial. Não atualize a documentação retroativamente.
Posso usar esses modelos no PromptHub?
Sim. O PromptHub armazena campos de metadados de prompts que se mapeiam diretamente para os modelos de Bloco de Versão e Bloco de Config API. Use o modelo como rascunho e então copie os campos para o PromptHub quando estiver pronto para compartilhá-lo com sua equipe.