Um agente de código com IA começa toda conversa com o mesmo problema: ele não faz ideia de como o seu projeto funciona. Ele sabe Python genérico, React genérico, Markdown genérico — mas não sabe que o seu codebase coloca funções utilitárias em helpers/, ou que esse serviço específico usa Pydantic v2, ou que todos os seus posts de blog precisam terminar com uma seção “Further reading”.

Você pode ensinar essas coisas pra ele no chat, toda sessão, pra sempre. Ou você pode escrever rules.

Este post é sobre rules — o que são, como são carregadas, quando usar em vez de outras ferramentas, e o que faz uma boa rule. Os exemplos são da configuração deste próprio blog, porque é o mais concreto que tenho.

A menor rule possível

Uma rule é um arquivo Markdown com frontmatter YAML, dentro de uma pasta que o agente observa. O frontmatter é configuração. O corpo é orientação.

---
description: Voice and tone guide for blog posts
globs:
  - "src/content/posts/**/*.md"
  - "src/content/posts/**/*.mdx"
alwaysApply: false
---

# Blog writing conventions

When editing a post, prefer short paragraphs in casual posts.
Don't over-polish — leave the author's voice intact.

Essa é a forma completa. Três campos de frontmatter, um corpo em Markdown, salve como .cursor/rules/blog-writing-conventions.mdc (ou CLAUDE.md numa pasta, ou como quer que a sua ferramenta chame — o formato de arquivo varia, a ideia não), e o agente vai carregar na próxima vez que tocar num arquivo correspondente.

A maioria dos agentes de código com IA modernos tem alguma versão disso. Cursor chama de rules. Claude Code chama de CLAUDE.md. Outras ferramentas têm seus próprios nomes. O formato de arquivo ainda não é padronizado, mas o conceito subjacente é: orientação por projeto, por padrão de arquivo, carregada automaticamente no contexto do agente.

O frontmatter faz o roteamento

O corpo de uma rule é orientação direta — Markdown bem simples. A parte interessante é o frontmatter, porque ele controla quando a rule é anexada.

Existem aproximadamente três modos:

---
alwaysApply: true
---

Essa rule é carregada em toda conversa no projeto. Use com parcimônia. A janela de contexto do agente tem um orçamento, e rules sempre carregadas gastam esse orçamento quer sejam relevantes ou não. Reserve alwaysApply: true para coisas que genuinamente se aplicam a todo arquivo — padrões de código, guardrails de comportamento, políticas de segurança.

---
description: Voice guide for blog posts
globs:
  - "src/content/posts/**/*.md"
alwaysApply: false
---

Essa rule carrega só quando o agente está mexendo num arquivo que corresponde a um dos globs. Editando src/content/posts/2026-04-24-rules-as-project-memory.md? A rule é anexada automaticamente. Editando src/components/Button.astro? A rule fica fora do caminho.

Esse é o modo que mais uso. Ele escala. Você pode ter uma dúzia de rules num projeto, cada uma com escopo para uma pasta ou tipo de arquivo diferente, e só as relevantes carregam para qualquer tarefa.

---
description: Add a new search filter to the AI agent pipeline
alwaysApply: false
---

Sem globs, não é always-applied. Essa rule aparece no catálogo de rules disponíveis do agente, mas só é anexada quando o agente decide que é relevante — geralmente porque o pedido do usuário corresponde à descrição. Use isso para rules procedurais que não estão vinculadas a um arquivo, tipo “os passos para adicionar uma nova feature do tipo X.”

Os três modos juntos permitem construir uma biblioteca de rules onde cada rule é carregada apenas quando é útil. Parece óbvio. Não é o que a maioria dos projetos faz. Rules roteadas são o caminho do meio entre um arquivo gigante sempre ativo e deixar o agente reinventar as convenções do projeto toda sessão.

Para que rules servem

Rules servem para convenções que se aplicam a um arquivo ou pasta, que não mudam de sessão para sessão, e que o agente não descobriria sozinho.

Concretamente:

• Convenções específicas do projeto. “Todas as rotas de API ficam em apps/api/routes/. Use injeção de dependência do FastAPI para auth. Schemas Pydantic v2 ficam em schemas/.”
• Guias de voz ou estilo. A rule de convenções de escrita deste blog é exatamente isso. O agente não tem como inferir a minha voz. A rule diz pra ele.
• Lógica de decisão que o agente deve seguir. “Use a categoria X para posts sobre A, categoria Y para posts sobre B.” Algumas linhas que economizam dezenas de follow-ups de “na verdade deveria ser Y”.
• Guardrails de segurança. “Não inclua nomes reais de clientes em nenhum arquivo dentro de .cursor/rules/.” Esse é o tipo de restrição que, uma vez escrita, previne um erro recorrente para sempre.

Para que rules não servem

Essa é a parte que demorei um pouco para entender.

Rules não são para tarefas pontuais. Se você se pega escrevendo uma rule pra algo que vai fazer uma vez, você escreveu um prompt na verdade. Coloca esse texto na sua mensagem.

Rules não são para coisas que dependem de estado ao vivo. Se a resposta muda de sessão para sessão — “qual é a contagem atual de vagas abertas no sistema?” — isso não é uma rule. É uma chamada de ferramenta ou uma skill (sobre a qual vou escrever depois).

Rules não são para código. Se você está tentado a colocar uma função dentro do corpo de uma rule e fazer o agente colar em todo lugar, escreva um utilitário de código e deixe o agente importá-lo. Rules são para orientação que o agente deve seguir ao gerar código, não para código em si.

Rules não substituem revisão. Uma rule que diz “sempre valide inputs” é útil mas não substitui realmente ler o que o agente produz. Rules elevam o piso; elas não colocam teto no que pode dar errado.

O maior erro que vejo — inclusive da minha parte, repetidamente — é recorrer a uma rule quando a melhor ferramenta é uma abstração diferente. Rules são um mecanismo entre vários. Nem sempre são a resposta.

Uma rule é melhor quando é pequena

A tentação, uma vez que você começa a escrever rules, é fazê-las longas. Grandes arquivos detalhados de rule que cobrem cada caso de borda. Rules com subseções e sub-subseções. Rules que tentam ser o design doc completo do projeto.

Isso vai contra a forma como o agente as usa. O agente lê a rule e trata cada sentença como orientação. Rules longas diluem a orientação importante com orientação de baixa prioridade. Rules longas também gastam mais do orçamento de contexto, o que significa menos espaço para o arquivo que você está de fato editando.

As rules que realmente mudaram o comportamento do agente, pra mim, foram as curtas e opinativas. Uma página de prosa concisa. Algumas seções com cabeçalho. Uma lista de coisas a evitar. Uma lista de coisas a manter. Isso é suficiente.

Quando uma rule cresce além de duas páginas, começo a me perguntar se são duas rules tentando ser uma. Na maioria das vezes, são.

Rules, skills e subagents

A versão curta antes dos próximos posts entrarem mais fundo:

• Rules carregam automaticamente quando arquivos correspondem. Elas direcionam o comportamento do agente em tarefas existentes.
• Skills são carregadas sob demanda pelo nome. São mais como procedimentos reutilizáveis ou playbooks.
• Subagents são invocações isoladas de um agente menor para uma tarefa específica. Mantêm o trabalho fora do seu contexto principal.

Você normalmente vai precisar dos três. Rules são a fundação porque são baratas e silenciosas. Os outros dois entram em cena quando você supera o que rules sozinhas conseguem fazer.

Como eu escrevo uma nova rule

Quando sento para escrever uma nova rule, sigo mais ou menos isso:

1. Qual é o problema recorrente? Vale a pena escrever uma rule quando o agente cometeu o mesmo erro duas vezes. Uma vez é azar; duas vezes é padrão.
2. Qual é a menor frase que resolve? Tente escrever a rule em uma frase primeiro. Se for suficiente, você tem a sua rule. Se não, expanda só o quanto precisar.
3. Qual é o glob certo? Onde o agente vai estar quando essa orientação importa? Esse é o glob. Resista ao impulso de fazer **/* — escopo estreito produz direcionamento mais preciso.
4. Vou querer encontrar isso daqui a seis meses? Dê um nome de arquivo claro. blog-writing-conventions.mdc é greppable de um jeito que style.mdc não é.
5. Use por uma sessão e edite depois. A primeira versão está sempre ligeiramente errada. Use numa tarefa real, observe onde o agente ainda erra, edite a rule. Duas ou três iterações é normal.

Esse é o loop inteiro. A maioria das minhas rules levou trinta minutos de escrita e mais uma hora de edição ao longo das próximas sessões de uso.

Elas se acumulam

A coisa que eu não previ, quando comecei a escrever rules alguns meses atrás, foi o quanto elas se acumulariam.

Cada rule, por si só, é um pequeno direcionamento. Um empurrão. A saída fica um pouco melhor de uma forma específica. As primeiras rules parecem quase não valer a pena escrever — estou fazendo todo esse meta-trabalho pra economizar alguns segundos por sessão.

Aí você tem uma dúzia de rules. O agente agora conhece a sua voz, a estrutura do seu projeto, a sua política de segurança, as suas convenções de teste, a sua lógica de categorias, o seu formato de imagem, os seus guardrails de segurança, o seu padrão de further-reading. Toda sessão começa com tudo isso já no lugar. A conversa não é menos rica — é o mesmo tipo de conversa de antes, mas agora a camada de baixo está resolvida. Seus prompts podem ser mais curtos. As saídas do agente podem ser mais precisas. Os erros que você corrigia repetidamente pararam de acontecer.

Esse é o momento em que rules deixam de parecer configuração e passam a parecer memória. O projeto se lembra de como funciona. O agente pega essa memória automaticamente. Sua conversa pode ser sobre o problema real, não sobre lembrar o agente das decisões da semana passada.

Isso não é pouco. É a maior parte do motivo pelo qual eu as escrevo.