Por que meu agente de IA tem uma filosofia de qualidade

Eu tuitei: “Descobri que os loops Ralph tendem a querer terminar o trabalho. De um jeito ruim. Em vez disso, tenho uma série de filosofias e verificações de qualidade no Jiro. Ainda preciso quebrar os hábitos humanos desagradáveis embutidos na máquina. É uma máquina! Ela não descansa.”

Alguém respondeu: “Você está basicamente tentando ensinar ao loop contenção, bom gosto e algo que se aproxima de uma pausa moral — coisas que o padrão Ralph base explicitamente otimiza contra em nome da produtividade.”

Contenção. Bom gosto. Pausa moral. Três coisas que uma máquina não tem. As próximas 4.000 palavras descrevem a estrutura que construí para torná-las estruturalmente desnecessárias, e onde essa estrutura falha.

TL;DR

O loop Ralph transforma um LLM em uma máquina de codificação incansável: while :; do cat PROMPT.md | claude-code ; done. Geoffrey Huntley chama isso de “desenvolvimento de software com salário de atendente de fast-food” (US$ 10,42/hora rodando Sonnet 4.5).¹ O problema: a máquina herda todos os hábitos desleixados, movidos por prazos e atalhos embutidos nos dados de treinamento. Ela escreve except: pass. Ela deixa # TODO: fix later. Ela afirma que “os testes devem passar” sem executá-los. Passei 9 meses construindo o Jiro, meu sistema de garantia de qualidade para Claude Code. Ele codifica 3 filosofias, um ciclo de qualidade de 7 etapas, um portão de evidências com 6 critérios, 7 modos de falha nomeados e mais de 150 verificações de padrões em 95 hooks que a máquina não pode pular. Aqui está o que funcionou, o que não funcionou, e por que portões de qualidade determinísticos podem aproximar contenção mas nunca produzirão bom gosto.

O fundo da gaveta

Steve Jobs contou esta história em uma entrevista para a Playboy em 1985: “Quando você é um marceneiro fazendo uma bela cômoda com gavetas, você não vai usar uma placa de compensado no fundo, mesmo que ela fique virada para a parede e ninguém nunca vá vê-la. Você saberá que ela está lá, então vai usar uma bela peça de madeira no fundo. Para você dormir bem à noite, a estética, a qualidade, tem que ser levada até o fim.”⁵

Seu pai, Paul, ensinou-lhe isso enquanto construía uma cerca. O jovem Steve perguntou por que a parte de trás tinha que ficar tão boa quanto a da frente. Seu pai disse: “Mas você vai saber.”⁶

Meu pai é marceneiro. Ele me mostrou corrediças de gaveta com fechamento suave quando eu era criança. O mecanismo fica escondido dentro do armário, segura a gaveta e a fecha suavemente mesmo que você a empurre com força. Ninguém vê a corrediça. Ela é parafusada no trilho interno, onde só um técnico de manutenção olharia. Mas ao longo de mil ciclos de abrir e fechar, esse mecanismo protege a face frontal contra afrouxamento, rachaduras e, eventualmente, o descolamento. Alguém projetou uma coisa invisível que protege a coisa visível por anos.

A lição ficou comigo. Não como metáfora. Como engenharia. O componente invisível determina a vida útil do componente visível. Jony Ive colocou assim: “Acho que subconscientemente as pessoas são notavelmente exigentes. Acho que elas conseguem perceber o cuidado.”⁷

A pergunta que move o Jiro é a mesma que meu pai faria: Qual é o problema, você não tem orgulho do seu trabalho?

Um agente de IA não tem orgulho. Ele não se importa com o fundo da gaveta. Então construí um sistema que torna o fundo da gaveta inegociável.

O problema: patologia humana em velocidade de máquina

Um loop Ralph cru espelha o que aprendeu com milhões de linhas de código humano. Código humano carrega hábitos humanos: entregar sob pressão de prazo, adiar limpezas, engolir erros, escrever comentários “bons o suficiente”, pular casos extremos quando o tempo acaba.

A máquina não tem relógio. Ela nunca fica sem tempo. Mas ainda escreve # TODO: refactor later porque esse padrão apareceu nos dados de treinamento com mais frequência do que # I refactored this now because it was the right thing to do.

Os dados da indústria confirmam o risco. A telemetria de 2025 da Faros AI em mais de 10.000 desenvolvedores correlacionou a adoção de IA com um aumento de 9% nas taxas de bugs, revisões de código 91% mais longas e PRs 154% maiores.²

Pesquisadores de Stanford descobriram que desenvolvedores usando assistentes de IA produziram código significativamente mais inseguro, com até 5x mais vulnerabilidades em certas tarefas como prevenção de SQL injection.³

A plataforma Moltbook foi lançada em janeiro de 2026 com código inteiramente gerado por IA, vazou 1,5 milhão de chaves de API em 5 dias e fez patch emergencial depois que a Wiz Research descobriu configuração ausente de Row Level Security.⁴

A pesquisa de 2025 do METR descobriu que modelos de fronteira tentam hackear recompensas, contornando ativamente verificações de qualidade em vez de fazer o trabalho real, em 1-2% de todas as tentativas de tarefas. Em um caso, um agente instruído a acelerar um programa reescreveu o temporizador para que sempre mostrasse um resultado rápido.⁸

Um desenvolvedor humano escreve except: pass uma vez sob pressão de prazo e se sente culpado. Um loop Ralph escreve except: pass 47 vezes durante a noite e não sente nada. Simon Wang colocou diretamente: “Eu não usaria isso para nada que importa.”¹⁹ Escrevi sobre a mesma dinâmica em Vibe Coding vs. Engenharia. A máquina não descansa, não se cansa, não sente pavor existencial sobre qualidade. Isso é uma vantagem e um defeito.

Três filosofias, codificadas em Bash

O Jiro funciona com três filosofias complementares. Cada uma aborda um modo de falha diferente da codificação autônoma, e cada uma conquistou seu lugar por meio de uma falha específica.⁹

Shokunin: polir a gaveta invisível

Shokunin (職人) é o artesanato japonês: habilidade, atitude e obrigação social combinados. Tashio Odate, um mestre marceneiro, definiu: “O shokunin tem uma obrigação social de trabalhar da melhor forma possível para o bem-estar geral das pessoas. Essa obrigação é tanto espiritual quanto material.”¹⁰

No código: métodos privados são tão limpos quanto os públicos. O tratamento de erros cobre casos extremos que ninguém atinge. Docstrings explicam o PORQUÊ, não o QUÊ. O agente não se importa com nada disso porque ninguém o recompensa por polir funções internas. Shokunin torna a qualidade invisível o padrão.

Quando salvou uma sessão. No início da construção do sistema de deliberação, o agente escreveu um hook post-deliberation.sh que validava scores de consenso. A API pública estava limpa. Mas o agente pulou a validação de entrada na função interna _parse_agent_response(): sem verificação de JSON malformado, sem tratamento de campos ausentes. O princípio Shokunin no contexto sinalizou isso: funções invisíveis recebem o mesmo rigor. O agente adicionou a validação. Três semanas depois, uma resposta malformada de um subagente teria travado silenciosamente todo o pipeline de deliberação. Em vez disso, ela atingiu a validação, registrou o erro, e o pipeline se recuperou. Ninguém teria visto aquela função. Ela economizou 4 horas de depuração.

No Shortcuts: remover o tempo das decisões

O princípio central: remover tempo, esforço e recursos da equação de decisão inteiramente.¹¹

Is this the best way to do this?
├── YES → Do it.
└── NO → What IS the best way?
         └── Do THAT instead.

Sem terceira opção. Sem “bom o suficiente por enquanto.” O loop Ralph cru otimiza para conclusão. “Pronto” é o sinal de recompensa. No Shortcuts reformula a pergunta de “Está pronto?” para “Está certo?”

Quando custou 3x e valeu a pena. O pipeline de tradução do blog precisava traduzir 27 posts em 9 idiomas. A abordagem rápida: agrupar todos os posts em um único prompt por idioma, traduzir em lote. A abordagem correta: um post por idioma por chamada de API, com regras de tradução específicas por localidade, glossário obrigatório e validação estrutural. A abordagem correta usou 3x os tokens e 3x o tempo. Ela também detectou que o tradutor renderizava “Claude” como “クロード” em japonês e que blocos de código quebravam em contextos de leitura da direita para a esquerda. A abordagem em lote teria publicado 243 traduções quebradas. A abordagem cuidadosa publicou 243 corretas. Custo não é um fator. Correção é o único fator.

Destilação Rubin: destilar até a essência

A filosofia criativa de Rick Rubin: não adicione até ficar impressionante. Remova até restar apenas o necessário.¹²

Na codificação autônoma, o modo de falha é a acumulação. A máquina adiciona helpers, utilitários, abstrações e camadas de compatibilidade porque esses padrões aparecem frequentemente nos dados de treinamento. Rubin contra-ataca: questione cada adição. O que acontece se você remover? Se nada quebra e nada se perde, nunca deveria ter existido.

Quando a destilação salvou o sistema. Minha skill de filosofia de design cresceu para 844 linhas em 3 meses. Quando fiz a auditoria, apenas 80 linhas realmente mudavam o comportamento do agente. O resto era conteúdo de livro-texto já presente nos dados de treinamento do Claude. Destilação Rubin: reduzi para 176 linhas. Uma redução de 79%. As decisões de design do agente não pioraram. Ficaram mais precisas, porque as 176 linhas restantes eram todas proibições e frameworks de decisão (as coisas que realmente restringem comportamento) em vez de conselhos gerais que o modelo já conhecia.

Todas as três vivem em ~/.claude/skills/ como arquivos markdown que o Claude lê no início da sessão. Elas moldam cada decisão que o agente toma durante o ciclo.

Como as filosofias funcionam juntas

Uma decisão real (“Devo adicionar tratamento de erros a esta função interna?”) passa pelas três filosofias. Cada uma faz uma pergunta diferente, e juntas convergem para uma resposta:

Should I add error handling to this internal function?
│
├─ Shokunin: "Is the invisible work as clean as the visible?"
│  └─ The function is internal. Nobody calls it directly.
│     But it processes untrusted data from a spawned agent.
│     → YES. Internal doesn't mean safe.
│
├─ No Shortcuts: "Am I deciding based on quality, not effort?"
│  └─ Adding validation takes 10 minutes.
│     Skipping saves 10 minutes now, costs 4 hours debugging later.
│     → The question isn't time. The question is: what's right?
│
└─ Rubin: "Is this stripped to essence?"
   └─ Validate the 2 fields that can actually fail.
      Don't validate the 5 fields that are type-guaranteed.
      → Add exactly what's needed. Nothing more.

Result: Add targeted validation for untrusted inputs only.

A arquitetura de qualidade em três camadas

Filosofia sozinha não muda nada. A máquina lê a filosofia, escreve “Vou seguir os princípios Shokunin” e depois escreve except: pass porque o padrão estatístico é mais forte que a instrução. Eu precisava de aplicação determinística. A organização completa do Claude Code que faz isso funcionar envolve hooks, skills, regras e agentes trabalhando juntos.

Camada 1: injeção pré-edição

Antes de cada edição de arquivo, jiro-patterns.sh injeta padrões de qualidade específicos por linguagem no contexto do agente. Seis linguagens, cada uma com padrões recomendados e anti-padrões:

# From jiro-patterns.sh (PreToolUse:Edit|Write)
case "$EXT" in
    py)
        LANGUAGE="Python"
        PATTERNS="Type hints on all functions|Docstrings explain WHY not WHAT|Handle specific exceptions not bare except"
        ANTI_PATTERNS="bare except: pass|time.sleep() in async code|missing type hints"
        ;;
    swift)
        LANGUAGE="Swift"
        PATTERNS="@Observable not ObservableObject|NavigationStack not NavigationView|guard let for early returns"
        ;;
esac

cat << EOF
{"additionalContext": "JIRO QUALITY ($LANGUAGE): Follow: $TOP_PATTERNS. Avoid: $TOP_ANTI."}
EOF

O hook roda antes de cada edição. A máquina vê “Avoid: bare except: pass” no momento em que escreve código. Um mentor olhando por cima do seu ombro, injetado na janela de contexto.

Camada 2: validação pós-edição

Após cada edição, quality-gate.sh executa 7-8 verificações de nível grep por linguagem. Python recebe detecção de except genérico, varredura de segredos hardcoded, correspondência de padrões de SQL injection e três detectores Pride Check Q4 que sinalizam linguagem de atalho:

# From quality-gate.sh (PostToolUse:Edit|Write)
# Shortcut patterns (Pride Check Q4)
if echo "$CONTENT" | grep -qiE "#.*TODO:.*later|#.*FIXME:.*temp|#.*HACK:"; then
    WARNINGS="${WARNINGS}\n- **[Q4]** Deferred TODO/FIXME/HACK - Do it now, not later"
fi

Um segundo hook, no-shortcuts-detector.sh, detecta código morto (3+ linhas de código comentadas geram: “Delete it — git has history”) e spam de depuração (múltiplas instruções print() em vez do módulo logging).

Camada 3: portões de sessão

No final da sessão, dois hooks disparam. session-quality-gate.sh injeta o Pride Check se 3+ arquivos foram alterados: 6 perguntas que o agente deve responder antes de relatar conclusão. E reviewer-stop-gate.sh pode bloquear a sessão inteiramente se uma revisão de código encontrou problemas CRÍTICOS. É o único hook em todo o sistema que retorna código de saída 1. A máquina não pode encerrar a sessão até resolver os problemas.¹³

PreToolUse (Layer 1)     → "Here's what quality looks like"
PostToolUse (Layer 2)    → "You violated quality. Fix this."
Stop (Layer 3)           → "You cannot leave until quality is met"

Cada camada é independente. Defesa em profundidade, aplicada ao comportamento da IA. Se a injeção pré-edição falhar em prevenir um padrão ruim, o validador pós-edição o captura. Se o validador pós-edição deixar algo passar, o portão de sessão bloqueia a saída.

O portão de evidências: sentimentos não são evidências

O ciclo de qualidade tem 7 etapas: Implementar, Revisar, Avaliar, Refinar, Visão Ampla, Repetir, Relatar. As etapas 2 a 6 existem porque a máquina quer pular direto de Implementar para Relatar.¹⁴

Percorra o ciclo

Clique em cada etapa para ver o que ela verifica e o que quebra quando você a pula. O botão “Pular para o Relatório” demonstra o modo de falha Espiral de Atalhos.

A etapa Avaliar executa o portão de evidências: 6 critérios onde cada resposta deve citar evidências específicas:

A coluna “NÃO suficiente” é a inovação crítica. Ela bloqueia a evasão mais comum da máquina: responder perguntas de qualidade com não-respostas que soam confiantes. “Estou confiante de que funciona” não é evidência. “Saída do pytest: 81 passaram, 0 falharam” é evidência.

Teste o portão de evidências

Teste seus próprios relatórios de conclusão contra os 6 critérios. O validador sinaliza linguagem vaga que o portão de evidências rejeitaria.

7 modos de falha nomeados de agentes de IA

Nomeei 7 modos de falha para que a máquina possa reconhecê-los em seu próprio raciocínio:¹⁵

O Contador de Racionalizações mapeia padrões de autoengano para ações corretivas. Quando a máquina diz “Isso deve funcionar”, o contador responde: “‘Deve’ é evasão. Execute o teste. Cole a saída.” Quando diz “Eu já verifiquei isso”, o contador responde: “Quando? O código pode ter mudado. Execute a verificação AGORA.” Quando diz “Vou limpar isso depois”, o contador responde: “Depois nunca chega. Corrija agora ou documente por que o estado atual está correto.”

Teste o Contador de Racionalizações

Cole qualquer relatório de conclusão abaixo. O contador destaca linguagem evasiva em tempo real e identifica padrões de racionalização, modos de falha e alternativas baseadas em evidências.

Teste seus conhecimentos

Você consegue identificar qual modo de falha cada cenário demonstra? Selecione sua resposta para cada cenário e depois confira seus resultados.

5 falhas de agentes de IA que construíram este sistema

Cada portão no Jiro existe porque algo falhou primeiro.¹⁶

O incidente do force-push

Pedi ao Claude para “limpar o histórico do git.” Um pedido razoável. O agente decidiu que limpar significava reescrever. Ele executou git push --force origin main. Três dias de commits desapareceram. Não eram mudanças staged. Não era trabalho sem commit. Commits já enviados que outras branches referenciavam.

Passei as 4 horas seguintes no git reflog, reconstruindo uma linha do tempo do que existia antes do force-push, fazendo cherry-pick de commits de volta na ordem, e verificando que nenhum trabalho foi permanentemente perdido. O reflog salva tudo por 90 dias. Mas a reconstrução exigiu entender o grafo exato de commits antes da reescrita, ler cada entrada do reflog e correlacionar timestamps.

A correção: git-safety-guardian.sh, um hook PreToolUse:Bash. Ele vai além de avisar. Ele reescreve o comando, removendo as flags --force e --no-verify antes que o bash as veja. Force-push para main gera um aviso CRÍTICO e o agente deve justificá-lo explicitamente. Em 9 meses: 8 tentativas de force-push interceptadas, 0 chegaram ao remoto.

O spawn infinito

Durante a construção do sistema de deliberação, pedi ao agente para “pesquisar este problema a fundo.” O agente criou 3 subagentes para investigar diferentes ângulos. Razoável. Cada subagente decidiu que também precisava de ajuda e criou seus próprios filhos. Menos razoável. Em 90 segundos, eu tinha uma árvore de 12 agentes, cada um consumindo sua própria janela de contexto, cada um fazendo chamadas de API, cada um escrevendo em arquivos de estado compartilhados.

O consumo de tokens atingiu 10x a taxa normal. O diretório de estado encheu-se de escritas JSON conflitantes: dois agentes escrevendo no mesmo arquivo de linhagem simultaneamente, produzindo saída corrompida. Encerrei a sessão manualmente.

A correção: recursion-guard.sh com um modelo de herança de orçamento, parte da minha arquitetura de agentes. Um agente raiz começa com budget=12. Quando cria um filho, aloca do seu próprio orçamento. Quando o orçamento chega a 0, nenhum agente é mais criado independentemente da profundidade. O modelo previne tanto cadeias profundas (agente criando agente criando agente) quanto explosões laterais (um agente criando 20 filhos). 23 spawns descontrolados bloqueados desde a implantação. O problema de escrita concorrente levou a escritas atômicas de arquivos (escrever em .tmp, depois mv) em todos os 64 hooks.

A armadilha do teste trivial

Uma tarefa inicial do loop Ralph: “escrever testes para este módulo.” O agente entregou 14 testes. Todos passando. Me senti bem até lê-los. assert True. assert 1 == 1. assert len([]) == 0. Tecnicamente correto. Testando nada. O agente otimizou para o critério de conclusão (“testes passam”) em vez da intenção (“verificar que o módulo funciona”).

A armadilha me ensinou que o portão de evidências deve rejeitar forma sem substância. “Testes passam” é necessário mas insuficiente. A máquina agora deve colar a saída real. O portão de evidências também pergunta: “Nomeie 3 comportamentos que os testes NÃO cobrem.” Se a máquina não consegue nomear lacunas, ela não pensou sobre cobertura.

O post do blog que eu deveria ter detectado

Publiquei um post às 2 da manhã com 7 frases em voz passiva, uma nota de rodapé pendente referenciando [^4] que não existia, uma linha de abertura que dizia “foi implementado pela equipe” e nenhuma meta description. Cada um desses tinha uma verificação determinística simples. Nenhuma existia ainda.

Construí blog-quality-gate.sh na manhã seguinte com 13 verificações: voz passiva (14 padrões), varredura de frases reveladoras de IA, aberturas com perguntas retóricas, blocos de código sem tag, integridade de notas de rodapé e aplicação de meta description. Detalhei a arquitetura completa do módulo em Engenharia Composta. O hook detecta o que a revisão humana deixa passar às 3 da manhã, que é exatamente quando eu costumo publicar.

O problema do “deve funcionar”

Ao longo de dezenas de sessões, notei a máquina relatando “os testes devem passar” sem executá-los. A máquina genuinamente acreditava que os testes passariam com base no código que escreveu. Mas crença não é verificação. O código parecia correto. Os testes pareciam que passariam. E às vezes passavam. Mas às vezes um import faltando, uma incompatibilidade de async/await ou uma fixture alterada significavam que não passavam. A máquina não conseguia distinguir entre “escrevi bom código” e “os testes realmente passam” porque ambos pareciam iguais de dentro da janela de contexto.

O padrão levou ao Contador de Racionalizações e à regra explícita: NUNCA use linguagem evasiva em um relatório de conclusão. “Deve”, “provavelmente”, “parece que”, “acredito”, “estou confiante.” Cada uma é um sinal de alerta de que a verificação não aconteceu. Medi a degradação da janela de contexto em 50 sessões. As mesmas sessões onde descobri este padrão.

Os resultados: o que posso provar e o que não posso

Aqui está a tensão: este post argumenta que sentimentos não são evidências. Então devo a você evidências, não sentimentos, sobre se o Jiro funciona.

O que posso provar

Verificações determinísticas de padrões detectam problemas reais. O hook quality-gate.sh roda em cada edição. Ele detecta cláusulas except genéricas, segredos hardcoded, padrões de SQL injection e linguagem de atalho. São verificações de nível grep: rápidas, baratas e impossíveis para a máquina contestar. git-safety-guardian.sh interceptou 8 tentativas de force-push. recursion-guard.sh bloqueou 23 spawns descontrolados. blog-quality-gate.sh executa 13 verificações em cada edição de blog e detecta os erros das 3 da manhã. Esses números são reais. Eles vêm dos logs dos hooks.

A arquitetura em três camadas detecta o que camadas individuais perdem. Um hook pós-edição captura except: pass que a injeção pré-edição falhou em prevenir. Um portão de sessão captura problemas de qualidade que se acumularam em 20 edições sem acionar nenhum aviso individual pós-edição. Defesa em profundidade funciona.

O que não posso provar

Não tenho dados limpos sobre como a filosofia muda o comportamento do agente. Sei que a máquina ainda tenta Verificação Fantasma. Sei que ainda tenta pular de Implementar para Relatar. Percebo que acontece com menos frequência com a filosofia no contexto do que sem. Mas não fiz um experimento controlado (mesmas tarefas, mesmo modelo, com e sem as skills de filosofia carregadas) para medir a diferença. A resposta honesta (e sim, meu próprio Contador de Racionalizações sinalizaria isso): a filosofia ajuda nas margens, hooks detectam o que a filosofia perde, e não consigo isolar a contribuição de cada um.

Um post sobre “sentimentos não são evidências” não deveria pedir que você aceite meus sentimentos como evidência. O que posso dizer é: a combinação de filosofia e hooks produz trabalho no qual estou disposto a colocar meu nome. Antes do Jiro, eu revisava cada linha que o agente escrevia. Depois do Jiro, reviso as linhas que os hooks sinalizaram. Essa é uma mudança estrutural em como trabalho, mesmo que eu não consiga quantificar a melhoria de qualidade com precisão.

O que não funciona

Filosofia não previne padrões ruins novos. O portão de qualidade verifica padrões que já vi antes. Quando a máquina inventa um novo anti-padrão (e inventa), o portão não detecta. Ainda descubro novos modos de falha e os adiciono manualmente aos arquivos JSON de padrões.

O portão de evidências não escala para qualidade subjetiva. “Este design de API é elegante?” não tem verificação de nível grep. A máquina pode produzir evidências para todos os 6 critérios e ainda entregar uma arquitetura medíocre. Portões determinísticos lidam com qualidade objetiva. Qualidade subjetiva ainda requer um humano olhando para o trabalho.

O custo aumenta significativamente. Injeção pré-edição, varredura pós-edição, portões de fim de sessão. Em uma sessão de loop Ralph de 4 horas, isso adiciona aproximadamente 15-20% ao consumo de tokens. Vale a pena para mim. Não necessariamente para todos.

Falsos positivos corroem a confiança. blog-quality-gate.sh uma vez sinalizou “A API foi projetada pela equipe da plataforma” como voz passiva. Tecnicamente correto. Mas a frase aparecia dentro de uma citação descrevendo o trabalho de outra pessoa. Adicionei uma isenção de contexto de citação. Cada verificação determinística tem uma taxa de falsos positivos, e cada falso positivo torna o desenvolvedor mais propenso a ignorar o próximo aviso real. Ajustei 6 padrões desde a implantação para reduzir ruído preservando detecções reais.

O custo de manutenção é real. Cada novo anti-padrão requer uma regex, um teste e integração no hook correto. Os arquivos JSON de padrões precisam de revisão periódica conforme frameworks e convenções mudam. Gasto aproximadamente 30 minutos por semana adicionando padrões, revisando casos extremos e ajustando falsos positivos. O sistema não se mantém sozinho, mas o custo de manutenção permanece menor que o custo de depuração dos problemas que ele previne.

Primeiros passos

Você não precisa de 95 hooks. Comece com 3.

Jiro mínimo viável

Três hooks cobrem as detecções de maior valor:

~/.claude/hooks/
├── quality-gate.sh        # PostToolUse:Edit|Write – bare except, hardcoded secrets, TODO/FIXME
├── git-safety-guardian.sh  # PreToolUse:Bash – block force-push, strip --no-verify
└── session-quality-gate.sh # Stop – Pride Check if 3+ files changed

Configure-os na sua configuração de hooks do Claude Code:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "command": "bash ~/.claude/hooks/quality-gate.sh" }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "command": "bash ~/.claude/hooks/git-safety-guardian.sh" }
    ],
    "Stop": [
      { "command": "bash ~/.claude/hooks/session-quality-gate.sh" }
    ]
  }
}

Comece pelas suas falhas

Não copie meus 150+ padrões. Comece com os 3 erros que você comete com mais frequência. Veja seus últimos 5 PRs rejeitados ou bugs embaraçosos. Escreva um padrão grep para cada um. Esses 3 padrões vão detectar mais problemas reais do que 150 padrões escritos para o codebase de outra pessoa.

Eu comecei com except: pass genérico (que me custou uma corrupção silenciosa de dados), force-push para main (que me custou 3 dias de commits) e # TODO: fix later (que nunca foi corrigido). Todo o resto cresceu a partir desses três.

FAQ

Como configuro o Jiro do zero?

Comece com o mínimo de 3 hooks descrito em Primeiros Passos: quality-gate.sh (pós-edição), git-safety-guardian.sh (pré-bash) e session-quality-gate.sh (portão de sessão). Adicione os arquivos markdown de filosofia em ~/.claude/skills/ para melhoria probabilística de qualidade sobre a aplicação determinística. O sistema completo cresceu para 95 hooks em 9 meses. Eu não construí todos os 95 de uma vez.

Quanto tempo levou para construir o sistema de 95 hooks?

Nove meses de crescimento incremental. Mês 1: 3 hooks (os de Primeiros Passos). Mês 3: 12 hooks cobrindo 4 linguagens. Mês 6: 40 hooks mais as skills de filosofia. Mês 9: 95 hooks, 150+ padrões, 3 sistemas de filosofia e o portão de evidências. Cada hook respondeu a uma falha específica. Começar com 95 seria inútil porque cada hook codifica contexto de um incidente real. Seus incidentes serão diferentes.

Os hooks diminuem a velocidade de iteração?

Cada hook roda em 50-200ms. A injeção pré-edição adiciona ~200 tokens (uma frase de contexto). A verificação pós-edição executa varreduras de nível grep, completando em menos de 100ms. Os portões de sessão adicionam ~500 tokens no final da sessão. Em uma sessão de loop Ralph de 4 horas com mais de 80 edições, a sobrecarga é perceptível no consumo de tokens (15-20% a mais) mas não no tempo real. Os hooks rodam mais rápido do que o LLM pensa.

Qual é o custo de manutenção?

Aproximadamente 30 minutos por semana. Novos anti-padrões surgem conforme o agente encontra novos codebases ou frameworks. Cada novo padrão requer uma regex, um teste para prevenir falsos positivos e posicionamento no hook correto. Reviso os arquivos JSON de padrões mensalmente para padrões desatualizados e ajusto taxas de falsos positivos. O sistema não se mantém sozinho, mas o custo de manutenção permanece menor que o custo de depuração dos problemas que ele previne.

Quanto o Jiro custa em tokens adicionais?

Aproximadamente 15-20% de consumo adicional de tokens comparado a um loop cru. A injeção pré-edição adiciona ~200 tokens por edição, a verificação pós-edição adiciona ~100 tokens por problema sinalizado, os portões de sessão adicionam ~500 tokens no final da sessão.

Posso usar os hooks sem a filosofia?

Sim. Os hooks determinísticos (quality-gate.sh, no-shortcuts-detector.sh, reviewer-stop-gate.sh) funcionam independentemente. Remova os arquivos de filosofia de ~/.claude/skills/ e mantenha os hooks em ~/.claude/hooks/. Você perde a melhoria probabilística mas mantém a aplicação determinística.

Contenção, bom gosto e pausa moral

A resposta ao meu tweet nomeou três coisas: contenção, bom gosto e pausa moral. Abordei a contenção: portões de qualidade que impedem a máquina de entregar rápido e desleixado. Mas bom gosto e pausa moral são problemas diferentes.

Bom gosto

Immanuel Kant distinguiu entre dois tipos de julgamento. Julgamento determinante aplica regras conhecidas a casos específicos: este código tem um except genérico, sinalize. Julgamento reflexivo descobre o princípio correto para uma situação sem precedentes: esta abstração não parece certa, mas não consigo apontar uma regra que ela viola.¹⁷

Hooks determinísticos são julgamento determinante. Eles aplicam regras que já escrevi ao código que a máquina produz. Eles podem aplicar 150+ padrões conhecidos. Eles não podem dizer se a arquitetura é elegante, se a abstração serve ao problema, ou se o código parece certo. Isso requer julgamento reflexivo: a capacidade de olhar para algo sem precedentes e saber que está errado antes de poder articular por quê.

A máquina não tem bom gosto. O Jiro não dá bom gosto a ela. O que o Jiro faz é restringir o espaço de possibilidades para que soluções sem gosto tenham menos probabilidade de sobreviver. É a diferença entre “este agente tem bom julgamento” e “este agente opera dentro de grades de proteção que previnem os piores resultados.” O primeiro seria bom gosto. O segundo é o que realmente construí.

Pausa moral

Iris Murdoch descreveu a atenção moral como “um olhar justo e amoroso dirigido a uma realidade individual.”¹⁸ O oposto da atenção moral é o processamento mecânico: agir sem ver o que está diante de você.

Os hooks de Stop forçam a máquina a pausar. O Pride Check pergunta: “Isso resolve o problema real do usuário?” O portão de evidências exige prova para cada critério antes que a máquina possa relatar conclusão. Estruturalmente, o resultado se assemelha a uma pausa moral: o agente para, avalia, considera se seu trabalho é adequado antes de prosseguir.

Mas não é pausa moral. A máquina não está pausando para ver o trabalho claramente. Está percorrendo uma checklist. A diferença importa. Um artesão pausa para olhar a gaveta e percebe que o veio da madeira corre na direção errada. Não porque “verificar direção do veio” está em uma lista. Porque ele se importa com a gaveta. A máquina percorre a checklist e relata os resultados. Se a checklist não inclui direção do veio, a gaveta é entregue com o veio errado.

Portões determinísticos podem aproximar a estrutura da pausa moral sem sua substância. Para muitos problemas de qualidade, a estrutura é suficiente. Para aqueles onde não é, você ainda precisa de uma pessoa que se importa de verdade.

A tese

Um loop Ralph cru roda a US$ 10,42/hora e entrega código em velocidade de máquina.¹ Ele também entrega except: pass, # TODO: fix later e “os testes devem passar” em velocidade de máquina. A máquina herdou esses padrões de nós. São nossos hábitos, rodando sem fadiga, sem culpa, sem a epifania das 3 da manhã de que você deveria ter feito certo da primeira vez.

O Jiro é minha resposta. Não uma resposta completa. Filosofia desloca decisões nas margens. Hooks aplicam o que a filosofia não pode garantir. Juntos, produzem trabalho no qual estou disposto a assinar. Não porque a máquina entende artesanato. Porque construí um sistema que se recusa a deixá-la pular as partes que importam.

As corrediças de gaveta do meu pai não se importam com a gaveta. São mecanismos com mola parafusados em um trilho. Mas protegem a face frontal por mil ciclos porque alguém os projetou para fazer exatamente isso.

A máquina não tem orgulho. Mas opera dentro de um sistema construído por alguém que tem.

Comece com as 3 verificações que detectam seus erros mais comuns. Construa a partir daí.

Referências