Primeiro vem a spec.E lê-a antes do código.

O ciclo: spec, revisão, plano, revisão, tarefas, build

Em vez de um grande prompt e uma pilha de código, o trabalho passa por documentos, cada um verificado por si antes de o seguinte ser escrito.

1. Spec: o quê e porquê

   O que a funcionalidade tem de fazer, para quem e o que não deve fazer. Ainda sem nomes de ficheiros nem escolhas de tecnologia.

2. Plano: como

   A abordagem: que partes mudam, por que ordem, com que riscos. O plano responde à spec.

3. Tarefas: passos pequenos

   Uma checklist que o agente pode percorrer e assinalar, cada tarefa pequena o suficiente para ser verificada.

4. Build

   Só agora o agente escreve código, a partir de documentos que já leu.

Um modelo curto de spec

Uma spec não precisa de ser longa. Seis títulos bastam para apanhar a maioria dos mal-entendidos:

# Feature name

## Goal
## Non-goals
## Users
## Requirements
## Edge cases
## Open questions

Non-goals e Open questions são os que as pessoas saltam e de que os agentes mais precisam. Um agente a quem se diz o que não construir, e o que ainda está por decidir, pergunta em vez de adivinhar.

Fazê-lo no Claude Code, no Codex e no Cursor

Os três podem escrever os documentos, e cada um tem um plan mode para o passo de planeamento: plan mode do Claude Code, plan mode do Codex e plan mode do Cursor.

Para tornar o passo de revisão automático, ponha uma regra no CLAUDE.md ou no AGENTS.md: depois de escrever uma spec ou um plano, enviá-lo para revisão no DotMD com request_review e esperar. O agente pára então depois de cada documento e espera pelos seus comentários ou pela sua aprovação, sem gastar tokens enquanto espera. O DotMD pode acrescentar a regra por si: veja CLAUDE.md e AGENTS.md.

Uma revisão que escala

O chat é um mau sítio para rever um documento. Leia antes a spec formatada no DotMD, selecione a passagem errada e prima ⌥⌘M. O comentário fica ligado às suas linhas, por isso o agente sabe exatamente o que quer dizer. Pode escrever primeiro todos os comentários e enviá-los de uma vez.

Quando o agente os tiver corrigido, cada alteração é mostrada no ficheiro: texto antigo a vermelho, texto novo a verde, junto ao comentário a que responde. Accept ou Reopen para cada uma. O DotMD também lista as alterações que ninguém pediu. Veja Rever alterações.

Para uma segunda opinião, deixe outro agente rever primeiro. Uma spec escrita pelo Claude Code e comentada pelo Codex chega-lhe com as lacunas óbvias já marcadas, e é você quem decide que observações chegam a quem a escreveu: Um agente revê o outro.

Ferramentas para o desenvolvimento orientado por specs

• Markdown simples no repositório. Uma pasta docs/specs e o modelo acima são uma configuração completa.
• Os plan modes. A forma própria de cada agente planear antes de construir.
• GitHub Spec Kit. Um toolkit de código aberto que dá ao seu agente comandos para cada passo e escreve spec.md, plan.md e tasks.md por si: GitHub Spec Kit.

Seja qual for a sua escolha, os documentos são ficheiros Markdown, e o DotMD lê qualquer um deles.

Perguntas sobre o desenvolvimento orientado por specs

Mais perguntas