Qué está pasando → qué hacer
Busca por síntoma, no por título. El enlace bajo "qué hacer" lleva a la sección que describe ese mecanismo. El índice completo de todos los artículos está al final de esta página.
Esta tabla presupone Claude Code (el agente de programación de Anthropic). hook, CLAUDE.md, subagent y auto memory son los nombres de sus funciones.
| Qué está pasando | Qué hacer |
|---|---|
| Cada vez que la IA ejecuta los tests, decenas de miles de líneas de salida inundan el contexto |
Enruta todas las ejecuciones de tests a través de un único script wrapper, escribe la salida completa en un archivo de log y devuelve a la IA solo un resumen de los fallos. |
| Cuantas más notas de conocimiento guarda la IA, más tiene que leer cada sesión futura |
Usa un hook PreToolUse que se ejecute justo antes de escribir en memoria para que la IA lea antes una checklist, y deja el archivo de instrucciones (CLAUDE.md) reducido a una sola línea: "lee antes de escribir". |
| Los tests pasan, pero no está claro si realmente protegen algo |
Escribe una política de una página sobre mutation testing (romper el código a propósito para ver si los tests lo detectan) y haz que la IA la lea cada vez que le pidas revisar los tests. |
| La IA a veces usa una skill registrada y a veces no |
Deja el comando como un script normal, bloquea las invocaciones incorrectas con un hook PreToolUse e indica a la IA qué documentación debe leer. |
| Una vez que el trabajo pasa a un sub-agente, no se ve qué está pasando hasta que termina |
Define en YAML qué tareas pueden delegarse a un sub-agente y qué archivos de entrada deben existir antes de lanzarlo, y verifícalo con un hook antes de que arranque. |
| Cuantas más reglas se añaden al archivo de instrucciones, menos se respetan las reglas anteriores |
Reescribe cada regla de "no hagas X", una por una, como un test automatizado (Minitest) capaz de detectar la infracción. |
| La memoria compartida entre sesiones paralelas se desordena, y hacer que lean la política no ayuda |
Traslada la misma política a un hook PostToolUse y muéstrala junto al diff justo después de guardar. Mantén el contenido igual: cambia solo el momento en que se muestra. |
| Aunque se ha dejado escrito cómo manejar un fallo, la IA repite el mismo error la próxima vez |
Resume la política de reintento en unas pocas líneas en un archivo, y haz que un hook que detecte el fallo la inserte automáticamente. |
| Incluso leyendo las notas de traspaso y el informe de finalización, faltan las partes incómodas |
Coloca siempre, junto al informe de finalización, números obtenidos mecánicamente, como los de git diff --stat. |
| Los números que cuenta la máquina se convierten en otros distintos para cuando llegan al informe |
Añade un prefijo fijo a la línea con el número, y haz que un hook compruebe que se copió literalmente. |
| Interrumpir a la IA a mitad de tarea descoloca todo lo que hace después |
En lugar de que una persona interrumpa a mitad de tarea, deja que intervengan un hook PostToolUse que devuelve la política justo después de guardar y un hook que detecta el fallo y devuelve el trabajo. La persona espera a un punto de corte. |
| Al final de una sesión, no está decidido qué hay que leer y qué no |
No leas el entregable ni el registro de trabajo: decide el resultado únicamente por el exit code de los tests o del linter. |
| Una propuesta que ya se rechazó vuelve a aparecer en la siguiente sesión |
Reúne cada decisión rechazada en un único documento, con un formato fijo. |
| Aunque se ha escrito una prohibición de una línea, se interpreta tanto de más como de menos |
En el único documento que reúne las decisiones rechazadas (por ejemplo non_goals.md), añade un apartado de "motivo" a cada prohibición, junto a la conclusión. |
| La prohibición está bien escrita pero no se respeta, y cada vez alguien pregunta al respecto |
En el documento de decisiones rechazadas, añade un apartado de "alcance" a cada prohibición y enumera, una por línea, los casos límite que generan dudas. |
| Al dar las mismas instrucciones a varios sub-agentes, cada uno devuelve el trabajo en una forma distinta |
En la lista de tareas delegables a un sub-agente, indica explícitamente los archivos de entrada que deben prepararse antes del lanzamiento. |
| Las prohibiciones sin ningún test automatizado se acumulan sin ser más que texto en una página |
En el documento de decisiones rechazadas, añade un apartado de "verificación automática" a la lista y marca, elemento por elemento, si existe un test automatizado (Minitest) correspondiente. |
| Cada trabajo de la IA termina con un "por favor, abre la pantalla y compruébalo" |
Prepara un único smoke test con Playwright, y decide el resultado por el registro que queda en la base de datos, no por el aspecto de la pantalla. |
| Cada vez que la IA dice algo ligeramente desviado, eres tú quien lo explica y lo corrige |
En lugar de que una persona explique y corrija cada desviación, escribe la corrección en el stderr del hook (exit 2) y en los mensajes de fallo de los tests automatizados, para que ese sea el camino por el que llega a la IA. |
| La lista de decisiones rechazadas sigue creciendo y parece que llegará un punto en que nadie la lea |
Añade un apartado de "opciones no adoptadas" al final del documento de decisiones rechazadas, y registra ahí las propuestas rechazadas. |
| Las líneas de "ejecuta esto siempre" del archivo de instrucciones nunca disminuyen |
Usa un test automatizado que compruebe si cada comando que el archivo de instrucciones marca como "ejecutar siempre" existe también en un pre-commit hook. |
| Aunque se ha escrito exactamente cómo hacerlo, la corrección no vuelve hecha de ese modo |
En lugar de dictar el procedimiento, define, para cada caso de uso, los archivos de entrada que deben existir antes de poder lanzar un sub-agente. |
| Reportar un bug significa escribir los pasos y los síntomas cada vez, tú mismo |
Instala un formulario de reporte de bugs donde la persona solo escribe una frase describiendo el síntoma, y deja que JavaScript recoja automáticamente la URL, el historial de acciones y la información del navegador. |
| Escribir "primero dame un plan" cada vez es en sí mismo una tarea repetitiva |
No hace falta ninguna implementación nueva. Coloca un único documento de diseño, y la IA leerá los documentos existentes y seguirá el mismo formato. |
| Las líneas que más se quiere que se cumplan son las que se escriben con más énfasis, pero no se sabe si eso ayuda |
Deja de intentar medir el efecto: en su lugar, cuenta las líneas del archivo de instrucciones que usan énfasis y añade un test automatizado (un ratchet) que falle en cuanto ese número supere un umbral. |
| El entregable de un sub-agente vuelve en una forma distinta a la esperada |
Para cada caso de uso de sub-agente, define en un único documento los criterios de aceptación de su entregable: nombre de archivo, formato, campos obligatorios. |
| Encontrar un error da ganas de exigir: "¿de verdad leíste esto?" |
En lugar de exigir una respuesta, fija la segunda frase de cada petición a la plantilla de pregunta "¿no es cierto que ...?". |
| Responder "eso no es" a la respuesta obtenida no la mejora en nada |
En lugar de señalarlo tú mismo, presenta las prohibiciones sin alternativa mediante un hook PostToolUse, mostrado junto al diff justo después de guardar. |
| La IA habla del contenido de un archivo como si lo hubiera abierto, sin haberlo hecho |
Haz que la IA escriba markers correspondientes tanto en el documento referenciado como en el código, y verifica con un test automatizado que esos markers existen de verdad. |
| La IA sigue preguntando "¿A o B?" y el trabajo se detiene mientras decides |
Deja de responder al momento: haz que la elección la decida un test automatizado o un hook. |
| La IA está haciendo la revisión, pero no está claro qué es lo que no está mirando |
Usa un test automatizado externo que cuente elementos para detectar cualquier test automatizado que recorra archivos pero no tenga una aserción de mínimo sobre el conteo (por ejemplo, assert_operator ... :>=). |
| Las capturas de pantalla se acumulan, pero no está claro cuál verificó qué |
Antes de mirar la pantalla, exige responder a dos preguntas — "qué se está verificando" y "por qué no basta un método más barato" — y mantén una guía de una página que priorice la opción más barata, en el orden test unitario → test de integración → E2E. |
| Se puso un paso que exige dejarlo por escrito, pero no se puede contar cuántas ejecuciones lo saltaron |
Antes de una captura de pantalla o un E2E, haz escribir un archivo de declaración que diga qué se va a verificar (por ejemplo tmp/visual_verification.md), convierte su existencia en una precondición de un hook PreToolUse, y que sin él no arranque ni la captura ni el E2E. |
| El mismo test vuelve a ejecutarse aunque el código no ha cambiado, y toca esperar igualmente |
Añade una opción --last al script wrapper de tests que reproduzca el log anterior, para que no haga falta volver a ejecutar. |
| No se rompió nada, y aun así aparece una fila de errores desconocidos |
Haz que el script wrapper de tests tome un lock exclusivo (aprovechando la atomicidad de mkdir), y que se niegue a ejecutar si no puede obtenerlo. |
| Un informe que dice "los tests pasan" no menciona las partes que nunca se ejecutaron |
Etiqueta los tests E2E pesados por nombre de área y omítelos (skip) por defecto, e imprime cada vez la lista de áreas que no se ejecutaron. |
| No hay forma de saber después si una instrucción que especificaba cómo proceder realmente se siguió |
Cuando quieras que se siga un procedimiento, no refuerces la redacción de la instrucción: cámbiala para que seguir el procedimiento deje un rastro en el entregable (por ejemplo, imprimir una línea por cada archivo abierto). |
| Un wrapper que se puso en marcha se abandona a mitad de camino, volviendo al comando en bruto |
Cuando quieras que se use el wrapper, no refuerces la instrucción: comprueba en su lugar si todavía queda un motivo para volver al comando en bruto, es decir, si al wrapper le falta alguna capacidad. |
| Hacer la misma pregunta repetidamente da una respuesta distinta cada vez, y resumir pierde algo |
Antes de fusionar varias respuestas en una, imprime con qué frecuencia apareció cada tipo de hallazgo: cuántos de cuántos lo señalaron. |
| No hay forma de saber si una línea que dice "haz X si hace falta" llegó a activarse alguna vez |
No escribas instrucciones condicionales como "haz X si hace falta": impón ese paso con un hook que bloquee el avance hasta que se cumpla. |
| Decir "piénsalo de nuevo" cambia la respuesta, pero no está claro si la IA realmente quedó convencida |
En lugar de devolverlo con un "piénsalo de nuevo", señala con precisión qué premisa es errónea. |
| Escribir "no adivines" hizo que la IA empezara a volver sin haber construido nada |
No entregues solo una prohibición: acompáñala de una salida alternativa, como "si no aplica ningún caso, indica 'no aplica'". |
| Cuanto más se prolonga una conversación que va bien, más esfuerzo cuesta verificarla |
Termina la sesión en cada límite de tarea, y empieza la siguiente tarea en una sesión nueva. |
| Todos los entregables son correctos, pero se va acumulando un desperdicio que nunca aparece en ellos |
Una vez completados los entregables, ejecuta un script que analice, de una sola vez, el propio registro de trabajo (transcript). |
| Las notas dejadas para la siguiente persona se desincronizan de la realidad y quedan obsoletas |
No dejes el conocimiento en un documento: incrústalo en el mensaje de fallo de un test automatizado o en el mensaje de parada de un hook, para que aparezca justo en el momento en que se necesita. |
| Se sigue indagando en la causa, y la lectura continúa incluso después de encontrar la respuesta |
Cuenta, a partir del registro de trabajo, las rachas de lecturas que no cambiaron nada, y escribe una condición de parada de una línea antes de empezar a indagar. |
| El modelo más barato se convierte en el predeterminado sin medir si realmente encaja con el uso |
Dale la misma tarea al modelo barato y al modelo caro, y decide solo después de contar por separado los turnos hasta terminar y la cantidad leída de nuevo, reutilizada (cache read) y escrita. |
| Cuando algo no funciona, la solución a la que se recurre es subir de modelo, no mejorar el mecanismo |
Dale la misma tarea al modelo más caro y al más barato, y convierte en una comprobación permanente los puntos donde solo falla el más barato. |
| Una investigación que la sesión principal podría terminar sola se delega a un sub-agente por si acaso |
Antes de delegar, comprueba si el agente padre ya tiene ese contexto. Si lo tiene, sigue en el agente padre; entrega a un sub-agente solo el grueso de la lectura que no tiene ya. |
| Por defecto se divide el trabajo en cuatro y se lanzan todos a la vez, sin más |
Dale a cada sub-agente solo lo que pueda devolver en una sola respuesta. Lo que fija el costo no es cuántos sub-agentes hay, sino cuántas idas y vueltas hace cada sub-agente resultante de la división con el agente padre. |
| Un "mira esto también" se inyecta desde fuera a mitad del trabajo |
Espera a un punto de corte natural del trabajo, y luego incorpora la petición adicional con el alcance reducido. Al preguntarle a la propia IA por carencias, añade siempre: "si es suficiente, dilo explícitamente". Así tiene una salida (escape hatch) y no necesita inventarse una carencia. |
| Se intenta decidir qué modelo usar comparándolos directamente entre sí |
Antes de empezar a comparar modelos, cuenta a cuántos hooks o tests automatizados equivale el esfuerzo de esa comparación. Si puedes escribir más mecanismos que ese número, ponlos en marcha antes de comparar. |
| "No hubo diferencia" se usa como motivo para dar por cerrada la verificación |
Antes de cerrar con "no hubo diferencia", cuenta dos cosas: si algún resultado quedó excluido del recuento (por ejemplo sub-agentes fallidos), vuelve a incluirlo y recuenta; si más de la mitad de los ítems da cero en todas las condiciones, reformula la tarea y mide de nuevo. |
Todos los artículos
Serie por serie, desde la introducción hasta el último capítulo.
はじめに —— 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話