Sem instruções persistentes, cada sessão de agente é um júnior novo: esquece o linter, inventa pasta, commit afoito, ignora o design system. Rules e skills são o jeito de transformar “o que a gente sempre faz” em contexto carregável — versionado no git, revisável no PR, igual para Cursor, Claude Code, OpenCode e o que mais o time usar.
Rules vs skills (definição prática)
| Rules | Skills | |
|---|---|---|
| Papel | Políticas sempre (ou quase sempre) ativas | Procedimentos sob demanda |
| Tom | “Nunca faça X / sempre faça Y” | “Quando o usuário pedir Z, siga este playbook” |
| Onde costuma viver | .cursor/rules, CLAUDE.md, AGENTS.md | SKILL.md / pastas de skills do produto |
| Tamanho | Curto, scorável | Pode ser longo: passos, checklists, exemplos |
Regra de ouro: rule é lei do repo; skill é manual de operação. Se tudo for rule, o contexto explode e o modelo dilui o que importa. Se tudo for skill, o agente só se comporta bem quando alguém lembra de invocar.
O padrão AGENTS.md / CLAUDE.md
Vários harnesses convergem para um arquivo na raiz (ou por pacote):
# AGENTS.md
## Stack
- Next.js App Router, TypeScript strict, Yarn
## Não fazer
- Não adicionar dependência sem pedir
- Não commitar sem o usuário pedir
## Como verificar
- yarn lint && yarn test
Claude Code prioriza CLAUDE.md; Cursor lê rules em .cursor/rules e também entende AGENTS.md em muitos setups. OpenCode documenta AGENTS.md. Em times multi-tool, mantenha uma fonte canônica e, se preciso, um ponteiro curto nos outros arquivos (“ver AGENTS.md”).
Detalhe de produto varia — trate paths como convencões do seu harness atual.
Rules que valem ouro (e as que não)
Valem:
- Fronteiras de confiança (secrets, produção,
force push). - Comandos de verificação reais do repo.
- Convenções de pasta e naming que o lint não pega.
- “Commit só quando pedido” / política de PR.
Não valem como rule global:
- Tutorial de 400 linhas sobre um framework.
- Preferências pessoais de um dev.
- Texto que contradiz o CI.
Se a rule não cabe em uma tela, provavelmente é skill ou doc humana.
Anatomy de uma skill útil
Uma skill boa responde três perguntas em segundos: quando usar, o que fazer, o que nunca fazer.
---
name: create-pr
description: Use when opening a pull request for the current branch.
---
# Create PR
1. git status + git diff + git log vs main
2. Push com -u se necessário
3. gh pr create com summary e test plan
4. Devolver a URL
Never force-push to main.
Dicas:
descriptionrica: é o que o roteador do agente usa para decidir se a skill aplica.- Passos numerados com comandos literais.
- Zero placeholders do tipo “adicione tratamento de erro adequado”.
- Uma skill = um job (abrir PR ≠ deploy ≠ inventar feature).
Isso combina com orquestração: workers recebem skills diferentes (implementar vs só revisar). Ver orquestração de agentes.
Padronizar o time sem burocracia
- Comece com 5 rules que o CI não cobre.
- Extraia skills só depois da terceira vez que alguém repetir o mesmo prompt.
- Revise skills no PR como código: diff de procedimento.
- Delete skill que ninguém invocou em 60 dias.
- Separe skill de produto (MCP, browser) de skill de git.
Ferramentas diferentes? O conteúdo importa mais que o formato. Um AGENTS.md bem escrito já reduz 80% da deriva; rules/skills específicas refinam o resto. Mapa das tools: OpenCode vs Cursor vs Claude Code vs Orca.
Ligação com MCP
Rules dizem política; MCP expõe capacidade (Jira, DB read-only, docs). Sem rules, o agente chama tools demais; sem MCP, ele alucina integrações. Os dois se complementam — MCP para agentes de código.
Exemplo de rule curta:
Use o MCP de docs só para APIs externas.
Nunca use tools de deploy em branches que não sejam main.
Exemplo de pacote mínimo para um repo Next.js
AGENTS.md # canônico
.cursor/rules/
git-safety.mdc # commits, push, amend
frontend.mdc # padrões do design system
skills/
pr/SKILL.md
verify/SKILL.md # lint + test + o que olhar no diff
No verify skill, fixe os comandos do projeto (yarn lint, yarn test) — agentes adoram inventar npm no repo Yarn.
Checklist
- Existe um arquivo canônico de instruções no git?
- Rules cabem em “sempre / nunca”?
- Skills têm description acionável e passos verificáveis?
- Segredos e produção estão explicitamente fora de escopo?
- Alguém revisa mudanças nesses arquivos como código?
Conclusão
Agentes sem rules são dados; com rules ruins são lentos; com skills demais são confusos. O sweet spot é poucas leis claras + playbooks curtos para tarefas repetidas. Versionar isso no repo é o que faz o “comportamento do time” sobreviver à troca de modelo ou de IDE.
Mais sobre meu trabalho e projetos: portfolio.