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. A lista de artigos está no final desta página, fora do índice reverso.
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.
A frase que uma pessoa digita quando algo dá errado
「Limpe todos os todos. Consulte https://typing-tube.net/articles/pt/lookup.md, revise esta sessão e verifique se algo deu errado.」
Daqui sai apenas uma lista de problemas. Como corrigi-los é você quem decide, conforme o seu projeto.
| O que está acontecendo | Abordagem sugerida |
|---|---|
| No.1 Toda vez que a IA roda os testes, dezenas de milhares de linhas de saída inundam o contexto |
Exemplo:Centralize a execução dos testes em um wrapper e devolva à IA só o resumo das falhas. |
| No.2 Quanto mais notas de conhecimento a IA salva, mais cada sessão futura precisa ler |
Exemplo:Faça ler uma checklist antes de escrever na memória, e deixe só uma linha no arquivo sempre lido. |
| No.3 Os testes passam, mas não fica claro se eles realmente protegem alguma coisa |
Exemplo:Instrua a IA a fazer mutation testing. |
| No.4 Às vezes a IA usa uma skill registrada, às vezes não |
Exemplo:Bloqueie chamadas incorretas na entrada e indique a documentação a ler. |
| No.5 Depois que o trabalho é passado a um sub-agent, você não vê o que está acontecendo até ele terminar |
Exemplo:Liste as tarefas delegáveis e verifique-as com um hook antes de iniciar o sub-agent. |
| No.6 Quanto mais regras você adiciona ao arquivo de instruções, menos as regras anteriores são seguidas |
Exemplo:Reescreva cada "não faça X", uma de cada vez, como teste automatizado que detecta a violação. |
| No.7 A memória compartilhada entre sessões paralelas fica bagunçada, e fazer a IA ler a política não resolve |
Exemplo:Não mude o que é lido; mude só o momento, mostrando logo após salvar. |
| No.8 Mesmo depois de anotar como lidar com uma falha, a IA comete o mesmo erro de novo na próxima vez |
Exemplo:Ao detectar a falha, insira automaticamente a política de nova tentativa. |
| No.9 Mesmo lendo as notas de handoff e o relatório de conclusão, as partes inconvenientes estão faltando |
Exemplo:Coloque sempre, ao lado do relatório de conclusão, números contados pela máquina. |
| No.10 Os números contados pela máquina viram números diferentes até chegarem ao relatório |
Exemplo:Marque a linha do número com um prefixo fixo e use um hook para verificar que foi copiada ao pé da letra. |
| No.11 Interromper a IA no meio da tarefa desorganiza tudo o que ela faz depois |
Exemplo:Não interrompa durante o trabalho; espere o corte. Deixe a interrupção a cargo do mecanismo. |
| No.12 No fim da sessão, não está decidido o que precisa ser lido e o que não precisa |
Exemplo:Não leia o entregável nem o log de trabalho; julgue só pelo exit code. |
| No.13 Uma proposta já rejeitada volta a aparecer na sessão seguinte |
Exemplo:Reúna as decisões rejeitadas em um único documento. |
| No.14 Mesmo com uma proibição de uma linha escrita, ela acaba sendo interpretada de forma mais ampla ou mais restrita do que deveria |
Exemplo:Escreva, em cada proibição, o "motivo" ao lado da conclusão. |
| No.15 A proibição está escrita corretamente, mas não é seguida, e toda vez alguém vem perguntar a respeito |
Exemplo:Escreva o "escopo" de cada proibição e liste, linha a linha, os casos-limite. |
| No.16 Ao dar a mesma instrução a vários sub-agents, cada um retorna em um formato diferente |
Exemplo:Na lista de tarefas delegáveis, especifique os insumos exigidos antes de iniciar. |
| No.17 Proibições sem teste automatizado se acumulam, permanecendo só texto no papel |
Exemplo:Indique, para cada proibição, se existe teste automatizado correspondente. |
| No.18 Todo trabalho da IA termina com "abra a tela e confira" |
Exemplo:Julgue a aprovação pelos dados deixados, não pela aparência da tela. |
| No.19 Toda vez que a IA diz algo um pouco fora do ponto, é você quem explica e corrige |
Exemplo:Não explique e corrija você mesmo; devolva pela mensagem de falha do hook e do teste automatizado. |
| No.20 A lista de decisões rejeitadas não para de crescer e parece caminhar para o ponto em que ninguém mais a lê |
Exemplo:Envie as propostas rejeitadas para "não adotado", no final. |
| No.21 As linhas "sempre execute isto" do arquivo de instruções nunca parecem diminuir |
Exemplo:Confira se o comando marcado "sempre execute" no arquivo de instruções também existe no mecanismo. |
| No.22 Mesmo depois de escrever exatamente como fazer, a correção não volta daquele jeito |
Exemplo:Não dite o procedimento; defina só os insumos exigidos antes de começar. |
| No.23 Relatar um bug significa escrever os passos e os sintomas você mesmo, toda vez |
Exemplo:A pessoa escreve só uma frase com o sintoma; o resto é coletado automaticamente. |
| No.24 Digitar "primeiro me dê um plano" toda vez já é, em si, uma tarefa repetitiva |
Exemplo:Basta colocar um documento de design; a IA segue o mesmo formato. |
| No.25 As linhas que você mais quer que sejam seguidas são escritas com mais ênfase, mas não dá para saber se isso ajuda |
Exemplo:Pare de medir o efeito; conte as linhas com ênfase e fixe um limite. |
| No.26 O entregável de um sub-agent volta em um formato diferente do esperado |
Exemplo:Defina os critérios de aceite do entregável antes de delegar. |
| No.27 Encontrar um erro dá vontade de perguntar: "você realmente leu isso?" |
Exemplo:Não cobre resposta; pergunte no formato "não é verdade que ...?". |
| No.28 Responder "não é isso" para a resposta recebida não a torna melhor |
Exemplo:Não aponte você mesmo; mostre a proibição junto do diff logo após salvar. |
| No.29 A IA fala sobre o conteúdo de um arquivo como se o tivesse aberto, quando não abriu |
Exemplo:Faça escrever o mesmo identificador na referência e na implementação, e use um teste automatizado para verificar que esse identificador existe. |
| No.30 A IA fica perguntando "A ou B?" e o trabalho trava enquanto você decide |
Exemplo:Não responda na hora; faça o critério de escolha ser decidido pelo mecanismo. |
| No.31 A IA está fazendo a revisão, mas não fica claro o que ela não está olhando |
Exemplo:Detecte de fora os testes automatizados que varrem arquivos sem limite mínimo de contagem. |
| No.32 As capturas de tela vão se acumulando, mas não fica claro qual delas verificou o quê |
Exemplo:Antes de capturar, faça escrever "o que verificar" e teste o meio mais barato primeiro. |
| No.33 Existe uma etapa que exige escrever algo, mas não é possível contar quantas execuções pularam essa etapa |
Exemplo:Antes da captura ou do E2E, exija escrever "o que verificar"; sem isso, não roda. |
| No.34 O mesmo teste roda de novo mesmo sem o código ter mudado, e você espera por isso mesmo assim |
Exemplo:Permita reler o log anterior, em vez de repetir a mesma execução. |
| No.35 Nada foi quebrado, mas uma fileira de erros desconhecidos aparece |
Exemplo:Adquira um lock exclusivo para a execução dos testes; sem ele, não roda. |
| No.36 O relatório "os testes passaram" não menciona as partes que nunca rodaram |
Exemplo:Pule os testes pesados por padrão, e liste sempre as áreas não executadas. |
| No.37 Não há como saber depois se uma instrução que especificava como proceder foi realmente seguida |
Exemplo:Não reforce a instrução; faça o procedimento deixar rastro no entregável. |
| No.38 Um wrapper que você colocou em prática é abandonado no meio do caminho, voltando ao comando puro |
Exemplo:Não reforce a instrução; verifique se ainda há motivo para voltar ao comando puro. |
| No.39 Fazer a mesma pergunta repetidas vezes traz uma resposta diferente a cada vez, e resumir tudo faz algo se perder |
Exemplo:Antes de resumir, mostre quantos, de quantos, levantaram cada tipo de observação. |
| No.40 Não há como saber se uma linha do tipo "faça X se necessário" chegou a disparar |
Exemplo:Não escreva "se necessário"; bloqueie o avanço até essa etapa ser cumprida. |
| No.41 Dizer "pense de novo" muda a resposta, mas não fica claro se a IA realmente se convenceu |
Exemplo:Não devolva sem mais; aponte especificamente qual premissa está errada. |
| No.42 Escrever "não adivinhe" fez a IA passar a voltar sem construir nada |
Exemplo:Não dê só a proibição; ofereça a saída de escrever "não aplicável". |
| No.43 Quanto mais tempo uma conversa que está indo bem continua, mais trabalho dá para verificá-la |
Exemplo:Encerre a sessão no corte e comece a próxima em uma nova sessão. |
| No.44 Todos os entregáveis estão corretos, mas o desperdício que não aparece neles continua se acumulando |
Exemplo:Quando o entregável estiver pronto, tabule o log de trabalho uma vez. |
| No.45 As notas deixadas para a próxima pessoa saem de sincronia com a realidade e ficam desatualizadas |
Exemplo:Não deixe o conhecimento em documento; incorpore-o na mensagem de parada. |
| No.46 A investigação da causa continua, e a leitura segue mesmo depois de a resposta já ter aparecido |
Exemplo:Conte as leituras seguidas sem mudar nada, e escreva a condição de parada antes de investigar. |
| No.47 O modelo de menor preço é definido como padrão sem medir se ele realmente serve para o caso de uso |
Exemplo:Dê a mesma tarefa ao modelo barato e ao caro, e decida após contar turnos e volume. |
| No.48 Quando algo não funciona, a solução buscada é um modelo maior, não um mecanismo melhor |
Exemplo:Dê a mesma tarefa aos dois modelos, e torne teste automatizado os pontos em que só o barato falhar. |
| No.49 Uma pesquisa que a sessão principal conseguiria terminar sozinha é passada a um sub-agent só por precaução |
Exemplo:Não delegue o que o agente pai já tem; delegue só a leitura que falta. |
| No.50 A opção padrão é dividir o trabalho em quatro e rodar tudo ao mesmo tempo, só porque sim |
Exemplo:Delegue ao sub-agent só o que cabe em uma resposta. O custo é o número de idas e voltas, não de sub-agents. |
| No.53 "Olha isso também" é injetado de fora no meio do trabalho |
Exemplo:Espere o corte e peça com escopo reduzido, acrescentando "diga se já está suficiente". |
| No.52 A escolha de qual modelo usar está sendo feita comparando-os lado a lado |
Exemplo:Antes de comparar, conte a quantos mecanismos equivale esse esforço. |
| No.51 "Não houve diferença" está sendo usado como motivo para encerrar a verificação |
Exemplo:Antes de encerrar, reconte o que foi excluído da contagem e o que deu zero em todas as condições. |
| No.54 De um dia para o outro a IA passou a trabalhar de outro jeito, e você não mudou nem as instruções nem as configurações |
Exemplo:Não escreva o que conflita com a instrução do produto; complete só o que ela não decide. Para mudar a forma de trabalhar, troque a configuração. |
Lista de artigos
Daqui para baixo não faz parte do índice reverso: são links para os artigos, série por série, 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 校正の方法に、先に本編を当てる技術 —— AI が書いた方針に、その本自身の地雷が 10 個あった日
- 番外編 C-2 仕組みと人を分ける技術 —— 自動テストを置いたその手で、自動テストの外側で 2 度転んだ日
- 番外編 C-3 要素ごとに観点を変える技術 —— 一様に当てた点検が、要素をまたいだところで数を落とす
- 番外編 C-4 似た指示語を読み分ける技術 —— 1 字違いで、別の作業を頼んだことになる
- 番外編 C-5 作業の流れを見る技術 —— 終わりにしたつもりの日に、まだ起きていたこと
- 番外編 C-6 作業を進める技術 —— 選ぶ場面が、1 つも残らなかった日
- 番外編 C-7 読まずに止める技術 —— 決まったはずの判断が、1 分後に取り消されました
- 番外編 D-1 症状で読む —— 片付いた報告に、症状が混ざります
- 番外編 D-2 根拠で読む —— 突き合わせた報告に、症状が混ざります
- あとがき —— 本当の事実はどうでもいい話