# Claude Code: Как не дать документации устареть от кода и перестать терять $50 в месяц на "галлюцинациях"
Каноническая страница: https://plainews.ru/posts/claude-ai-documentatsionny-dolg
Опубликовано: 2026-05-25T07:02:44.711Z

Ваш AI-помощник перестанет работать, если забыть о документационном долге. Узнайте, как поддерживать внешнюю память Claude и перестать исправлять его ошибки.
Когда вы пишете свой код, вы — автор, ревьюер и тимлид. Но если вы работаете в одиночку, документация для вашего 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 ошибается не по своей вине: документационный долг в соло-проектах