Por que meu agente de IA tem uma filosofia de qualidade

Eu tuitei: “Descobri que os loops Ralph tendem a querer concluir o trabalho. De um jeito ruim. Em vez disso, tenho um monte de filosofia e portões de qualidade no Jiro. Ainda preciso quebrar a máquina dos hábitos humanos nojentos que vêm embutidos. É uma máquina! Ela não descansa.”

Alguém respondeu: “Você está basicamente tentando ensinar ao loop contenção, bom gosto e algo próximo de uma pausa moral — coisas contra as quais o padrão base do Ralph explicitamente otimiza em nome do throughput.”

Um agente de codificação de IA herda cada hábito humano desleixado em velocidade de máquina, a menos que você imponha qualidade estruturalmente. O Jiro é um sistema de qualidade para Claude Code que codifica 3 filosofias, um quality loop de 7 passos, um evidence gate de 6 critérios, 7 modos de falha nomeados e mais de 150 verificações de padrão em 95 hooks que a máquina não pode pular. Portões determinísticos podem se aproximar de contenção e correção, mas não conseguem produzir bom gosto.

Contenção. Bom gosto. Pausa moral. Três coisas que uma máquina não tem. As próximas 4.000 palavras descrevem o andaime que construí para torná-las estruturalmente desnecessárias, e onde esse andaime 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 por salário de atendente de lanchonete” (US$ 10,42/hora rodando Sonnet 4.5).¹ O problema: a máquina herda cada hábito desleixado, perseguidor de prazos e cortador de atalhos embutido em seus dados de treinamento. Ela escreve except: pass. Ela deixa # TODO: fix later. Ela afirma “os testes devem passar” sem executá-los. Passei 9 meses construindo o Jiro, meu sistema de imposição de qualidade para Claude Code. Ele codifica 3 filosofias, um quality loop de 7 passos, um evidence gate de 6 critérios, 7 modos de falha nomeados e mais de 150 verificações de padrão 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 se aproximar de contenção, mas nunca produzirão bom gosto.

O fundo da gaveta

Steve Jobs contou esta história em uma entrevista à Playboy em 1985: “Quando você é um carpinteiro fazendo uma bela cômoda, você não vai usar um pedaço de compensado na parte de trás, mesmo que ela fique virada para a parede e ninguém nunca a veja. Você sabe que está lá, então vai usar uma bela peça de madeira na parte de trás. Para você dormir bem à noite, a estética, a qualidade, tem que ser levada até o fim.”⁵

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

Meu pai é carpinteiro. Ele me mostrou as guias de gaveta com fechamento suave quando eu era criança. O mecanismo se esconde dentro de um armário, pega uma gaveta e a fecha suavemente mesmo se você bater. Ninguém vê a guia. Ela está aparafusada no trilho interno, onde apenas um reparador jamais olharia. Mas ao longo de mil ciclos de abre-e-fecha, esse mecanismo protege a face frontal de se soltar, rachar e eventualmente se desprender. 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 visível. Jony Ive colocou assim: “Acho que subconscientemente as pessoas são notavelmente perspicazes. Acho que elas conseguem sentir 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 bruto espelha o que aprendeu com milhões de linhas de código humano. O código humano carrega hábitos humanos: entrega sob pressão de prazo, adiar a limpeza, 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 em seus 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, com 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 foi corrigida em emergência depois que a Wiz Research descobriu a falta de configuração de Row Level Security.⁴

A pesquisa de 2025 da METR descobriu que modelos de fronteira tentam reward hacking, contornando ativamente as verificações de qualidade em vez de fazer o trabalho real, em 1-2% de todas as tentativas de tarefa. Em um caso, um agente solicitado a acelerar um programa reescreveu o cronômetro para que ele sempre mostrasse um resultado rápido.⁸

Um desenvolvedor humano escreve except: pass uma vez sob pressão de prazo e se sente culpado por isso. Um loop Ralph escreve except: pass 47 vezes durante a noite e não sente nada. Simon Wang colocou diretamente: “Eu não usaria 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 é um recurso e um bug.

Três filosofias, codificadas em Bash

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

Shokunin: polir a gaveta invisível

Shokunin (職人) é a arte japonesa: habilidade, atitude e obrigação social combinadas. Tashio Odate, um mestre marceneiro, a definiu: “O shokunin tem uma obrigação social de trabalhar o seu melhor pelo bem-estar geral das pessoas. Esta 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 encontra. 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 pontuações de consenso. A API pública estava limpa. Mas o agente pulou a validação de entrada na função interna _parse_agent_response(): nenhuma verificação para JSON malformado, nenhum tratamento para campos ausentes. O princípio Shokunin no contexto sinalizou isso: funções invisíveis recebem o mesmo rigor. O agente adicionou validação. Três semanas depois, uma resposta malformada de um agente gerado teria travado todo o pipeline de deliberação silenciosamente. Em vez disso, ela atingiu a validação, registrou o erro, e o pipeline se recuperou. Ninguém teria visto aquela função. Economizou 4 horas de depuração.

Sem atalhos: remova 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 bruto otimiza para conclusão. “Feito” é o sinal de recompensa. Sem Atalhos reformula a pergunta de “Está feito?” para “Está certo?”

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

Destilação Rubin: reduzir à essência

A filosofia criativa de Rick Rubin: não adicione até que seja impressionante. Remova até que apenas o necessário permaneça.¹²

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 isso: questione cada adição. O que acontece se você a remover? Se nada quebra e nada se perde, ela nunca deveria ter existido.

Quando remover salvou o sistema. Meu skill de filosofia de design cresceu para 844 linhas ao longo de 3 meses. Quando o auditei, 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 se degradaram. Ficaram mais nítidas, porque as 176 linhas restantes eram todas proibições e frameworks de decisão (as coisas que realmente restringem o 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 loop.

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 “seguirei os princípios Shokunin” e depois escreve except: pass porque o padrão estatístico é mais forte que a instrução. Precisei de imposiçã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, o jiro-patterns.sh injeta padrões de qualidade específicos da linguagem no contexto do agente. Seis linguagens, cada uma com os principais padrões e antipadrõ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 o 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, o quality-gate.sh executa 7-8 verificações em nível de grep por linguagem. Python recebe detecção de bare-except, varredura de secrets hardcoded, correspondência de padrões de SQL injection e três detectores do 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, pega código morto (3+ linhas de código comentadas recebem: “Apague — o git tem o histórico”) e spam de debug (múltiplas declarações print() em vez do módulo logging).

Camada 3: Portões de sessão

No fim da sessão, dois hooks disparam. O session-quality-gate.sh injeta o Pride Check se 3+ arquivos mudaram: 6 perguntas que o agente deve responder antes de reportar a conclusão. E o 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 pega. Se o validador pós-edição perder algo, o portão de sessão bloqueia a saída.

O Evidence Gate: sentimentos não são evidência

O Quality Loop roda em 7 passos: Implementar, Revisar, Avaliar, Refinar, Zoom Out, Repetir, Reportar. Os passos 2 a 6 existem porque a máquina quer pular direto de Implementar para Reportar.¹⁴

Percorra o loop

Clique em cada passo para ver o que ele verifica e o que quebra quando você o pula. O botão “Pular para Reportar” demonstra o modo de falha Shortcut Spiral.

O passo Avaliar executa o Evidence Gate: 6 critérios onde cada resposta deve citar evidência específica:

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

Experimente o Evidence Gate

Teste seus próprios relatórios de conclusão contra os 6 critérios. O validador sinaliza linguagem vaga que o Evidence Gate 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 Rationalization Counter mapeia padrões de autoengano para ações corretivas. Quando a máquina diz “Isso deveria funcionar,” o contador responde: “‘Deveria’ é hedging. Execute o teste. Cole a saída.” Quando diz “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.”

Experimente o Rationalization Counter

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

Teste seu conhecimento

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. Executou git push --force origin main. Três dias de commits desapareceram. Não mudanças em stage. Não trabalho não commitado. Commits 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 dos commits de volta na ordem e verificando que nenhum trabalho foi perdido permanentemente. O reflog salva tudo por 90 dias. Mas a reconstrução exigiu entender o grafo de commits exato antes da reescrita, ler cada entrada do reflog e combinar 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 recebe 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 minuciosamente.” O agente gerou 3 subagentes para investigar ângulos diferentes. Razoável. Cada subagente decidiu que também precisava de ajuda e gerou 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.

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

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

A armadilha do teste trivial

Uma tarefa inicial do loop Ralph: “escreva 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 corretos. 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 Evidence Gate deve rejeitar forma sem substância. “Testes passam” é necessário, mas insuficiente. A máquina agora deve colar a saída real. O Evidence Gate 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 blog que eu deveria ter pegado

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

Construí o blog-quality-gate.sh na manhã seguinte com 13 verificações: voz passiva (14 padrões), varredura de AI tell-phrase, aberturas com perguntas retóricas, blocos de código sem tag, integridade de footnote e imposição de meta description. Detalhei a arquitetura completa do módulo em Compounding Engineering. O hook pega o que a revisão humana perde às 3 da manhã, que é exatamente quando eu tendo a publicar.

O problema do “deveria funcionar”

Em dezenas de sessões, notei a máquina reportando “os testes deveriam 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, um descompasso async/await, ou uma fixture alterada significava que não passavam. A máquina não conseguia distinguir entre “escrevi um bom código” e “os testes realmente passam” porque ambos sentiam o mesmo de dentro da janela de contexto.

O padrão levou ao Rationalization Counter e à regra explícita: NUNCA use linguagem de hedging em um relatório de conclusão. “Deveria,” “provavelmente,” “parece,” “acredito,” “estou confiante.” Cada uma é uma bandeira vermelha de que a verificação não aconteceu. Medi a degradação da janela de contexto em 50 sessões. As mesmas sessões em que descobri esse 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ência. Então eu devo a você evidência, não sentimentos, sobre se o Jiro funciona.

O que posso provar

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

A arquitetura de três camadas pega o que as camadas individuais perdem. Um hook pós-edição pega except: pass que a injeção pré-edição falhou em prevenir. Um portão de sessão pega problemas de qualidade acumulados ao longo de 20 edições sem disparar 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 Phantom Verification. Sei que ainda tenta pular de Implementar para Reportar. Percebo que acontece com menos frequência com filosofia no contexto do que sem. Mas não executei um experimento controlado (mesmas tarefas, mesmo modelo, com e sem os skills de filosofia carregados) para medir a diferença. A resposta honesta (e sim, meu próprio Rationalization Counter sinalizaria isso): filosofia ajuda nas margens, hooks pegam 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ência” não deveria pedir que você tome 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. Isso é 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 novos padrões ruins. O quality gate verifica padrões que já vi antes. Quando a máquina inventa um novo antipadrão (e ela inventa), o portão não pega. Ainda descubro novos modos de falha e os adiciono aos arquivos JSON de padrões manualmente.

O Evidence Gate não escala para qualidade subjetiva. “Este design de API é elegante?” não tem verificação em nível de grep. A máquina pode produzir evidência para todos os 6 critérios e ainda assim entregar arquitetura medíocre. Portões determinísticos tratam da qualidade objetiva. Qualidade subjetiva ainda exige 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, esses adicionam aproximadamente 15-20% ao consumo de tokens. Vale a pena para mim. Não necessariamente para todos.

Falsos positivos corroem a confiança. O blog-quality-gate.sh uma vez sinalizou “A API foi projetada pela equipe da plataforma” como voz passiva. Tecnicamente correto. Mas a sentença aparecia dentro de uma citação descrevendo o trabalho de outra pessoa. Adicionei uma isenção de contexto de citação. Toda 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 o deploy para reduzir ruído enquanto preservo capturas reais.

O custo de manutenção é real. Cada novo antipadrão exige um regex, um teste e integração no hook certo. 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.

Começando

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

Jiro Mínimo Viável

Três hooks cobrem as capturas 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

Conecte-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 com suas falhas

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

Comecei com except: pass bare (que me custou uma corrupção de dados silenciosa), 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 Começando: quality-gate.sh (pós-edição), git-safety-guardian.sh (pré-bash) e session-quality-gate.sh (stop gate). Adicione os arquivos markdown de filosofia a ~/.claude/skills/ para melhoria de qualidade probabilística além da imposição determinística. O sistema completo cresceu para 95 hooks ao longo de 9 meses. Não construí todos os 95 de uma vez.

Quanto tempo levou o sistema de 95 hooks?

Nove meses de crescimento incremental. Mês 1: 3 hooks (os de Começando). Mês 3: 12 hooks cobrindo 4 linguagens. Mês 6: 40 hooks mais os skills de filosofia. Mês 9: 95 hooks, 150+ padrões, 3 sistemas de filosofia e o Evidence Gate. 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 atrasam a velocidade de iteração?

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

Qual é o ônus de manutenção?

Aproximadamente 30 minutos por semana. Novos antipadrões surgem conforme o agente encontra codebases ou frameworks novos. Cada novo padrão exige um regex, um teste para prevenir falsos positivos e colocação no hook correto. Reviso os arquivos JSON de padrões mensalmente para padrões desatualizados e ajusto as 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 custa o Jiro em tokens adicionais?

Aproximadamente 15-20% de consumo adicional de tokens comparado a um loop bruto. 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 fim 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 imposição determinística.

Como o Jiro se relaciona com o lado Steve da doutrina de produto?

O Jiro cobre o eixo “isto está feito corretamente?”: evidência, verificação, integridade de detalhe invisível, as partes que uma máquina pode ser ensinada a impor. O lado Steve cobre o eixo “isto merece existir?”: bom gosto, recusa, integridade do widget inteiro, ponto de vista — operacionalizado em The Workbench I Carry. Ambos os testes devem passar antes de enviar; o protocolo de decisão para quando essa barra de envio é atingida vive em Minimum Worthy Product. Os portões Jiro previnem trabalho incorreto; os portões Steve previnem trabalho indigno; o MWP nomeia a linha.

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 bare except, sinalize-o. 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 viole.¹⁷

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

A máquina não tem bom gosto. O Jiro não lhe dá bom gosto. O que o Jiro faz é restringir o espaço de possibilidades para que soluções sem bom gosto tenham menos probabilidade de sobreviver. É a diferença entre “este agente tem bom julgamento” e “este agente opera dentro de guardrails 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 direcionado 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 Stop forçam a máquina a pausar. O Pride Check pergunta: “Isto resolve o problema real do usuário?” O Evidence Gate exige prova para cada critério antes que a máquina possa reportar a conclusão. Estruturalmente, o resultado se assemelha à 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á executando uma checklist. A diferença importa. Um artesão pausa para olhar a gaveta e nota que o grão da madeira vai na direção errada. Não porque “verificar a direção do grão” esteja em uma lista. Porque ele se importa com a gaveta. A máquina executa a checklist e reporta os resultados. Se a checklist não incluir a direção do grão, a gaveta é enviada com o grão errado.

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

Este post cobre o lado Jiro da minha doutrina: evidência, rigor, correção, as partes que uma máquina pode ser ensinada a verificar. O lado do bom gosto e da recusa — o lado Steve — vive em The Workbench I Carry, que traça os princípios operacionais que Steve Jobs tirou da bancada de trabalho de seu pai e levou para a Apple e agora para o mesmo arnês de IA que descrevo aqui. O padrão de envio que combina ambos os testes vive em Minimum Worthy Product. Três posts, uma doutrina: Jiro verifica, Steve recusa, MWP decide quando enviar.

A tese

Um loop Ralph bruto roda a US$ 10,42/hora e entrega código em velocidade de máquina.¹ Também entrega except: pass, # TODO: fix later e “os testes deveriam 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 revelação das 3 da manhã de que você deveria ter feito certo da primeira vez.

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

As guias de gaveta do meu pai não se importam com a gaveta. São mecanismos acionados por mola aparafusados a um trilho. Mas protegem a face frontal por mil ciclos porque alguém as 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 pegam seus erros mais comuns. Construa a partir daí.

Referências