agents-md-starter

O que agents-md-starter faz?

Saída: AGENTS.md na raiz do repositório como a única fonte da verdade, mais CLAUDE.md contendo @AGENTS.md (Claude Code lê CLAUDE.md e suporta importações @path). Todo comando no arquivo deve ter sido executado com sucesso ou estar claramente marcado como não verificado.

Passo 1 — Escanear

python3 scripts/scan_repo.py /caminho/para/repo            # resumo legível
python3 scripts/scan_repo.py /caminho/para/repo --json     # fatos como JSON
python3 scripts/scan_repo.py /caminho/para/repo --draft > AGENTS.draft.md   # template preenchido

Ele detecta: linguagens por contagem de arquivos, gerenciador de pacotes a partir de lockfiles, scripts em package.json, alvos de Makefile, ferramentas em pyproject.toml (pytest, ruff, mypy, uv/poetry), arquivos de build Go/Rust/Java, frameworks (Next.js, Astro, Vite, Django, FastAPI, Rails…), workspaces de monorepo, workflows de CI, arquivos de exemplo .env e arquivos de regras de agente existentes. Ele nunca executa código do repositório.

Passo 2 — Ler antes de escrever

• Leia cada arquivo de regras existente que encontrou (CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, CONTRIBUTING.md). Mantenha suas regras reais; mescle, remova duplicatas, descarte as genéricas ("escreva código limpo").
• Leia o workflow de CI: os comandos que o CI executa são a definição mais confiável de "testes passam".
• Folheie 2–3 arquivos fonte representativos para capturar as convenções reais (nomenclatura, tratamento de erros, estilo de importação) — não invente convenções que o código não segue.

Passo 3 — Verificar comandos

Execute comandos de instalação/build/teste/lint a partir do rascunho (de forma segura: sem deploy, sem migrações contra bancos de dados reais, sem publicar). Para cada um: mantenha se funcionar; corrija se a variante correta for óbvia; caso contrário, marque (unverified) e avise o usuário. Anote quanto tempo a suíte de testes leva se for lenta.

Passo 4 — Escrever AGENTS.md

Comece de assets/AGENTS.template.md. Regras para um bom conteúdo:

• Curto. Mire em menos de ~150 linhas. Agentes leem isso a cada tarefa; cada linha custa contexto.
• Específico e verificável: "Execute pnpm test --filter web antes de commitar" é melhor que "teste seu código".
• Coloque os comandos primeiro. Depois estrutura, convenções, pegadinhas e regras de "não fazer".
• Registre o não óbvio: arquivos gerados que não devem ser editados, variáveis de ambiente necessárias para testes, o teste lento que deve ser pulado localmente, onde segredos nunca devem ir.
• Monorepos: AGENTS.md raiz para regras compartilhadas + packages/x/AGENTS.md aninhado para comandos específicos do pacote (agentes que suportam leem o arquivo mais próximo).

Passo 5 — Conectar as outras ferramentas

• Claude Code: crie CLAUDE.md a partir de assets/CLAUDE.template.md (ele contém @AGENTS.md). Se um CLAUDE.md já existir, mova suas regras para AGENTS.md e deixe apenas anotações específicas do Claude abaixo da importação.
• Codex: lê AGENTS.md nativamente — nada mais é necessário.
• Cursor: lê AGENTS.md na raiz; migre o conteúdo de .cursorrules para AGENTS.md e, após o usuário concordar, apague .cursorrules (obsoleto). Mantenha .cursor/rules/*.mdc apenas para regras com escopo de glob.
• Gemini CLI: lê GEMINI.md por padrão; defina "context": {"fileName": ["AGENTS.md", "GEMINI.md"]} em .gemini/settings.json ou crie um GEMINI.md de uma linha apontando para AGENTS.md. Verifique a documentação da versão instalada se essa chave mudou.
• Symlinks (ln -s AGENTS.md CLAUDE.md) também funcionam, mas quebram em checkouts Windows sem core.symlinks; a abordagem de importação é mais segura.

Veja references/tool-support.md para o arquivo que cada ferramenta lê.

Passo 6 — Relatar

Liste: arquivos criados/alterados, comandos verificados (com resultado), comandos marcados como não verificados, regras descartadas como duplicadas ou genéricas, e qualquer coisa que você precise que o usuário decida (ex.: apagar .cursorrules?). Não faça commit a menos que o usuário peça.