Claude Code забывает всё после сессии — 5 способов заставить его вести документацию за вас

Claude Code забывает всё после сессии — 5 способов заставить его вести документацию за вас

Каждая новая сессия Claude Code — это чистый лист. Модель не помнит, какой файл вы редактировали вчера, как называется таблица в базе и почему тот endpoint написан именно так. На маленьком pet-проекте это терпимо. На продакшен-платформе с 135 таблицами и 80 страницами — это баги, которые стоят по 15–30 минут отладки каждый.

TL;DR: Пять подходов к тому, чтобы Claude Code перестал угадывать структуру проекта и начал поддерживать документацию сам: два живых markdown-файла, паттерн Document & Clear, трёхфайловая система для задач, автообновление через GitHub Actions и поиск по истории команд вместо ручного ведения доков.

Проблема: амнезия между сессиями

Разработчик с Reddit описал типичный сценарий: он работает на healthcare SaaS-платформе — 135 таблиц, 60+ файлов с API-роутами, 15 клиентов в продакшене. Claude Code раз за разом:

• Редактировал мёртвый файл на 41 КБ вместо актуального (одна фича, разные имена файлов)
• Ссылался на device_readings в SQL-запросах — такой таблицы не существует, правильная называется vital_signs
• Придумывал имена колонок, не проверяя схему базы

Каждый такой промах — это 15–30 минут отладки. На healthcare-платформе это ещё и вопрос безопасности.

CLAUDE.md решает часть проблемы — Claude Code читает его в начале каждой сессии. Но если проект большой, запихнуть в один файл всю нужную информацию невозможно: по рекомендациям Anthropic, каждая строка в CLAUDE.md съедает токены при каждом API-вызове. Один из разработчиков в GitHub-репозитории best practices советует держать его под 200 строк.

Нужен механизм, при котором Claude Code сам поддерживает актуальную документацию и обращается к ней по необходимости.

Способ 1: два живых markdown-файла

Самый надёжный подход, проверенный на реальном продакшене. Идея: создать два отдельных документа — детальный справочник и компактный гайд — и научить Claude Code обновлять их после каждой задачи.

Шаг 1 — сгенерировать скелет автоматически

Указываете Claude Code на ключевые файлы проекта — App.tsx (фронтенд-роуты), server.js (бэкенд-маршруты), навигационные компоненты — и просите:

Проанализируй эти файлы и создай ROUTE_REFERENCE.md — полный справочник
всех страниц с компонентами, API-эндпоинтами, таблицами БД и правами доступа.

Через 7 минут получается файл на ~2000 строк, где каждая страница описана так: путь → компонент → бэкенд-эндпоинт → таблицы БД → уровень доступа. Сгенерировано из кода, а не написано вручную — потому что Claude Code находит маршруты, о которых вы сами забыли.

Шаг 2 — добавить контекст, который код не расскажет

Автоматически сгенерированный скелет знает структуру, но не знает историю. Создаёте второй файл — SYSTEM_DOCS.md (~600 строк) — и добавляете:

• Архитектуру аутентификации (как реально работает auth-модель)
• Известные баги с приоритетами
• Статус data cleanup (что починено, что ждёт)
• Лог недавних изменений
• TODO из security-аудита

Шаг 3 — подключить к Claude Code

В CLAUDE.md добавляете ссылки:

## Документация проекта
- Перед началом работы прочитай @ROUTE_REFERENCE.md для структуры маршрутов
- Прочитай @SYSTEM_DOCS.md для контекста, багов и архитектурных решений
- После завершения задачи обнови соответствующие секции в обоих файлах
- Заполни поле "Last audited: YYYY-MM-DD" для каждой обновлённой секции

Дополнительно создаёте кастомную команду .claude/commands/hey-claude.md, которая запускается перед каждой задачей и напоминает Claude Code прочитать доки.

Шаг 4 — git-трекать оба файла

Оба документа попадают в git — и автоматически разворачиваются на dev и production серверах через обычный деплой. Никакой ручной синхронизации.

Результат

Каждая задача теперь идёт по циклу: Claude Code читает доки → знает, какой файл редактировать и какую таблицу использовать → делает фичу → обновляет доки с датой проверки. Документация становится точнее с каждой сессией, а не гниёт в репозитории. По словам автора, за две недели после настройки — ни одного инцидента с «неправильным файлом» или «несуществующей таблицей».

Время на настройку: ~2 часа (в основном ревью автоматически сгенерированного скелета).

Способ 2: Document & Clear

Если ваша задача укладывается в одну сессию, но сессия слишком длинная — классический паттерн из сборника best practices:

1. Claude Code пишет прогресс в .md файл
2. Вы делаете /clear для сброса контекста
3. Новая сессия начинается с чтения этого файла
4. Работа продолжается с чистым контекстом

Ключевое правило: сбрасывайте контекст на 60K токенов или 30% заполнения — не ждите лимита. По данным из анализа контекстных окон, качество ответов начинает деградировать задолго до формального лимита. Когда контекст заполнен на 90%, у модели остаётся всего ~20K токенов для reasoning — и компактизация часто проваливается.

Важный нюанс: один из разработчиков в best practices репо отмечает, что автоматический /compact ненадёжен — «opaque, error-prone, and not well-optimized». Ручной Document & Clear работает предсказуемее, потому что вы контролируете, что именно сохраняется.

Способ 3: трёхфайловая система для задач

Для мультисессионных задач — структурированный вариант Document & Clear:

~/dev/active/[task-name]/
├── [task-name]-plan.md      # Утверждённый план
├── [task-name]-context.md   # Ключевые файлы, решения
└── [task-name]-tasks.md     # Чеклист работ

Каждый файл — живой документ, который обновляется в процессе. Перед коммитом проверяете, что план актуален. Новая сессия начинается с чтения всех трёх файлов — Claude Code продолжает ровно с того места, где остановился.

Подход работает особенно хорошо для задач на несколько дней, где переключение контекста неизбежно. Один из разработчиков на LinkedIn описывает похожий подход с живым «work plan» и отмечает рост уверенности в результатах с ~50% до 80%.

Способ 4: автообновление через GitHub Actions

Если хочется убрать человека из цикла обновления доков — Claude Code + GitHub Actions. Два варианта:

PR-triggered workflow: разработчик открывает PR с изменениями кода → Actions запускает Claude Code → тот анализирует gh pr diff, находит, какие доки нужно обновить → коммитит обновления в тот же PR.

Scheduled workflow: cron-задача раз в сутки просматривает все коммиты за последние 24 часа → Claude Code собирает изменения в один PR с обновлённой документацией.

Первый вариант точнее (доки обновляются в контексте конкретного изменения), второй дешевле по токенам (один прогон вместо десятков).

Способ 5: cc-dejavu — поиск вместо ведения

Радикально другой подход: не вести документацию вообще, а искать по истории команд. cc-dejavu — инструмент, который индексирует все bash-команды, которые Claude Code когда-либо запускал, и позволяет искать по ним:

deja search rebase
# → git rebase -i HEAD~3 --autosquash
#   12/15/2025 | ~/projects/billing-api

Автор инструмента объясняет философию: «Проблема CLAUDE.md в том, что это статическое знание, которое устаревает и живёт в изолированных проектах. Deja переворачивает подход — вместо поддержки знаний Claude ищет то, что реально работало. История и есть документация».

Этот подход работает для команд и конфигураций, но не заменяет структурную документацию — он не знает, какие таблицы у вас в базе.

Подводные камни

Документация на 2000 строк съедает контекст. Каждый раз, когда Claude Code читает ROUTE_REFERENCE.md через @-ссылку, весь файл попадает в контекст. Для 2000-строчного справочника это 15–20K токенов — и они тратятся при каждом вызове. По данным из best practices, если MCP-серверы и документация вместе забирают больше 20K токенов, Claude Code начинает работать заметно хуже. Решение: вместо @-ссылки в CLAUDE.md пишите «Когда работаешь с роутами, прочитай ROUTE_REFERENCE.md» — тогда файл подгружается только по необходимости.

Claude Code уверенно заполняет доки неверной информацией. Автор оригинального поста специально предупреждает: обновление документации после задачи должно касаться только тех секций, которые относятся к выполненной работе. Если дать Claude Code обновить «заодно» другие разделы — он с абсолютной уверенностью впишет неправильные данные. DoltHub подтверждает: Claude Code «не стесняется менять тесты вместо кода» и создаёт параллельные реализации с префиксом "New", оставляя мёртвый код.

Автокомпактизация теряет контекст документации. Если сессия длинная и срабатывает auto-compact, модель может потерять именно ту часть контекста, где хранилась информация из документации. PhotoStructure описывает проблему: план-файлы после компактизации теряют критерии успеха, список prerequisite-файлов и gotchas из предыдущих сессий. Решение: важные факты дублируйте в CLAUDE.md (он не подвергается компактизации).

GitHub Actions workflow стоит денег. Каждый запуск Claude Code через API — это токены. Если в проекте 20 PR в день, PR-triggered workflow может обойтись в $5–15/день на токенах. Scheduled workflow раз в сутки будет стоить $0.50–2.

Вердикт

Из пяти подходов самый надёжный — первый (два живых markdown-файла). Он не требует инфраструктуры, работает с любым планом Claude Code и даёт кумулятивный эффект: каждая сессия делает документацию точнее. Document & Clear и трёхфайловая система — отличные дополнения для длинных задач, но не заменяют базовый справочник. GitHub Actions — для команд с бюджетом на автоматизацию. cc-dejavu — хорош для глобального поиска команд, но не решает проблему структурной амнезии.

Если проект маленький (до 20 файлов, пара таблиц) — CLAUDE.md на 50 строк закроет все потребности. Если проект реальный, с десятками таблиц и сотнями файлов — два живых документа окупятся за первый же день.

Как попробовать

1. Сгенерируйте скелет: откройте Claude Code в корне проекта и попросите Проанализируй все роуты, компоненты, API-эндпоинты и таблицы БД. Создай ROUTE_REFERENCE.md с полным маппингом

2. Создайте SYSTEM_DOCS.md с секциями: архитектура, известные баги, последние изменения, security-TODO. Добавьте контекст, который Claude Code не может вывести из кода

3. Добавьте в CLAUDE.md правило: «Перед работой прочитай SYSTEM_DOCS.md. После завершения задачи обнови соответствующие секции и заполни Last audited»

4. Закоммитьте оба файла в git — документация должна версионироваться как код

5. Попробуйте промпт для проверки:

Какой компонент отвечает за страницу /dashboard/settings?
Какие таблицы она использует? Проверь по ROUTE_REFERENCE.md.

• Официальные best practices Claude Code — что включать и не включать в CLAUDE.md
• GitHub-репо с 84 советами от сообщества — курируемая коллекция tips and tricks
• cc-dejavu — поиск по истории команд Claude Code