6 documentos para escrever antes de pedir um app para a IA

Quando você pede um app sem dar detalhes, a IA precisa decidir sozinha o que você não disse: quem usa, quais telas existem, que banco de dados entra, qual é o visual. Cada decisão dessas é um palpite. A autora do post salvo defende escrever seis documentos antes do pedido, nesta ordem: PRD, TRD, fluxo do app, briefing de design, esquema do back-end e plano de implementação. A lista é dela, não um padrão oficial, mas a ideia por trás é bem sustentada pelas fontes oficiais.

A documentação de boas práticas do Claude Code diz que as sessões dão errado, na maior parte das vezes, porque o Claude não tem informação que não consegue tirar do código. Ela recomenda dizer o que você quer, o que significa estar pronto e quais são as preferências entre abordagens possíveis. Para quem ainda não sabe bem o que quer, o guia sugere pedir que o Claude entreviste você até conseguir escrever a especificação e a salve em um arquivo SPEC.md. Depois, a recomendação é começar uma sessão nova para construir a partir desse arquivo, com o contexto limpo e uma definição escrita do que é concluído.

O GitHub Spec Kit, um kit de código aberto com licença MIT, leva a mesma ideia mais longe e chama o método de desenvolvimento orientado a especificação. A especificação vira a fonte da verdade e o código é gerado a partir dela. O fluxo tem uma constituição com os princípios do projeto, a especificação (o que os usuários precisam e por quê, sem falar de tecnologia), o plano técnico, a lista de tarefas e a implementação. Quando algo está ambíguo, os modelos do kit mandam a IA marcar com NEEDS CLARIFICATION em vez de adivinhar. Lovable, v0 e Cursor dizem algo parecido em seus guias: defina o produto, o contexto de uso, as restrições e o visual antes de gerar, e use o modo de planejamento para a ferramenta fazer perguntas antes de escrever código.

Compare a lista da autora com o que as fontes mostram. O PRD corresponde à especificação do Spec Kit (spec.md). O TRD, que nenhuma fonte oficial chama por esse nome, corresponde ao plano técnico (plan.md). O esquema do back-end corresponde ao modelo de dados e aos contratos de API que o Spec Kit gera junto com o plano. O plano de implementação corresponde à lista de tarefas (tasks.md). O fluxo do app e o briefing de design não são arquivos do Spec Kit, mas o Lovable recomenda mapear a jornada do usuário e definir a direção de design antes de construir, e o v0 pede contexto de uso e restrições visuais. Ou seja: seis documentos é uma boa forma de organizar, não uma regra. O que vale é a ordem do menos técnico para o mais técnico.

Esqueleto do PRD, que diz o que construir e por quê. Escreva as seções: problema; público e seus contextos de uso; objetivo em uma frase; funcionalidades obrigatórias, cada uma com critério de aceite; fora do escopo; como saber se deu certo. Não fale de tecnologia aqui. Essa separação vem do modelo de especificação do Spec Kit, que manda focar no que os usuários precisam e por quê.

Esqueleto do TRD, que diz com o que construir. Escreva: linguagem e framework; onde o app roda; serviços externos; autenticação; regras de desempenho e segurança; bibliotecas permitidas e proibidas; para cada escolha, o motivo. O Spec Kit pede justamente que o plano técnico registre a justificativa de cada decisão, para a IA não trocar uma escolha sua por outra sem avisar.

Esqueleto do fluxo do app: lista de telas; para cada tela, o que a pessoa vê e quais ações pode fazer; para cada ação, para onde ela leva; o caminho principal do início ao fim (por exemplo, entrar, criar, salvar, compartilhar); e os estados de carregando, vazio e erro. O guia do Lovable recomenda mapear a jornada do usuário e pensar em estados de login, dados dinâmicos, carregamento, vazio e erro antes de construir.

Esqueleto do briefing de design: estilo em poucas palavras (por exemplo, calmo e elegante); cores com os códigos; fontes; espaçamento e cantos; componentes principais; comportamento em celular e computador; regras de acessibilidade; referências de telas que você gosta. O Lovable lista diretrizes de design (cores, tipografia, layout) entre o que vale guardar nas instruções do projeto, e o v0 recomenda informar estilo, plataforma, layout, sistema de cores e responsividade. Você também pode colar uma captura de tela como referência.

Esqueleto do esquema do back-end: lista de tabelas; para cada tabela, os campos e seus tipos; chaves e relações entre tabelas; quem pode ler e escrever cada dado; endpoints ou funções com entrada e saída; variáveis de ambiente necessárias (só os nomes, nunca os valores). Esqueleto do plano de implementação: etapas pequenas em ordem, cada uma com o que muda, como testar e o que significa concluído, começando pelo mínimo que roda. Dividir em etapas está alinhado ao Spec Kit, que gera uma lista de tarefas a partir do plano, e ao Lovable, que recomenda construir um componente por vez.

Na prática com um agente: crie uma pasta docs na raiz do projeto e salve cada documento nela em Markdown. Peça à IA para escrever cada um e responda às perguntas dela; no Claude Code, você pode usar o pedido de entrevista que a documentação sugere. Revise cada documento antes de passar ao próximo. Depois, crie um CLAUDE.md curto na raiz, que o Claude Code lê no início de toda sessão (o comando /init gera uma primeira versão). Nele, aponte para os documentos com a sintaxe @docs/prd.md. A documentação recomenda manter o arquivo abaixo de 200 linhas e avisa que arquivos importados também entram no contexto, então escreva ali só o essencial. Se o seu repositório já usa AGENTS.md, o Claude Code lê esse arquivo quando não há CLAUDE.md. Antes de construir, entre no modo de planejamento com Shift+Tab (ou claude --permission-mode plan): o Claude lê e propõe um plano sem editar nada até você aprovar. O Cursor tem um modo parecido, também aberto com Shift+Tab.

Cuidados. Documento não garante resultado: a documentação do Claude Code trata o CLAUDE.md como contexto, não como regra imposta, e regras que não podem ter exceção pedem outro mecanismo, como hooks. Documentos longos demais pioram a atenção da IA, então prefira esqueletos enxutos e atualize-os quando decidir mudar algo, ou eles passam a contradizer o código. Não coloque senhas, chaves ou tokens em nenhum desses arquivos. Se quiser a versão completa do método, o Spec Kit exige Python 3.11 ou mais novo e a ferramenta uv; veja o passo a passo no repositório oficial. O post promete 6 modelos prontos; este guia não os usa e não os avaliou. Os esqueletos acima foram montados a partir do que as fontes oficiais pedem.