Cursor Rules: Contexto Persistente para o Seu Agente de IA
Passei meses repetindo as mesmas instruções para o Cursor no início de cada conversa. Documenta em pt-BR. Usa Conventional Commits. Segue o loop Plan → Work → Review. Toda sessão, o mesmo onboarding manual.
Isso é um problema de design, não uma limitação inevitável. Rules são o mecanismo para injetar contexto persistente no agente antes que ele responda à primeira palavra.
O problema
Um agente de IA operando sem contexto de projeto é como contratar um consultor sênior e pular o onboarding.
Ele toma decisões tecnicamente corretas, mas contextualmente erradas: inglês onde o projeto documenta em pt-BR, commits sem prefixos convencionais, arquivos em PascalCase onde o projeto usa kebab-case.
Quem mais sofre são os times com padrões bem definidos — eles perdem consistência toda vez que uma conversa nova começa.
Anatomia de uma Rule
Rules são arquivos .mdc em .cursor/rules/, com frontmatter YAML e corpo em Markdown:
---
description: "Convenções de projeto para documentação e commits"
globs: []
alwaysApply: true
---
# Compound Engineering Workflow
- Documentação em pt-BR, código em inglês
- Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:
- Loop obrigatório: Plan → Work → Review → Compound
Três modos de ativação
alwaysApply: true carrega em toda conversa, sem exceção. Use para convenções universais — idioma, estilo de commit, loop de trabalho. O custo é consumir tokens de contexto todas as vezes, mesmo quando irrelevante.
Glob-scoped (globs: ["*.rb", "app/**/*.rb"]) ativa quando um arquivo correspondente está aberto. Ideal para padrões de linguagem específica, frameworks ou uma camada da aplicação.
Manual (@rules/nome) é invocada explicitamente. Para regras estreitas que só importam em situações pontuais.
Por que não as alternativas
Repetir contexto num system prompt customizado não escala, não é versionado com o projeto e é difícil de manter por vários desenvolvedores.
Colocar tudo numa Rule gigante perde modularidade. Uma Rule de 2.000 tokens consumida em toda conversa que só precisava de 200 é desperdício de contexto.
Comentários no código são lidos pelo agente, mas não são confiáveis como fonte de verdade de convenção.
O que custa
Você ganha consistência entre conversas sem esforço manual, onboarding de novos membros pelas próprias Rules e contexto versionado junto ao código.
Você aceita que Rules alwaysApply consomem tokens em toda conversa — em projetos com muitas regras, esse custo de contexto sobe. E Rules não são dinâmicas: quando uma convenção muda, você edita o arquivo na mão.
Como isso falha
Rules em conflito. Duas Rules alwaysApply estabelecendo padrões opostos. O agente vai tentar reconciliar, ou priorizar a que carregou por último, de forma não determinística.
O sinal de alerta: o agente começa a ignorar padrões que você sabe que estão numa Rule. Normalmente isso significa conflito entre regras, ou que a conversa cresceu a ponto de a Rule ser empurrada para fora da janela de atenção.
Over-specification. Uma Rule tão detalhada que cobre edge cases demais e fica internamente contraditória. Uma Rule deve cobrir um domínio específico, não todos os casos possíveis.
Desatualização. O projeto evoluiu e a Rule não, então o agente segue a convenção antiga. Trate Rules como código: revise em code review, atualize junto com refactors.
O que eu aprendi
Comece com menos Rules e adicione conforme identificar inconsistências reais. Não tente antecipar tudo — uma Rule escrita para resolver um problema concreto é mais eficaz que uma escrita preventivamente.
AGENTS.md e .cursor/rules/ atendem audiências diferentes: agentes CLI versus o agente da IDE. Em projetos que usam ambos, mantenha os dois — mas não copie e cole. Cada um deve ter o nível de detalhe que seu consumidor precisa.
E o mais importante: uma Rule existir não significa que o agente vai segui-la em 100% dos casos. Rules reduzem inconsistência; não a eliminam. Trate como probabilístico, não determinístico, e calibre conforme observa o comportamento real.