Cursor Rules: como configurar regras para projetos TypeScript

O ganho está em reduzir o retrabalho na revisão. Em uma conta ilustrativa, quatro desenvolvedores que fazem três correções de cinco minutos por semana gastam 60 minutos repetindo convenções. Isso não é uma promessa de economia. Conte quais correções deixam de ser necessárias após a configuração e desconte o tempo de manutenção das regras. O custo da assinatura é outra questão, abordada no artigo sobre preços do Cursor.

Onde configurar as Cursor Rules

Mantenha as decisões de código compartilhadas junto do código. As preferências pessoais de resposta devem continuar no âmbito pessoal.

As instruções de um AGENTS.md em um subdiretório valem para esse diretório e seus descendentes, em conjunto com as orientações dos diretórios superiores; as mais específicas têm prioridade. Para as regras de equipe, projeto e usuário, a ordem documentada em caso de conflito é Team → Project → User. Referência de regras do Cursor

Para uma equipe pequena, minha escolha padrão são as regras de projeto. Uma instrução como “use nossos componentes de formulário existentes” pertence ao repositório. “Seja breve na resposta final” é uma preferência sua. Separar essas decisões evita que uma preferência pessoal vire política da equipe sem querer.

Como definir quando cada regra entra no contexto

O frontmatter, aquele pequeno bloco de configurações acima do texto da regra, define quando ela é incluída no contexto.

Na seleção pelo agente, ele escolhe a regra com base na descrição. Um glob é um padrão de caminho de arquivo. Sintaxe e critérios de aplicação

Pense na inclusão da regra como a entrega de uma ordem de serviço à bancada certa. Uma instrução muito bem escrita não ajuda em uma tarefa que nunca a recebe. Aplique os requisitos básicos de segurança a todas as tarefas, direcione as orientações de estilo aos arquivos relevantes e deixe a seleção a critério do agente quando a pertinência da orientação depender da tarefa.

Três regras prontas para copiar em uma aplicação web com TypeScript

Crie os arquivos abaixo no repositório. Eles trazem sugestões de convenções para o seu projeto, com os campos de frontmatter e a sintaxe de padrões da referência do Cursor. As instruções são pontos de partida para adaptar, e não padrões de código prescritos pelo Cursor.

Estilo: aplique a regra aos arquivos TypeScript

Salve em .cursor/rules/style.mdc:

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

- Follow the nearest existing module's naming and import conventions.
- Prefer named exports unless the framework requires a default export.
- Reuse existing UI components and utilities before adding alternatives.
- Keep formatting in the repository's formatter and linter configuration.

O exemplo pressupõe que o código da aplicação fica em src/; ajuste os caminhos à estrutura do repositório. O foco, de propósito, são decisões que um formatador não resolve, como saber se a aplicação já tem um botão adequado ou uma função utilitária para datas. Ajuste a preferência de exportação se a equipe tiver escolhido outro padrão. A regra deve descrever como o repositório funciona, sem mudar suas convenções de forma implícita.

Testes: descreva as tarefas que precisam deles

Salve em .cursor/rules/tests.mdc:

---
description: Testing requirements when adding features, fixing bugs, or changing TypeScript behavior
alwaysApply: false
---

- Cover changed behavior with a focused regression test.
- Use the existing test runner, fixtures, and file naming conventions.
- Read package.json for the relevant test script; do not invent a command.
- Report the command and actual result, or explain why tests were not run.

O objetivo é ter um teste útil e um relato fiel do resultado. A correção de um bug deve deixar evidências de que a falha original está coberta. Uma refatoração deve preservar o comportamento relevante. Nenhuma das duas precisa de outro framework de testes nem de um relatório que confunda “teste escrito” com “teste passou”.

Quando quiser usar essa lista de verificação explicitamente, inclua @tests no pedido. Se a equipe quiser aplicá-la a toda tarefa, mude o modo de aplicação para Always Apply. Trate isso como uma decisão consciente de política da equipe; com apenas a descrição, a seleção fica por conta do agente.

Segurança: mantenha os requisitos básicos enxutos

Salve em .cursor/rules/security.mdc:

---
alwaysApply: true
---

- Never put secrets in source code, test fixtures, or application logs.
- Use existing server-side authentication and authorization helpers.
- Validate untrusted input at server boundaries with the existing schemas.
- Do not remove permission checks to make a feature or test pass.

Substitua a referência às funções auxiliares existentes pelos caminhos reais dos módulos do repositório quando souber quais são. Os requisitos básicos precisam ser fáceis de entender durante uma tarefa comum de implementação. “Torne isso seguro” dá pouco material para quem revisa; “preserve a verificação de autorização” aponta um requisito concreto.

Esse arquivo contém instruções; ele não é uma barreira de segurança. Continue aplicando as verificações de acesso no código e revisando mudanças sensíveis. O próprio Cursor alerta para não depender de orientações de IA como único controle de segurança. Orientações sobre Team Rules

Valide a configuração com uma mudança real

Escolha uma tarefa pequena que já tenha exigido correções repetidas. Alterar a validação de um formulário é um bom exemplo: envolve um componente, muda um comportamento e recebe dados do usuário.

1. Registre o resultado esperado. Identifique o componente existente que deve ser reutilizado, o comportamento a testar e o ponto de validação a preservar.
2. Salve os três arquivos e confira o status das regras. O Cursor mostra as regras em Customize → Rules; o comando /create-rule também está disponível no Agent. Como criar uma regra
3. Peça a mudança com os arquivos relevantes no contexto. Faça um pedido realista. Uma tarefa que repete todas as regras não permite avaliar se a configuração ajudou.
4. Revise o diff e as verificações relatadas. Procure a convenção aplicada de fato, não uma garantia de que as regras foram seguidas. Se a lista de testes for importante nessa experiência, peça @tests explicitamente.
5. Inclua as regras úteis no mesmo commit da mudança. Dê à equipe um ponto de partida que possa ser revisado. Melhore uma frase vaga antes de adicionar outro arquivo.

Se uma convenção não for seguida, diferencie duas falhas: a regra não chegou ao contexto da tarefa, ou chegou, mas a instrução não funcionou. No primeiro caso, ajuste o critério de aplicação. No segundo, torne a instrução mais clara, acrescente um exemplo ou use uma verificação automatizada.

Quais convenções vale a pena registrar

Comece pelos erros recorrentes que mais custam à equipe. Estes são usos práticos a considerar, em ordem do trabalho de revisão que podem evitar.

Não transforme essa lista em obrigação de criar mais cinco arquivos. Se um problema ainda não aconteceu, deixe-o de fora. Se uma ferramenta consegue verificar o requisito com precisão, prefira essa verificação. Uma regra útil preenche a lacuna entre o pedido da tarefa e as ferramentas que o repositório já tem.

E o antigo arquivo .cursorrules?

Use .cursor/rules/*.mdc para seguir a configuração de projeto documentada atualmente. Em 11 de outubro de 2026, a página de regras não menciona .cursorrules e, portanto, não confirma se o arquivo legado ainda funciona. Referência atual

Se o repositório ainda usa o arquivo antigo, minha recomendação é transferir as instruções úteis para regras de projeto com foco bem definido, usando os três arquivos acima como ponto de partida. Escolha os critérios de aplicação e valide uma tarefa real antes de aposentar a cópia antiga. Não preserve convenções obsoletas só porque já estavam escritas.

O que muda em relação a CLAUDE.md e AGENTS.md

A ideia em comum é manter instruções permanentes do projeto: o Claude Code tem o CLAUDE.md, e o Codex lê os acordos de trabalho em AGENTS.md. A opção do Cursor em Markdown simples atende a esse mesmo uso básico, enquanto os arquivos .mdc oferecem escolhas de aplicação. Mantenha as convenções consistentes entre as ferramentas, mas configure de forma consciente como cada uma carrega as instruções; copiar o texto não equivale a copiar as configurações. Em equipes que usam vários agentes, defina um responsável pelas convenções compartilhadas para que os arquivos não virem fontes de verdade concorrentes.

Duas ferramentas pequenas que vale criar depois da configuração

Um verificador de regras do repositório é a oportunidade mais promissora para uma liderança de engenharia: conferir extensões de arquivo, campos reconhecidos de frontmatter e padrões que não correspondem a nenhum arquivo versionado. A menor versão útil é um relatório local gerado durante a revisão. O sinal de demanda é modesto: na pesquisa deste artigo, o DataForSEO retornou 140 buscas mensais estimadas por “cursor rules examples”. Isso mostra interesse em um tema próximo, não que as pessoas pagariam pela solução. A limitação é clara: uma regra com estrutura válida ainda pode dar orientações ruins. Definição da métrica

Um pacote de revisão das convenções da equipe pode ajudar quem lidera a manutenção de vários repositórios. Transforme comentários recorrentes de revisão e exemplos aprovados em uma proposta de diff das regras, com um revisor definido para cada mudança. O DataForSEO retornou 70 buscas mensais estimadas por “cursor team rules”. Comece como uma ferramenta interna; as Team Rules nativas já cuidam da distribuição, então outro painel para armazenar regras seria um produto de pouco valor. O trabalho útil é decidir o que merece virar uma instrução permanente. Definição da métrica

Dúvidas comuns ao configurar as regras

Na próxima semana, escolha uma correção recorrente, torne a regra correspondente mais precisa e teste-a no próximo pull request do dia a dia. Para avaliar o produto de forma mais ampla, leia a análise do Cursor ou as melhores alternativas ao Cursor.

Se você quer integrar isso ao fluxo de desenvolvimento de uma equipe, é no trabalho com sistemas de IA em produção que essa necessidade se encaixa.