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.
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.
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.
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.
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.
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.
é uma regra só, aplicada em três camadas. o ponteiro vai onde é oficialmente suportado, e nunca do lado que tu usa todo dia.
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.@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
.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 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.
# 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 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.
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.
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.
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.
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.
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.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..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.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.
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.
essas eu aprendi na marra, no meu próprio repositório.
@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.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.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.
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.