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

Referências