Когда вы пишете свой код, вы — автор, ревьюер и тимлид. Но если вы работаете в одиночку, документация для вашего AI-помощника (будь то Claude, GPT-4 или Gemini) устаревает быстрее, чем сам код. Это не баг модели. Это документационный долг, и он стоит вам не только времени, но и реальных денег за токены.

Почему Claude Code «забывает» всё после сессии?

Большинство разработчиков сталкиваются с тем, что AI-помощник, который отлично пишет код, начинает принимать устаревшие решения, когда речь заходит о деталях проекта: старые версии баз данных, несуществующие функции или неактуальные ограничения по длине текста.

Проблема не в том, что Claude не обладает знаниями; проблема в том, что он не имеет долгосрочной памяти о вашем проекте. Каждая новая сессия — это новый старт, и его единственным источником истины становится ваш CLAUDE.md или STATE.md.

Если в этом документе есть расхождение с кодом, модель не паникует. Она просто действует с идеальной уверенностью, как будто то, что написано в файле, является абсолютной, непреложной правдой.

Помни: Чем дольше живет проект, тем выше цена ошибки. И эту цену вы платите из своего кармана — не только токенами, но и временем на исправление «галюцинаций».

Три типа документационного долга, которые ломают AI-помощь

Чтобы справиться с этой проблемой, нужно перестать думать о документации как об артефакте, который нужно написать один раз. Это должен стать процесс.

Я выделил три типа документационного долга, которые различаются по сложности обнаружения:

1. «Документ не успевает за кодом» (Самый частый)

Это самый простой, но самый назойливый тип долга. Вы переименовали функцию validate_post_length в validate_content_limit, а в README.md или в промпте для Claude всё ещё написано старое имя.

Как ловить: Автоматизация. Вам нужен парсер, который собирает все упоминания функций, переменных и эндпоинтов из вашей документации и сравнивает их с реальными определениями в кодовой базе.

Что можно сделать вручную (быстро): Прогоните grep по всем файлам документации, ищите все упоминания функций, которые вы недавно рефакторили.

```bash

Пример поиска устаревших имен в markdown-файлах

grep -r "старое_имя_функции" ./docs/ ```

2. «Документ врет сам себе» (Самый коварный)

Это конфликт между разными частями документации. Например, в ARCHITECTURE.md указано, что сервис должен принимать данные длиной 2400 знаков, а в API.md — 4000 знаков. Ни один из этих фактов не «устарел» формально, они просто конфликтуют.

Как ловить: Проверка согласованности. Создайте единый «источник правды» (Source of Truth), куда должны вносить данные только конкретные, ответственные люди (даже если это только вы сами).

3. «Документация отсутствует» (Самый дорогой)

Это не долг, а просто отсутствие критически важного контекста. Например, вы переехали с SQLite на Postgres, но нигде об этом не упомянули. Для Claude это значит, что он должен работать с SQLite, и любая попытка миграции или запроса будет ошибочной.

Как ловить: Чек-лист критических изменений. Каждый раз, когда вы меняете слой данных (DB, API-интерфейс, шифрование), вы должны немедленно обновить специальный файл, например, STATE.md.

Процесс, который заменяет код-ревью для соло-разработчика

Я понял, что полагаться на память или на одноразовую чистку невозможно. Нужен процесс. Я использую подход «Двух слоев и двух сессий», который позволяет поддерживать документацию в режиме реального времени.

💡 Этап 1: Поддержка «Источника правды» (Source of Truth)

Вместо одного гигантского CLAUDE.md, разделите контекст на три файла:

1. `ARCHITECTURE.md`: Высокоуровневая схема (что, зачем, как взаимодействуют системы). Изменяется редко.
2. `STATE.md`: Фактические, технические ограничения. Здесь только цифры, версии, типы данных. (Например: DB: Postgres 16.2, Max_length: 4000, Auth: JWT v2).
3. `CURRENT_TASK.md`: Контекст текущей сессии. Здесь описывается только задача, которую вы решаете прямо сейчас.

💡 Этап 2: Правило «Протоколирование изменений»

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

Пошаговый рабочий процесс:

1. Планирование: Перед тем как писать фичу, откройте STATE.md и запишите: «Я собираюсь изменить Max_length с X на Y. Я обновил схему БД».
2. Реализация (Код): Пишите код.
3. Протоколирование (Документация): После того как код работает и вы сделали коммит, вы не просто «забываете» обновить доки. Вы возвращаетесь к STATE.md и вносите явное, структурированное обновление:

```markdown

[ПРИМЕЧАНИЕ: 2026-05-25]

Изменено: Максимальная длина контента. Было: 2400 знаков. Стало: 4000 знаков. Причина: Требование клиента X. ```

💡 Этап 3: Ограничение контекста при вызове AI

Никогда не кидайте в Claude весь проект. Всегда подавайте ему только необходимый, актуальный контекст:

1. Системный промпт: Обязательно включайте в него ссылки на STATE.md и ARCHITECTURE.md.
2. Фрагмент кода: Всегда выделяйте конкретный блок кода, который вы хотите, чтобы AI изменил, и прикрепляйте к нему соответствующий фрагмент из документации.

```

Промпт для Claude:

Ты — опытный Backend-разработчик, работающий над проектом, который использует PostgreSQL 16.2. Обрати внимание, что максимальная длина текста для статьи составляет 4000 знаков. Тебе нужно доработать функцию process_article_data. Используй только следующий код и следуй правилам, изложенным в STATE.md.

[Вставить STATE.md]

[Вставить код функции] ```

Подводные камни: Где это ломается

1. Иллюзия полноты: Самый большой соблазн — думать, что достаточно просто добавить пару абзацев. На самом деле, нужно обновлять все критические точки: версии пакетов, ограничения по данным, и архитектурные решения.
2. Сложность автоматизации: Написание идеального парсера, который сравнивает код и доки, — это проект сам по себе. Начните с ручных, но обязательных чек-листов.
3. Усталость: В конце дня вы устанете от процесса обновления документации. Сделайте это обязательной частью коммита. Нельзя коммитить код, не обновив STATE.md.

Что попробовать дальше

• Скрипт валидации: Напишите простой скрипт (например, на Python), который проходит по всем вашим *.md файлам и ищет упоминания функций/классов, которые были удалены или переименованы в последних коммитах.
• AI-аудитор: Используйте саму LLM, чтобы провести ревью документации. Задайте ей промпт: «Я только что обновил функцию X. Проверь, пожалуйста, все упоминания X в этой документации и исправь все устаревшие ссылки». Это сэкономит вам время и заставит модель работать на вашу дисциплину.

Источники

• Habr AI: Когда Claude Code ошибается не по своей вине: документационный долг в соло-проектах