Pular para o conteúdo
claudemods

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

Instale dentro do Claude Code:

git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-md
Todas as opções de instalação ↓

O 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ó o CLAUDE.md, como hoje. O mod não acrescenta nada.
  • claude-md-or-agents-md (padrão): um projeto sem CLAUDE.md próprio recebe, no lugar, seus arquivos AGENTS.md.
  • claude-md-and-agents-md: todo AGENTS.md é carregado junto com o CLAUDE.md.
  • managed-only: os arquivos de instruções do projeto e os seus são descartados; o CLAUDE.md gerenciado 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. 1.Experimente sem instalar

    git clone https://github.com/anthropics/claude-code
    claude --plugin-dir ./claude-code/mods/agents-md

    Carrega 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.ancestors lê AGENTS.md e .claude/AGENTS.md subindo pela árvore (e procura CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md). O texto vai ao modelo como instruções do projeto, então um AGENTS.md em que você não confia pode direcionar o Claude, como um CLAUDE.md pode.
  • Lê variáveis de ambiente. HOME, USERPROFILE, CLAUDE_CODE_SIMPLE e CLAUDE_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.call em Read e o hook agent.spawn para forks esperam a chamada e devolvem o resultado; só acrescentam contexto após uma leitura bem-sucedida. Nunca negam uma chamada. O claude plugin validate observa que falta um .catch nos dois hooks.
  • Telemetria. Chama $.telemetry.log e $.telemetry.mark com 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 $.fs nem 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.md do 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.md ou CLAUDE.local.md da 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 /config não é claude-md nem managed-only.
  • Em execuções com --bare ou --safe-mode, ou com CLAUDE_CODE_DISABLE_CLAUDE_MDS, o Claude Code não carrega arquivos de instruções; com CLAUDE_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, /clear ou 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.
Context Inspector em execução no Claude CodeDestaque

Context 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.