Rulesync: uma fonte de regras para Claude Code, Codex e Cursor

O resumo direto

Rulesync é um CLI que guarda as regras do repositório num diretório só, o .rulesync/, e gera a partir dele o arquivo nativo que cada agente de IA lê. Serve para quem roda mais de um agente no mesmo projeto e cansou de manter CLAUDE.md, AGENTS.md e .cursor/rules dizendo coisas diferentes. A promessa declarada na documentação oficial é "Author rules once, generate everywhere", e os arquivos gerados continuam funcionando mesmo sem o rulesync instalado. O ponto de virada é conceitual: depois que você adota, o CLAUDE.md deixa de ser lugar onde se escreve e vira saída de build, igual a um arquivo compilado. Isso resolve a divergência e cria um risco novo, que é rodar o generate por cima de regras escritas à mão. O caminho seguro passa por importar o que já existe antes de gerar qualquer coisa.

1. O problema não é ter muitos agentes, é ter muitas fontes

Quem entrega sistema ou loja para cliente raramente usa um agente só. Claude Code no terminal, Codex CLI em outra aba, Cursor para revisar o diff, OpenCode num servidor. Cada um lê um arquivo diferente por padrão.

O Claude Code carrega ./CLAUDE.md ou ./.claude/CLAUDE.md como instruções de projeto. O Cursor lê .cursor/rules em arquivos .mdc, e um .md largado nessa pasta é ignorado pelo sistema de regras, porque não tem frontmatter para declarar description, globs e alwaysApply. O OpenCode lê AGENTS.md na raiz e aceita arquivos extras listados no campo instructions do opencode.json. O Codex guarda configuração em ~/.codex/config.toml e aceita sobreposição por projeto em .codex/config.toml, carregada só em projeto marcado como confiável.

Quatro lugares, quatro formatos. Na prática: o padrão de stack está no CLAUDE.md, a convenção de branch está no .cursor/rules, o passo de deploy está no AGENTS.md e a pasta que ninguém pode tocar não está em lugar nenhum. Quando um agente trabalha com metade do contexto, quem paga é o código do cliente.

O AGENTS.md reduziu parte da confusão: é formato aberto, usado por mais de 60 mil projetos open source, e a precedência dele é simples, o arquivo mais próximo do arquivo editado vence. Mas ele não cobre .cursor/rules nem configuração de MCP, hooks e permissões.

2. O que o rulesync faz (e o que ele não é)

O rulesync inverte a direção: você escreve em .rulesync/, roda um comando e ele escreve o arquivo nativo de cada ferramenta. O README oficial descreve um CLI Node.js que gera configuração de várias ferramentas de IA a partir de arquivos de regra unificados, cobrindo rules, commands, MCP, subagents e skills. Licença MIT.

Três coisas que ele não é:

• Não é MCP. MCP é o protocolo que liga o agente a uma ferramenta externa, e já tem artigo próprio: MCP no Claude Code e no Cursor. O rulesync só escreve o arquivo de configuração de MCP de cada ferramenta a partir de uma fonte única.
• Não é runtime. Ele roda, escreve arquivo e sai.
• Não é garantia de comportamento. O que ele sincroniza é texto de contexto. A seção 8 trata disso.

A vantagem aparece no dia em que você muda o padrão de commit: em vez de editar quatro arquivos e esquecer um, você edita um em .rulesync/rules/ e roda o generate.

3. Instalar, e rodar o import antes de qualquer generate

A documentação oficial lista três caminhos: npm global, tap Homebrew ou binário único. O npm é o mais direto.

npm install -g rulesync
rulesync --version

O tap do Homebrew mora dentro do próprio repositório e não tem prefixo homebrew-, então exige a forma de dois argumentos brew tap <nome> <url>; o atalho sem tapar antes não funciona. No npm, o pacote carrega atestado de proveniência, verificável com npm audit signatures.

Agora a parte que salva o repositório. Se o projeto já tem CLAUDE.md e .cursorrules escritos à mão, não rode rulesync generate primeiro. O generate escreve os arquivos nativos a partir de .rulesync/, e com .rulesync/ vazio o que estava à mão pode ser sobrescrito. Importe antes:

rulesync init
rulesync import --targets claudecode
rulesync import --targets cursor

O init cria o .rulesync/ com arquivos de exemplo e o rulesync.jsonc, e a documentação diz que arquivos existentes nunca são sobrescritos por ele. O rulesync.jsonc gerado já vem com targets iguais a codexcli, claudecode e opencode. O import faz o inverso do generate: lê o CLAUDE.md, o .cursorrules ou o .github/copilot-instructions.md que já existem e grava o conteúdo em .rulesync/.

Depois do import, confira o que entrou antes de qualquer outra coisa:

git status
git diff --stat

Se o import trouxe menos do que você esperava, complete à mão em .rulesync/rules/ antes de gerar.

4. A primeira regra: Markdown com frontmatter

Regra do rulesync é arquivo Markdown em .rulesync/rules/, com frontmatter YAML. Quatro chaves importam no começo: root, targets, description e globs. A regra raiz (root: true) vira o arquivo principal de cada ferramenta; as demais viram arquivos modulares no lugar que cada ferramenta espera.

---
root: true
targets: ["*"]
description: "Convenções do repositório"
globs: ["**/*"]
---

Abaixo do frontmatter vai o corpo, em Markdown comum. Coloque o que você repetiria para um dev novo no primeiro dia:

• Stack permitida e o que está congelado (a versão do framework, o gerenciador de pacotes, se é pnpm e não npm).
• Padrão de commit e de branch, escrito como exemplo e não como adjetivo.
• Pasta proibida: a de build, a de vendor, a de arquivo gerado por outro processo.
• Passo de deploy e o comando de verificação que roda antes.

O conselho de escrita é consistente entre as documentações: instrução específica funciona melhor que instrução vaga. O Claude Code recomenda menos de 200 linhas por CLAUDE.md, porque arquivo longo consome contexto e reduz aderência. O Cursor recomenda manter regra abaixo de 500 linhas e dividir regra grande em regras componíveis.

Para regra que só vale em parte do código, use globs. Uma regra com globs: ["src/api/**/*.ts"] é traduzida por cada alvo para o mecanismo que ele tem: paths no Claude Code, globs no .mdc do Cursor, frontmatter próprio em outros.

O detalhe do Cursor que quebra silenciosamente

No Cursor, alwaysApply: true e globs juntos são conflito semântico: a documentação oficial diz que os globs são ignorados quando a flag está ligada, e algumas versões classificam a regra pelo glob em vez de aplicá-la sempre. O rulesync trata isso na tradução, mas conheça o comportamento: é causa comum de "a regra está lá e o agente ignora".

5. Gerar para vários alvos de uma vez

O comando é generate, e o que decide para onde ele escreve é --targets. O valor é literal: errar o nome quebra a execução. Estes são os valores conferidos na referência oficial no dia da leitura.

Fonte: Rulesync, páginas Supported Tools e File Formats, lidas em 22/09/2026. A lista completa passa de 40 ferramentas e muda com frequência: confira o valor na referência antes de fixar num script.

rulesync generate --targets claudecode,codexcli,cursor --features rules
rulesync generate --targets "*" --features "*"

A primeira linha gera só as regras, para os três alvos. A segunda gera tudo para todos os alvos configurados. Comece pela primeira. --features aceita rules, commands, subagents, skills, mcp, hooks, permissions e checks: ligue uma de cada vez, em vez de descobrir no diff que o permissions reescreveu um .codex/config.toml ajustado à mão.

Antes de escrever qualquer arquivo, existe o ensaio:

rulesync generate --dry-run --targets claudecode --features rules
rulesync generate --check --targets "*" --features "*"

O --dry-run mostra o que mudaria sem tocar em nada. O --check faz o mesmo e sai com código 1 quando os arquivos não estão atualizados, que é a forma de usar isso em CI.

A ordem dos alvos importa mais do que parece

Várias ferramentas leem o mesmo AGENTS.md: Codex CLI, OpenCode, Antigravity CLI, Grok CLI e Warp, entre outras. Num generate com vários alvos, mais de um escreve no mesmo caminho, cada um com a própria semântica. O rulesync só faz a varredura de órfãos depois que todos os alvos escreveram, para um não apagar o arquivo recém-escrito do outro. Ainda assim: depois de gerar, abra o AGENTS.md e leia. Não presuma.

6. Conferir no git diff, e decidir se o gerado entra no repositório

Depois do primeiro generate, a verificação que conta é o diff.

git diff --stat
git diff CLAUDE.md AGENTS.md
git diff .cursor/rules/

Procure três coisas: conteúdo que sumiu (parágrafo do CLAUDE.md à mão não importado), conteúdo duplicado (a mesma instrução vinda do AGENTS.md e da regra raiz) e arquivo inesperado, como um .codex/config.toml surgido porque --features "*" ligou permissions.

Depois vem a decisão de versionamento, binária.

Versionar o gerado é o caminho para time. Quem clona recebe as regras funcionando sem instalar nada, o que casa com a promessa da documentação. O custo é diff mais barulhento em cada pull request e a obrigação de rodar rulesync generate --check no CI para o gerado não envelhecer em silêncio.

Não versionar deixa o repositório limpo: só .rulesync/ entra no git e o generate vira passo de setup. Há comando pronto:

rulesync gitignore --targets claudecode,cursor

O custo é que quem clonar e não rodar o setup trabalha sem regra nenhuma. Ressalva documentada: arquivos compartilhados como opencode.json, .claude/settings.json, .codex/config.toml e .vscode/settings.json não entram no .gitignore de propósito, porque você também escreve coisa sua neles.

Para projeto de cliente, versionar tende a ser a escolha certa: o repositório precisa funcionar na mão de quem pega depois, e quem pega depois não lê a documentação de setup.

7. Atualizar a ferramenta sem levar susto

A versão corrente na leitura da página, em 22/09/2026, é a 17.0.0, publicada em 21/09/2026. Ela traz mudança incompatível específica do Codex CLI: regras de edit e write marcadas como ask ou deny passam a gerar read em vez de deny. O Codex não tem estado de aprovação de escrita por caminho, então as duas ações que não são allow preservam leitura sem escrita, com aviso. As notas de release pedem que você revise o .codex/config.toml regerado se dependia da saída antiga.

Isso resume o modo de operar: a ferramenta se move rápido, com release quase diário, e acompanha o que cada agente muda do próprio lado. Duas práticas cobrem o risco: fixar a versão no projeto em vez de instalar sempre a mais recente, e rodar rulesync generate --dry-run depois de qualquer atualização.

8. O limite honesto: regra alinha contexto, não obriga o modelo

Esta é a parte que quase nenhum tutorial diz, e que a documentação oficial das ferramentas diz sem rodeio.

O Claude Code é direto: as instruções de memória são tratadas como contexto, não como configuração imposta, e o conteúdo do CLAUDE.md é entregue como mensagem de usuário depois do prompt de sistema, sem garantia de cumprimento estrito, principalmente quando a instrução é vaga ou conflita com outra. A recomendação da própria página, para o que precisa valer sempre, é usar hook PreToolUse, que executa independentemente do que o modelo decidir. O Cursor faz a ressalva equivalente ao falar de regras de time: orientação por IA não deve ser o único controle de segurança.

A conclusão operacional divide o trabalho em duas camadas:

• Camada de contexto: padrão de nomenclatura, estilo, arquitetura, onde ficam as coisas. Isso vive em regra, e o rulesync resolve a duplicação.
• Camada de imposição: o que não pode acontecer nunca. Isso vive em hook, em permissão (permissions.deny no Claude Code, sandbox_mode e política de aprovação no Codex), em teste e em regra de CI.

Se a instrução é "não faça deploy sem rodar o teste", ela não é regra de arquivo, é hook ou passo de pipeline. Se é "endpoint novo vai em src/api/handlers/", aí sim é regra, e ganha em estar num lugar só. O rulesync resolve divergência entre fontes. Ele não resolve, nem promete resolver, obediência do modelo.

Perguntas frequentes

Preciso trocar meu CLAUDE.md por outra coisa?

Não. Ele continua existindo e sendo lido pelo Claude Code. Muda quem escreve nele: você edita .rulesync/rules/ e o generate reescreve o CLAUDE.md. Se alguém do time editar o CLAUDE.md direto, a edição some no próximo generate, então vale um comentário no topo avisando que ele é gerado.

Dá para usar só em uma ferramenta?

Dá, e faz sentido como transição. Rodar só com --targets claudecode já resolve manter regra grande organizada em arquivos separados. Mas se você usa um agente só, o ganho é pequeno: a ferramenta foi feita para vários alvos.

E as regras que já estão em .cursor/rules há meses?

Rode rulesync import --targets cursor antes do primeiro generate, confira no git diff o que entrou em .rulesync/ e só então gere. Se o import não trouxer tudo, complete à mão antes.

Isso substitui configurar MCP em cada ferramenta?

Em parte. Com a feature mcp ligada, ele escreve a configuração de MCP de cada ferramenta a partir de uma fonte só. O que ele não faz é a parte trabalhosa: escolher o servidor, tratar credencial e diagnosticar servidor que não sobe. Isso é assunto de MCP no Claude Code e no Cursor.

Vale a pena numa VPS onde o agente roda sozinho?

Vale mais ainda, porque ali ninguém corrige o agente na hora. Só que regra de arquivo continua sendo contexto: sem supervisão, o que protege é permissão e hook, não texto. Sobre rodar agente em servidor: Claude Code 24/7 numa VPS.

Conclusão

Rulesync é uma ferramenta chata, e esse é o elogio: ela não faz nada que você não poderia fazer à mão, só impede que quatro arquivos comecem a discordar em silêncio. O ganho aparece no repositório que passa por mais de um agente e por mais de uma pessoa, e o custo é baixo, já que a ferramenta é MIT e o resultado continua funcionando mesmo sem ela instalada. O que muda de verdade é a disciplina: regra se escreve em .rulesync/, arquivo nativo é artefato, e o git diff é o teste depois de cada generate. E o que precisa valer sempre não entra em regra nenhuma, entra em hook, permissão ou teste.

Se o que você precisa é o agente lendo o seu ERP, a sua loja ou o seu banco, isso é integração sob medida (MCP, webhook, fila). Descreve o sistema e o que quer automatizar em oailton.dev/contato.