agents-md-audit

Verifica instruções AGENTS.md ou CLAUDE.md existentes contra evidências do projeto e política. Use para revisões periódicas, verificações de desvio após alterações ou para estabelecer ou continuar um registro de auditoria Git. Relata defeitos e limites de verificação, retém descobertas não resolvidas e prepara uma mensagem de checkpoint. Aplica correções ou cria o checkpoint apenas quando autorizado.

O que é agents-md-audit?

A skill 'agents-md-audit' é uma ferramenta de auditoria para arquivos de instrução de agentes de IA, como AGENTS.md e CLAUDE.md. Ela verifica se as instruções documentadas correspondem ao estado real do projeto e à política estabelecida, priorizando alegações que poderiam enganar um agente. A auditoria é somente leitura por padrão, preparando correções e uma mensagem de checkpoint para revisão; aplica correções ou cria um checkpoint apenas quando autorizado. A skill suporta plataformas como Claude Code, Cursor e Codex, e é usada para revisões periódicas, verificações de desvio após mudanças e para estabelecer ou continuar um registro de auditoria Git. Ela cobre verificação de precisão e política, manutenção, decisões e avisos, e forma, e produz um relatório detalhado com descobertas novas, carregadas e fechadas, além de uma mensagem de checkpoint que inclui o relatório de auditoria e trailers específicos.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/has2k1/agents-grimoire/tree/HEAD/skills/agents-md-audit

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Auditoria de AGENTS.md

Audite instruções contra o estado do projeto e a política estabelecida. Priorize alegações que possam enganar um agente. A forma do documento e a frequência de edição por si só não estabelecem um defeito. Relate nenhum defeito quando as verificações demonstrarem nenhum; documentação de inicialização breve e instruções precisas não alteradas podem ser suficientes.

Mantenha a auditoria somente leitura por padrão, incluindo o índice e o histórico do Git. Prepare correções e uma mensagem de checkpoint para revisão. Aplique correções ou crie um checkpoint quando a solicitação autorizar essa ação; use a autoridade existente sem pedi-la novamente. Execute verificações sem correção automática ou outras opções de escrita na fonte e relate pré-requisitos de execução que não estão disponíveis.

Cobertura

Registre a cobertura como os arquivos, alegações, histórico e verificações realmente examinados.

  1. Registre a revisão do repositório e o estado da árvore de trabalho. Faça um inventário dos arquivos de instrução, regras ancestrais relevantes, substituições, importações, links e mapas de módulos no repositório. Inclua sistemas CLAUDE.md existentes, em vez de assumir que AGENTS.md é seu ponto de entrada ativo.
  2. Confirme quais arquivos o harness pretendido descobre e quais exigem leituras explícitas. Verifique caminhos de carregamento relevantes e orçamentos de tamanho em relação à configuração disponível ou documentação atual do harness. Marque entrega desconhecida como não verificada; nomes de arquivos e colocação de diretório por si só não provam o carregamento.
  3. Declare arquivos e alegações a verificar, qualquer amostragem, pré-requisitos de comando e o histórico disponível. Limite o veredito quando o repositório estiver sujo, o histórico for superficial ou indisponível, ou as verificações não puderem ser executadas. Audite alterações locais separadamente de um snapshot confirmado; não as atribua ao seu SHA. Quando uma verificação for executada em arquivos diferentes do snapshot confirmado, como uma árvore de trabalho com alterações locais, declare onde foi executada e quais caminhos diferiram.

Histórico e descobertas anteriores

Para um repositório Git, selecione a linha de base antes de verificar alterações intervenientes. Sem histórico Git, verifique o estado atual e relate que a verificação histórica não está disponível.

Uma auditoria concluída terminou suas verificações declaradas de todo o repositório; ela pode relatar defeitos, amostragem e verificações indisponíveis com limites explícitos. Um resultado limpo significa que nenhum defeito foi demonstrado dentro das verificações concluídas. Uma auditoria que não pode terminar produz um relatório, mas nenhum checkpoint.

Um checkpoint é um commit Git vazio de pai único cuja mensagem armazena o relatório de uma auditoria concluída e os trailers do modelo de Mensagem de checkpoint. Seu único pai é a revisão auditada, o snapshot confirmado examinado por essa auditoria. Alterações locais são separadas desse snapshot. Um commit é um checkpoint apenas quando atende a todas as condições em Seleção de linha de base; qualquer outro commit é um commit comum, independentemente do que sua mensagem diga.

Uma linha de base é o checkpoint mais próximo no histórico do primeiro pai do branch alvo. Ela define o limite do histórico, a revisão após a qual a auditoria inspeciona alterações até a revisão auditada. Suas descobertas Novas e Carregadas são o conjunto completo de descobertas anteriores abertas. Uma auditoria que não produz checkpoint deixa a linha de base inalterada.

A saída de inicialização permanece documentação candidata até ser verificada e não pode por si só fornecer uma linha de base.

Seleção de linha de base

Percorra o histórico do primeiro pai do branch alvo a partir de HEAD. Trate commits com um trailer Agents-Audit-Version como candidatos; identifique-os pelo trailer em vez do assunto. Por exemplo:

git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidato> | git interpret-trailers --parse

Esses comandos encontram candidatos. Um candidato é um checkpoint apenas quando sua mensagem e objetos Git atendem a todas estas condições:

  • Cada trailer no modelo de mensagem tem um valor não conflitante, a versão é suportada e a revisão da skill ou hash de conteúdo é identificável.
  • O commit tem exatamente um pai. O SHA completo desse pai é igual a Agents-Audit-Commit, e tanto a árvore do pai quanto a do commit são iguais a Agents-Audit-Tree. A igualdade da árvore sozinha não pode detectar repetição em um histórico diferente que por acaso produza os mesmos arquivos.
  • O commit está no histórico do primeiro pai do alvo.
  • Agents-Audit-Previous nomeia o checkpoint anterior mais próximo no histórico do primeiro pai da revisão auditada, ou none para um limite de histórico inicial explicitamente estabelecido. O commit nomeado deve ser ele próprio um checkpoint.
  • A mensagem contém cada seção de relatório do modelo, com cobertura declarada. A menos que Agents-Audit-Previous seja none, cada ID sob descobertas Novas ou descobertas Carregadas no checkpoint nomeado aparece sob descobertas Carregadas ou descobertas Fechadas.

Como cada predecessor deve ser ele próprio um checkpoint, verifique candidatos do mais antigo para frente e reutilize cada resultado; cada commit é então verificado uma vez. Selecione o candidato mais próximo que atenda a essas condições como a linha de base. Trate qualquer outro candidato como um commit comum na janela de histórico: não leia nenhuma descoberta ou fechamento de sua mensagem e deixe-o de fora do relatório e da mensagem do checkpoint. Quando um predecessor não estiver disponível ou o histórico superficial impedir essas verificações, declare a lacuna. Não substitua silenciosamente um limite de histórico conhecido pelos últimos poucos commits ou declare o trabalho como primeira auditoria. Se nenhuma linha de base puder ser estabelecida, verifique o estado atual dentro de limites explícitos e deixe a cobertura histórica não verificada. Para uma primeira auditoria genuína sem checkpoint anterior, verifique o estado atual e declare um limite de histórico inicial explícito.

Rebase, cherry-pick e squash dão novos pais aos commits, portanto, verifique as condições novamente após reescrever o histórico. Estabeleça checkpoints duráveis após integração quando o histórico de recursos for esmagado.

Verificações

Precisão e política

  • Verifique comandos em relação à configuração do projeto e seus pré-requisitos. Execute verificações viáveis em um ambiente adequado. Atribua falhas a uma invocação desatualizada, um defeito de implementação, um pré-requisito indisponível ou uma verificação incompleta; um comando de teste válido que encontra uma regressão não está desatualizado.
  • Resolva referências nomeadas, caminhos, importações e entradas de mapa de módulo. Inspecione renomeações, propriedade compartilhada e regras ancestrais aplicáveis antes de chamar uma instrução ausente. Demonstre o defeito e, em seguida, julgue sua gravidade pela consequência provável para um agente seguindo a instrução, não apenas por um símbolo ausente.
  • Verifique invariantes importantes em relação à implementação e testes, tratando docstrings e comentários como alegações, não como evidência. Verifique uma afirmação condicional com entradas em ambos os lados de sua condição. Distinga descrições de política: código intencional ainda pode violar um limite estabelecido. Resolva conflitos usando a autoridade da tarefa e decisões registradas; não reescreva a política apenas para corresponder ao código que a viola.
  • Inspecione avisos em relação a caminhos concretos de falha ou regressão. Remova detalhes obsoletos ou superficiais, retenha uma salvaguarda útil quando contorná-la ainda for um risco realista e apare explicações já adequadamente suportadas por testes ou aplicação. Prefira orientação presente a um histórico de falhas corrigidas.

Relate defeitos demonstrados como desatualizados, contraditos, ausentes, conflitos de política ou avisos obsoletos. Mantenha alegações incertas sob verificações não verificadas. Inclua a instrução afetada, evidência do repositório, consequência e correção proposta.

Manutenção

Inspecione alterações de código, configuração, dependência e instrução desde o limite do histórico. Mapeie cada alteração relevante para alegações que ela possa invalidar, incluindo arquivos de instrução não alterados. Use palavras-chave de mensagem de commit e contagens opcionais de commits que alteraram código e instruções juntos para escolher alterações para inspeção, não para julgar a qualidade da documentação.

Relate um defeito de manutenção apenas quando uma alteração invalidou uma alegação documentada ou omitir uma instrução necessária. Permita que um invariante preciso sobreviva a muitas alterações intocadas. Trate correções independentes, commits de inicialização, reparos de auditoria e commits de checkpoint como trabalho legítimo. Uma refatoração entre módulos não precisa editar instruções cujas alegações permanecem verdadeiras.

Decisões e avisos

Inspecione decisões arquiteturais independentemente da descoberta de correção de bugs. Procure escolhas aceitas cuja consequência deva restringir alterações futuras e cuja razão não seja aparente a partir do código. Use uma explicação registrada ou confirmação pelo tomador de decisão; um diff prova uma alteração, não sua intenção. Elabore a regra, a razão e as condições para reconsideração apenas quando evidenciadas e ainda úteis. Deixe uma alternativa rejeitada que vale a pena mencionar em um comentário na fonte que ela afeta, onde um agente alterando esse código a encontrará. Durante a inicialização, continue a usar apenas fontes atuais; não extraia o histórico do Git em busca de razões ou invente justificativas.

Para bugs significativos diagnosticados, verifique se a lição ainda impede um erro dispendioso ou repetido. Proponha uma entrada concisa registrando o sintoma, mecanismo e reconhecimento ou prevenção apenas quando adicionar orientação útil. Quando contornar uma abstração puder reintroduzir a falha, reformule o aviso como uma salvaguarda concisa e explique por quê. Proponha exclusão quando o mecanismo não existir mais, o erro for superficial ou a aplicação já carregar a lição adequadamente. Mantenha mecanismos incertos como propostas para confirmação.

Forma

Verifique a forma após a precisão. Coloque regras de todo o repositório no arquivo raiz, regras compartilhadas por módulos em um arquivo de raiz de fonte ou pacote (um hub) e regras de módulo distintas em um arquivo local (uma folha). Use apenas os escopos que precisam de orientação separada; permita projetos de um arquivo, múltiplos hubs e seções vazias omitidas. Mantenha uma explicação canônica e permita um breve lembrete com escopo e um link quando melhorar a descoberta. Preserve versões aplicáveis, datas de verificação, plataformas e condições de medição. Remova narração de progresso obsoleta, justificativa inventada, duplicação desnecessária e instruções que não ajudam mais com uma alteração. Julgue a especificidade por decisões úteis, não pela frequência com que o texto muda.

Relatório

Declare se as instruções verificadas são precisas e limite essa conclusão às alegações examinadas. Registre a revisão, conteúdo sujo ou ignorado examinado, inventário de instruções, alegações verificadas ou amostradas, limite do histórico, resultados do comando, ambiente e versões relevantes e verificações não resolvidas. Mantenha o relatório interpretável a partir do próprio repositório, usando caminhos relativos ao repositório e revisões Git como evidência.

Verifique novamente cada descoberta em aberto da linha de base e coloque-a sob descobertas Carregadas ou descobertas Fechadas antes de finalizar o relatório.

Separe as descobertas nestas seções; escreva None quando uma estiver vazia:

  • Registre novas descobertas com IDs estáveis recentes, instruções afetadas, evidências, consequências e correções necessárias.
  • Carregue cada descoberta não resolvida da linha de base, incluindo aquelas que ela listou como novas, com seu ID, seu checkpoint de origem (o checkpoint que a registrou pela primeira vez) e um relato completo de sua evidência, consequência e correção necessária. Mantenha uma descoberta aberta quando sua resolução não puder ser verificada e divulgue evidências que não podem ser validadas.
  • Feche descobertas com a resolução ou substituição verificada e evidências de suporte. Registre cada fechamento uma vez e, em seguida, omita-o de relatórios posteriores. Mantenha seu histórico no checkpoint anterior, em vez de crescer um arquivo em cada relatório.

Aloque IDs sem reutilizar os aposentados; por exemplo, use um carimbo de data/hora UTC específico da auditoria mais um contador e retenha esse ID daí em diante. Declare no relatório se a auditoria foi concluída; uma auditoria interrompida ou inacabada termina com o relatório. Reivindique um resultado limpo apenas dentro das verificações que o demonstram.

Mensagem de checkpoint

Prepare a seguinte mensagem como parte da entrega de uma auditoria concluída. Inclua o próprio relatório de auditoria, não ponteiros para um rastreador de problemas externo, um relatório local ou outra fonte externa. Use o assunto sem cabeçalho e os trailers exatamente como mostrado, com cabeçalhos ## e linhas em branco para as seções do relatório. Registre IDs de objeto completos e uma revisão ou hash de skill identificável, em vez de depender de um caminho instalado.

chore: registrar auditoria de documentação do agente

## Cobertura

Examinados <arquivos ou diretórios de instrução relativos ao repositório>.
Verificadas <alegações e verificações realizadas, incluindo qualquer amostragem>.
Inspecionado histórico de <limite do histórico> até a revisão auditada.
Usados <ambiente e versões de ferramentas relevantes, e onde as verificações foram executadas>.

## Verificações não verificadas

<Verificações não concluídas e suas razões, ou None.>

## Descobertas novas

<ID estável, instrução e seção afetadas, descoberta, evidência,
consequência e correção necessária para cada nova descoberta; ou None.>

## Descobertas carregadas

<ID estável, checkpoint de origem e um relato autocontido de cada
descoberta não resolvida, incluindo evidência, consequência e correção
necessária; ou None.>

## Descobertas fechadas

<ID estável, resolução ou substituição e evidência de suporte
para cada descoberta que esta auditoria fecha; ou None.>

Agents-Audit-Version: 1
Agents-Audit-Commit: <SHA completo do commit pai auditado>
Agents-Audit-Tree: <SHA da árvore auditada>
Agents-Audit-Skill-Revision: <revisão da skill ou hash de conteúdo>
Agents-Audit-Previous: <SHA do checkpoint de linha de base ou none>

Criação de checkpoint

Crie um checkpoint apenas para uma auditoria concluída e somente com autorização para essa escrita. Exija que a revisão auditada ainda seja HEAD e que as instruções e o código auditados sejam representados em sua árvore. Confirme correções autorizadas primeiro e verifique o snapshot resultante antes de registrar seu checkpoint. Atualize o relatório e os trailers para descrever esse snapshot verificado se as correções alteraram a revisão auditada. Exclua conteúdo não confirmado ou ignorado de alegações sobre o snapshot confirmado e registre qualquer limite de cobertura resultante. Recuse-se a registrar um checkpoint para um estado sujo observado como se

…

[truncado para tradução]}}

Habilidades Relacionadas