AI Coding

MISTAKES.md и Claude Code: как превратить повторную ошибку в правило

Как вести журнал MISTAKES.md для Claude Code: фиксация сбоев, изоляция секретов, порог повторяемости и превращение ошибок в проектные правила и тесты.

BT

BetterToken

Редакция
4 мин чтения

Когда вы работаете с Claude Code в сложном проекте, агент неизбежно сталкивается с неочевидными ограничениями окружения: устаревшими типами, скрытыми зависимостями или спецификой сборщика. Если каждый раз исправлять ошибку заново в диалоге, тратится контекст и время. Но попытка скормить агенту многостраничный лог сессии или надеяться на «память модели» приводит к шуму и потере фокуса.

Рабочее решение — вести компактный файл MISTAKES.md в корне репозитория. В нём фиксируются только повторяемые сбои, проверенные причины и правила предотвращения, которые затем переходят в проектные тесты и конфигурацию.

1. Отличие MISTAKES.md от лога сессии

Не путайте журнал ошибок с дампом терминала:

ПараметрЛог сессии (Transcript)Журнал MISTAKES.md
ОбъёмТысячи строк диалога и промежуточных команд5–10 строк на инцидент
НазначениеАудит конкретного прогонаБаза прецедентов для предотвращения сбоев
Хранение секретовМожет содержать токены (требует чистки)Строго запрещено: ключи и токены исключаются
Срок жизниВременный артефактПостоянная часть документации до автоматизации

MISTAKES.md должен оставаться лаконичным, чтобы агент мог прочесть его в начале сессии без перегрузки контекстного окна.

2. Структура записи об ошибке

Каждая запись состоит из четырёх обязательных полей:

  1. Факт (Incident): что именно сломалось и при каких условиях (код ошибки, команда).
  2. Влияние (Impact): к чему это привело (остановка сборки, порча миграции).
  3. Причина (Root Cause): подтверждённый источник проблемы. Если точная причина ещё не доказана, она явно маркируется как [Гипотеза].
  4. Предотвращение (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?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-101&utm_content=mistakes-md-claude-code-workflow](https://docs.bettertoken.ai/ai-tools/claude-code?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-099&utm_content=mistakes-md-claude-code-workflow).

---

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

Нет

Да

Да

Нет

Инцидент произошёл

Ошибка повторилась > 1 раза?

Оставить запись в MISTAKES.md для наблюдения

Можно покрыть тестом или linter?

Добавить unit-тест / ESLint-правило / pre-commit hook

Добавить строгое правило в CLAUDE.md / AGENTS.md

Удалить или архивировать запись в MISTAKES.md

  1. Первый случай: добавляем короткую запись в MISTAKES.md.
  2. Второй случай (рецидив): если ошибку можно поймать механически, пишем linter-правило или автотест. Это надёжнее текстовых инструкций.
  3. Если механический контроль невозможен: формулируем негативное правило в CLAUDE.md (например: «Никогда не запускать jest без флага --runInBand в CI»).
  4. Архивация: как только внедрён тест или hook, запись из активного MISTAKES.md удаляется, чтобы файл не разрастался.

4. Проверка на следующей задаче

Чтобы убедиться, что правило работает:

  1. Запустите новую чистую сессию Claude Code.
  2. Дайте агенту схожую задачу, провоцирующую ранее зафиксированную ошибку.
  3. Проверьте, обращается ли агент к инструкциям и соблюдает ли запрет.
  4. Если агент снова нарушает правило, ужесточите формулировку в 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.

Читайте также

Готовы оптимизировать LLM workflow?

Подключите единый API, управляйте ключами и контролируйте расходы на AI-модели в BetterToken.