O que está acontecendo → o que fazer
Busque pelo sintoma, não pelo título. O link abaixo de "o que fazer" leva à seção que descreve a solução. O sumário completo de todos os artigos está no final desta página.
Esta tabela pressupõe o Claude Code (o agente de programação da Anthropic). hook, CLAUDE.md, subagent e auto memory são os nomes de seus recursos.
| O que está acontecendo | O que fazer |
|---|---|
| Toda vez que a IA roda os testes, dezenas de milhares de linhas de saída inundam o contexto |
Centralize a execução dos testes em um único script wrapper, grave toda a saída em um arquivo de log e devolva à IA apenas um resumo das falhas. |
| Quanto mais notas de conhecimento a IA salva, mais cada sessão futura precisa ler |
Use um hook PreToolUse que roda logo antes de gravar na memória para fazer a IA ler uma checklist primeiro, e mantenha no arquivo de instruções (CLAUDE.md) apenas uma linha: "leia antes de escrever". |
| Os testes passam, mas não fica claro se eles realmente protegem alguma coisa |
Escreva uma política de uma página sobre mutation testing (técnica de quebrar o código de propósito para ver se os testes detectam) e faça a IA ler esse documento sempre que pedir uma revisão dos testes. |
| Às vezes a IA usa uma skill registrada, às vezes não |
Mantenha o comando como um script comum, bloqueie invocações incorretas com um hook PreToolUse e aponte para a documentação que a IA deve ler. |
| Depois que o trabalho é passado a um sub-agent, você não vê o que está acontecendo até ele terminar |
Defina em YAML quais tarefas podem ser delegadas a um sub-agent e quais arquivos de entrada precisam existir antes de iniciá-lo, e verifique isso com um hook antes do início. |
| Quanto mais regras você adiciona ao arquivo de instruções, menos as regras anteriores são seguidas |
Reescreva cada regra do tipo "não faça X", uma de cada vez, como um teste automatizado (Minitest) capaz de detectar a violação. |
| A memória compartilhada entre sessões paralelas fica bagunçada, e fazer a IA ler a política não resolve |
Mova o mesmo arquivo de política para um hook PostToolUse e mostre-o junto com o diff logo após salvar. Mantenha o conteúdo igual — mude apenas o momento. |
| Mesmo depois de anotar como lidar com uma falha, a IA comete o mesmo erro de novo na próxima vez |
Resuma a política de nova tentativa em algumas linhas em um arquivo, e tenha um hook que detecta a falha e a insere automaticamente. |
| Mesmo lendo as notas de handoff e o relatório de conclusão, as partes inconvenientes estão faltando |
Sempre coloque, ao lado do relatório de conclusão, números obtidos mecanicamente por algo como git diff --stat. |
| Os números contados pela máquina viram números diferentes até chegarem ao relatório |
Adicione um prefixo fixo à linha com o número, e tenha um hook que verifica se ele foi copiado ao pé da letra. |
| Interromper a IA no meio da tarefa desorganiza tudo o que ela faz depois |
Em vez de uma pessoa interromper no meio da tarefa, deixe que intervenham um hook PostToolUse que devolve a política logo após salvar e um hook que detecta a falha e devolve o trabalho. A pessoa espera um ponto de corte. |
| No fim da sessão, não está decidido o que precisa ser lido e o que não precisa |
Não leia o entregável nem o log de trabalho — julgue aprovação ou reprovação só pelo exit code dos testes ou do linter. |
| Uma proposta já rejeitada volta a aparecer na sessão seguinte |
Consolide toda decisão rejeitada em um único documento, usando um formato fixo. |
| Mesmo com uma proibição de uma linha escrita, ela acaba sendo interpretada de forma mais ampla ou mais restrita do que deveria |
No documento único que reúne as decisões rejeitadas (por exemplo non_goals.md), adicione uma seção "motivo" a cada proibição, ao lado da conclusão. |
| A proibição está escrita corretamente, mas não é seguida, e toda vez alguém vem perguntar a respeito |
No documento de decisões rejeitadas, adicione uma seção "escopo" a cada proibição e liste, linha por linha, os casos-limite que geram dúvida. |
| Ao dar a mesma instrução a vários sub-agents, cada um retorna em um formato diferente |
Na lista de tarefas que podem ser delegadas a um sub-agent, especifique explicitamente os arquivos de entrada que devem estar prontos antes do início. |
| Proibições sem teste automatizado se acumulam, permanecendo só texto no papel |
No documento de decisões rejeitadas, adicione uma seção "verificação mecânica" à lista e indique, item por item, se existe um teste automatizado (Minitest) correspondente. |
| Todo trabalho da IA termina com "abra a tela e confira" |
Prepare um único smoke test com Playwright, e julgue aprovação ou reprovação pelo registro deixado no banco de dados, não pela aparência da tela. |
| Toda vez que a IA diz algo um pouco fora do ponto, é você quem explica e corrige |
Em vez de uma pessoa explicar e corrigir cada desvio, escreva a correção no stderr do hook (exit 2) e nas mensagens de falha dos testes automatizados, para que esse seja o caminho pelo qual ela chega à IA. |
| A lista de decisões rejeitadas não para de crescer e parece caminhar para o ponto em que ninguém mais a lê |
Adicione uma seção "não adotado" ao final do documento de decisões rejeitadas, e registre ali as propostas rejeitadas. |
| As linhas "sempre execute isto" do arquivo de instruções nunca parecem diminuir |
Use um teste automatizado para verificar se todo comando que o arquivo de instruções marca como "sempre execute" também existe em um hook de pre-commit. |
| Mesmo depois de escrever exatamente como fazer, a correção não volta daquele jeito |
Em vez de ditar o procedimento, defina, por caso de uso, os arquivos de entrada que precisam existir antes de um sub-agent poder ser iniciado. |
| Relatar um bug significa escrever os passos e os sintomas você mesmo, toda vez |
Configure um formulário de relato de bugs em que a pessoa digita apenas uma frase descrevendo o sintoma, e deixe o JavaScript coletar automaticamente a URL, o histórico de ações e as informações do navegador. |
| Digitar "primeiro me dê um plano" toda vez já é, em si, uma tarefa repetitiva |
Nenhuma implementação nova é necessária. Basta colocar um único documento de design em vigor, e a IA lerá os documentos existentes e seguirá o mesmo formato. |
| As linhas que você mais quer que sejam seguidas são escritas com mais ênfase, mas não dá para saber se isso ajuda |
Pare de tentar medir o efeito — em vez disso, conte as linhas do arquivo de instruções que usam ênfase, e adicione um teste automatizado (um ratchet) que falha quando essa contagem ultrapassa um limite. |
| O entregável de um sub-agent volta em um formato diferente do esperado |
Para cada caso de uso de sub-agent, defina em um único documento os critérios de aceitação do entregável — nome do arquivo, formato, campos obrigatórios. |
| Encontrar um erro dá vontade de perguntar: "você realmente leu isso?" |
Em vez de cobrar uma resposta, fixe a segunda frase de cada pedido no modelo de pergunta "não é verdade que ...?". |
| Responder "não é isso" para a resposta recebida não a torna melhor |
Em vez de apontar você mesmo, apresente proibições sem alternativa por meio de um hook PostToolUse, mostrado junto com o diff logo após salvar. |
| A IA fala sobre o conteúdo de um arquivo como se o tivesse aberto, quando não abriu |
Faça a IA escrever markers correspondentes tanto no documento referenciado quanto no código, e verifique com um teste automatizado que esses markers realmente existem. |
| A IA fica perguntando "A ou B?" e o trabalho trava enquanto você decide |
Pare de responder na hora — organize as coisas para que a escolha seja decidida por um teste automatizado ou um hook. |
| A IA está fazendo a revisão, mas não fica claro o que ela não está olhando |
Use um teste automatizado externo que conta coisas para detectar qualquer teste automatizado que varre arquivos mas não tem uma asserção de limite mínimo na contagem (por exemplo, assert_operator ... :>=). |
| As capturas de tela vão se acumulando, mas não fica claro qual delas verificou o quê |
Antes de conferir a tela, exija respostas para duas perguntas — "o que está sendo verificado" e "por que um método mais barato não resolve" — e mantenha uma diretriz de uma página para tentar primeiro a opção mais barata, na ordem teste unitário, teste de integração e depois E2E. |
| Existe uma etapa que exige escrever algo, mas não é possível contar quantas execuções pularam essa etapa |
Antes de uma captura de tela ou de um E2E, faça escrever um arquivo de declaração que diga o que será verificado (por exemplo tmp/visual_verification.md), torne sua existência uma pré-condição de um hook PreToolUse, e sem ele a captura ou o E2E não começa. |
| O mesmo teste roda de novo mesmo sem o código ter mudado, e você espera por isso mesmo assim |
Adicione uma opção --last ao script wrapper de testes, que reproduz o log anterior, tornando a nova execução desnecessária. |
| Nada foi quebrado, mas uma fileira de erros desconhecidos aparece |
Faça o script wrapper de testes adquirir um lock exclusivo (usando a atomicidade do mkdir), e recuse-se a rodar se não conseguir obtê-lo. |
| O relatório "os testes passaram" não menciona as partes que nunca rodaram |
Marque os testes E2E pesados com uma tag pelo nome da área e faça skip deles por padrão, imprimindo sempre a lista das áreas que não rodaram. |
| Não há como saber depois se uma instrução que especificava como proceder foi realmente seguida |
Quando quiser que um procedimento seja seguido, não reforce as palavras da instrução — em vez disso, mude o processo para que segui-lo deixe um rastro no entregável (por exemplo, fazendo com que ele imprima uma linha para cada arquivo aberto). |
| Um wrapper que você colocou em prática é abandonado no meio do caminho, voltando ao comando puro |
Quando quiser que o wrapper seja usado, não reforce a instrução — em vez disso, verifique se ainda existe um motivo para recorrer ao comando puro, ou seja, se falta alguma capacidade ao wrapper. |
| Fazer a mesma pergunta repetidas vezes traz uma resposta diferente a cada vez, e resumir tudo faz algo se perder |
Antes de combinar várias respostas em uma só, imprima a frequência de cada tipo de observação — quantas, de quantas, a levantaram. |
| Não há como saber se uma linha do tipo "faça X se necessário" chegou a disparar |
Não escreva instruções condicionais como "faça X se necessário" — em vez disso, force a etapa com um hook que bloqueia o avanço até que ela seja concluída. |
| Dizer "pense de novo" muda a resposta, mas não fica claro se a IA realmente se convenceu |
Em vez de devolver com "pense de novo", aponte especificamente qual premissa está errada. |
| Escrever "não adivinhe" fez a IA passar a voltar sem construir nada |
Não entregue apenas uma proibição — combine-a com uma saída alternativa, como "se nada se aplicar, gere 'não aplicável'". |
| Quanto mais tempo uma conversa que está indo bem continua, mais trabalho dá para verificá-la |
Encerre a sessão em cada limite de tarefa, e comece a próxima tarefa em uma nova sessão. |
| Todos os entregáveis estão corretos, mas o desperdício que não aparece neles continua se acumulando |
Quando os entregáveis estiverem prontos, rode um script para tabular o próprio log de trabalho (transcript), uma única vez. |
| As notas deixadas para a próxima pessoa saem de sincronia com a realidade e ficam desatualizadas |
Não deixe o conhecimento em um documento — incorpore-o na mensagem de falha de um teste automatizado ou na mensagem de interrupção de um hook, para que apareça exatamente no momento em que é preciso. |
| A investigação da causa continua, e a leitura segue mesmo depois de a resposta já ter aparecido |
Conte, a partir do log de trabalho, sequências de leituras que não mudaram nada, e escreva em uma linha uma condição de parada antes de começar a investigar. |
| O modelo de menor preço é definido como padrão sem medir se ele realmente serve para o caso de uso |
Dê a mesma tarefa ao modelo barato e ao modelo caro, e decida só depois de contar separadamente os turnos até a conclusão e as quantidades lidas de novo, reaproveitadas (cache read) e escritas. |
| Quando algo não funciona, a solução buscada é um modelo maior, não um mecanismo melhor |
Dê a mesma tarefa ao modelo mais caro e ao mais barato, e transforme em uma verificação permanente os pontos em que só o mais barato falha. |
| Uma pesquisa que a sessão principal conseguiria terminar sozinha é passada a um sub-agent só por precaução |
Antes de delegar, verifique se o agente pai já tem esse contexto. Se tiver, continue nele; entregue a um sub-agent apenas o grande volume de leitura que ele ainda não tem. |
| A opção padrão é dividir o trabalho em quatro e rodar tudo ao mesmo tempo, só porque sim |
Dê a cada sub-agent apenas o que ele consegue devolver em uma única resposta. O que define o custo não é a quantidade de sub-agents, mas quantas idas e voltas cada sub-agent resultante da divisão faz com o agente pai. |
| "Olha isso também" é injetado de fora no meio do trabalho |
Espere um ponto de corte natural do trabalho e então incorpore o pedido extra com escopo reduzido. Ao perguntar à própria IA sobre lacunas, sempre acrescente: "se estiver suficiente, diga isso explicitamente". Assim ela tem uma saída (escape hatch) e não precisa inventar uma lacuna. |
| A escolha de qual modelo usar está sendo feita comparando-os lado a lado |
Antes de começar a comparar modelos, conte a quantos hooks ou testes automatizados equivale o esforço dessa comparação. Se for possível escrever mais mecanismos do que esse número, coloque-os em prática antes de comparar. |
| "Não houve diferença" está sendo usado como motivo para encerrar a verificação |
Antes de encerrar com "não houve diferença", conte duas coisas: se algum resultado foi excluído da contagem (por exemplo sub-agents que falharam), coloque-o de volta e recalcule; se mais da metade dos itens tiver zero em todas as condições, reformule a tarefa e meça de novo. |
Sumário de todos os artigos
Série por série, na ordem da introdução até o artigo final.
はじめに —— 3 つの連載を、1 冊に
バイブコーディングにおける読まない技術
- 読まない技術 序論 AIの出力を、もうほとんど読んでいない
- 読まない技術 第1回 テスト結果を読まない技術
- 読まない技術 第2回 メモリを読まない技術
- 読まない技術 第3回 単体テストを読まない技術
- 読まない技術 第4回 スキルを使わない技術
- 読まない技術 第5回 サブエージェントの出力だけは読め
- 読まない技術 第6回 ルールを読まない技術
- 読まない技術 第7回 共有メモリを整理しない技術
- 読まない技術 第8回 修正履歴を読まない技術
- 読まない技術 第9回 引き継ぎを読まない技術
- 読まない技術 第10回 AIに要約しろと言わない技術
- 読まない技術 第11回 口を挟まない技術
- 読まない技術 第12回 作業結果を読まない技術
- 読まない技術 最終回 AIの出力を、ほとんど読まなくなった
AIの意見を聞かない技術
言わない技術
- 言わない技術 序論 AI に指示することが、ほとんどなくなった
- 言わない技術 第1回 検証を指示しない技術
- 言わない技術 第2回 具体的な指示を出さない技術
- 言わない技術 第3回 不具合詳細を書かない技術
- 言わない技術 第4回 計画を書けと言わない技術
- 言わない技術 第5回 念を押さない技術
- 言わない技術 第6回 サブエージェントの出力だけは、細かく指示しろ
- 言わない技術 第7回 AI を問い詰めない技術
- 言わない技術 第8回 AI にダメ出ししない技術
- 言わない技術 第9回 AI に考えさせない技術
- 言わない技術 第10回 質問に答えない技術
- 言わない技術 第11回 AI にレビューをさせない技術
- 言わない技術 最終回 何もしない技術
付録
はじめに —— 前巻の続きを、もう 1 冊に
確かめない技術
動かさない技術
追わない技術
番外編
- 番外編 A-1 整理する技術 —— 記録が増えたときに、何が起きているか
- 番外編 A-2 指示を残す技術 —— 「調べるだけ」が通らなかった日
- 番外編 A-3 参照するタイミングを変える技術 —— 2,000 行の壁
- 番外編 A-4 導出を依頼者の言葉と分ける技術 —— 誰も言っていない条件が、memory に載った日
- 番外編 A-5 memory を要約しない技術 —— 整理から、要約を抜く
- 番外編 A-6 責務で線を引く技術 —— 仕組みが増えたときに、どれを消すか
- 番外編 A-7 読まれたかを確かめる技術 —— 確かめるのをやめて、読めていない形を止めた
- 番外編 A-8 面積で数える技術 —— 読ませた量で数えていたら、102 倍外していました
- 番外編 A-9 ルールを短くする技術 —— 読みに来るのは、止められた直後の人です
- 番外編 B-1 連載を本にする技術 —— 本単位のスイッチでは、足りなかった日
- 番外編 C-1 校正の方法に、先に本編を当てる技術 —— 方法を決める文が、本文と同じ地雷を踏んでいた日
- 番外編 C-2 仕組みと人を分ける技術 —— 検査を置いたその手で、検査の外側で 2 度転んだ日
- 番外編 C-3 要素ごとに観点を変える技術 —— 一様に当てた点検が、要素をまたいだところで数を落としていた
- 番外編 C-4 指示の揺れを、事故として残す技術 —— 事故を見て置いた仕組みは、まだ一度も鳴っていない
- 番外編 C-5 作業の流れを見る技術 —— 終わりにしたつもりの日に、まだ起きていたこと
- 番外編 C-6 作業を進める技術 —— 選ぶ場面が、1 つも残らなかった日
- 番外編 C-7 基準の出どころを見る技術 —— 2 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話