# Desenvolvimento baseado em especificações com Claude Code e Cursor Canonical: https://specscore.md/pt-br/articles/claude-code-specs/ Última atualização: 6 de novembro de 2026 [Claude Code](https://code.claude.com/docs/en/overview) é uma ferramenta de programação agêntica que lê uma base de código, edita arquivos e executa comandos. [Cursor](https://cursor.com/docs/rules) é o editor cujas regras de projeto ficam em `.cursor/rules` como arquivos `.mdc`. O [desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/) (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](https://specscore.md/), uma [especificação de funcionalidade](https://specscore.md/feature-specification) é o arquivo de uma capacidade do produto, um [requisito](https://specscore.md/requirement-specification) (REQ) é uma regra nomeada dentro dessa funcionalidade, e um [critério de aceitação](https://specscore.md/acceptance-criteria-specification) (AC) é uma condição abstrata opcional que aponta para uma ou mais dessas regras. A [integração contínua](https://specscore.md/pt-br/validators/) (CI) é uma verificação automática em cada mudança proposta. A verificação é um comando da [interface de linha de comando](https://specscore.md/pt-br/cli/) (CLI), `specscore spec lint`, da CLI em [specscore/specscore-cli](https://github.com/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. ## 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](https://specscore.md/pt-br/articles/feature-spec-template/). `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](https://specscore.md/pt-br/articles/lint-specs-in-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](https://github.com/specscore/specscore-cli/blob/main/README.md) 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](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) em [specscore/specscore-cli](https://github.com/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. ```text 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. ```text 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](https://specscore.md/feature-specification) 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](https://specscore.md/pt-br/cli/install/). 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](https://specscore.md/pt-br/articles/feature-spec-template/). 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](https://specscore.md/pt-br/articles/lint-specs-in-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](https://github.com/specscore/ai-plugin-specscore), sob a [licença MIT](https://github.com/specscore/ai-plugin-specscore/blob/main/LICENSE). O [README das skills](https://github.com/specscore/ai-plugin-specscore/blob/main/skills/README.md) dele diz que os usuários invocam `/specscore:`. 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](https://specscore.md/pt-br/ai/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](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md) 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](https://specscore.md/pt-br/ai/specstudio-skills/) é o fluxo de trabalho guiado. O repositório é [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills), sob a [licença MIT](https://github.com/specscore/specstudio-skills/blob/main/LICENSE). 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](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) em [specscore/specscore](https://github.com/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](https://specscore.md/pt-br/articles/lint-specs-in-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](https://github.com/specscore/specscore/blob/main/LICENSE) em [specscore/specscore](https://github.com/specscore/specscore). A licença da CLI é [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE) em [specscore/specscore-cli](https://github.com/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](https://specscore.md/pt-br/spec-driven-development/tools/) 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](https://github.com/Fission-AI/OpenSpec) documenta `openspec validate` na sua [referência da CLI](https://openspec.dev/docs/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](https://github.com/eyaltoledano/claude-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](https://github.github.io/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](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) 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](https://specscore.md/pt-br/articles/lint-specs-in-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. - [Claude Code — visão geral (CLAUDE.md)](https://code.claude.com/docs/en/overview) - [Cursor — Regras (as regras de projeto são arquivos .mdc)](https://cursor.com/docs/rules) - [specscore-cli — funcionalidade agent-setup](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) - [specscore-cli — README (agent setup e instalação do plugin)](https://github.com/specscore/specscore-cli/blob/main/README.md) - [specscore/specscore-cli](https://github.com/specscore/specscore-cli) - [specscore-cli — licença Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE) - [specscore/specscore](https://github.com/specscore/specscore) - [specscore/specscore — licença CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE) - [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) - [specscore/ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore) - [ai-plugin-specscore — licença MIT](https://github.com/specscore/ai-plugin-specscore/blob/main/LICENSE) - [ai-plugin-specscore — README das skills](https://github.com/specscore/ai-plugin-specscore/blob/main/skills/README.md) - [ai-plugin-specscore — README (cópia para o Cursor)](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md) - [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills) - [specstudio-skills — licença MIT](https://github.com/specscore/specstudio-skills/blob/main/LICENSE) - [specstudio-skills — README (versão 0.0.7)](https://github.com/specscore/specstudio-skills/blob/main/README.md) - [CLI Skills](https://specscore.md/pt-br/ai/cli-skills/) - [SpecStudio Skills](https://specscore.md/pt-br/ai/specstudio-skills/) - [Modelo de PRD em Markdown para programar com IA](https://specscore.md/pt-br/articles/feature-spec-template/) - [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/) - [Especificação de funcionalidade](https://specscore.md/feature-specification) - [Especificação de critérios de aceitação](https://specscore.md/acceptance-criteria-specification) - [Referência da CLI do OpenSpec — openspec validate](https://openspec.dev/docs/cli) - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) - [eyaltoledano/claude-task-master](https://github.com/eyaltoledano/claude-task-master) - [Documentação do GitHub Spec Kit (data da página 28 de setembro de 2026)](https://github.github.io/spec-kit/) - [Ferramentas de desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/tools/) ## Relacionados - [Modelo de PRD em Markdown para programar com IA](https://specscore.md/pt-br/articles/feature-spec-template/) - [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/) - [Como escrever critérios de aceitação que um agente de IA possa verificar](https://specscore.md/pt-br/articles/acceptance-criteria/) - [Sintaxe de requisitos EARS explicada, com exemplos](https://specscore.md/pt-br/articles/ears-requirements/) - [Desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/) - [Ferramentas de desenvolvimento baseado em especificações](https://specscore.md/pt-br/spec-driven-development/tools/) - [CLI Skills](https://specscore.md/pt-br/ai/cli-skills/) - [SpecStudio Skills](https://specscore.md/pt-br/ai/specstudio-skills/) - [CLI](https://specscore.md/pt-br/cli/) - [Especificação de funcionalidade](https://specscore.md/feature-specification)