shimo4228/agent-stocktake

agent-stocktake — Auditoria de Qualidade de Definições de Agente

Avalie toda definição de agente sob <harness>/agents/*.md e atribua a cada um um veredito: Manter / Melhorar / Atualizar / Mesclar / Rebaixar para skill / Dissolver / Aposentar. A unidade de auditoria é o arquivo, mas a unidade de custo é dividida entre duas camadas — essa divisão é a razão desta skill existir como um terceiro irmão ao lado de skill-stocktake e rules-stocktake.

Nota de design — o modelo de custo híbrido. O custo de uma skill é poluição de gatilho (disparo probabilístico degrada a seleção); o custo de uma regra é residência (sempre carregada). Um agente tem ambos ao mesmo tempo: sua description é injetada em toda sessão via listagem "Available agent types" (residência, como uma regra), enquanto seu corpo carrega apenas quando o agente é invocado (invocação, como uma skill — mas acionada pelo julgamento de delegação do Claude, não por correspondência de descrição com as palavras do usuário). Portanto, a descrição é auditada quanto à densidade de residência e o corpo quanto à qualidade de invocação, com perguntas diferentes para cada camada.

Nota de design 2 — edições aprovadas são aplicadas por esta skill, no ramo de apply. Mesmo raciocínio que rules-stocktake: nenhum mecanismo de melhoria existe para definições de agente, e o corpus é pequeno o suficiente para ler em um contexto — delegação seria engenharia excessiva. A exceção de transferência é Rebaixar para skill (criar uma skill é trabalho do skill-writer).

Raízes. <harness> abaixo é o harness que esta auditoria cobre: ~/.claude por padrão, ou .claude/ de um repositório quando a skill harness-stocktake executa em modo projeto (sua seção Raízes mapeia os caminhos, nomeia a evidência que é n/a lá, e diz quais verificações de convenção se aplicam). O ledger <ledger> pertence a esse harness: ${CLAUDE_SKILL_DIR}/results.json quando o diretório desta skill está dentro de <harness> (o harness carrega sua própria cópia da skill), senão <harness>/stocktake/agent-stocktake.json (um plugin instalado, ou modo projeto). De qualquer forma, é commitado com as outras alterações do harness no ramo de apply.

Modos ($ARGUMENTS)

Argumento	Comportamento
nenhum / full	Ler e avaliar toda definição de agente (padrão)
changed	Reavaliar apenas arquivos cujo mtime é mais novo que evaluated_at do <ledger>; carregar o restante do ledger

changed detecta alterações inline (sem script):

Caminhos abaixo começam em ${CLAUDE_SKILL_DIR}, o diretório que contém este SKILL.md; um agente que não substitui a variável a lê como aquele diretório.

find <harness>/agents -name "*.md" -newermt "$(jq -r .evaluated_at "<ledger>")"

Como em rules-stocktake, as verificações de integridade da Fase 1 sempre executam sobre o conjunto completo — aposentar uma skill ou hook quebra silenciosamente uma referência dentro de um corpo de agente não modificado, e mtime não pode detectar isso. Qualquer agente cuja verificação de referência (Passo 3 abaixo) falhar recentemente se junta ao conjunto de reavaliação. O script também não tem modo changed, por uma razão diferente: os pares quase duplicados e o total de residência são propriedades do conjunto, então um corpus parcial forneceria números errados em vez de menos números.

Fase 1 — Evidência, inventário, uso

Passo 1 — Execute o script de evidência (não conte manualmente)

uv run --frozen --project "${CLAUDE_SKILL_DIR}" \
       --directory "${CLAUDE_SKILL_DIR}" \
       python scripts/agent_evidence.py --root <harness>

Modo evidência: JSON no stdout, exit 0 quantas descobertas houver (exit 2 apenas quando o corpus é ilegível). Ele mede e enumera; nunca atribui um veredito.

Transcreva o JSON em descobertas — nunca remeça a olho. O que ele fornece:

Campo JSON	Substitui
desc_words / body_lines / total_desc_words	a passagem wc -w / wc -l
tools.items[].status + registry.known_tools	builtin / unverified / mcp. unverified significa "não na lista datada do script", não "não existe" — você tem o registro de ferramentas ativo e o script não, então confirme um unverified contra sua própria lista de ferramentas antes de chamá-lo de evidência Update. registry.known_tools.as_of é a data dessa lista (null quando --known-tools a substituiu)
tools.items[].server_in_config + registry.mcp_config_files	Não é um veredito. Diz apenas se o servidor aparece nos arquivos de configuração local listados — servidores fornecidos por um conector nunca aparecem lá, então um false não é "aposentado". null significa que nenhuma fonte de configuração foi analisada. Verifique o status de cada fonte antes de usar isso; um false ao lado de uma fonte não-ok não é evidência
unreadable	arquivos que a varredura não pôde abrir, com uma razão. Não vazio significa que a varredura está incompleta — nomeie-os e corrija antes de declarar um total, porque uma instrução de supressão dentro de um arquivo ilegível agora está certificadamente ausente
tools_unparsable	agentes cuja linha tools: não foi analisada (ex. estilo flow YAML). Seus items é [], que parece idêntico a um agente sem chave tools: — ou seja, irrestrito. Não é; a lista simplesmente não foi lida
description_near_duplicates	a verificação de descrições quase idênticas; gêmeos dividem o tráfego de delegação, então cada par alimenta a pergunta de sobreposição do Estágio 1
suppression_candidates	candidatos numerados por linha para a pergunta de supressão do Estágio 1 (o catálogo é bilíngue porque o corpus é)
always_never_candidates	candidatos numerados por linha para a pergunta de sobre-restrição, apenas corpo — uma descrição é um gatilho de delegação, não uma instrução para o agente

Os dois últimos são candidatos, não descobertas — leia cada linha citada antes de escrever. O catálogo também é um piso, não um censo: ele contém cinco redações extraídas de um corpus, então uma supressão escrita de outra forma ("pule qualquer coisa sobre a qual você não tenha certeza", "evite descobertas que seriam apenas ruído") não aparece em nenhum campo JSON. Continue lendo por essas; uma lista vazia não é um atestado de saúde.

As taxas de falso positivo medidas residem fora deste arquivo, então este passo não carrega números que se tornem obsoletos.

Passo 2 — Leia os gates que já possuem o resto

Três verificações ficam fora do script porque, em um harness que tem um gate de lint (<harness>/scripts/hooks/harness_lint.py), esse gate as possui. Leia sua saída quando existir; sem ela, faça as três verificações com Read / Grep:

• Frontmatter analisa e carrega name, description, origin, model, e model é um alias → o lint_agents do script de lint (no harness do autor ele executa em .claude/verify.sh e no hook pre-commit). Uma origem ausente, onde o harness declara a convenção de origem, ainda é uma descoberta de integridade, alimentando Melhorar.
• name é igual ao stem do nome do arquivo → o mesmo lint_agents. Ele não admite julgamento e o registro de delegação chaveia nele, então pertence a um gate que impede um commit — não a evidência que um leitor pode ou não transcrever. Uma descoberta aqui é um commit bloqueado, não um veredito de stocktake.
• Links Markdown dentro de corpos de agente resolvem → o mesmo script's lint_markdown_links (seus escopos incluem agents).

Passo 3 — Resolva referências de caminho literal (a única verificação que mais ninguém possui)

lint_markdown_links vê apenas sintaxe de link, e scan_refs.py do skill-health varre a árvore de skills. Um caminho escrito como prosa dentro de um corpo de agente (<harness>/hooks/foo.sh, skills/foo/SKILL.md) não é coberto por nenhum dos dois. Grepe o corpus por eles e ls cada um.

Passo 4 — Inventário

Enumere com Glob: <harness>/agents/*.md. Leia cada arquivo em um contexto (o corpus é pequeno). As colunas de residência e corpo vêm do JSON do Passo 1 — nunca confie em números escritos em docs, incluindo este.

Passo 5 — Contagens de uso

Entrada de evidência: baixo uso nomeia um candidato, e o conteúdo decide o veredito. Quando a configuração mantém um log de uso de agente (<harness>/metrics/agent-usage.jsonl; ausente = uso n/a), leia-o inline (um hook de log de uso como log-agent-usage.sh anexa um evento invoke por lançamento da ferramenta Agent, chaveado por seu campo agent, cujo valor é o subagent_type) e conte eventos por agente em 7 / 30 / 90 dias. Agregue com um one-liner descartável python3/jq.

• Se o log estiver ausente ou seu primeiro evento for mais novo que 90 dias, renderize o uso como — (não medido). Nunca renderize como 0 — não medido e não usado são fatos diferentes.
• Contagens são limites inferiores: apenas lançamentos da ferramenta Agent (Task) são capturados. Workers agent() de Workflow, dispatch interno de plugin e maquinário embutido que contorna a chamada de ferramenta não alcançam o hook. Um agente de baixo uso entra no Estágio 1 como candidato a Aposentar/Dissolver; seu valor pode ser episódico (ex. revisores de paper disparam apenas perto de um depósito), então o conteúdo decide.
• Log existe desde 2026-07-27; antes dessa data não há medição alguma.

Declare o resultado da varredura upfront, pegando as contagens do JSON do Passo 1: agents_total menos qualquer coisa em unreadable, que deve ser nomeado, total_desc_words (o imposto de residência por sessão da listagem), falhas de integridade, e se o uso é mensurável. Carregue falhas para o Estágio 1 como evidência pré-computada.

Fase 2 — Avaliação (totalmente inline, holística)

Leia cada corpo enquanto vê o conjunto inteiro.

Estágio 1 — tela binária (todo agente). Sim/Não explícito por item; superfície apenas as respostas Não. As duas primeiras perguntas auditam a camada de descrição (residência), as restantes a camada de corpo (invocação):

• A descrição merece sua residência? — densa, distinta e que habilita seleção na listagem sempre carregada; declara quando delegar E quando NÃO delegar
• A descrição é verdadeira em relação ao corpo? — o que promete é o que o corpo faz (uma descrição divergente desvia a delegação toda sessão, mesmo se o corpo estiver bom)
• Corpo livre de instruções de supressão? — comece pelos suppression_candidates deste agente no JSON da Fase 1, tratados conforme o Passo 1. O que conta: limiares de confiança ("relate apenas descobertas das quais você tem ≥N% de certeza", "atribua a cada descoberta uma confiança e descarte as baixas"), pisos de gravidade ("apenas alta gravidade"), enquadramentos "seja conservador". A orientação da geração atual é: relate tudo, filtre em uma passagem separada — uma instrução de supressão é seguida literalmente e descarta descobertas silenciosamente. Um Não aqui é um candidato a Melhorar-por-inversão: reescreva a instrução na direção oposta, nunca apenas delete a seção (deletar deixa o quadro supressivo; inverter o substitui)
• Cópia de origem externa atual? — para um agente cujo origin é um repositório externo e cujo corpo é uma cópia literal (ex. uma sobreposição embutida como Explore), a versão da fonte nomeada no comentário principal do corpo corresponde à ferramenta instalada (claude --version); uma incompatibilidade é um Update (diff contra o bundle e recopiar). As perguntas de supressão e sobre-restrição são puladas para tais cópias — o corpo é do fornecedor, não nosso
• Corpo livre de sobre-restrição de geração anterior? — procedimentos passo a passo exaustivos para julgamento que o modelo atual mantém nativamente, ênfase repetida, pares SEMPRE/NUNCA que o julgamento de contexto circundante deveria possuir. Os always_never_candidates da Fase 1 localizam os tokens; decidir se um acerto é uma diretiva ou apenas cita as palavras é o trabalho desta pergunta
• Não absorvido pelo substrato? — o harness agora cobre o trabalho deste agente nativamente (maquinário de revisão nativo, modo plano, comandos slash embutidos)? Absorção → candidato a Dissolver; a afirmação deve nomear seu absorvedor concretamente. Julgue com o eixo contexto fresco/rico: papéis que se beneficiam de contexto fresco (revisão, verificação adversarial, avaliação de essência — descorrelação do custo irrecuperável do proponente) legitimamente vivem em um subagente; papéis que se beneficiam de contexto rico (planejamento, geração, implementação — intenção do usuário, restrições na conversa) são trabalho do loop principal, então para eles o próprio loop principal conta como um absorvedor. Duas justificativas auxiliares legitimamente substituem a atração de contexto rico: um contrato de renderização de entrada congelada — o chamador congela um pacote autocontido antes da invocação, então o contexto da conversa não é necessário por design (prompt-forager, que recebe uma linha de propósito) — e isolamento de contexto em massa — o trabalho lê ou produz volume que poluiria o contexto principal (pesquisador, um ângulo de pesquisa web por execução)
• Referências técnicas atuais? — verifique incondicionalmente todo artefato que o corpo nomeia: ls cada caminho referenciado, execute verificações --help / versão para comandos nomeados, flags, nomes de modelo e listas de ferramentas. "Verificar se parece desatualizado" é frase proibida — a condição é o que dilui; afirmações verificáveis deterministicamente recebem verificações determinísticas, toda vez
• Único dentro do conjunto? — nenhum outro agente (ou skill) possui o mesmo trabalho; uma divisão orquestrador→sub-agente documentada NÃO é sobreposição

Oito perguntas e não mais — decomposição adicional degrada o julgamento holístico (consulte Referências).

Estágio 2 — teste de pressão do veredito (apenas candidatos não-Manter). Gere 1–3 perguntas atômicas sim/não específicas do agente que tentam refutar o veredito preliminar, cada respondida com uma linha de evidência (leitura de arquivo, verificação de caminho, --help, WebSearch, verificação de doc do harness). Para candidatos a Dissolver uma pergunta é obrigatória: "A funcionalidade absorvente do harness pode ser nomeada concretamente — Sim/Não" — uma alegação de absorção que não pode nomear seu absorvedor é refutada. E quando um Dissolver está prestes a ser refutado por uma capacidade que a contraparte do substrato não tem (uma ferramenta, um sub-agente conectado), uma contra-pergunta é obrigatória antes de aceitar a refutação: "O subagente é o lugar certo para usar essa capacidade — ou o loop principal a possui de qualquer forma?" Existência de capacidade é necessária mas não suficiente; o eixo contexto fresco/rico decide onde a capacidade pertence (precedente: a refutação do planejador colapsou porque o loop principal possui toda a ferramenta Agent). Agentes vinculados a Manter não recebem perguntas dinâmicas.

Avaliação é *