---
title: Claude Code, Codex e outros agentes no mesmo repositório (sem duplicar nada)
description: Como deixar teu repositório agnóstico a modelo: um arquivo de instrução, uma pasta de skills, vários agentes lendo tudo. Com o passo a passo, as pegadinhas e o rollback.
url: https://ratosdeia.com.br/guias/varios-agentes-um-repositorio/
---

🐀 guia · repositório agnóstico

# vários agentes, *um repositório* só

claude code, codex, hermes, opencode. cada semana aparece um melhor, e às vezes o que tu usa cai o dia inteiro. dá pra deixar teu repositório de um jeito que **qualquer agente pluga e já sabe de tudo**, sem duplicar arquivo e sem ficar sincronizando cópia. esse é o passo a passo, com as pegadinhas que só aparecem depois que tu roda.

**1** arquivo real

o resto é ponteiro

**1** pasta de skills

servindo todos os agentes

**0** sincronização

nada pra manter atualizado

o problema

## a régua muda a cada poucas semanas

claude code dominou a conversa, o codex subiu forte, o kimi k3 estourou. e nem sempre a troca acontece por qualidade: às vezes é preço que sobe, fila, limite estourado ou um dia inteiro fora do ar. a pergunta que importa é **quanto te custa trocar**.

contexto dentro da ferramenta

tudo mora no projeto do chat

↓

aparece uma opção melhor

↓

tu explica tudo de novo

↓

tu fica onde tá

contexto no repositório

tudo mora em pasta e markdown

↓

aparece uma opção melhor

↓

tu abre o agente novo na pasta

↓

ele já sabe de tudo

**o teste que vale:** quanto tempo leva pra plugar um agente novo e ele produzir algo útil sozinho? se leva um dia, tu tá refém. se leva um comando, tu tá agnóstico.

antes de qualquer arquivo

## a maior parte disso não é técnica

o que deixa teu sistema agnóstico é ter **pasta e arquivo organizados**: o contexto do teu negócio escrito em texto, cada projeto no seu lugar, teus processos documentados onde o agente alcança. isso serve pra qualquer agente que existe hoje e pros que vão aparecer, e é onde mora quase todo o trabalho.

o trabalho de verdade

organizar o contexto em pastas e arquivos de texto

é o que qualquer agente lê sem tu configurar nada, hoje e daqui a dois anos. leva semanas, é chato, e é o que ninguém pode fazer por ti. se tu ainda não tem isso, **começa por aqui** e nem lê o resto da página.

o ajuste que falta

os nomes de arquivo e a pasta de skills

leva alguns minutos e é o que esse guia resolve. sem ele, tu tem a casa arrumada e o agente novo parado na porta.

por isso quem já montou o segundo cérebro num repositório sofre pouco com troca de ferramenta: **o difícil já tá feito.** o que sobra é o acerto de nomes que vem a seguir.

a boa notícia

## eles só discordam do nome do arquivo

todos os agentes leem a mesma coisa: texto simples numa pasta. o que muda é onde cada um procura. essa tabela é o mapa inteiro.

o que é

claude code

codex

hermes

instruções do projeto

`CLAUDE.md`

`AGENTS.md`

`HERMES.md`

pasta dele no projeto

`.claude/`

`.codex/`

não tem

skills

`.claude/skills/`

`.agents/skills/`

segue o repo

formato da skill

pasta com um `SKILL.md`

igual, sem mudar nada

igual

ajustes do agente

`settings.local.json`

`config.toml`

própria

o que vale em todo projeto teu

`~/.claude/`

`~/.codex/` e `~/.agents/skills/`

no servidor dele

até onde ele enxerga

olha pra dentro das subpastas

olha só de onde tu abriu ele pra fora

para no primeiro arquivo que achar

**repara na linha do formato da skill:** é a mesma coisa nos dois. uma pasta com um arquivo `SKILL.md` dentro, texto puro. isso não é coincidência: existe um **padrão aberto** pra isso (chama-se Agent Skills), e o claude code, o codex, o cursor, o gemini e mais de trinta ferramentas já falam ele. ou seja, a skill que tu escreveu pensando no claude code roda no codex **sem reescrever nada**. tu não tá adaptando pra outra ferramenta, tu tá num formato que não é de ninguém. o problema é só o endereço onde cada um vai procurar.

e a saída ingênua pra resolver endereço é manter **uma cópia por nome**. é o que quase todo tutorial ensina, e é o que apodrece: em duas semanas as cópias divergem, e o agente que leu a errada trabalha com informação falsa achando que tá certo.

a regra

## uma fonte de verdade, o outro nome vira ponteiro

é uma regra só, aplicada em três camadas. o ponteiro vai onde é oficialmente suportado, e nunca do lado que tu usa todo dia.

1

instruções: o AGENTS.md é o arquivo real

todo o conteúdo vive no `AGENTS.md`. o `CLAUDE.md` fica com **uma linha só**, que é o import nativo do claude code. funciona no windows sem permissão de admin (importa se tu vai reproduzir isso no teu note), e ainda dá pra colocar um bloco embaixo do import que só o claude enxerga.

CLAUDE.md inteiro

copiar

@AGENTS.md

\# daqui pra baixo é opcional, e só o claude code lê
\## claude code
\- instruções específicas que o codex não precisa ver

2

skills: uma pasta de verdade e um atalho pra ela

com arquivo dá pra usar o import de uma linha. **com pasta não existe import**, então a ligação aqui é um **atalho**. a pasta de verdade fica em `.claude/skills`, e o atalho é o `.agents/skills` apontando pra ela. o que não pode é ter as duas de verdade. (por que esse lado e não o contrário: um parágrafo abaixo.)

o que é esse atalho (e por que não é uma cópia)

o nome técnico é **link simbólico**, ou symlink. pensa num encaminhamento de correspondência: tu registra um endereço novo que só diz "o que chegar aqui, entrega naquele outro endereço". **a casa continua sendo uma só.**

na prática: quando o codex abre a pasta `.agents/skills`, o sistema entrega pra ele o conteúdo de `.claude/skills`, sem ele nem perceber. tu edita uma skill num lugar só, e os dois agentes veem a mudança na hora, porque **é o mesmo arquivo**. isso é diferente do atalho que tu cria arrastando ícone na área de trabalho, que só funciona quando tu clica nele: esse aqui vale pra qualquer programa que abrir a pasta.

**no windows tem o mesmo recurso, com outro nome** (junction), e o melhor: não precisa de permissão de administrador. o comando muda, a ideia é idêntica.

como criar no mac ou linux, se tu usa o terminal

copiar

\# o comando é: ln -s  <a pasta de verdade>  <o atalho a criar>
\# primeiro o destino, depois o nome novo. é a ordem que confunde todo mundo.

ln -s ../.claude/skills .agents/skills

\# o ../ no começo é porque o atalho mora dentro de uma pasta.
\# caminho relativo assim continua funcionando em outra máquina.

no windows, o comando é outro (mas não precisa de admin)

copiar

\# no windows o atalho de pasta chama-se junction. no prompt de comando:
mklink /J .agents\\skills .claude\\skills

\# aqui a ordem inverte: primeiro o atalho, depois o destino.

e se tu não usa terminal

a maioria de nós não usa mais, e não precisa. **pede pro agente que já tá aberto fazer.** ele roda o comando, te mostra o resultado e tu confere.

pra colar no agente

copiar

cria um atalho de sistema chamado .agents/skills apontando
pra pasta .claude/skills que já existe aqui. usa o recurso
certo pro meu sistema (link simbólico no mac ou linux,
junction no windows) e não peça permissão de administrador.
não copia os arquivos: quero uma pasta só, dois endereços.

depois me mostra que o atalho ficou apontando pro lugar
certo e me diz como eu desfaço isso se precisar.

**como saber se deu certo:** pede pro agente listar a pasta. atalho aparece com uma setinha e o destino do lado (`skills -> ../.claude/skills`). teste melhor ainda: abre o outro agente e pergunta quais skills ele enxerga. se ele listar as tuas, acabou.

**por que a pasta de verdade fica do lado do claude, e não do codex:** hoje o claude code tem um bug aberto quando a pasta de skills **dele** é o atalho (ele reclama na validação). o codex não tem esse problema com a dele. então a pasta real vai pro lado do claude e o atalho pro lado do codex, e ninguém reclama. não importa em qual agente tu começou: mover as skills pra essa pasta é coisa de uma vez.

**e não versiona o atalho.** ele é da tua máquina, não do projeto. se tu usa git e trabalha em mais de um computador (ou compartilha o repositório com alguém no windows), coloca `.agents/skills` no teu `.gitignore` e deixa cada máquina criar o seu. é rápido, e evita o atalho chegar quebrado do outro lado.

3

regras por agente: só o que é diferente

se um agente precisa de regra própria, ela vira arquivo separado com **só o delta**, e não uma cópia inteira. no nosso caso o arquivo do hermes contradiz o canônico de propósito: eu trabalho direto na branch principal, o agente é proibido. se um apontasse pro outro, ele daria push na principal e dispararia deploy sozinho.

**o corte é esse:** o que vale pra todo mundo vira fonte única. o que muda por agente vira um arquivo curto de exceções. nada é copiado, então nada tem como divergir.

mão na massa

## o passo a passo, em 4 movimentos

dá pra fazer na mão ou pedir pro próprio agente fazer. em qualquer um dos dois, faz num repositório com git em dia, pra poder voltar atrás.

1

renomeia, não copia

teu `CLAUDE.md` vira `AGENTS.md` com `git mv`. usar o git pra mover mantém o histórico do arquivo e é o que torna o rollback trivial depois.

2

cria o ponteiro

um `CLAUDE.md` novo, com uma linha: `@AGENTS.md`. o claude code resolve esse import sozinho, e como o arquivo tá no mesmo diretório, ele nem pede aprovação.

3

liga as skills

o atalho ligando as duas pastas de skill: a de verdade em `.claude/skills`, o atalho em `.agents/skills`. e **não coloca esse atalho no versionamento** (ele é da tua máquina). se tu tem skills instaladas pra usar em qualquer projeto, ali o atalho é **por skill**, uma a uma, que é a forma que a documentação descreve.

4

repete nas subpastas que importam

se teu repositório tem projetos dentro dele (cada um com o seu arquivo de instrução), o mesmo par vale em cada um. **não precisa fazer em tudo:** começa pelos que tu abre todo dia.

o atalho: deixa o agente fazer

abre o agente que tu já usa, na raiz do repositório, e cola o pedido abaixo. ele varre, faz as mudanças e te mostra o que fez. depois tu confere com `git status` antes de aceitar.

prompt pra colar

copiar

quero que esse repositório seja legível por mais de um agente
(claude code, codex e outros), sem duplicar conteúdo nenhum.
regra principal: cada informação existe uma vez só, e o outro
nome vira apenas um apontamento pra ela. nunca crie uma segunda
cópia de um arquivo de instrução ou de uma pasta de skills,
porque duas cópias sempre acabam divergindo.

antes de mexer em qualquer coisa, me mostre o que você encontrou
e o que pretende fazer, e espere eu aprovar.

um cuidado importante: se você achar arquivos de instrução com
nomes diferentes e conteúdos diferentes, não escolha um e
sobrescreva o outro. pare, me mostre onde eles divergem e
me deixe decidir.

sobre as skills: a pasta de verdade fica em .claude/skills e o
atalho em .agents/skills apontando pra ela. use o recurso certo
pro meu sistema (link simbólico no mac/linux, junction no
windows), sem admin, e adicione o atalho ao .gitignore.

não toque em pastas de dependências, material de terceiros ou
projetos de cliente.

faça as mudanças de um jeito que preserve o histórico do
versionamento e, no final, me explique em linguagem simples o
que mudou e como desfazer tudo se eu quiser voltar atrás.

o que morde depois

## quatro coisas que só aparecem rodando

essas eu aprendi na marra, no meu próprio repositório.

🕳

a cópia apodrece calada

meu arquivo do codex era uma cópia de 20 dias antes, com um **localizar e substituir** que trocou a palavra "claude" por "codex" até dentro dos caminhos de pasta. ele apontava pra lugares que não existem. o agente lia aquilo e acreditava. **arquivo errado é pior que arquivo nenhum.**

↕

um olha pra baixo, o outro pra cima

o claude code enxerga instruções e skills de subpasta quando trabalha em arquivos de lá. o codex faz o contrário: varre da pasta onde tu abriu ele **até a raiz**, e nunca desce. na prática, abrindo na raiz o codex não vê o que tá aninhado. a solução é abrir ele de dentro da pasta.

🔁

ponteiro apontando pra si mesmo

eu tinha dois arquivos com `@AGENTS.md` escrito **dentro do próprio AGENTS.md**. import que não importa nada, e ninguém avisa. depois de mexer, abre o agente e pergunta algo que só está no arquivo, pra confirmar que ele leu mesmo.

↩

rollback antes de precisar

como tudo foi movido com `git mv`, **um revert devolve tudo**, e nenhum texto se perde: o ponteiro tem uma linha e o conteúdo real segue no histórico. anota o identificador do commit anterior antes de começar.

e a memória compartilhada entre eles?

tem gente indo além disso, fazendo os agentes dividirem a mesma memória de longo prazo entre sessões (o fabio akita mantém um projeto assim, o ai-memory). é novo, a gente ainda não usa em produção, e pra maioria dos casos **as três camadas de cima já resolvem**.

o que tu organiza em pasta e arquivo é o que sobrevive à próxima troca de modelo.

todo o resto tu vai refazer. o agente é o motor, e ele troca. **o repositório é a estrada.** no ratosOS essa estrutura já vem montada assim por design, e no curso mais a comunidade a gente monta a tua junto, em cima da tua operação de verdade.

bora deixar teu sistema agnóstico? [conhecer o curso →](https://ratosdeia.com.br/claudeos/) [ver a comunidade](https://ratosdeia.com.br/comunidade/)

🐀 **ratos de ia** · dobralabs laboratório de ia · design, tecnologia e ia

[×

quer montar teu sistema com agentes?

o curso + a comunidade + o RatosOS, mão na massa

quero →](https://ratosdeia.com.br/claudeos/)