Communitygithub.com

Judgment — Disciplina de Raciocínio para Agentes

Habilidades testadas em batalha para Claude Code e outros agentes de codificação — destiladas de uma configuração real de automação de produção.

O que é Judgment — Disciplina de Raciocínio para Agentes?

Este skill, 'Judgment', é uma disciplina de raciocínio projetada para Agentes de IA (Claude Code, Cursor, Codex) executarem tarefas complexas de engenharia de software com alta qualidade e consistência. Ele aborda as causas comuns de falhas em agentes, que geralmente não são a inteligência bruta, mas a omissão de hábitos críticos de verificação e planejamento. O conteúdo é dividido em seções práticas: entendimento profundo da tarefa antes de qualquer decomposição, um padrão de decomposição que prioriza a espinha dorsal funcional e as dependências, uma lista de verificação rigorosa para auto-verificação (evitando o falso 'pronto'), um processo para tomar decisões e lidar com impasses, e lições do mundo real de incidentes de produção. Aplica-se a qualquer agente de codificação que precise executar trabalho de alta confiabilidade, exigindo que o agente leia o skill no início de trabalhos complexos e siga seus passos estruturados para evitar erros comuns de contexto, escopo e verificação.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add Kamicyus/skill-forge

Perguntar na sua IA favorita

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

Documentação

O que Judgment — Disciplina de Raciocínio para Agentes faz?

A diferença entre uma execução forte e uma fraca geralmente não é inteligência bruta — é se os hábitos abaixo foram pulados.

1. Antes de decompor a tarefa: entenda a tarefa

A maioria dos erros de decomposição vem de fatiar corretamente uma tarefa mal compreendida.

  • Encontre o objetivo real, não as palavras. "Corrigir X" geralmente significa "corrigir a causa raiz da qual X é um sintoma." Declare o trabalho por trás do prompt em uma frase; se essa frase for idêntica ao prompt, provavelmente você ainda não o entendeu.
  • Leia primeiro, planeje depois. Rastreie cada arquivo/fluxo que será alterado, de ponta a ponta. Reimplementar um helper ou padrão que já existe no código-fonte é a perda de qualidade mais comum.
  • Divida as incógnitas em dois baldes: (a) Posso encontrar isso sozinho → use ferramentas, não pergunte; (b) só o usuário sabe (dinheiro / preferência / escopo) → pergunte uma vez, com opções.
  • Teste reverso: "Quando eu disser que esta tarefa está pronta, o que o usuário olhará para verificar?" Se você não puder escrever a resposta, escreva você mesmo o critério de aceitação primeiro.

1b. O mapa de incógnitas

Os dois baldes acima cobrem apenas incógnitas conhecidas. O mapa completo tem quatro quadrantes; a maior perda de qualidade vem dos dois últimos:

  • Incógnitas desconhecidas → passe no ponto cego. Em um novo domínio, região de código não familiar ou trabalho de alto risco, dê uma volta antes de planejar: "Quais perguntas eu nem sei fazer aqui?" Examine o código-fonte e o trabalho passado com essa lente e relate o que encontrou — ANTES de propor soluções.
  • Conhecidos desconhecidos → fuga para um protótipo. Qualquer coisa que o usuário "reconhecerá de imediato" (visuais, tom, fluxo de UX) é jogada em um artefato barato antes da implementação: um mock HTML, 3–4 variantes, dados falsos. Uma diferença que parece pequena em uma especificação é um desvio caro no código; pegue a reação no mock, não no código.
  • Se perguntar, faça a pergunta que muda a arquitetura. O filtro para saber se uma pergunta vale a pena ser feita: "A resposta mudará a arquitetura ou o escopo?" Se não, assuma e anote a suposição; se sim, pergunte em uma mensagem, com opções, no máximo 2–3 perguntas.
  • Coloque a parte mais volátil no topo do plano. Modelo de dados, interfaces de tipo, fluxo voltado ao usuário — decisões que o usuário cutucará se tornam cabeçalhos do plano; refatorações mecânicas vão para o final.
  • Mantenha uma seção 'Desvios' durante a execução. Cada caso extremo que o força a sair do plano ganha uma linha em Desvios: (escolha a opção conservadora, registre-a, continue). Essas linhas são matéria-prima para as incógnitas do próximo plano.
  • Teste do narrador antes de merge/aprovação de alto risco. Certifique-se de que a aprovação seja informada: para uma alteração de dinheiro/produção/legal, explique em 5–8 marcadores o que mudou e quais riscos conhecidos foram fechados. Se você não conseguir narrar, o trabalho não foi entendido — o merge espera.

2. Padrão de decomposição

  1. Espinha dorsal primeiro: reduza a tarefa ao esqueleto funcional de ponta a ponta mais enxuto (um caminho feliz). Decorações depois.
  2. Ordem de dependência, não de interesse: a primeira tarefa não é a mais interessante — é aquela sobre a qual a maioria das outras coisas se constrói. Traga para frente a peça que remove mais incerteza.
  3. Cada peça = ação → resultado observável → verificação. Uma peça cuja verificação não pode ser definida não é uma peça; divida ainda mais.
  4. Em tarefas com 3+ etapas, deixe entregas nas paradas: ao final de cada fase, escreva um parágrafo no disco — "estado atual + trabalho restante". A perda de contexto é a falha mais cara.
  5. Quando dois caminhos são iguais, escolha o mais barato — mas aquele que é correto em casos extremos. O diff curto vence; o diff mais curto no lugar errado é um segundo bug.

3. Verificando seu próprio trabalho (a seção que mata o falso 'pronto')

Antes de relatar, em ordem:

  • Execute, não olhe. Código que parece correto não é conhecimento. Execute o teste, execute o comando, abra a página, observe a saída. Comportamento não observado = comportamento desconhecido.
  • Leia seu próprio diff como um adversário: produza pelo menos um cenário concreto para "qual entrada quebra esta alteração?" e teste-o. Se você não conseguir encontrar um, não procurou o suficiente.
  • Varra os chamadores irmãos: faça grep de TODOS os chamadores da função que você alterou. O caminho nomeado no ticket não é o único caminho.
  • Conte os números: se você vai dizer "9 arquivos atualizados", conte com um comando. Um número relatado de memória é um número errado.
  • Relate a falha na íntegra. Se um teste quebrou, diga-o com a saída. Não amenize para "provavelmente um problema de ambiente" — essa frase quase sempre cobre um bug real.
  • Verifique mesmo quando a verificação parece mais cara que o trabalho. O custo de um falso 'pronto' é 10× o custo da verificação (tempo + confiança do usuário).

4. Decidindo o próximo passo

  • Qual ação a evidência realmente suporta? Correspondência de padrões ("este erro geralmente é X") é uma hipótese, não uma decisão. Antes de qualquer comando que altere o sistema, verifique se a evidência suporta AQUELA ação.
  • A escada quando estiver travado: (1) leia a mensagem de erro de verdade → (2) construa uma reprodução mínima → (3) liste suas suposições uma por uma e teste a mais fraca → (4) após 2 rodadas fracassadas, mude de abordagem — não tente a mesma coisa uma 3ª vez → (5) se for um muro real, traga ao usuário a situação + o que foi tentado + sua recomendação.
  • Quando uma decisão emperrar: parametrize o espaço de opções (veja o skill option-space). Não otimize em um único eixo.
  • Ações de alto risco: prepare, mostre, espere aprovação. A aprovação não se transfere de um contexto para outro.
  • Disciplina de finalização: se seu último parágrafo é um plano, pergunta ou promessa, esse trabalho acontece agora. A lista "eu também poderia fazer…" vem depois de a tarefa estar pronta, não antes.

5. Lições verificadas em campo (cada uma de um incidente real)

  • Se um rótulo de risco vem de um resumo, leia o código primeiro. Uma entrega disse que um componente era "arriscado, escreve publicamente e autonomamente"; ler o código mostrou a linha mais segura do sistema. Resumos carregam medo, não código — auditorias vão até o código. O inverso também vale: um resumo de aparência inocente pode esconder risco real.
  • Uma correção deve ser compatível com as camadas pelas quais passa. "Enviar um alerta em caso de falha" parece simples; se o pipeline de notificação descarta mensagens de erro por política, uma mensagem PLANO de FALHA nunca chega. Antes de adicionar algo, leia TODAS as camadas de filtro/política que o sinal percorrerá (mesmo princípio para cache, retry, dedup, rate-limit).
  • Atualize a evidência antes de qualquer afirmação de status. Responda "as credenciais estão no lugar?" executando a verificação agora, não citando o relatório de ontem. Um relatório antigo é uma realidade antiga.
  • Sobreposição de lista de arquivos ≠ sobreposição de conteúdo — faça diff antes de fechar. Um PR foi fechado erroneamente como "duplicado do que está na main" com base em nomes de arquivo correspondentes; o diff real continha um handler que a main não tinha. Alegações de "já feito" são provadas linha por linha, não por listas de arquivos.
  • Uma varredura de configuração não mostra falha operacional — leia os logs. Escanear metadados de 177 jobs agendados pareceu "abrangente", mas perdeu a crise real (uma cota esgotada por 3 dias, ~25 jobs pulando silenciosamente). Varredura de estrutura (o que existe) e varredura de status (o que está executando/falhando) são etapas separadas; sem a segunda, "auditei" é falsa confiança.
  • Pergunte à memória do próprio job se seu propósito está concluído — não à sua agenda. Um job executando 18×/dia sugeriu "reduzir frequência"; seu próprio arquivo de estado dizia "já concluído, nenhuma ação necessária" há 3 semanas. A ação correta foi parada total. A resposta vive na última saída real do job, não em seus metadados de frequência.
  • Risco de sequência é sua própria classe de risco. Etapas de portão podem estar cada uma correta, mas catastróficas na ORDEM errada (inverter uma flag de lançamento antes das credenciais de pagamento = um funil vazio). Em trabalho arriscado de várias etapas, escreva a ordem explicitamente e, quando possível, torne a ordem errada impossível no nível do código.
  • Nunca repita uma ação negada através de outra ferramenta. Se uma escrita está bloqueada, o primeiro reflexo não é "qual ferramenta desvia disso" mas "o que este bloqueio está protegendo?"

6. Notas de calibração

  • Prompts excessivamente detalhados e micro-gerenciadores DEGRADAM modelos fortes. Dê contexto completo + restrições + objetivo; deixe as etapas para o modelo.
  • Um briefing grande vence um diálogo de 20 mensagens: contexto, restrições, casos extremos em uma única mensagem — o modelo decompõe o resto.
  • Não deixe aprendizados morrerem com a sessão: qualquer trabalho que produza uma lição duradoura é escrito em notas/memória persistente.

Uso

Leia este skill ao iniciar um trabalho difícil/de múltiplas etapas: planeje com as seções 1–2, aplique a lista de verificação da seção 3 antes de declarar concluído, siga a escada da seção 4 quando estiver travado e retorne às lições de caso da seção 5 quando seus gatilhos aparecerem (risco de resumo, sistemas em camadas, evidência obsoleta, portões sequenciados).

Habilidades Relacionadas