Разработчики часто сталкиваются с тем, что ИИ-агенты при работе над кодом систематически совершают одни и те же ошибки. Исправления в текущем сеансе часто не помогают: после перезагрузки агент забывает прошлые наставления, так как обучение агента при выводе (inference) не меняет базовую модель, а лишь добавляет контекст к диалогу. Попытки внести правки в общие инструкции (например, AGENTS.md) решают проблему лишь частично, так как при увеличении контекста важные правила могут теряться, а файл с инструкциями рискует стать слишком громоздким для эффективного анализа.
Организация базы знаний для предотвращения ошибок
Эффективным решением стала реализация MISTAKES.md — специализированного файла, который содержит записи о зафиксированных сбоях и методах их исправления. В отличие от общих инструкций, этот файл служит своего рода проекто-зависимым реестром прошлых неудач. Суть метода заключается в принудительном чтении этого файла агентом перед началом планирования или внесением изменений в код.
Структура и ведение записей в MISTAKES.md
Для поддержания актуальности базы данных используется компактный шаблон. Запись об ошибке должна состоять из нескольких критически важных полей:
- Краткое описание ошибки: что именно сделал агент неправильно.
- Первопричина: какое решение привело к сбою.
- Предотвращение: конкретное правило для применения в будущем.
- Верификация: способ подтверждения того, что ошибка была успешно устранена.
Автор методики рекомендует придерживаться строгого формата: сохранять записи краткими, объединять повторяющиеся инциденты и игнорировать случайные технические неполадки, такие как сбои сети или мелкие опечатки. Важно избегать общих рекомендаций типа «пиши чистый код», так как они не дают модели четких инструкций для принятия специфических решений.
Автоматизация процесса чтения исправлений
Чтобы MISTAKES.md работал эффективно, агент должен обращаться к нему до начала активной работы. В случае использования Claude Code это можно автоматизировать с помощью хуков (hooks). Хук — это небольшой сценарий, который выполняется автоматически при достижении определенного этапа в рабочем процессе агента, например, при запуске сессии или её возобновлении.
При настройке хука SessionStart система проверяет наличие файла MISTAKES.md и принудительно считывает его содержимое. Полученные данные добавляются в контекст модели до обработки первого пользовательского промпта. Важным преимуществом такого подхода является то, что хуки работают независимо от того, решает ли агент выполнить действие самостоятельно; они исполняются «обвязкой» (agent harness) при наступлении заданного события. Аналогичные механизмы жизненного цикла существуют во многих современных системах для работы с ИИ-агентами, что делает этот подход масштабируемым инструментом для повышения качества разработки.
Почему исправления в текущем сеансе — это тупик
Проблема заключается в самой природе работы LLM. Когда вы даете агенту корректирующую инструкцию, вы не модифицируете веса базовой модели. Агент использует модель на этапе инференса (вывода), поэтому ваша правка становится лишь дополнительным фрагментом контекста. Как только сессия завершается и начинается новая, весь накопленный контекст сбрасывается. Если информация не была сохранена во внешнем хранилище и не извлечена оттуда при следующем запуске, агент «забывает» всё, что вы обсуждали.
Файл `AGENTS.md` частично решает вопрос персистентности (устойчивости) инструкций, но он не может принудительно внедрить их в процесс принятия решений. Например, Codex загружает содержимое такого файла в качестве сообщения с ролью `user`. Модель видит эти правила наряду с вашим промптом и текущими данными, однако наличие правила не делает запрещенное действие физически невозможным. Правило в `AGENTS.md` лишь влияет на вероятности выбора модели, но не гарантирует соблюдение запрета.
Кроме того, по мере роста проекта возникает «эффект потери контекста»: модели работают менее надежно, когда критически важная информация оказывается погребена в середине длинного массива данных. Постоянное добавление исходного кода и логов выполнения команд в контекст приводит к тому, что важные проектные правила уходят на второй план. Если вы будете вносить каждую правку в `AGENTS.md`, вы лишь ускорите процесс превращения инструкций в громоздкий массив текста, который модели всё труднее анализировать.
Философия MISTAKES.md: обучение на ошибках
Если вы используете такие инструменты, как Claude Code, вы можете применять хуки, чтобы заставить агента вернуться к проверке своего вывода. Однако такой пересмотр ограничен рамками текущей сессии и не сохраняет понимание причин провала для будущего. Чтобы предотвратить повторение одной и той же ошибки через неделю, вы должны внедрить урок в контекст модели *до того*, как она выберет подход к задаче. Именно здесь на помощь приходит `MISTAKES.md`.
Это проектно-специфичный реестр подтвержденных ошибок. Каждая запись не просто констатирует факт сбоя, а идентифицирует конкретное решение, которое к нему привело. Это позволяет модели сопоставить текущую ситуацию с прошлым негативным опытом.
Шаблон записи в MISTAKES.md
Для ведения лога рекомендуется использовать следующий формат (в качестве отправной точки):
«`markdown
# MISTAKES.md
Review relevant entries before planning or editing code.
Add an entry after a confirmed mistake or user correction.
Keep entries short, specific, and project-related.
Merge repeated mistakes instead of creating duplicates.
Do not record transient tool failures or unverified guesses.
## Entry format
### [YYYY-MM-DD] [Short title]
**Mistake:** [What the agent did wrong]
**Root cause:** [Why the decision failed]
**Prevention:** [The rule to apply next time]
**Verification:** [How to confirm the mistake was avoided]
«`
Ключевыми полями являются «Первопричина» и «Предотвращение». Запись о том, что агент «сломал аутентификацию», бесполезна без объяснения того, какое именно решение привело к сбою. Правило предотвращения должно формулировать верный подход в терминах, которые агент может применить непосредственно в своем рабочем цикле.
Техническая реализация и роль хуков
Чтобы система работала, недостаточно просто создать файл — агент обязан его прочитать до принятия любых решений. Автор метода реализовал это, добавив инструкцию в `AGENTS.md`, обязывающую агента просматривать реестр ошибок перед планированием или редактированием кода. В экосистеме Claude Code файл `AGENTS.md` импортируется через `CLAUDE.md`.
Автоматизация обеспечивается через хук `SessionStart`. Каждый раз, когда Claude запускает новую сессию или возобновляет работу с существующей, выполняется небольшой скрипт, который проверяет наличие `MISTAKES.md` и считывает его содержимое. Вывод этого скрипта добавляется в контекст модели до обработки первого промпта пользователя. Важно, что этот же хук срабатывает повторно после того, как контекст «сжимается» (compacted), что гарантирует сохранение записей даже в ходе длительных и сложных задач.
Хуки — это не просто удобная надстройка, это механизм, работающий на уровне «обвязки» агента. В отличие от инструкций в промпте, агент не принимает решения, запускать ли хук или игнорировать его. Harness (каркас) агента исполняет его принудительно при наступлении события. Несмотря на то что термин «хуки» часто встречается в контексте Claude Code, этот функционал не является эксклюзивным. Жизненные циклы (lifecycle hooks) — общепринятая практика в архитектуре ИИ-агентов, хотя названия, триггеры и способы конфигурации могут различаться в зависимости от конкретного инструментария.
