Desenvolvimento baseado em especificações com Claude Code e Cursor

Claude Code é uma ferramenta de programação agêntica que lê uma base de código, edita arquivos e executa comandos. Cursor é o editor cujas regras de projeto ficam em .cursor/rules como arquivos .mdc. O desenvolvimento baseado em especificações (SDD) é a prática de escrever a especificação antes do código e tratar a especificação como a fonte da verdade. Um documento de requisitos de produto (PRD) é a prosa que enuncia o problema e o escopo antes de partir o trabalho em tarefas. No SpecScore, uma especificação de funcionalidade é o arquivo de uma capacidade do produto, um requisito (REQ) é uma regra nomeada dentro dessa funcionalidade, e um critério de aceitação (AC) é uma condição abstrata opcional que aponta para uma ou mais dessas regras. A integração contínua (CI) é uma verificação automática em cada mudança proposta. A verificação é um comando da interface de linha de comando (CLI), specscore spec lint, da CLI em specscore/specscore-cli. Nesta página, as especificações do Cursor são esse arquivo de funcionalidade junto com a regra de projeto do Cursor que diz ao agente para fazer o lint dele.

Última atualização: 6 de novembro de 2026

O que vai na funcionalidade e o que vai no arquivo do agente

O arquivo da funcionalidade contém a obrigação. Um README de funcionalidade sob spec/features/ traz as regras #### REQ: e os critérios ### AC:. A forma preenchida, o plano e a tarefa são o modelo de PRD em Markdown. specscore spec lint verifica essa forma: cabeçalhos, seções obrigatórias, linhas do índice e referências. Não decide se a ideia de produto é boa. Lintar especificações na CI é o relato mais longo do comando.

O arquivo do agente contém as instruções para uma ferramenta. A visão geral da Anthropic diz que CLAUDE.md é um arquivo Markdown na raiz do projeto que o Claude Code lê no início de cada sessão. A documentação de regras do Cursor diz que uma regra de projeto é um arquivo .mdc em .cursor/rules e que um arquivo .md simples nesse diretório é ignorado porque não tem frontmatter. Esses arquivos dizem ao agente como trabalhar no repositório. Não são a especificação que o linter verifica. Um requisito que existe só em CLAUDE.md ou só em .cursor/rules/specscore.mdc é invisível para specscore spec lint.

O que specscore agent setup escreve

O README da CLI diz que specscore agent setup escreve o arquivo de instruções de cada agente e, quando esse agente tem um diretório de skills, copia para ele os pacotes de skills do SpecScore. O comando ignora um arquivo existente, a menos que você passe --force. O contrato é a funcionalidade agent-setup em specscore/specscore-cli.

Esse contrato mapeia o id de caller claude para CLAUDE.md e .claude/skills/, e o id de caller cursor para .cursor/rules/specscore.mdc e .cursor/skills/. Execute o comando dentro de um projeto que já tem specscore.yaml. Se esse arquivo falta, o comando sai com o código 6 e a mensagem sugere specscore init. Uma invocação que nomeia os dois agentes é specscore agent setup claude,cursor. A funcionalidade diz que uma lista separada por vírgulas é o mesmo que argumentos separados. Os diretórios pai são criados. Cada caminho é informado como adicionado, modificado ou ignorado.

O CLAUDE.md gerado inclui o título do projeto, exemplos de CLI que passam --caller claude e a linha de instalação /plugin install specscore@specscore. O arquivo do Cursor é Markdown com frontmatter YAML. O frontmatter contém description e alwaysApply: true. A tabela de regras do Cursor diz que alwaysApply: true significa que a regra entra em todo chat. --no-skills escreve os arquivos de instruções e não copia os pacotes de skills. A mesma tabela do contrato também nomeia codex, copilot, antigravity.google, pi.dev, opencode e deepseek. Esta página segue os dois agentes do título.

Escreve os arquivos do Claude Code e do Cursor. Execute-o num projeto que tem specscore.yaml.

specscore agent setup claude,cursor

Caminhos que o contrato atribui a claude e cursor. Os diretórios de skills não são criados quando você passa --no-skills. Um arquivo existente permanece como está, a menos que você passe --force.

CLAUDE.md
.claude/skills/
.cursor/rules/specscore.mdc
.cursor/skills/

O arquivo de instruções aponta para a árvore de funcionalidades. Ele não a substitui. Depois do setup, o Claude Code ainda tem de ler spec/features/, e a regra do Cursor ainda tem de apontar para a mesma árvore. A especificação de funcionalidade continua sendo o documento que specscore spec lint aceita ou rejeita.

Executar specscore spec lint no ciclo

Instale a CLI primeiro. Os métodos de instalação estão na página de instalação. Depois mantenha a funcionalidade e o linter no mesmo ciclo do agente.

Escreva a funcionalidade antes do prompt

Adicione o README da funcionalidade, a linha do índice de funcionalidades e specscore.yaml usando o modelo de PRD. Ponha cada obrigação sob ## Behavior como #### REQ: {slug}. Aponte os critérios de aceitação para esses ids com **Requirements:**. Deixe CLAUDE.md e .cursor/rules/ para o passo seguinte.

Linte antes de o agente editar o código

Execute specscore spec lint no repositório. Uma árvore limpa imprime 0 violations found e sai com o código 0. O relatório de falha — arquivo, linha, severidade, regra, mensagem — está em Lintar especificações na CI. Corrija a funcionalidade até esse comando ficar limpo. Um agente que parte de uma funcionalidade que o linter já rejeita vai copiar a forma quebrada.

Aponte Claude Code e Cursor para a árvore

Execute specscore agent setup claude,cursor. Leia os arquivos adicionados CLAUDE.md e .cursor/rules/specscore.mdc e confirme que eles nomeiam a árvore de especificações e a CLI, inclusive --caller. Se um dos arquivos já existia, o comando o ignora. Passe --force só quando a intenção é substituir esse arquivo.

Peça uma tarefa que nomeie um critério

Na sessão do agente, nomeie a funcionalidade e o critério de aceitação que o trabalho tem de satisfazer. Uma tarefa de plano faz isso com **Verifies:** e um id de critério de aceitação. Peça ao agente para executar specscore spec lint de novo antes de terminar e para alterar o arquivo da funcionalidade quando o comportamento mudar. O arquivo de instruções diz ao agente para executar o comando. O arquivo da funcionalidade é o que o comando verifica.

Skills que expõem lint, feature e task

As linhas de instalação no README da CLI para o plugin wrapper são /plugin marketplace add specscore/ai-marketplace e /plugin install specscore@specscore. O repositório do plugin é specscore/ai-plugin-specscore, sob a licença MIT. O README das skills dele diz que os usuários invocam /specscore:<skill-name>. Os wrappers distribuídos incluem /specscore:spec, que encapsula specscore spec lint; /specscore:feature, que encapsula specscore feature (list, info, tree, deps, refs, new e change-status); e /specscore:task, que encapsula specscore task. /specscore:change-status cobre as mudanças de status de funcionalidade e de ideia. A página CLI Skills neste site é esse wrapper. specscore agent setup copia esses pacotes de skills para .claude/skills/ e .cursor/skills/, a menos que você passe --no-skills.

O README do plugin diz que o Cursor não tem um comando de instalação remota e carrega as skills de .cursor/skills/ no projeto ou de ~/.cursor/skills/. A cópia manual que ele mostra é git clone de ai-plugin-specscore e cp -R de skills/* para .cursor/skills/. specscore agent setup cursor é o comando que faz essa cópia por você, a partir do marketplace que a especificação de funcionalidade nomeia.

SpecStudio Skills é o fluxo de trabalho guiado. O repositório é specscore/specstudio-skills, sob a licença MIT. A linha de instalação do Claude Code no README dele é /plugin install specstudio@specscore, e diz que o Claude Code instala o plugin specscore como dependência. A seção de status nomeia a versão 0.0.7 e diz que as skills ideate, specify, plan, implement, verify e recap estão ativas o bastante para dogfood. A tabela de inventário do mesmo README documenta specstudio:ideate e specstudio:specify em detalhe. Essas skills escrevem artefatos SpecScore. Elas não substituem specscore spec lint.

O mesmo comando na CI

dogfood.yml em specscore/specscore define SPECSCORE_VERSION como v0.39.1 e executa specscore spec lint em pull requests e em pushes para a main. O trecho do workflow e o relatório de texto estão em Lintar especificações na CI. Uma funcionalidade que quebra um cabeçalho faz esse job falhar, quer o arquivo tenha sido escrito pelo Claude Code, quer pelo Cursor. O ciclo do agente e a CI chamam o mesmo comando.

A licença do formato é CC BY 4.0 em specscore/specscore. A licença da CLI é Apache-2.0 em specscore/specscore-cli.

Outras ferramentas de desenvolvimento baseado em especificações publicam verificações diferentes. As frases abaixo usam só o que as próprias páginas desses projetos dizem. O guia de ferramentas registra as mesmas páginas como lidas em 30 de outubro de 2026, exceto a página inicial da documentação do Spec Kit, que imprime 28 de setembro de 2026.

OpenSpec documenta openspec validate na sua referência da CLI. Esse comando verifica a estrutura de change e de spec do OpenSpec. Ele não verifica um cabeçalho SpecScore ### AC:.

O README do Task Master descreve a análise de um PRD em tarefas com task-master parse-prd. Não descreve um linter para esse PRD.

GitHub Spec Kit descreve um fluxo de trabalho de agente cujas fases escrevem artefatos Markdown. Essa página inicial da documentação não descreve um comando que linta um README de funcionalidade SpecScore na CI.

Perguntas frequentes

O que é Claude Code spec-driven development?

É escrever a funcionalidade SpecScore antes de o Claude Code escrever o código e depois manter CLAUDE.md como o arquivo de instruções que aponta para essa funcionalidade. A funcionalidade contém os requisitos (REQ) e os critérios de aceitação (AC). specscore spec lint verifica a funcionalidade. specscore agent setup claude escreve CLAUDE.md num projeto que já tem specscore.yaml.

Para onde vão as especificações do Cursor?

A obrigação do produto vai no README da funcionalidade sob spec/features/. A regra de projeto do Cursor vai em .cursor/rules/specscore.mdc. Os arquivos de skills vão em .cursor/skills/. specscore agent setup cursor escreve a regra e, a menos que você passe --no-skills, copia os pacotes de skills. A própria documentação do Cursor é a fonte de como as regras .mdc são aplicadas.

CLAUDE.md substitui a especificação de funcionalidade?

Não. CLAUDE.md é o que o Claude Code lê como instruções. O README da funcionalidade é o que specscore spec lint verifica. A funcionalidade agent-setup diz que o arquivo gerado ensina ao agente a árvore de especificações e os comandos da CLI. Não diz que o arquivo de instruções é a especificação.

E se CLAUDE.md ou a regra do Cursor já existir?

O comando ignora o arquivo existente e imprime uma linha de ignorado que menciona --force. Os bytes existentes permanecem. Passe --force só quando a substituição é o que você quer. A mesma regra de ignorar vale para um arquivo de skill que já está presente.

Qual skill executa o linter?

No README das skills do plugin, /specscore:spec encapsula specscore spec lint. Você também pode executar esse comando da CLI, na sessão do agente ou na CI. /specscore:feature e /specscore:task encapsulam os comandos de funcionalidade e de tarefa. Eles não lintam por si.

O linter avalia a prosa?

Não. specscore spec lint verifica a estrutura. Lintar especificações na CI mostra o relatório. Uma verificação estrutural limpa não é uma revisão de produto.

Fontes

O comportamento de agent-setup é o contrato em specscore-cli spec/features/cli/agent/setup/README.md na main, lido em 6 de novembro de 2026. Os nomes das skills vêm de ai-plugin-specscore skills/README.md na main, lido no mesmo dia. A linha de instalação do SpecStudio e a lista de status da versão 0.0.7 vêm de specstudio-skills README.md na main, lido no mesmo dia. A descrição do Claude Code e a frase sobre CLAUDE.md vêm de code.claude.com/docs/en/overview. Os caminhos das regras de projeto do Cursor vêm de cursor.com/docs/rules. dogfood.yml neste repositório fixa SPECSCORE_VERSION em v0.39.1. As páginas de concorrentes são as ligadas abaixo; o guia de ferramentas as registra como lidas em 30 de outubro de 2026, exceto a página inicial da documentação do Spec Kit, que imprime 28 de setembro de 2026.