agents-md: Claude Code AGENTS.md como instruções do projeto
Carrega AGENTS.md como instruções do projeto, como o CLAUDE.md, com quatro modos em /config.
Permissões
- Intercepta chamadas de ferramentasVê cada chamada de ferramenta que o Claude faz (tool.call / tool.check) e pode bloqueá-la ou alterá-la.
- Altera a interfaceDesenha na interface do Claude Code: faixas, painéis, texto de status, notificações (ui.render / $.ui.*).
- testado com
- v2.1.310
- último teste
- requer
- Claude Code ≥ 2.1.287
- superfícies
- nenhuma
- código-fonte
- Anthropic (anthropics)
Instale dentro do Claude Code:
git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-mdO que este mod faz?
agents-md é um mod da Anthropic (anthropics/claude-code) que dá ao Claude Code AGENTS.md como fonte de instruções. Muitos repositórios guardam as instruções para agentes em AGENTS.md, enquanto o Claude Code lê CLAUDE.md. O mod entrega os arquivos AGENTS.md ao Claude Code como arquivos de instruções do projeto, de modo que o modelo os vê no mesmo lugar e com o mesmo enquadramento de um CLAUDE.md.
Uma opção, instructionFiles, define o que é carregado:
claude-md: só oCLAUDE.md, como hoje. O mod não acrescenta nada.claude-md-or-agents-md(padrão): um projeto semCLAUDE.mdpróprio recebe, no lugar, seus arquivosAGENTS.md.claude-md-and-agents-md: todoAGENTS.mdé carregado junto com oCLAUDE.md.managed-only: os arquivos de instruções do projeto e os seus são descartados; oCLAUDE.mdgerenciado da organização e a memória permanecem.
Os arquivos são procurados da raiz do sistema de arquivos até o diretório de trabalho, e contam tanto AGENTS.md quanto .claude/AGENTS.md. Quando o Claude lê um arquivo num subdiretório, o AGENTS.md desse diretório é anexado ao resultado, como o Claude Code faz com um CLAUDE.md aninhado. O mod não desenha nada na tela; o efeito está no que o modelo sabe.
Demonstração
A gravação inicia o Claude Code com o mod carregado no pequeno projeto de demonstração. Antes do clipe, uma linha de preparação oculta grava um AGENTS.md curto no projeto (duas regras: mensagens de commit começam com o id do ticket, como DEMO-123, e npm test roda antes de cada commit). O projeto não tem CLAUDE.md. No clipe perguntamos: "Without reading any file: what does my AGENTS.md say about commit messages? One sentence." O Claude responde em cerca de dois segundos, sem chamar nenhuma ferramenta, que as mensagens de commit começam com o id do ticket, como DEMO-123, porque o arquivo já estava no contexto.
Instalação
Use qualquer um dos métodos do bloco de instalação; eles instalam a partir do repositório anthropics/claude-code. O repositório não tem um marketplace.json que liste este plugin, então o bloco usa o próprio repositório como origem. O modo padrão não exige configuração: inicie uma sessão num projeto com AGENTS.md e sem CLAUDE.md.
$ install agents-md
Requer Claude Code ≥ 2.1.287
Instala a partir do marketplace do autor: anthropics/claude-code
1.Experimente sem instalar
git clone https://github.com/anthropics/claude-code claude --plugin-dir ./claude-code/mods/agents-mdCarrega o mod só para uma sessão. Nada é adicionado às suas configurações.
Como funciona
hooks/register.ts é o único módulo em hooks/hooks.json; todo o resto em hooks/ são peças auxiliares que ele importa. Nos dois modos de carregamento, um hook prompt.context recebe os arquivos de instruções que o Claude Code já carregou, procura AGENTS.md para cima com $.fs.ancestors e responde com a lista mais os arquivos novos como arquivos project. Esta é a busca, de hooks/register.ts:
const found = isClaudeProject
? NONE
: await $.fs.ancestors({ names: Names.AGENTS_NAMES }).catch(() => {
isWalkFailed = true
return NONE
})
const added = Files.unseenFiles(Files.filesOf(found), handed)unseenFiles descarta um arquivo cujo caminho o Claude Code já tem, ou cujo texto é igual ao de um arquivo de projeto entregue (por exemplo, um CLAUDE.md que é link simbólico para AGENTS.md). Um hook tool.call em Read deixa a leitura terminar e, para um arquivo sob a raiz do projeto, anexa os AGENTS.md dos diretórios entre a raiz e esse arquivo como Contents of <path>:, uma vez por laço de agente. Um hook agent.spawn para forks copia o conjunto já entregue ao pai, para que um fork não receba os mesmos arquivos duas vezes.
Personalize
A opção é a linha "Project instructions" de /config, um seletor com os quatro valores. À mão, ela vai nas configurações de usuário, em --settings ou nas configurações gerenciadas (o .claude/settings.json de um projeto não é lido para opções de plugins):
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}Com claude --plugin-dir mods/agents-md, a mesma entrada usa a chave "agents-md". A chave antiga projectInstructions continua sendo respeitada até que instructionFiles receba um valor diferente do padrão. O README do autor lista oito pontos em que o AGENTS.md ainda difere do CLAUDE.md; por exemplo, diretórios de --add-dir não contribuem com AGENTS.md e /memory não conhece esses arquivos.
Permissões e segurança
Lemos todos os arquivos que o plugin pode executar: plugin.json, hooks/hooks.json, hooks/register.ts, todos os módulos auxiliares de hooks/ que ele importa e os testes. Não há package.json, script de instalação, binário nem código empacotado, e as fontes não contêm caracteres fora do ASCII.
- Lê arquivos.
$.fs.ancestorslêAGENTS.mde.claude/AGENTS.mdsubindo pela árvore (e procuraCLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md). O texto vai ao modelo como instruções do projeto, então umAGENTS.mdem que você não confia pode direcionar o Claude, como umCLAUDE.mdpode. - Lê variáveis de ambiente.
HOME,USERPROFILE,CLAUDE_CODE_SIMPLEeCLAUDE_CODE_DISABLE_ATTACHMENTS, só para resolver caminhos com~e pular anexos onde o Claude Code não anexa nada. Não grava variáveis de ambiente. - Intercepta chamadas de ferramentas. O hook
tool.callemReade o hookagent.spawnpara forks esperam a chamada e devolvem o resultado; só acrescentam contexto após uma leitura bem-sucedida. Nunca negam uma chamada. Oclaude plugin validateobserva que falta um.catchnos dois hooks. - Telemetria. Chama
$.telemetry.loge$.telemetry.markcom contagens e escolhas fechadas (modo, número de arquivos e importações, tamanho total, algumas marcas). O README diz que não levam caminho nem texto e que são descartadas onde o plugin de telemetria da Anthropic não está instalado. Não verificamos esse plugin. - Sem rede, sem processos, sem gravações, sem daemons. O mod não usa
fetch, shell, escrita com$.fsnem temporizadores em segundo plano. Grava apenas uma linha de log de depuração via$.ui.log:no CLAUDE.md found; AGENTS.md loaded: <paths>. - Licença. O
LICENSE.mddo repositório diz "© Anthropic PBC. All rights reserved" e sujeita o uso aos Commercial Terms da Anthropic; por isso a página éredistributable: false: apontamos para o código e não o espelhamos.
O claude plugin validate não relatou erros. Mostrou apenas um aviso não bloqueante de "sem ícone" para o diretório do plugin, as duas notas de .catch citadas e o conselho de que o README não tem uma linha de instalação. Os 5 testes do autor passaram no Claude Code 2.1.310.
- Intercepta chamadas de ferramentas
- Vê cada chamada de ferramenta que o Claude faz (tool.call / tool.check) e pode bloqueá-la ou alterá-la.
- Altera a interface
- Desenha na interface do Claude Code: faixas, painéis, texto de status, notificações (ui.render / $.ui.*).
Compatibilidade e solução de problemas
Verificado com o Claude Code 2.1.310 no macOS (validate, testes e gravação da demo). O README o descreve como plugin embutido (agents-md@builtin), então uma versão do Claude Code que o inclua pode já carregá-lo; o /plugin lista os embutidos e permite desativá-lo ali. Se o seu AGENTS.md não for carregado:
- Procure um
CLAUDE.md,.claude/CLAUDE.mdouCLAUDE.local.mdda raiz até o diretório de trabalho. No modo padrão, qualquer um deles faz o mod ficar de fora. - Confira se a opção em
/confignão éclaude-mdnemmanaged-only. - Em execuções com
--bareou--safe-mode, ou comCLAUDE_CODE_DISABLE_CLAUDE_MDS, o Claude Code não carrega arquivos de instruções; comCLAUDE_CODE_DISABLE_ATTACHMENTS, os anexos aninhados são pulados. - Num cliente leve o mod não encontra nada, porque os arquivos do espaço de trabalho são remotos.
- Depois de mudar a opção, os arquivos novos chegam com o próximo contexto montado pelo Claude Code: o próximo turno,
/clearou uma compactação.
Perguntas frequentes
- O Claude Code lê AGENTS.md sem este mod?
- Segundo o README do mod, o motor carrega só o CLAUDE.md e o plugin acrescenta o AGENTS.md. Com a opção em claude-md, o plugin não acrescenta nada e o CLAUDE.md é carregado como sempre.
- O que acontece se meu projeto tiver CLAUDE.md e AGENTS.md?
- No modo padrão, claude-md-or-agents-md, o mod fica de fora quando existe um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md em qualquer ponto da raiz até o diretório de trabalho. Em claude-md-and-agents-md ele carrega os dois e pula um AGENTS.md que o CLAUDE.md já importa ou aponta por link.
- Ele envia o texto do meu AGENTS.md para algum lugar?
- O código não faz chamadas de rede nem executa comandos. Ele entrega apenas contagens (número de arquivos, de importações, tamanho total, modo) a um objeto de telemetria. Segundo o README, essas linhas só existem onde o plugin de telemetria da Anthropic está instalado e não trazem caminho nem texto de arquivo.
- Como mudo o modo?
- Abra /config e escolha um valor na linha "Project instructions", ou defina instructionFiles em pluginConfigs nas suas configurações de usuário. A mudança recarrega o módulo e o próximo contexto montado pelo motor usa o novo modo.
- Posso reutilizar o código no meu próprio plugin?
- Não copiando. O LICENSE.md do repositório diz "All rights reserved" e remete aos Commercial Terms da Anthropic, então esta página aponta para o código e não o espelha.
# Mods relacionados
DestaqueContext Inspector
Mostra o que preenche o contexto do Claude Code, quanto é desperdício e o que a compactação manteve.
- status
- painel
- notificação
- Grava arquivos
- Intercepta chamadas de ferramentas
- Lê seus prompts
- Altera a interface
- Adiciona comandos/ferramentas
testado com v2.1.303
Mais em Timers, tarefas e standups.