agentes-md-setup

agents-md-setup

Faça do AGENTS.md a única fonte de verdade para instruções de agentes/projetos, e aponte o arquivo de cada ferramenta para ele via link simbólico. Um arquivo, lido por todos os agentes — sem duplicação, sem divergência.

Por que essa estrutura

• AGENTS.md é o padrão emergente entre ferramentas (Cursor, Codex e outras o leem).
• Claude Code lê CLAUDE.md. Você não pode fazer o harness ler AGENTS.md em seu lugar via prompt ou skill — mas um link simbólico CLAUDE.md → AGENTS.md faz com que Claude abra CLAUDE.md e obtenha o conteúdo de AGENTS.md. Esse é o mecanismo; nada mais é necessário.
• Resultado: edite apenas AGENTS.md; todo agente permanece sincronizado.

Decisão: o que já existe?

1. Nenhum dos arquivos → crie AGENTS.md a partir do modelo abaixo.
2. Apenas CLAUDE.md (um arquivo real) → torne-o a fonte de verdade:

   git mv CLAUDE.md AGENTS.md       # preserva o histórico (ou: mv se não estiver no git)
   

3. Apenas AGENTS.md → mantenha como está (bom).
4. Ambos existem como arquivos reais → NÃO sobrescreva cegamente. Compare-os; mescle em AGENTS.md (ele vence como o arquivo canônico), confirme com o usuário se os conteúdos diferirem, depois remova o CLAUDE.md independente.
5. CLAUDE.md já é um link simbólico para AGENTS.md → já está pronto; pare.

Criar o link simbólico

ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md        # o git armazena como um link simbólico real (modo 120000)

Verifique se foi commitado como link simbólico, não como cópia:

git ls-files -s CLAUDE.md          # o modo deve ser 120000

Opcionalmente, aponte outras ferramentas para o mesmo arquivo:

ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md

Monorepos (Turborepo / workspaces)

Mantenha um AGENTS.md raiz para convenções do repositório inteiro (com o link simbólico CLAUDE.md como acima) e adicione um AGENTS.md com escopo em cada workspace que precisar de suas próprias regras — apps/<app>/AGENTS.md, packages/<pkg>/AGENTS.md — cada um com seu próprio link simbólico irmão criado de dentro desse diretório para que o destino seja relativo:

cd apps/web && ln -s AGENTS.md CLAUDE.md   # CLAUDE.md -> ./AGENTS.md (mesmo dir)

• Claude Code lê o CLAUDE.md mais próximo para os arquivos em que está trabalhando, então arquivos aninhados complementam a raiz em vez de substituí-la. Coloque coisas do repositório inteiro na raiz; coloque apenas o delta específico do pacote em cada workspace — não duplique a raiz.
• Sempre faça cada link simbólico relativo à sua própria pasta (ln -s AGENTS.md CLAUDE.md enquanto estiver cd no workspace), nunca apontando de volta para a raiz — links relativos ao mesmo diretório sobrevivem a checkout/movimentação.
• O Turborepo em si não lê esses arquivos (são para agentes), então nenhuma alteração em turbo.json é necessária. Se quiser que eles sejam expostos, você ainda pode anotar a convenção no AGENTS.md raiz.

README

Se não houver README.md, crie um mínimo (nome do projeto, descrição de uma linha, comandos de setup/execução). Mantenha a documentação voltada para humanos em README.md e instruções para agentes em AGENTS.md — não misture os dois.

Caveat para Windows / CI (importante)

Links simbólicos do Git precisam de core.symlinks=true e podem quebrar em checkouts do Windows ou em alguns runners de CI (o link simbólico se torna um arquivo de texto contendo AGENTS.md). Se o projeto for direcionado ao Windows, prefira o fallback: um real CLAUDE.md minúsculo cujo conteúdo inteiro é um ponteiro —

Veja [AGENTS.md](./AGENTS.md) para instruções do projeto e do agente.

— aceitando que ele deve ser mantido sincronizado manualmente (ou via uma verificação). O link simbólico é melhor em qualquer lugar onde links simbólicos sejam confiáveis.

Não desfaça depois

Se você vir CLAUDE.md como um link simbólico para AGENTS.md, isso é intencional — edite AGENTS.md, nunca substitua o link simbólico por uma cópia.

Modelo de AGENTS.md

# AGENTS.md

Instruções para agentes de IA e humanos trabalhando neste repositório.
`CLAUDE.md` é um link simbólico para este arquivo; este arquivo é a fonte de verdade.

## Visão geral do projeto
<o que é isso, em 1–3 frases>

## Comandos
- instalar: `…`
- dev: `…`
- build: `…`
- test / lint / format: `…`

## Convenções
- <estilo de código, linguagem/ runtime, formatação>
- Mensagens de commit: <ex. Conventional Commits>
- <qualquer coisa que um agente não deve fazer, ou deve sempre fazer>

## Estrutura
<direórios chave e o que está em cada um>