Spec-driven development no Cursor: como escrever a spec antes de pedir o código

O agente entrega em trinta segundos aquilo que você não pediu, e lá se vão duas horas desfazendo

Fala aí, beleza? Se você já roda o Cursor no dia a dia, conhece a cena: pedido vago, agente animado, dez arquivos alterados e uma feature inteira que ninguém encomendou 😅

O problema quase nunca é o modelo, é o pedido

Spec-driven development no Cursor é inverter essa ordem: você escreve a especificação antes do prompt, deixando registrado o que é escopo, o que NÃO é escopo e como saber que a coisa ficou pronta

Neste post eu mostro como encaixar esse fluxo com o que o editor já tem: arquivos de contexto em .cursor/rules, o AGENTS.md na raiz, o Plan Mode e uma revisão final contra critérios de aceite

Um aviso honesto antes de seguir: não existe um botão chamado "spec" no Cursor… o que existe é Rules, AGENTS.md e Plan Mode, e o método é montado em cima desses três, mais a sua revisão contra os critérios de aceite no fim

O que você precisa antes de escrever a spec

Checklist curtinho, nada de PC da Nasa aqui:

• Projeto sob controle de versão: as Project Rules vivem em .cursor/rules, dentro do repositório, versionadas junto do código. Ou seja, a spec anda com o projeto e o time inteiro pega ela no git pull
• Noção de onde cada camada de instrução mora: são três camadas (Project Rules, User Rules, que são globais do seu ambiente, e Team Rules, gerenciadas pelo dashboard do time), além do AGENTS.md na raiz, que o Cursor lê nativamente junto das outras
• A decisão de qual tipo de ativação a regra vai usar, tomada antes de escrever o arquivo

"Tipo de ativação?" É o dropdown que muda os campos do frontmatter e define quando aquela regra entra no contexto. São quatro, segundo a documentação de regras do Cursor:

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Como escrever a spec antes de pedir o código no Cursor (passo a passo)

1. Escreva o documento de escopo antes de abrir o chat

Três blocos, sem enfeite: o problema, o que está fora de escopo e os critérios de aceite em formato verificável

Critério verificável é aquele que alguém consegue conferir olhando a tela ou rodando o código, sem opinião no meio

O erro comum deste passo: escrever desejo no lugar de critério. "A tela tem que ficar boa" não dá pra verificar; "ao enviar o formulário sem e-mail, exibir erro no campo e não chamar a API" dá

Importante: o Cursor não reconhece nenhum formato mágico de critério de aceite. Isso aqui é prática de redação sua, não recurso do produto

2. Crie a regra dentro de .cursor/rules com extensão .mdc

A estrutura fica mais ou menos assim no repositório:

   meu-projeto/
     AGENTS.md
     .cursor/
       rules/
         escopo-checkout.mdc
     src/

O erro comum deste passo: salvar como .md. Um .md simples dentro de .cursor/rules é ignorado pelo sistema de regras, porque ele não tem o frontmatter de description, globs e alwaysApply. A extensão obrigatória é .mdc, e eu já vi gente jurar que "o Cursor não lê minhas regras" só por causa dessa letrinha

3. Preencha o frontmatter e escolha o tipo de ativação

O frontmatter YAML da regra .mdc usa exatamente três campos:

   ---
   description: Escopo e critérios de aceite do checkout
   globs: src/checkout/**
   alwaysApply: false
   ---

   ## Escopo
   Ajustar apenas o fluxo de pagamento em src/checkout

   ## Fora de escopo
   Não alterar o carrinho, não trocar a stack, não criar novas dependências

   ## Critérios de aceite
   1. Cartão recusado exibe mensagem no formulário e mantém os dados preenchidos
   2. Nenhum arquivo fora de src/checkout é modificado

O erro comum deste passo: deixar alwaysApply: true achando que os globs continuam filtrando. Não continuam. Com alwaysApply: true, os campos globs e description são ignorados e a regra entra sempre. Se você quer a regra anexada só quando um arquivo correspondente está no contexto, o combo é alwaysApply: false com globs preenchido

4. Use o AGENTS.md na raiz pra instrução persistente do projeto

O Cursor lê o AGENTS.md da raiz nativamente, junto de Project, Team e User Rules, seguindo a especificação aberta do arquivo

Pense nele como o "leia isso antes de encostar no projeto": convenções, o que nunca deve ser mexido, como as pastas estão organizadas

O erro comum deste passo: transformar o arquivo em depósito de tudo. O conteúdo de uma regra aplicada é inserido no INÍCIO do contexto do modelo, então texto morto ali não é decoração, é peso em toda sessão

5. Abra o Plan Mode com Shift + Tab e deixe ele perguntar

No campo de input do agente, Shift + Tab liga o Plan Mode: o agente pesquisa o codebase, faz perguntas de esclarecimento e entrega um plano revisável antes de sair implementando

Se você já usa o modo de plano no Claude Code, a ideia é a mesma: separar o "pensar" do "escrever"

O erro comum deste passo: responder as perguntas de esclarecimento na pressa, no modo "tanto faz, pode seguir". Cada resposta vaga aí vira decisão inventada lá na frente

6. Edite o plano em Markdown, é aqui que você corta o excesso

O plano gerado vira um arquivo Markdown editável, com file paths e code references, e você pode adicionar ou remover itens da lista de tarefas. Ele também suporta diagramas Mermaid inline, gerados dentro do próprio plano

Passe o olho item por item e apague tudo que não estava no seu documento de escopo

O erro comum deste passo: aprovar de bater o olho. Todo to-do que sobra vira código que alguém vai revisar depois

7. Salve com "Save to workspace" e versione

Esse botão grava o plano na pasta .cursor/plans/ do projeto

Aí o plano deixa de ser papo de chat e vira artefato do repositório, que sobrevive ao fechamento da sessão e entra no code review

8. Puxe o contexto certo na hora de executar, com @ mentions

O Cursor usa @ mentions pra trazer contexto específico pro chat. Entre os símbolos disponíveis estão @Files, @Folders, @Code, @Docs, @Git, @Past Chats, @Cursor Rules, @Web, @Link, @Recent Changes e @Lint Errors

Na prática: aponta o plano, aponta a regra com @Cursor Rules, aponta as pastas que ele pode tocar

O erro comum deste passo: mandar executar sem apontar nada e torcer pro agente adivinhar onde a coisa mora

9. Revise a entrega contra os critérios de aceite do passo 1

Não contra a sua memória do que você queria, contra o texto escrito lá atrás

Critério que não passa é tarefa não concluída, e não "quase lá"

Como isso funciona na prática: o método rodando num projeto real

Esse fluxo eu rodei num projeto meu, com o Claude Code, o agente que mais uso hoje. A tela muda de produto pra produto, a ordem não: spec primeiro, agente depois

O fluxo foi esse: primeiro eu montei a documentação em arquivos separados, requisitos, design e tarefas, e só DEPOIS abri o agente

São os mesmos blocos do passo 1, só espalhados em arquivos: o escopo e os critérios de aceite moram no de requisitos, o fora de escopo vira restrição explícita no design e no prompt de regras, e a ordem de execução vira o de tarefas

Pedi que ele lesse os documentos e gerasse um arquivo de contexto condensado, porque sem isso o conhecimento se perde quando a sessão fecha, e a versão resumida ainda gasta menos token

O prompt de regras que eu uso ali manda seguir exatamente os documentos, não adicionar funcionalidade fora dos requisitos, não mudar a stack definida no design e executar uma tarefa por vez

Na hora de executar eu referencio a tarefa pelo número do documento de tarefas e peço pro agente PARAR quando terminar. Mesmo que o modelo tenda a parar sozinho, eu prefiro ser explícito a ser implícito

A sequência rodou tarefa a tarefa: setup do projeto, depois autenticação, depois o gerador de QR code

A autenticação saiu em cerca de 2 minutos, e no fim eu subi o projeto na porta 3002, gerei um QR code, baixei o PNG e escaneei pra confirmar que abria a minha plataforma mesmo 🙂

Dois números de UMA demonstração, na minha máquina, num projeto pequeno: isso é observação, não é benchmark, e eu não vou te vender como promessa

O que eu senti de verdade ali: a etapa inicial é mais demorada, escrever a spec dá trabalho

Mas depois que a base está documentada os prompts ficam curtos e simples, porque não é mais preciso caprichar em cada pedido, e as tarefas seguintes ficam mais rápidas e previsíveis

Minha régua prática pra decidir se compensa: se o projeto passa de três prompts, ou se já dá pra prever autenticação, pagamento, perfis de usuário e dashboard, então vale aplicar SDD. Pra uso pessoal simples, nem sempre precisa

No vídeo eu mostro também uma alternativa automatizada, um framework que faz perguntas sobre o sistema e cria a estrutura de documentos sozinho, em fases, em vez de você escrever os arquivos à mão. Se for por esse caminho, minha recomendação é ler o repositório e comparar as versões antes de adotar

Veja o fluxo completo em vídeo

No vídeo abaixo você vê a documentação sendo montada, o arquivo de contexto condensado sendo gerado e as tarefas saindo uma a uma até o QR code funcionar de verdade

A spec foi ignorada pelo agente: o que checar

Escreveu a regra, o agente fez o que quis, e agora? Três casos que aparecem sempre

1. A regra nunca entra no contexto

Sintoma: o agente age como se o arquivo não existisse, em qualquer conversa

Causa: o arquivo foi salvo como .md dentro de .cursor/rules. Um .md simples é ignorado pelo sistema de regras, ele não tem o frontmatter de description, globs e alwaysApply

Correção: renomeie pra .mdc e preencha o frontmatter

2. A regra entra sempre, até onde não deveria

Sintoma: uma regra específica de uma pasta aparece influenciando tarefa que não tem nada a ver

Causa: alwaysApply: true sobrepõe globs e description, então a regra entra em toda sessão

Correção: troque pra alwaysApply: false com globs preenchido, assim ela é anexada só quando um arquivo correspondente está no contexto

3. A regra existe, mas não é puxada na conversa certa

Sintoma: às vezes funciona, às vezes não, e você jura que não mudou nada

Causa: a ativação está em Apply Manually, que só entra quando a regra é @-mencionada no chat

Correção: mencione com @Cursor Rules naquela conversa, ou troque o tipo de ativação no dropdown

E a prevenção pros três: lembre que o conteúdo da regra aplicada é inserido no início do contexto do modelo. O que está escrito ali pesa na sessão inteira, então regra enxuta e específica rende mais que manifesto de dez páginas

Quando vale escrever a spec antes (e quando é só burocracia)

Vale a pena quando:

• A feature toca vários arquivos e você já consegue prever o efeito colateral
• É refactor com regra de negócio no meio, daqueles em que "funciona" não basta
• Outra pessoa vai revisar o código, e o plano salvo em .cursor/plans/ vira histórico de decisão versionado junto
• O projeto é novo e já nasce com múltiplas features, banco de dados e API

É só burocracia quando:

• É ajuste de uma linha, um texto, um espaçamento
• Você está explorando, ainda sem saber o que quer
• É protótipo descartável, daqueles que morrem sexta à noite

Em time tem duas peças que se encaixam bem aqui: as Team Rules, gerenciadas pelo dashboard do time, e as Agent Skills, definidas em arquivos SKILL.md, que o agente invoca quando são relevantes

E tem um detalhe que aumenta o valor da spec: o Cursor 3, disponível desde 2 de abril de 2026, executa vários agentes em paralelo entre repositórios e ambientes. Quanto mais agente rodando ao mesmo tempo, menos você consegue vigiar prompt por prompt, e mais o escopo escrito faz o trabalho por você

O Plan Mode, aliás, já vinha apanhando melhoria antes disso, nos changelogs 2.1 e 2.2

Próximo passo: escreva a spec do seu próximo commit

A ideia central é simples e chata de aceitar: o escopo escrito ANTES é o que evita o retrabalho depois

Não tem prompt mágico que substitua isso, e quem já refez feature inteira porque "faltou combinar" sabe do que eu tô falando 😅

Próximo passo pequeno, pra hoje mesmo: pega a próxima tarefa da sua fila, escreve os critérios de aceite dela, cria uma regra .mdc em .cursor/rules, abre o Plan Mode com Shift + Tab e salva o plano no workspace antes de deixar o agente escrever a primeira linha

Depois me conta nos comentários o que quebrou no seu fluxo: regra ignorada, plano aprovado com pressa ou agente saindo da curva mesmo com tudo documentado?

Até o próximo post!