Neste artigo
Um PRD para coding agent é um documento curto que responde três coisas antes de qualquer código existir: o que o sistema faz, quem pode fazer o quê, e o que ele explicitamente não faz. Ele não substitui conversa, ele substitui a adivinhação que o agente faria sozinho quando a instrução for vaga.
Eu escrevo o meu em markdown, dentro do repositório, e ele entra no commit junto com o código. Assim a spec e a implementação envelhecem juntas, e quando alguém pergunta por que uma regra é daquele jeito, a resposta está versionada.
Por que o PRD de produto tradicional não serve aqui?
PRD clássico é escrito para humano decidir prioridade. Esse aqui é escrito para uma máquina não inventar. São públicos diferentes e o que falta em cada um é diferente.
Um PRD de produto pode dizer “o usuário gerencia seus projetos” e todo mundo entende. O agente lê isso e precisa decidir sozinho se gerenciar inclui apagar, se apagar é soft delete ou hard delete, se um projeto apagado some do relatório histórico, e se o dono pode transferir a posse para outra pessoa. Ele vai decidir as quatro, sem te avisar, e vai decidir diferente em cada arquivo que tocar.
Então a régua do PRD para agente é essa: toda frase que admite duas implementações razoáveis precisa ser desempatada.
O que precisa estar no PRD?
São sete blocos. Nenhum deles precisa ser longo, todos precisam ser específicos.
- Problema e recorte. Uma frase do problema, e uma lista do que fica de fora nesta versão. A lista do que fica de fora é a que mais economiza tempo.
- Papéis e permissões. Quem existe no sistema e o que cada um pode ler, criar, editar e apagar. Uma tabela resolve.
- Entidades e relações. As cinco ou seis entidades principais, e como se ligam. Cardinalidade explícita: um projeto tem muitas tarefas, uma tarefa pertence a um projeto só.
- Fluxos críticos. Cadastro, pagamento, convite de usuário, o que for o coração do produto. Passo a passo, incluindo o que acontece quando falha no meio.
- Regras de negócio que não são óbvias. Aquelas que só existem na tua cabeça e no teu mercado.
- O que não fazer. Bibliotecas proibidas, padrões que você não quer, decisões já tomadas que o agente não deve reabrir.
- Critério de pronto. Como você vai saber que está aceitável.
Como isso fica na prática?
Um trecho real de PRD meu, na parte de permissões, que é onde o agente mais erra sozinho:
## Papéis
| Papel | Projetos | Tarefas | Faturamento |
|--------|---------------------|--------------------------|-------------|
| owner | CRUD, transfere | CRUD | ver, alterar|
| admin | CRUD | CRUD | ver |
| membro | ver os que participa| CRUD nas suas | nao acessa |
Regra dura: TODA query de leitura filtra por tenant_id do usuario logado.
Nao existe endpoint que devolva registro sem esse filtro, nem para admin.Essa última linha vale mais que três parágrafos de descrição, porque ela fecha a porta do erro que custa caro.
O agente ajuda a escrever o PRD?
Ajuda, mas no papel de revisor, não de autor. O que funciona pra mim é escrever o rascunho na mão, com as decisões que só eu posso tomar, e depois pedir pro agente listar as ambiguidades que restaram, sem resolver nenhuma. A pergunta é literalmente essa: quais frases aqui admitem mais de uma implementação razoável.
Ele devolve uma lista boa. Aí eu desempato uma por uma, na mão. Se eu deixar ele desempatar, volto ao problema original.
Quanto detalhe é detalhe demais?
| Tipo de decisão | Entra no PRD? | Por quê |
|---|---|---|
| Regra de permissão | Sempre | Erro aqui vaza dado entre clientes |
| Cardinalidade entre entidades | Sempre | Muda o schema, e schema é caro de desfazer |
| Comportamento em falha de pagamento | Sempre | Envolve dinheiro e o agente escolhe o caminho feliz |
| Nome de variável, estrutura de pasta | Não | Convenção do projeto resolve, e o agente segue bem |
| Qual biblioteca de data usar | Só se você tem preferência | Escolha dele costuma ser aceitável |
| Layout e microcópia | Não | Mais rápido ajustar vendo na tela |
O que acontece quando o PRD está vago?
Já paguei esse pedágio. Num projeto com convite de usuário, eu escrevi apenas “o admin convida pessoas para o workspace”. O agente implementou convite por e-mail com link, o que é razoável. Só que ele fez o link não expirar, aceitar múltiplos usos, e não validar se o e-mail que aceitou é o mesmo que foi convidado.
Nada disso apareceu em teste, porque o teste seguia o caminho feliz. Apareceu quando eu fui ler o código de autorização por outro motivo. Uma linha no PRD, dizendo que o convite expira em 72 horas, é de uso único e só é aceito pelo e-mail destinatário, teria resolvido antes.
Perguntas frequentes
PRD longo não desperdiça contexto do agente?
Desperdiça se você joga o documento inteiro em toda tarefa. O que eu faço é manter o PRD no repositório e referenciar só a seção relevante na tarefa. O agente lê o arquivo quando precisa.
Preciso reescrever o PRD quando a regra muda?
Sim, e essa é a parte que mais gente pula. PRD desatualizado é pior que PRD nenhum, porque o agente vai seguir a versão velha com confiança.
Serve para Codex também?
Serve, é o mesmo documento. A spec é sobre o produto, não sobre a ferramenta, e é justamente por isso que ela sobrevive à troca de ferramenta. Como eu divido o trabalho entre os dois está em Claude Code e Codex juntos, e o processo completo em como construir um SaaS com Claude Code e Codex.
