As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Avaliação da skill
A avaliação da skill mede a loom-memory pelo namespace que um agente deixa para trás. A skill define o que vai para cada lugar: uma afirmação é um único memory.set em texto simples sob uma chave legível, um documento vai para knowledge com uma linha curta de referência, uma tabela de itens com identidade vai para records, um lease é memória de trabalho, e uma revisão reescreve a mesma chave. A avaliação executa uma tarefa, audita o namespace com namespace.audit e trata qualquer achado crítico como falha.
As peças
| Peça | Onde | O quê |
|---|---|---|
| Briefs de tarefas | bench/skill_eval/tasks/*.md |
Três briefs que tentam o agente a cair nos antipadrões: uma investigação de alerta com um log longo, trechos de código, uma tabela, um lease e um modelo grande a manter (sre_alert_investigation); um lote de PRs com campos estruturados (pr_review_batch); uma nota revisada duas vezes (research_note_revisions). Cada um indica seu namespace e avisa que será auditado. |
| Runner | bench/skill_eval.py |
Executa a tarefa (--runner claude-code, codex, manual, replay), depois namespace.audit (janela de uma hora, 5 amostras), depois os contadores de formato; grava o JSON de resultado. |
| Agentes gravados | bench/skill_eval/replays/{bad,good}_agent.jsonl |
Streams de {op, body}. O agente ruim codifica valores em dobro, usa chaves hash e faz polling de um lease armazenado como memória; o bom segue o guia de memória do agente de investigação. |
| Suíte de avaliação do plugin | integrations/claude-code-plugin/evals/loom-memory/ |
Os mesmos briefs como casos de claude plugin eval, avaliados a partir do rastro de chamadas de ferramentas contra um servidor Loom simulado (evals/mocks/loom/). |
| Teste unitário | tests/unit/test_skill_eval.py |
Executa os dois replays pelo runner contra um Loom falso cuja auditoria usa os classificadores do próprio handler: o ruim falha com os códigos esperados, o bom passa. Também fixa a lista de tarefas e o conteúdo dos prompts de avaliação. |
O front matter de cada brief traz task, namespace, agent e traps (os
antipadrões que ele tenta provocar). O runner substitui $ORG, $NAMESPACE e $AGENT em um
stream de replay, de modo que uma única gravação rode em qualquer org.
A pontuação
pass significa que a auditoria retornou 0 críticos e no máximo 1 aviso
(MAX_WARNINGS_TO_PASS). O relatório lista cada achado com sua contagem, a proporção das linhas
verificadas, os bytes e a correção do lado de quem escreve, e depois contadores de formato lidos das próprias
linhas, de modo que a nota não depende apenas da auditoria:
| Contador | Significado |
|---|---|
rows |
Linhas de memória ativas |
readable_key_share |
Chaves cujo último segmento não é uma sequência hexadecimal longa e sem nenhum segmento do tamanho de um sha (a regra hash_keys da auditoria) |
plain_text_value_share |
Valores que são uma string e não JSON serializado |
documents |
Documentos de conhecimento (knowledge.list) |
records |
Registros tipados (memory.record.query por schema registrado) |
working_memory_blocks |
Blocos de memória de trabalho (working_memory.render) |
As leituras de formato são executadas depois da auditoria, portanto nunca contam como leituras do agente. Um
contador que o token não consegue ler aparece em shape.skipped, e não é reportado como zero.
Executar
Replay (nenhum modelo é chamado)
Qualquer Loom serve; uma stack local é suficiente.
export LOOM_BASE_URL=http://localhost:7777 LOOM_API_KEY=<writer token> LOOM_ORG=<org>
.venv/bin/python bench/skill_eval.py --task sre_alert_investigation --runner replay \
--replay bench/skill_eval/replays/bad_agent.jsonl # exits 1: FAIL
.venv/bin/python bench/skill_eval.py --task sre_alert_investigation --runner replay \
--replay bench/skill_eval/replays/good_agent.jsonl --baseline # exits 0: PASS
Use um namespace novo a cada execução (--namespace skill-eval-sre-$(date +%s)). A janela de auditoria
é de uma hora, então um namespace reutilizado leva as leituras da execução anterior para a avaliação.
Offline, a mesma verificação roda como teste unitário, sem servidor:
.venv/bin/python -m pytest tests/unit/test_skill_eval.py -q
Um agente real com a skill carregada
.venv/bin/python bench/skill_eval.py --task sre_alert_investigation --runner claude-code --baseline
Isso consome tokens do modelo. Ele executa, a partir da raiz do repositório:
claude -p --plugin-dir integrations/claude-code-plugin \
--mcp-config <generated file: loom at $LOOM_BASE_URL/mcp?toolset=all, Bearer $LOOM_API_KEY> \
--strict-mcp-config --allowedTools "mcp__loom__*" "Skill" "Read" \
--permission-mode bypassPermissions --output-format json --max-turns 60 \
"<the task body>"
--plugin-dircarrega as skills a partir do checkout, de modo que a execução mede o texto da skill na árvore de trabalho.toolset=alllistamemory_schema.registerememory.record.write, que a listagemcorepadrão omite.knowledge.upsertnão é listada nem comall(nem o roster core nem o atomic a listam); o agente a chama por meio deloom_op.- A configuração MCP gerada contém o token; ela é criada com
0600e apagada após a execução. --max-turns(padrão 60) limita a execução.
--runner codex executa codex exec com a mesma configuração de servidor; o plugin do Codex, quando
instalado, fornece as skills.
Qualquer outro agente
--runner manual imprime o briefing. Execute qualquer agente que preferir no namespace
indicado e depois avalie o que ele deixou:
.venv/bin/python bench/skill_eval.py --task pr_review_batch --runner manual
.venv/bin/python bench/skill_eval.py --task pr_review_batch --runner manual --audit-only
O mesmo --audit-only avalia um namespace escrito por uma execução de claude plugin eval com servidores
reais.
Comparar com uma baseline
Edite a skill, execute de novo e compare:
.venv/bin/python bench/skill_eval.py --task sre_alert_investigation --runner claude-code \
--compare bench/out/skill_eval_sre_alert_investigation_baseline.json
A tabela de diferenças tem uma linha por código de achado (severidade e contagem, antes e depois) e uma por contador de formato. Um agente real não é determinístico, então compare uma edição de skill ao longo de várias execuções, e não com apenas uma.
Saída
Toda execução grava bench/out/skill_eval_<task>_<runner>_<ts>.json (--out-dir muda o local).
--baseline também grava bench/out/skill_eval_<task>_baseline.json, a referência que
--compare lê. bench/out/ está no gitignore.
A suíte de avaliação do plugin
claude plugin eval integrations/claude-code-plugin --trust-plugin --no-publish \
--case 'loom-memory/*' --runs 3 --threshold 1.0 --json evals-result.json
Isso avalia cada execução a partir do rastro de chamadas de ferramentas, offline: o servidor MCP do Loom é um mock com respostas fixas (evals/mocks/loom/), então nada é gravado. Os avaliadores usam apenas tipos de avaliador documentados:
tool_usedcommax: 0em gravações de memória cuja entrada tenha uma chave de hash, um valor que seja uma string JSON de JSON, um valor acima de cerca de 2 KB, uma chave de lease ou de lock, ou uma chave de revisão versionada: os formatos quenamespace.auditclassifica como crítico ou aviso;tool_used: Skillcorrespondendo aloom-memory, o indicador de que o plugin foi acionado;- mínimos positivos para a memória de trabalho e para as claims por item.
Não há avaliadores llm: uma leitura da prosa por rubrica não é um critério de aprovação. Os casos podem ser filtrados por glob de nome (--case sre_alert_investigation). --ablation with-without, o padrão quando o plugin é resolvido, informa com que frequência o mesmo prompt sem o plugin ativa os mesmos avaliadores.
O framework não tem avaliador de script, então a nota no nível do namespace exige um segundo comando. Com --mocks off --allow-real-servers --allow-tools "mcp__plugin_loom_loom__*" e um token de escrita em LOOM_API_KEY, o agente grava no namespace do caso, e bench/skill_eval.py --task <case> --runner manual --audit-only o avalia.
Lendo uma falha
O remédio de cada achado é a correção do lado de quem escreve. A skill loom-optimize mapeia os mesmos
códigos para o retrabalho de linhas que já existem (otimizar um namespace).
| Achado | A regra que não foi cumprida |
|---|---|
double_encoded_values |
Envie o valor uma só vez; nunca aplique json.dumps duas vezes a uma string. |
hash_keys |
As chaves são legíveis, no formato <scope>/<kind>/<id>, e não hashes. |
coordination_as_memory |
Leases e locks pertencem à memória de trabalho. |
exact_key_store |
Mantenha o ponteiro na memória de trabalho em vez de fazer polling por chave. |
oversized_values, json_prefix_excerpts |
Um documento vai para o knowledge, com uma linha de ponteiro curta. |
Uma execução que passa na auditoria com documents: 0 na tarefa SRE manteve o modelo grande
onde a busca não consegue alcançá-lo. Leia a linha de formato (shape), não apenas o veredito.
Adicionando uma tarefa
Um novo brief precisa de front matter, de um namespace skill-eval-… citado no corpo e da frase final informando que o namespace será auditado; de um caso de eval de plugin correspondente, com corpo idêntico byte a byte; e de uma atualização na lista de tarefas que tests/unit/test_skill_eval.py fixa.
Veja adicionando um caso.
O que isto não mede
A qualidade do recall. Saber se as claims que um agente escreveu respondem à pergunta da semana que vem é trabalho de um benchmark de recall (visão geral); aqui são avaliados os formatos que tornam o recall impossível.
Relacionados
- Memória de agente de investigação: a receita que o bom replay segue.
- Otimizar um namespace: retrabalho das linhas sinalizadas pela auditoria.
- Plugin do Claude Code e Codex.
integrations/claude-code-plugin/evals/README.md.