teresal92/agent-readiness-audit

Auditoria de prontidão para agentes

Audite o repositório atual em relação à lista de verificação abaixo e relate lacunas. Esta é uma auditoria SOMENTE LEITURA: nunca modifique, crie ou exclua arquivos do repositório.

Passo 1: Descubra a stack

Antes de julgar qualquer coisa, identifique:

• Linguagens, frameworks, gerenciador de pacotes, estrutura de monorepo
• Linter, formatador e typechecker em uso
• Executor de testes
• Gerenciador de hooks (husky, lefthook, pre-commit, simple-git-hooks, .git/hooks puro)
• Sistema de CI e sua configuração
• Arquivos de instrução para agentes (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions, etc.)
• Diretórios contendo habilidades, runbooks, prompts ou documentos de fluxo de trabalho

Avalie usando as ferramentas que este repositório realmente usa. Não recomende trocar ferramentas a menos que as atuais não consigam fazer o trabalho.

Orçamento

• Comece com listagens de diretórios, arquivos de configuração e arquivos de instrução. Use grep, contagens e listagens de arquivos em vez de ler arquivos de origem por completo.
• Amostre no máximo 3 arquivos representativos por pacote principal.
• Se o repositório for muito grande para ser coberto, diga quais partes não foram examinadas.

Passo 2: Avalie cada item da lista de verificação

Atribua um status por item:

• PASS: claramente implementado e funcionando
• PARTIAL: existe, mas incompleto, desatualizado, não aplicado ou inconsistente
• MISSING: você verificou e não está presente
• N/A: não se aplica a esta stack (diga o porquê)
• UNCLEAR: você não conseguiu verificar (diga o que te impediu, por exemplo, CI externo ou partes do repositório não examinadas)

Apoie cada status com evidências: caminhos de arquivo, chaves de configuração ou trechos citados curtos (menos de 15 palavras cada). Nunca adivinhe: se você verificou e não encontrou nada, marque MISSING; se não conseguiu verificar, marque UNCLEAR.

Lista de verificação

1. Instruções compartilhadas para agentes
   • Arquivo de instrução único no nível raiz lido por todos os agentes e novos engenheiros
   • Cobre regras de estilo de código (estilo de exportação, estrutura de importação, organização de arquivos, antipadrões)
   • Exige validação de dados externos nos limites de confiança
   • Diz quais testes valem a pena escrever
   • Define um gate de conclusão: lint, typecheck e testes relevantes devem passar antes do commit
   • Está atualizado e específico. Verifique de 3 a 5 regras em relação ao código real e relate se o código as segue.
2. Habilidades de fluxo de trabalho no repositório
   • Fluxos de trabalho recorrentes documentados como habilidades passo a passo ou runbooks junto ao código
   • Cobertura: commits, abertura/empilhamento de PRs, revisão de código, aprovação de um PR no CI, mudanças de dependência, localização
   • Fluxos de trabalho específicos da stack cobertos (camada de dados, roteador, sistema de design, codegen, etc.)
   • Cada habilidade tem um gatilho, passos ordenados e uma definição de conclusão
   • As habilidades são a única fonte da verdade, não duplicadas ou contraditórias
3. Convenções aplicadas como regras de lint
   • Convenções documentadas têm regras de lint correspondentes
   • Regras de lint personalizadas ou plugins cobrem uso específico do projeto (busca de dados, estilização, testes, traduções)
   • Regras de antipadrão existem para erros comuns de agentes: asserções de tipo encadeadas ou desnecessárias, parâmetros com tipagem frouxa (unknown/any), spreads condicionais de objetos vazios, além de quaisquer padrões de baixa qualidade recorrentes encontrados neste código
   • Regras são erros, não avisos, sem desabilitações em massa
4. Gates automatizados
   • Hook de pré-commit formata, faz lint e verifica tipos do código alterado
   • Hook de pré-push faz lint ou testa pacotes afetados, incluindo dependentes
   • CI reexecuta as mesmas verificações para que os hooks não possam ser ignorados
   • Hooks são razoavelmente rápidos
   • Hooks estão configurados: a configuração do hook está commitada, existe uma etapa de instalação (script prepare, documento setup ou core.hooksPath), e os comandos que ele chama existem. Verifique lendo arquivos; nunca execute hooks.
5. Supervisão e estrutura
   • Decisões de arquitetura documentadas
   • Revisão de PR exigida antes do merge (verifique proteção de branch ou CODEOWNERS se visível)
   • Limites de pacotes e módulos são claros e aplicados

Passo 3: Encontre convenções não documentadas

Amostre o código em busca de padrões aplicados consistentemente mas não escritos em lugar nenhum, e de padrões que agentes comumente erram (tipagem frouxa, dados externos não validados, exportações inconsistentes, lógica duplicada). Liste os 5 principais candidatos para adicionar ao arquivo de instrução ou transformar em regras de lint.

Passo 4: Relatório

Produza:

1. Uma tabela de resumo: item, status, evidência em uma linha
2. Uma seção "lacunas": cada item PARTIAL, MISSING ou UNCLEAR, o que está errado e por que isso é importante para a confiabilidade do agente
3. Uma lista de recomendações priorizadas (maior alavancagem primeiro), cada uma com um próximo passo concreto e esforço aproximado (pequeno/médio/grande), expressa em termos das ferramentas existentes deste repositório
4. Os 5 principais padrões candidatos do Passo 3

Seja direto. Não encha com elogios. Se algo está bom, diga PASS e siga em frente.

Após o relatório, ofereça-se para estruturar as peças faltantes (arquivo de instrução inicial, modelos de habilidade, esboços de regras de lint), mas não crie nada até que seja solicitado.