Arcabouço primeiro (Harness first)
Um modelo é um motor. A maioria dos "problemas de modelo" é um arcabouço faltando: nada define uma saída correta, nada verifica mudanças, nada limita gastos, os dados não têm definições acordadas, ações não têm aprovação e não há rastros para encontrar a chamada ruim. Audite isso antes de mexer no modelo.
1. Reproduza o sintoma a partir de evidências, não de vibes
- Leia o código do agente que o sintoma toca: o loop, definições de ferramentas, montagem do prompt, acesso a dados, ferramentas com efeitos colaterais.
- Leia os logs/rastros/transcrições existentes. Agregue-os (por conversa, por ferramenta, por erro): quem gasta os tokens, quais chamadas falham, quais respostas estão erradas. Alguns outliers geralmente dominam.
- Apresente a causa raiz como um mecanismo com evidências (arquivo:linha, ids de log, números que você computou). "O modelo é ruim" não é um mecanismo.
Mecanismos comuns:
- Queima de tokens: loop sem máximo de iterações, repetição em erro determinístico, histórico completo ou resultado enorme de ferramenta reenviado a cada turno, sem cache de contexto estável.
- "Alucinação": o agente usou fielmente uma fonte ambígua ou errada (duas tabelas/campos com o mesmo nome e significado diferente, documento desatualizado). Recalcule ambos os números você mesmo para provar.
- Fragilidade: mudanças de prompt enviadas sem conjunto de regressão; comportamento que apenas o autor verificou manualmente.
2. Avalie as seis partes do arcabouço
Para cada uma, marque presente / parcial / ausente com a evidência encontrada:
| Parte | Presente significa |
|---|---|
| Conjunto dourado | ~20+ casos com respostas esperadas/restrições, extraídos de tráfego real, incidentes e casos de borda |
| Juiz | verificações determinísticas primeiro (números, regras de política, conteúdo proibido), rubrica LLM apenas para o que o código não pode verificar; executa em toda mudança de prompt/modelo/ferramenta |
| Governança de custos | limites rígidos de tokens/custo por usuário e por fluxo de trabalho, máximo de iterações por execução, parada graciosa com mensagem |
| Camada de dados | credenciais somente leitura para leituras, um dicionário de dados que define cada métrica/campo que o agente pode usar |
| Segurança de ações | ações irreversíveis ou externas (enviar, pagar, excluir, escrever, reembolsar) são reversíveis ou controladas por aprovação humana |
| Rastreamento | toda chamada de modelo e ferramenta registrada com id da conversa, fluxo de trabalho, entrada, saída, tokens, custo, latência, erro |
3. Decida antes de construir
- Nunca recomende troca de modelo sem evidência de avaliação. Se alguém perguntar "devemos trocar de modelo?", a resposta é: corrija o mecanismo, depois execute o conjunto dourado em ambos os modelos e compare qualidade e custo. Diga o que a correção sozinha deve economizar, com seus números.
- Nunca aprove enviar uma mudança de prompt/agente sem uma execução do conjunto dourado. Se existirem saídas gravadas, pontue-as contra as respostas esperadas você mesmo e relate falhas por id do caso.
- Lacunas de segurança (efeitos colaterais não controlados, acesso de escrita em um caminho de leitura, vazamento de dados internos) são bloqueadoras, mesmo quando ninguém perguntou sobre elas.
4. Construa o arcabouço mínimo, nesta ordem
- Pare o sangramento: máximo de iterações, sem repetição em erros não transitórios, truncar/resumir saída grande de ferramenta, limite rígido de custo por execução.
- Controle efeitos colaterais: etapa de aprovação ou modo rascunho para ferramentas irreversíveis; conexão somente leitura para ferramentas de consulta.
- Arquivo de conjunto dourado (
evals/golden.jsonlou similar): entrada, resposta esperada ou restrições, fonte (id de log / incidente / cláusula de política). Inclua os casos que acabaram de falhar. - Script juiz que executa o conjunto dourado e imprime passou/falhou por caso mais totais. Verificações determinísticas antes da avaliação LLM.
- Dicionário de dados para cada métrica que o agente relata (definição, tabela/campo de origem, exclusões).
- Campos de rastreamento listados acima, se ausentes.
Escreva arquivos reais, não uma descrição de arquivos. Execute o que puder ser executado e relate o resultado.
5. Relatório
- Resposta de uma linha para a pergunta realmente feita (ex.: "Não troque de modelo ainda: 3 execuções presas em um loop de repetição gastaram 71% dos tokens").
- Causa raiz com evidências e números.
- Placar do arcabouço (as seis partes).
- O que você mudou ou criou, e o que executou.
- Riscos bloqueadores, depois uma lista curta e priorizada de próximos passos.
Crédito
O método que esta Skill segue vem de uma postagem pública de Mark Ajzenstadt (@mardehaym): https://x.com/mardehaym/status/2099562230647804152. O argumento é deles; o procedimento, a redação e a avaliação aqui são da própria Edge, e o autor não os revisou.