Desenvolvimento orientado por PRD: como uso mais de 30 PRDs para entregar com agentes de IA

O workflow RalphBlaster da SaasMaker gera um pull request completo a partir de um ticket de uma linha em menos de 45 minutos, com o desenvolvedor sem tocar em nenhum código durante a implementação.¹

Eu tentei esse padrão. Funciona. Mas também falha de formas que os vídeos de demonstração não mostram.

TL;DR

Escrevi mais de 30 PRDs para tarefas de agentes de IA nos últimos seis meses. O padrão funciona bem para tarefas bem definidas com critérios de aceitação claros: endpoints CRUD, adição de testes, componentes de UI seguindo padrões estabelecidos. Ele falha para requisitos ambíguos, decisões arquiteturais inéditas e qualquer coisa que exija julgamento humano iterativo. Meu template de PRD evoluiu de um formato simples de user story para um documento estruturado com localização de arquivos, expectativas de testes, restrições e listas explícitas de “não mexa nisso”. Essa evolução aconteceu porque os agentes interpretavam PRDs vagos de formas surpreendentes.

O workflow que eu realmente uso

Passo 1: Criar um ticket

Defino o que precisa acontecer em linguagem simples. A especificidade importa mais do que eu imaginava inicialmente:

Vago (produz resultados imprevisíveis):

Add user preference saving to the settings page.

Específico (produz resultados previsíveis):

Add dark mode toggle to /settings. Persist to user_preferences
table (column: dark_mode, type: boolean, default: false).
Use existing SettingsForm component. Add toggle below the
notification section. No new dependencies.

A segunda versão restringe o agente o suficiente para que o resultado corresponda às expectativas. A primeira versão me deu uma página de configurações com um novo componente React, três novos pacotes npm e uma implementação com localStorage em vez da persistência em banco de dados que eu queria.

Passo 2: Gerar ou escrever o PRD

Minha skill /prd converte um ticket em um PRD estruturado com user stories, critérios de aceitação, localização de arquivos e expectativas de testes.² Um PRD típico se parece com:

## Story: Add dark mode toggle
**As a** user
**I want to** toggle dark mode from settings
**So that** I can read comfortably in low light

### Acceptance Criteria
- [ ] Toggle appears in SettingsForm below notifications
- [ ] Persists to user_preferences.dark_mode (boolean)
- [ ] Default: false (light mode)
- [ ] Toggle state reflects current DB value on page load

### Files to Modify
- app/routes/settings.py (add dark_mode to form handler)
- app/templates/settings.html (add toggle component)
- app/models/user.py (add dark_mode column if missing)

### Files NOT to Modify
- app/static/css/styles.css (dark mode CSS already exists)
- app/templates/base.html (already reads dark_mode class)

### Test Expectations
- Test toggle persists to database
- Test default value on new user
- Test toggle reflects current state on reload

A seção “Files NOT to Modify” foi a maior evolução do template. Sem ela, os agentes “melhoravam” arquivos relacionados de forma prestativa, introduzindo mudanças que eu não havia solicitado e não queria.

Passo 3: Implementação pelo agente

O agente trabalha em um git worktree isolado, evitando interferência com minha branch atual:³

# Create isolated worktree for agent task
git worktree add ../worktrees/dark-mode -b feature/dark-mode

# Agent works in ../worktrees/dark-mode/
# I continue working in main workspace

# Review and cleanup after merge
git worktree remove ../worktrees/dark-mode

Meu guard de recursão monitora o comportamento de spawn do agente. Meu guardião de segurança do Git impede que o agente faça force-push ou commit de credenciais. Esses hooks rodam automaticamente. Eu não supervisiono o agente durante a implementação.

Passo 4: Revisão

Uma notificação chega quando o agente conclui. Reviso o diff em relação aos critérios de aceitação do PRD. Se todos os critérios passam, faço o merge. Caso contrário, corrijo manualmente ou reinicio o agente com contexto atualizado.⁴

Onde o desenvolvimento orientado por PRD funciona

Endpoints CRUD com modelos de dados claros. O PRD especifica o modelo, as rotas e o formato de resposta. O agente gera boilerplate que segue os padrões existentes.

Adição de testes para código existente. “Escreva testes para app/content.py cobrindo load_post_by_slug com slug válido, slug inválido e arquivo ausente” produz testes úteis porque a função já existe e os critérios de aceitação são objetivos.

Componentes de UI seguindo padrões estabelecidos. “Adicione um filtro de categorias à página de listagem do blog usando o mesmo padrão de abas da página do guia” funciona porque o agente pode referenciar o padrão existente.

Migrações de banco de dados com schemas definidos. O PRD especifica colunas, tipos, valores padrão e restrições. O agente gera a migração e atualiza o modelo.

Onde o desenvolvimento orientado por PRD falha

Requisitos ambíguos. “Melhore o blog” não é um PRD. O agente fará mudanças, mas elas não corresponderão à sua intenção porque sua intenção não foi especificada.

Decisões arquiteturais inéditas. Quando precisei projetar o modelo de consenso do sistema de deliberação, nenhum PRD conseguia capturar a decisão. Precisei explorar opções, avaliar trade-offs e iterar no design. Isso exigiu minha skill de deliberação, não um PRD.

Otimização de performance. “Faça a página carregar mais rápido” exige profiling, medição e investigação iterativa. O agente não consegue analisar os padrões de tráfego da sua produção a partir de um PRD.

Código crítico de segurança. PRDs para sistemas de autenticação produzem código que lida com o caminho feliz. Casos extremos em autenticação (ataques de timing, fixação de sessão, CSRF em fluxos não padronizados) exigem expertise humana que PRDs não conseguem codificar.

Como meu template de PRD evoluiu

Versão 1 (Mês 1): User stories simples

As a user, I want to save preferences so I can customize my experience.

Problema: Vago demais. O agente fez suposições razoáveis porém erradas sobre mecanismo de armazenamento, posicionamento na UI e escopo.

Versão 2 (Mês 2): Adição de localização de arquivos

## Story: Save preferences
### Files to Modify
- app/routes/settings.py
- app/templates/settings.html

Problema: Melhor, mas os agentes ainda “melhoravam” arquivos adjacentes sem permissão.

Versão 3 (Mês 4): Adição de restrições

## Story: Save preferences
### Files to Modify (only these)
- app/routes/settings.py
- app/templates/settings.html
### Constraints
- No new dependencies
- Use existing database models
- Do not modify CSS

Problema: Os agentes às vezes ignoravam restrições quando elas conflitavam com “boas práticas” dos dados de treinamento.

Versão 4 (Atual): Exclusões explícitas + expectativas de testes

O template atual adiciona “Files NOT to Modify”, expectativas explícitas de testes e checkboxes de critérios de aceitação. Esta versão produz resultados previsíveis aproximadamente 85% das vezes. Os 15% restantes exigem uma segunda passada com instruções mais claras.⁵

A biblioteca de padrões de 30 PRDs

Após mais de 30 PRDs, padrões emergiram:

A taxa de sucesso para funcionalidades inéditas (50%) explica por que o desenvolvimento orientado por PRD complementa meu workflow em vez de substituí-lo. Metade das vezes, trabalho inédito exige iteração que PRDs não conseguem capturar antecipadamente.

Principais aprendizados

Para desenvolvedores solo: - Comece com um tipo de PRD bem definido (CRUD, testes) e valide o workflow antes de expandir para tarefas complexas - Adicione “Files NOT to Modify” a todo PRD; agentes vão prestativamente “melhorar” código que você não pediu para eles tocarem - Use git worktrees para isolar o trabalho do agente; o custo de limpeza de uma execução fracassada deve ser um comando, não uma sessão de arqueologia no Git

Para gestores de engenharia: - A qualidade do PRD determina a qualidade da saída do agente; invista em templates de PRD e processos de revisão antes de escalar o uso autônomo de agentes - Acompanhe a taxa de merge-sem-alterações para medir a maturidade do workflow; a taxa deve melhorar conforme os templates de PRD evoluem - Trabalho de arquitetura inédita e código crítico de segurança não devem ser delegados via PRD; reserve a delegação a agentes para tarefas bem definidas e repetíveis

Perguntas frequentes

O que é desenvolvimento orientado por PRD?

Desenvolvimento orientado por PRD é um workflow em que um Product Requirements Document define uma tarefa com especificidade suficiente para que um agente de IA consiga implementá-la de forma autônoma. O PRD inclui user stories, critérios de aceitação, localização de arquivos, restrições e expectativas de testes. O agente trabalha em um git worktree isolado enquanto você segue com outras tarefas. O padrão funciona melhor em tarefas bem definidas e repetíveis, como endpoints CRUD, adição de testes e componentes de UI seguindo padrões estabelecidos.

Quantos PRDs devo escrever antes de confiar no workflow?

Comece com 3 a 5 PRDs em uma única categoria na qual você tenha alta confiança sobre o resultado esperado, como adição de testes ou migrações de banco de dados. Na minha experiência, essas categorias alcançam taxas de sucesso em torno de 90%. Depois de validar que o template produz resultados previsíveis, expanda para componentes de UI (taxa de sucesso de cerca de 85%) e correções de bugs (cerca de 80%). Funcionalidades inéditas têm taxa de sucesso de aproximadamente 50% e não devem ser sua porta de entrada no desenvolvimento orientado por PRD.

Qual formato funciona melhor para PRDs usados com o Claude Code?

O formato de PRD mais eficaz tem cinco seções: uma user story com checkboxes de critérios de aceitação, uma lista “Files to Modify” com caminhos específicos, uma lista de exclusão “Files NOT to Modify”, expectativas de testes com cenários específicos e restrições (sem novas dependências, usar padrões existentes). A lista de exclusão foi de longe a maior melhoria do meu template, porque impede que os agentes modifiquem “prestativamente” código fora do escopo da tarefa.

O desenvolvimento orientado por PRD pode substituir a revisão de código humana?

Não. O desenvolvimento orientado por PRD substitui a etapa de implementação, não a de revisão. Todo PRD concluído ainda exige revisão humana em relação aos critérios de aceitação antes do merge. No meu workflow, uma notificação chega quando o agente conclui e eu reviso o diff critério por critério. O loop de qualidade e a verificação de testes independente complementam, mas não substituem, o julgamento humano sobre adequação arquitetural e correção.

Por que os agentes de IA às vezes ignoram as restrições do PRD?

Os agentes ignoram restrições quando elas conflitam com padrões dos dados de treinamento. Se o seu PRD diz “sem novas dependências” mas os dados de treinamento do modelo associam a tarefa a uma biblioteca específica, o modelo pode instalar a biblioteca mesmo assim. A solução são exclusões explícitas: listas como “Files NOT to Modify” e “não instalar” funcionam melhor do que restrições formuladas de forma positiva, porque dão ao agente um limite concreto em vez de uma diretriz genérica.

Referências