Что происходит → что делать
Ищите не по названию статьи, а по симптому. Ссылка под «Что делать» ведёт к разделу, где описано это решение. Полное оглавление всех статей — внизу этой страницы.
Эта таблица предполагает использование Claude Code (агента для программирования от Anthropic). hook, CLAUDE.md, subagent и auto memory — названия его функций.
| Что происходит | Что делать |
|---|---|
| Каждый раз, когда ИИ запускает тесты, в контекст выгружаются десятки тысяч строк вывода |
Направьте весь запуск тестов через один обёрточный скрипт, записывайте полный вывод в лог-файл и возвращайте ИИ только сводку по ошибкам. |
| Чем больше заметок со знаниями сохраняет ИИ, тем больше приходится читать в каждой следующей сессии |
Используйте PreToolUse hook, который срабатывает непосредственно перед записью в память и заставляет ИИ сначала прочитать чек-лист, а в файле инструкций (CLAUDE.md) оставьте только одну строку: «прочитайте перед тем, как писать». |
| Тесты проходят, но непонятно, действительно ли они что-то защищают |
Опишите на одной странице политику mutation testing (метод, при котором код намеренно ломают, чтобы проверить, упадут ли тесты), и давайте её ИИ читать каждый раз, когда просите проверить тесты. |
| ИИ иногда использует зарегистрированный skill, а иногда нет |
Оставьте команду обычным скриптом, блокируйте неверные вызовы через PreToolUse hook и указывайте ИИ, какую документацию прочитать. |
| После того как работа передана sub-agent'у, не видно, что происходит, пока он не закончит |
Опишите в YAML, какие задачи можно делегировать sub-agent'у и какие входные файлы должны существовать перед запуском, и проверяйте это hook'ом перед стартом. |
| Чем больше правил добавляется в файл инструкций, тем хуже соблюдаются добавленные раньше |
Переписывайте каждое правило «не делайте X» по одному в автоматический тест (Minitest), который умеет обнаруживать нарушение. |
| Память, которую делят параллельные сессии, замусоривается, и чтение политики этому не помогает |
Перенесите тот же файл политики в PostToolUse hook и показывайте его вместе с diff сразу после сохранения. Содержимое не меняйте — меняйте только момент показа. |
| Даже если способ обработки ошибки записан, в следующий раз ИИ повторяет ту же ошибку |
Соберите политику повторной попытки в файл на несколько строк и вставляйте её автоматически через hook, который обнаруживает ошибку. |
| Даже при чтении заметок передачи и отчёта о завершении не хватает неудобных деталей |
Каждый раз размещайте рядом с отчётом о завершении цифры, полученные механически, например через git diff --stat. |
| Числа, посчитанные машиной, к моменту попадания в отчёт превращаются в другие числа |
Добавьте к строке с числом фиксированный префикс и проверяйте hook'ом, что он скопирован дословно. |
| Если прервать ИИ посреди работы, всё, что он делает дальше, идёт наперекосяк |
Вместо того чтобы человек прерывал работу посередине, пусть вмешиваются PostToolUse hook, который сразу после сохранения возвращает политику, и hook, который обнаруживает ошибку и возвращает работу на доработку. Человек ждёт естественной границы. |
| К концу сессии неясно, что нужно прочитать, а что нет |
Не читайте ни результат, ни лог работы — судите об успехе только по exit code тестов или линтера. |
| Однажды отклонённое предложение снова всплывает в следующей сессии |
Собирайте все отклонённые решения в один документ по фиксированному формату. |
| Даже если запрет записан одной строкой, его толкуют то слишком широко, то слишком узко |
В едином документе, где собраны отклонённые решения (например non_goals.md), для каждого запрета добавьте заголовок «причина» рядом с выводом. |
| Запрет записан правильно, но не соблюдается, и каждый раз приходится это обсуждать |
В документе отклонённых решений для каждого запрета добавьте заголовок «область применения» и построчно перечислите пограничные случаи, вызывающие сомнения. |
| Одна и та же инструкция, розданная нескольким sub-agent'ам, возвращается каждый раз в разной форме |
В списке задач, которые можно делегировать sub-agent'у, прямо укажите входные файлы, которые нужно подготовить перед запуском. |
| Запреты без автоматического теста накапливаются, оставаясь просто текстом |
В документе отклонённых решений добавьте в список заголовок «машинная проверка» и отмечайте для каждого пункта, существует ли соответствующий автоматический тест (Minitest). |
| Каждая работа ИИ заканчивается словами «откройте экран и проверьте» |
Подготовьте один smoke-тест на Playwright и определяйте успех не по виду экрана, а по записи, оставшейся в БД. |
| Каждый раз, когда ИИ говорит что-то чуть не то, приходится самому объяснять и исправлять |
Вместо того чтобы человек объяснял и исправлял каждое отклонение, запишите замечание в stderr hook'а (exit 2) и в сообщения об ошибках автоматических тестов, чтобы именно по этому пути оно доходило до ИИ. |
| Список отклонённых решений продолжает расти, и похоже, что однажды его перестанут читать |
Добавьте в конец документа отклонённых решений раздел «непринятые варианты» и записывайте туда отклонённые предложения. |
| Строки «обязательно выполните это» в файле инструкций никак не сокращаются |
Проверяйте автоматическим тестом, действительно ли каждая команда, помеченная в файле инструкций как «обязательно выполнить», присутствует и в pre-commit hook. |
| Даже если передать точный порядок действий, исправление приходит не в том виде |
Вместо того чтобы диктовать порядок действий, определите для каждого случая использования входные файлы, которые должны существовать перед запуском sub-agent'а. |
| Чтобы сообщить о баге, каждый раз приходится самому описывать шаги и симптомы |
Разместите форму сообщения об ошибке, где человек вводит только одно предложение с описанием симптома, а URL, историю действий и информацию о браузере собирает автоматически JavaScript. |
| Каждый раз приходится тратить усилия на то, чтобы написать «сначала дай план» |
Новая реализация не нужна. Достаточно разместить один проектный документ — ИИ прочитает существующие документы и будет следовать тому же формату. |
| Строки, которые больше всего хочется, чтобы соблюдались, написаны наиболее настойчиво, но неясно, помогает ли это |
Откажитесь от измерения эффекта — вместо этого считайте в файле инструкций строки с выделениями и добавьте автоматический тест (ratchet), который падает, когда их число превышает порог. |
| Результат работы sub-agent'а возвращается в форме, отличной от ожидаемой |
Для каждого случая использования sub-agent'а опишите в одном документе критерии приёмки результата: имя файла, формат, обязательные поля. |
| Найдя ошибку, хочется спросить с упрёком: «вы вообще это читали?» |
Вместо упрёка зафиксируйте второе предложение каждого запроса как шаблон вопроса «разве не так, что …?». |
| Ответ «нет, не так» на полученный результат не делает его лучше |
Вместо того чтобы указывать на это самому, показывайте запреты без альтернативы через PostToolUse hook вместе с diff сразу после сохранения. |
| ИИ рассказывает о содержимом файла так, будто открывал его, хотя не открывал |
Заставьте ИИ оставлять соответствующие друг другу marker'ы и в документе, на который он ссылается, и в коде, и проверяйте автоматическим тестом, что marker'ы действительно существуют. |
| ИИ снова и снова спрашивает «А или Б?», и работа стоит, пока вы решаете |
Перестаньте отвечать сразу — сделайте так, чтобы выбор определялся автоматическим тестом или hook'ом. |
| ИИ проводит ревью, но неясно, что остаётся вне поля зрения |
Используйте внешний автоматический тест, который считает количество, чтобы выявлять автоматические тесты, сканирующие файлы, но не имеющие нижней границы (assert_operator ... :>=). |
| Скриншоты продолжают накапливаться, но непонятно, какой из них что именно подтверждает |
Перед проверкой экрана требуйте ответ на два вопроса — «что проверяется» и «почему не хватит более дешёвого способа», — и держите памятку на одну страницу о том, что сначала пробуют самый дешёвый вариант в порядке: unit-тест → интеграционный тест → E2E. |
| Шаг с обязательной записью введён, но невозможно посчитать, сколько запусков его пропустило |
Перед скриншотом или E2E пусть будет записан файл-декларация о том, что именно проверяется (например tmp/visual_verification.md); сделайте его наличие условием запуска PreToolUse hook, чтобы без него скриншот или E2E не запускались. |
| Один и тот же тест запускается снова, хотя код не менялся, и приходится ждать заново |
Добавьте в обёрточный скрипт тестов опцию --last, которая показывает предыдущий лог, чтобы повторный запуск не требовался. |
| Ничего не сломано, а вылезает целый ряд незнакомых ошибок |
Пусть обёрточный скрипт тестов берёт эксклюзивную блокировку (используя атомарность mkdir) и не запускается, если не смог её получить. |
| В отчёте «тесты проходят» не сказано, какая часть вообще не запускалась |
Помечайте тяжёлые E2E-тесты тегами по областям, пропускайте их по умолчанию и каждый раз выводите список областей, которые не запускались. |
| Нельзя потом понять, была ли на самом деле соблюдена инструкция, задающая порядок действий |
Если нужно, чтобы порядок действий соблюдался, не усиливайте формулировку инструкции — вместо этого сделайте так, чтобы следование порядку оставляло след в результате (например, выводите по одной строке на каждый открытый файл). |
| Установленный обёрточный скрипт со временем снова заменяют на голую команду |
Если нужно, чтобы использовался обёрточный скрипт, не усиливайте инструкцию — проверьте, не осталась ли причина возвращаться к голой команде, то есть не хватает ли обёртке какой-то возможности. |
| На один и тот же вопрос каждый раз приходит разный ответ, а при сведении в одно что-то теряется |
Перед тем как объединять несколько ответов в один, выводите, сколько раз встретился каждый тип замечания — сколько из скольких его упомянули. |
| Непонятно, сработала ли строка вида «сделайте X, если нужно» |
Не пишите условные инструкции вида «сделайте X, если нужно» — вместо этого принудительно требуйте этот шаг через hook, который не даёт продолжить без него. |
| Просьба «подумайте ещё раз» меняет ответ, но неясно, действительно ли ИИ убедился |
Вместо того чтобы возвращать со словами «подумайте ещё раз», конкретно укажите, какая посылка неверна. |
| После фразы «не гадайте» ИИ стал возвращаться, вообще ничего не создав |
Не передавайте только запрет — добавьте к нему запасной вариант вывода, например: «если ничего не подходит, выведите “не применимо”». |
| Чем дольше продолжается удачно идущий диалог, тем больше усилий уходит на проверку |
Завершайте сессию на границе задачи и начинайте следующую задачу в новой сессии. |
| Все результаты работы верны, но накапливаются потери, которые в них не отражены |
Когда результаты готовы, один раз прогоните скрипт, который подводит итог по самому логу работы (transcript). |
| Заметки со знаниями, оставленные для следующего, расходятся с реальностью и устаревают |
Не оставляйте знание в документе — встраивайте его в сообщение об ошибке автоматического теста или в сообщение об остановке hook'а, чтобы оно появлялось именно в нужный момент. |
| Копание в причине продолжается, и чтение идёт даже после того, как ответ уже найден |
Посчитайте по логу работы серии чтений подряд, которые ничего не изменили, и запишите одной строкой условие остановки перед началом копания. |
| Самая дешёвая по цене модель делается моделью по умолчанию без проверки, подходит ли она задаче |
Передайте одну и ту же задачу и дешёвой, и дорогой модели и решайте только после того, как отдельно посчитаете число шагов до завершения и объём заново прочитанного, переиспользованного (cache read) и написанного. |
| Если что-то не работает, вместо механизма чинят, повышая модель |
Передайте одну и ту же задачу и более дорогой, и более дешёвой модели, и превратите места, где падает только дешёвая, в постоянную проверку. |
| Исследование, которое основная сессия могла бы завершить сама, на всякий случай передают sub-agent'у |
Перед передачей проверьте, есть ли этот контекст уже у родительского агента. Если есть — продолжайте в родительском агенте; передавайте sub-agent'у только большой объём чтения, которого у него ещё нет. |
| По умолчанию работу делят на четыре части и запускают всё одновременно, просто на всякий случай |
Давайте одному sub-agent'у не больше, чем он может вернуть за один ответ. Цену определяет не число sub-agent'ов, а сколько раз каждый выделенный sub-agent ходит туда-обратно к родительскому агенту. |
| «Посмотрите ещё и на это» вставляют извне посреди работы |
Дождитесь естественной границы работы, а затем вносите дополнительный запрос с суженной областью. Спрашивая у самого ИИ о пробелах, всегда добавляйте: «если всё достаточно, прямо так и напишите». Это даёт ему выход (escape hatch), чтобы не выдумывать пробел. |
| Выбор модели пытаются сделать через прямое сравнение |
Перед тем как начать сравнивать модели, посчитайте, скольким hook'ам или автоматическим тестам равны затраты на это сравнение. Если механизмов, которые можно описать явно, больше, чем это число, сначала внедрите их. |
| Фразой «разницы не было» пытаются свернуть проверку |
Перед тем как сворачивать со словами «разницы не было», посчитайте две вещи: если какие-то результаты исключили из подсчёта (например, упавших sub-agent'ов) — верните их и пересчитайте; если у более чем половины пунктов ноль при всех условиях — переформулируйте задачу и измерьте заново. |
Оглавление всех статей
По каждой серии — от введения до заключительной части.
はじめに —— 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話