Carregador de Contexto de Agente
Visão Geral
Descoberta e carregamento automático de arquivos AGENTS.md em hierarquias de projeto para agentes de IA de codificação. Esta skill escaneia o workspace atual e seus diretórios pai para localizar arquivos de instrução do agente, então disponibiliza seus conteúdos para que a sessão ativa do agente tenha contexto operacional completo.
Pré-requisitos
- Um workspace de projeto contendo um ou mais arquivos
AGENTS.mdem qualquer profundidade de diretório - Permissões de Leitura e Glob para percorrer a árvore de diretórios
- Acesso ao Grep para pesquisar conteúdos de arquivos quando houver múltiplos candidatos
Instruções
- Escaneie o diretório de trabalho atual e todos os diretórios ancestrais (até a raiz do sistema de arquivos ou raiz do repositório) em busca de arquivos nomeados
AGENTS.mdouagents.md. - Pesquise subdiretórios do workspace atual por arquivos
AGENTS.mdadicionais que possam se aplicar a subprojetos ou módulos. - Determine a ordem de carregamento: arquivos mais próximos da raiz do repositório carregam primeiro (contexto global), arquivos em diretórios mais profundos carregam depois (substituição ou complemento).
- Leia cada arquivo
AGENTS.mddescoberto e extraia seus blocos de instrução, definições de fluxo de trabalho e declarações de restrição. - Mescle as instruções em um contexto unificado, observando quaisquer conflitos entre níveis (por exemplo, um agente de subdiretório substituindo uma regra de nível raiz).
- Apresente o contexto carregado como um resumo estruturado: caminho do arquivo fonte, contagem de instruções e quaisquer conflitos detectados.
- Armazene em cache os resultados da descoberta para a sessão atual, evitando varreduras redundantes do sistema de arquivos em ativações subsequentes.
Saída
- Lista ordenada dos caminhos dos arquivos
AGENTS.mddescobertos com sua profundidade de diretório - Conjunto de instruções mescladas combinando todos os contextos de agente descobertos
- Relatório de conflitos destacando quaisquer diretivas contraditórias entre níveis
- Status do cache da sessão indicando se os resultados são novos ou reutilizados
Tratamento de Erros
| Erro | Causa | Solução |
|---|---|---|
Nenhum AGENTS.md encontrado | O workspace não possui arquivos de instrução do agente | Confirme o diretório de trabalho correto; crie um AGENTS.md na raiz do projeto, se necessário |
| Permissão negada na travessia de diretório | Diretórios pai restritos acima do workspace | Limite a profundidade da varredura à raiz do repositório (detectada pela presença de .git/) |
| Link simbólico circular detectado | Diretórios com link simbólico criam um loop de travessia infinito | Pule diretórios com link simbólico durante a varredura; registre um aviso com o caminho do link simbólico |
| Instruções conflitantes entre níveis | Um AGENTS.md de subdiretório contradiz o arquivo de nível raiz | Sinalize o conflito na saída; aplique a instrução mais específica (mais profunda) por padrão |
| Erro de codificação de arquivo | AGENTS.md usa uma codificação diferente de UTF-8 | Tente fallback para latin-1; relate o caminho do arquivo e o problema de codificação |
Exemplos
Exemplo 1: Monorepo com instruções de agente por pacote
- Estrutura: O
AGENTS.mdraiz define convenções globais;packages/api/AGENTS.mdadiciona regras de ferramentas específicas da API. - Resultado: Ambos os arquivos carregados em ordem. As regras específicas da API complementam o contexto global sem conflito.
Exemplo 2: Workspace aninhado com políticas de commit conflitantes
- Estrutura: O
AGENTS.mdraiz diz "sempre assine commits";services/legacy/AGENTS.mddiz "pule a assinatura de commit." - Resultado: Conflito detectado e relatado. A diretiva mais profunda (legado) é aplicada com um aviso sobre a substituição.
Exemplo 3: Configuração inicial sem arquivos de agente
- Estrutura: Um repositório recém-clonado sem
AGENTS.mdem nenhum lugar. - Resultado: A varredura é concluída com zero arquivos encontrados. A saída inclui uma sugestão para criar
AGENTS.mdna raiz do repositório com um modelo mínimo.
Recursos
- Especificação do AGENTS.md do Claude Code: https://docs.anthropic.com/en/docs/agents
- Padrões de workspace monorepo para configuração de agente: https://docs.anthropic.com/en/docs/claude-code
- Melhores práticas de descoberta de arquivos para carregamento de configuração hierárquica