Разработчики жалуются, что AI повторяет одни и те же ошибки. «Я уже пять раз объяснял, что у нас нет Redux». «Он снова предлагает FTP вместо очереди». «Забывает про наш стиль именования».
Это не баг модели. Это отсутствие инженерии.
Почему агент «не учится»
Каждая новая сессия агента — чистый лист. Модель не помнит предыдущих разговоров. Всё, что она знает о вашем проекте — это то, что вы положили в контекст. Если не положили ничего специфичного — получите среднюю температуру по интернету.
Без доменного контекста агент опирается на массив обучающих данных, где production-grade архитектурные решения встречаются в разы реже, чем туториалы для начинающих. Результат: FTP вместо event-driven, глобальный стейт вместо локального, переименование переменных по паттерну «camelCase» там, где у вас давно snake_case.
Проблема не в том, что AI «не учится». Проблема в том, что никто не дал ему, чему учиться.
Механика: два файла
Любой агент, который автоматически подтягивает файл правил в контекст каждой сессии, можно превратить в накапливающую систему двумя строками.
Для Claude Code это CLAUDE.md. Для Cursor — .cursorrules или .mdc-файлы. Принцип одинаковый: инструкции в репозитории загружаются агентом автоматически при каждом запуске.
Добавить в файл правил две строки:
- Если принял решение, которое оказалось правильным и стоило усилий — запиши в decisions.md (паттерн + почему сработало, не более 3 предложений).
- Если допустил ошибку, которая привела к проблеме — определи корневую причину (не симптом) и запиши в mistakes.md.Вот и всё. Два текстовых файла в корне проекта.
С первой же сессии агент начинает пополнять оба файла. Каждая следующая сессия открывается с ними в контексте. Агент видит, что в этом проекте:
- dual write запрещён (и почему),
- Redis-кеш не подходит для этого типа данных,
- в прошлый раз так сделали — упало вот это.
Ошибки перестают повторяться — в инструмент закодирован доменный контекст, которого по умолчанию нет ни у одной модели.
Принцип, который за этим стоит
Есть правило, которое я проверял в разных контекстах — от AI-enablement в Askona, где я проводил воркшопы для 100–200 инженеров за сессию, до небольших командных проектов: правило, которого нет в инструменте, не соблюдается.
Встреча раз в квартал не помогает, документ в Confluence — тоже. Работает только то, что агент читает при каждом запуске. Документ, который никто не открывает, не существует для AI так же, как не существует для людей.
Это же правило работает в более сложных setup'ах. В репозитории github.com/dobryakov/cursor-rules — архитектурные стандарты как .mdc-файлы в git. Новый разработчик в команде наследует те же guardrail'ы с первого коммита, не с третьего месяца. AI-ассистент не предложит нарушить ни одно архитектурное правило, потому что оно у него в контексте, а не в корпоративной вики. Именно оттуда и вырос паттерн decisions/mistakes — как облегчённая версия того же подхода для личных и небольших командных проектов.
Failure modes
Паттерн прост. Но есть несколько мест, где он ломается, если не предусмотреть их заранее.
Файлы растут бесконтрольно. Без ограничения формата через несколько месяцев mistakes.md превращается в 300 строк, где 200 — вариации одного корневого паттерна. Решение: ограничить запись — не более 3 предложений, корневые причины не дублировать, не писать симптомы («была ошибка с API»), только механизм провала.
Корневая причина не определена. Агент пишет «была ошибка при работе с API» — это симптом, не причина. Причина: «попытка читать из Redis до завершения инициализации соединения». Добавить в инструкцию явное требование: корневая причина = конкретный технический механизм, не описание симптома.
Контекстное окно съедается. Если оба файла большие, они конкурируют с рабочим кодом за место в контексте. Решение: периодически просить агента сжать файлы, оставив только уникальные паттерны. Одна корневая причина — одна запись, независимо от количества случаев.
Записи устаревают после рефакторинга. После смены стека часть entries описывает уже несуществующую реальность. Добавить метку даты к каждой записи — устаревшие видны сразу при ревью.
Масштаб
Паттерн не ограничен личными проектами.
Личный проект: один файл CLAUDE.md, два файла памяти. Агент помнит, что вы уже пробовали, что не зашло, какой паттерн у вас «правильный».
Команда: файлы в git — decisions.md и mistakes.md как командный артефакт. Новый разработчик получает накопленный опыт с клонированием репозитория. Агент у каждого члена команды работает с одинаковым доменным контекстом.
Enterprise: модульная структура — отдельные .mdc-файлы по доменам (архитектура, безопасность, стиль API), decisions/mistakes разбиты по сервисам или командам. При этом механика та же — файлы в репозитории, автозагрузка в контекст.
Почему RAG здесь лишний
При слове «memory для агента» обычно начинается разговор о векторных базах, RAG-пайплайнах и fine-tuning'е. Всё это рабочее — но для большинства проектов оверинжиниринг.
RAG нужен, когда документов тысячи и нужна семантическая фильтрация — не всё в контекст, только релевантное. Decisions.md нужен, когда паттернов десятки и все они должны быть в контексте всегда. Это разные задачи.
Когда файл правил помещается в контекстное окно полностью — простое текстовое хранилище эффективнее и надёжнее RAG. Нет embedding-дрейфа, нет версионирования индекса, нет задержки на поиск. Просто markdown, который агент читает целиком при старте.
Паттерн работает с любым агентом, который автоматически подтягивает правила в контекст сессии. Конкретные пути под ваш инструмент — выбирайте сами. Механика одна.