O CLAUDE.md do seu projeto funciona no Antigravity? Como manter as regras valendo nos dois

Fala aí, beleza? Abriu o mesmo projeto no Antigravity e esperava que o <code>CLAUDE.md</code> continuasse mandando? Ele não procura esse arquivo

A documentação de Rules do Antigravity cita <code>GEMINI.md</code> e <code>AGENTS.md</code> na raiz do workspace como arquivos de regra, e analisa isso na inicialização pra aplicar as restrições. O <code>CLAUDE.md</code> não aparece ali como arquivo suportado

Aí nasce o problema chato de quem roda dois agentes no mesmo repositório: você acaba com duas listas de regras quase iguais, e uma delas SEMPRE está desatualizada 😀

Neste post a gente separa o que é detalhe de ferramenta e o que é padrão de projeto, monta uma fonte única de verdade e para de manter regra em dois lugares

Onde cada agente procura as regras do projeto

Antes de mexer em qualquer arquivo, vale localizar cada coisa no mapa

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Lendo a tabela de cima a baixo, dá pra sacar o ponto principal: o formato é o mesmo Markdown dos dois lados

O que muda é o NOME do arquivo e a forma de ativar a regra

Ou seja, você não precisa reescrever o conteúdo, precisa colocar ele no lugar certo 🙂

O que você precisa antes de unificar as regras

Lista curta, tudo verificável em 2 minutos:

• um <code>CLAUDE.md</code> já existente no projeto (se não tem, não tem o que unificar ainda)
• acesso à raiz do repositório git, que é justamente onde os dois procuram as coisas
• entender COMO o Claude Code carrega isso, que é o detalhe que pega gente desprevenida

Sobre o carregamento: o Claude Code carrega o <code>CLAUDE.md</code> do diretório de trabalho e de cada diretório pai no início da sessão. O de subdiretório é diferente, ele entra sob demanda, quando o Claude lê um arquivo daquela pasta com a ferramenta Read

E já ajusta a expectativa aqui, porque muita gente se anima à toa: import com <code>@caminho</code> organiza o conteúdo, mas NÃO economiza contexto

O arquivo importado carrega na inicialização junto com o <code>CLAUDE.md</code>, então a economia é de manutenção, não de tokens

Se o projeto ainda nem está versionado, resolve isso antes de continuar, nem que seja criando o repositório pelo Origin do Cursor se esse for o teu fluxo

Passo a passo: uma fonte de regras valendo nos dois

Bora ver na prática?

1. Triar o <code>CLAUDE.md</code> atual em duas pilhas: de um lado o que é padrão de projeto (stack, comandos de build e teste, convenções de código, o que não pode ser mexido), do outro o que é específico do Claude Code (subagentes, comandos, arquivos que vivem em <code>.claude/</code>). O erro comum deste passo é tratar detalhe de ferramenta como se fosse regra de projeto: instrução sobre subagente não diz nada pra outro agente, só polui

Se boa parte da tua pilha "específica" for skill, vale olhar como funciona manter suas skills num repositório só antes de empurrar tudo pro arquivo compartilhado

2. Mover a pilha "padrão de projeto" pro <code>AGENTS.md</code> na raiz do repositório. O AGENTS.md é um formato aberto em Markdown pra orientar agentes de programação, e é justamente um dos arquivos que o Antigravity analisa na inicialização. Nada de sintaxe exótica aqui, é Markdown padrão mesmo

<pre><code>meu-projeto/ ├── AGENTS.md &lt;- regras de projeto (a fonte de verdade) ├── CLAUDE.md &lt;- import + o que é só do Claude Code ├── .agents/ │ └── rules/ &lt;- regras de workspace do Antigravity └── .claude/ </code></pre>

3. No <code>CLAUDE.md</code>, deixar o import e só o que sobrou. A própria documentação do Claude Code indica criar um <code>CLAUDE.md</code> que importa o <code>AGENTS.md</code>, assim os dois leem as mesmas instruções sem duplicar conteúdo, e você ainda pode acrescentar instruções específicas do Claude embaixo

<pre><code>@AGENTS.md

Específico do Claude Code

• subagentes e comandos ficam em .claude/
• …

</code></pre>

O erro comum deste passo é copiar e colar o conteúdo do <code>AGENTS.md</code> pra dentro do <code>CLAUDE.md</code> "pra garantir". Aí você recriou a duplicação que veio matar, parabéns haha

4. Se não tem NADA específico do Claude, usa symlink. A documentação cita essa alternativa direto:

<pre><code>ln -s AGENTS.md CLAUDE.md </code></pre>

Tome cuidado no Windows: criar symlink exige privilégio de Administrador ou o Modo de Desenvolvedor ligado, e a orientação é usar o import <code>@AGENTS.md</code> no lugar. Esse é o erro comum aqui, tentar o <code>ln -s</code> num terminal comum e ficar caçando o motivo do erro

5. Quebrar o que é grande demais pra caber. Do lado do Antigravity, regras de workspace vão em arquivos dentro de <code>.agents/rules</code> (no workspace ou na raiz do repositório git), respeitando os 12.000 caracteres por arquivo de regra. Do lado do Claude Code, dá pra condicionar regra a caminho com frontmatter YAML no campo <code>paths</code>, e ela entra quando o Claude trabalha com arquivos que casam com o padrão:

<pre><code>— paths: – "src/**/*.ts" —

Regras que só valem pro código TypeScript do app </code></pre>

O erro comum: empurrar tudo pro arquivo da raiz e torcer. Regra que vale pra uma pasta só, mora perto da pasta

6. Enxugar o arquivo compartilhado. A documentação do Claude Code dá uma referência boa de mira: acima de 200 linhas o <code>CLAUDE.md</code> consome mais contexto e pode reduzir a aderência às instruções. Regra de projeto não é documentação, é o mínimo que o agente precisa saber pra não fazer besteira

Quando compensa unificar (e quando é melhor separar)

Nem todo projeto ganha com isso, então vamos aos cenários

Time que alterna entre agentes no mesmo repo:

Aqui unificar é quase obrigatório. Se metade do time roda Claude Code e a outra metade abre o Antigravity, duas listas de regras viram duas culturas de código dentro do mesmo projeto

Uma fonte só no <code>AGENTS.md</code> resolve, e o <code>CLAUDE.md</code> vira uma casca fininha com o import

Monorepo:

Regra por pasta faz MUITO mais sentido que um arquivo gigante na raiz

Os dois lados têm ferramenta pra isso: <code>paths</code> no frontmatter do Claude Code e o modo Glob no Antigravity, com padrões tipo <code>*.js</code> ou <code>src/**/*.ts</code>

Regra que só existe de um lado:

Instrução sobre subagente, sobre arquivo em <code>.claude/</code> ou sobre modo de ativação (Manual, Always On, Model Decision) não é padrão de projeto, é detalhe de ferramenta

Isso fica no arquivo daquela ferramenta e pronto, não sobe pro compartilhado

E por que escolher o <code>AGENTS.md</code> como base?

Porque é o lado com mais ecossistema em volta: formato aberto, nascido de esforço conjunto (OpenAI Codex, Amp, Jules do Google, Cursor, Factory) e mantido pela Agentic AI Foundation, sob a Linux Foundation

O site oficial declara mais de 60 mil projetos open source usando o formato, o que é bem massa pra algo que é só um Markdown na raiz 😀

Conclusão

A lógica fecha assim: uma fonte de verdade no <code>AGENTS.md</code>, um import <code>@AGENTS.md</code> no <code>CLAUDE.md</code>, e cada ferramenta guardando só o que é dela

O Antigravity lê o arquivo que ele procura, o Claude Code lê o dele, e você mantém regra em um lugar só

Próximo passo pra hoje: abre o <code>CLAUDE.md</code> do teu projeto, marca linha por linha o que é padrão de projeto, move essa parte pro <code>AGENTS.md</code> e roda uma tarefa pequena nos dois agentes pra conferir se a mesma regra está sendo respeitada

Se a mesma regra pegar nos dois lados, tá feito: acabou a manutenção em dobro 🙂

até o próximo post!