MISTAKES.md и Claude Code: как превратить повторную ошибку в правило
Как вести журнал MISTAKES.md для Claude Code: фиксация сбоев, изоляция секретов, порог повторяемости и превращение ошибок в проектные правила и тесты.
Содержание
MISTAKES.md и Claude Code: как превратить повторную ошибку в правило
Когда вы работаете с Claude Code в сложном проекте, агент неизбежно сталкивается с неочевидными ограничениями окружения: устаревшими типами, скрытыми зависимостями или спецификой сборщика. Если каждый раз исправлять ошибку заново в диалоге, тратится контекст и время. Но попытка скормить агенту многостраничный лог сессии или надеяться на «память модели» приводит к шуму и потере фокуса.
Рабочее решение — вести компактный файл MISTAKES.md в корне репозитория. В нём фиксируются только повторяемые сбои, проверенные причины и правила предотвращения, которые затем переходят в проектные тесты и конфигурацию.
1. Отличие MISTAKES.md от лога сессии
Не путайте журнал ошибок с дампом терминала:
| Параметр | Лог сессии (Transcript) | Журнал MISTAKES.md |
|---|---|---|
| Объём | Тысячи строк диалога и промежуточных команд | 5–10 строк на инцидент |
| Назначение | Аудит конкретного прогона | База прецедентов для предотвращения сбоев |
| Хранение секретов | Может содержать токены (требует чистки) | Строго запрещено: ключи и токены исключаются |
| Срок жизни | Временный артефакт | Постоянная часть документации до автоматизации |
MISTAKES.md должен оставаться лаконичным, чтобы агент мог прочесть его в начале сессии без перегрузки контекстного окна.
2. Структура записи об ошибке
Каждая запись состоит из четырёх обязательных полей:
- Факт (Incident): что именно сломалось и при каких условиях (код ошибки, команда).
- Влияние (Impact): к чему это привело (остановка сборки, порча миграции).
- Причина (Root Cause): подтверждённый источник проблемы. Если точная причина ещё не доказана, она явно маркируется как
[Гипотеза]. - Предотвращение (Prevention): конкретное действие, исключающее рецидив.
Пример записи
### ERR-014: Падение миграции PostgreSQL при DROP COLUMN без CASCADE
- **Факт**: Claude Code выполнил `ALTER TABLE orders DROP COLUMN customer_ref;` в migration 0042.
- **Влияние**: Сбой деплоя в staging из-за зависимого view `v_active_orders`.
- **Причина**: В проекте используются представления поверх базовых таблиц, требующие каскадного обновления или предварительного пересоздания view.
- **Предотвращение**: Все DDL-миграции с удалением колонок должны проверять зависимые представления через `pg_depend` перед выполнением.[!IMPORTANT] Изоляция секретов: Никогда не помещайте в
MISTAKES.mdреальные строки подключения, приватные ключи, токены или фрагменты.env. Собственный API Key для Claude Code настраивается в локальном окружении и не должен попадать в репозиторий.
Для надёжной интеграции Claude Code с кастомным API-провайдером используйте собственный Key и актуальную инструкцию BetterToken для Claude Code: https://docs.bettertoken.ai/ai-tools/claude-code.
3. Критерии перехода: из записи в правило или тест
Не каждая разовая опечатка заслуживает постоянной строчки в правилах. Превращайте запись в автоматизированный барьер по следующей схеме:
graph TD
A[Инцидент произошёл] --> B{Ошибка повторилась > 1 раза?}
B -- Нет --> C[Оставить запись в MISTAKES.md для наблюдения]
B -- Да --> D{Можно покрыть тестом или linter?}
D -- Да --> E[Добавить unit-тест / ESLint-правило / pre-commit hook]
D -- Нет --> F[Добавить строгое правило в CLAUDE.md / AGENTS.md]
E --> G[Удалить или архивировать запись в MISTAKES.md]
F --> G- Первый случай: добавляем короткую запись в
MISTAKES.md. - Второй случай (рецидив): если ошибку можно поймать механически, пишем linter-правило или автотест. Это надёжнее текстовых инструкций.
- Если механический контроль невозможен: формулируем негативное правило в
CLAUDE.md(например: «Никогда не запускать jest без флага —runInBand в CI»). - Архивация: как только внедрён тест или hook, запись из активного
MISTAKES.mdудаляется, чтобы файл не разрастался.
4. Проверка на следующей задаче
Чтобы убедиться, что правило работает:
- Запустите новую чистую сессию Claude Code.
- Дайте агенту схожую задачу, провоцирующую ранее зафиксированную ошибку.
- Проверьте, обращается ли агент к инструкциям и соблюдает ли запрет.
- Если агент снова нарушает правило, ужесточите формулировку в
CLAUDE.mdили сделайте проверку обязательным pre-commit hook.
Такой цикл обратной связи превращает случайные сбои в надёжный каркас инженерных стандартов проекта.
Оплата и пополнение баланса
Пополнение баланса и оплата API осуществляются в личном кабинете BetterToken. Платформа поддерживает удобные способы оплаты, мгновенное зачисление средств и единый баланс для всех доступных моделей.
Пример числового расчёта и тарифы
По состоянию на 15 августа 2026 года в каталоге цен BetterToken базовые ставки составляют:
- Вход: $3.00 за 1M токенов;
- Выход: $15.00 за 1M токенов;
- Чтение из кэша (cache read): $0.30 за 1M токенов.
Для типового запроса на 100 000 входных и 10 000 выходных токенов без кэша итоговая стоимость составит: 0.1 × $3.00 + 0.01 × $15.00 = $0.45.
