docs.md для AI-проекта: как сохранить знания, чтобы агент не забывал что уже решено

Каждая новая сессия AI-агента начинается с чистого листа. Он не помнит вчерашних решений, заново лезет изучать код, гадает про стек и повторяет ошибки, которые вы уже разбирали. Лечится это одним файлом. docs.md(в Claude Code он же CLAUDE.md) это память проекта: агент читает его в начале каждой сессии и работает как разработчик, который в теме, а не как новичок в первый день.

Ниже разберем по шагам: что класть в docs.md, а что туда тащить нельзя, как решенные проблемы превращаются в актив, чем docs.md отличается от CLAUDE.md и AGENTS.md, и главное, дадим готовый промпт, который соберет docs.md прямо из вашего кода.

TL;DR: docs.md это файл памяти AI-проекта, который агент подгружает при старте каждой сессии. Внутрь идут стек, архитектурные решения, соглашения, список решенных проблем и запреты. Держите его в пределах 200 строк, детали выносите ссылками, кладите в git и пересматривайте раз в неделю. В конце статьи промпт для генерации docs.md из существующего проекта.

Данные по командам и версиям актуальны для Claude Code и совместимых агентов на момент публикации.

Что такое docs.md и почему агент забывает решения без него

docs.md это persistent-память проекта. Агент читает файл при каждом запуске и получает контекст, который иначе пришлось бы объяснять заново. Без него каждая сессия стартует с нуля.

Файл памяти проекта подгружается автоматически в начале сессии и работает как онбординг-документ для агента. По официальной документации Claude Code, каждая сессия начинается с пустого контекстного окна, и перенести знания между сессиями можно двумя способами: файлом инструкций и auto memory. Все, что не записано на диск, теряется при закрытии окна.

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

docs.md закрывает этот разрыв. Внутри лежит то, что вы иначе печатали бы в промпт каждый день: какой стек, где важный код, каким паттернам следуем, какие грабли уже прошли. С таким файлом агент не тратит токены на разведку по репозиторию и не выдумывает архитектуру заново. Он сразу видит проект целиком. По сути это конфигурация поведения, а не просто документация (официальные доки Claude Code).

Что класть в docs.md, а что туда тащить нельзя

В docs.md идет постоянная, критичная для всего проекта информация: стек, структура, соглашения, команды, решения и запреты. Не идет то, что выводится из кода или касается одного файла.

Практическое правило от инженеров, которые ведут CLAUDE.md месяцами: файл держат до 200 строк, потому что дальше растет расход контекста и падает следование инструкциям. Внутрь кладут ключевые команды сборки, узкие термины проекта и предпочтительный рабочий процесс. Временное и локальное туда не тащат.

Что реально работает внутри docs.md:

• Стек и версии. Next.js, Python, aiogram и так далее. Агент перестает гадать и подставлять чужие паттерны.
• Структура проекта. Где лежит важный код, что за что отвечает. Экономит десятки лишних чтений файлов.
• Соглашения. Отступы, именование, «используем Server Actions вместо API routes». Стиль применяется сразу, без напоминаний.
• Команды. Как собрать, как прогнать тесты, как задеплоить. Одна строка вместо объяснений каждый раз.
• Решенные проблемы. Баги, которые уже победили, и почему выбрали именно это решение.
• Запреты. Чего агент делать не должен: не рефакторить чужой код, не трогать .env, не плодить настройки.

А вот чего в docs.md быть не должно. Не тащите туда то, что модель и так прочитает в коде. Не копируйте весь контекст сессии в надежде на лучшую память: переизбыток данных делает память агента хуже, а не лучше. И не пишите роман. Файл, который грузится каждый раз, должен читаться за минуту.

Как решенные проблемы превращаются в память проекта

Каждый разобранный баг стоит записать в docs.md вместе с причиной и решением. Так проект «умнеет»: агент перестает наступать на те же грабли, а вы перестаете объяснять одно и то же.

В сообществе Claude Code это называют compounding engineering: каждое зафиксированное решение усиливает агента, и дальше он работает эффективнее. После тяжелой сессии отладки достаточно попросить: «просуммируй все тупики, в которые мы залезли, и добавь в память проекта». Один абзац в файле экономит часы на следующей неделе.

Вот в чем штука. Самое дорогое в работе с агентом это не написание кода, а повторное объяснение того, что вы уже проходили. Модель забывает, вы напоминаете, круг повторяется.

Разрыв этого круга и есть главная ценность docs.md. Разобрались с хитрым багом в вебхуке Stripe, записали пометку: «вебхук требует raw body, не парсить до проверки подписи». Выбрали между двумя подходами к авторизации, зафиксировали какой и почему. На третьей итерации агент уже не предложит то, что вы отвергли на первой.

Записывать можно руками через команду /memory или прямо во время работы: в Claude Code строка, начатая с символа #, уходит в память сразу. Плюс с версии 2.1.59 у Claude Code появилась auto memory: агент сам ведет приватный журнал находок по кодовой базе и подгружает его на старте. docs.md и auto memory дополняют друг друга: правила пишете вы, а находки записывает агент.

Максим: «VibeCoderz мы собрали за неделю тремя скриптами, голосом в Claude Code. 6 200 материалов на портале. Без файла памяти агент на каждой сессии заново переспрашивал структуру. Записали решения один раз, и дальше пошло изи-каткой».

Как называется docs.md в разных инструментах

docs.md это общее название паттерна. У Claude Code это CLAUDE.md, у Codex и большинства агентов AGENTS.md, у Cursor свои rules, у Gemini CLI файл GEMINI.md. Механика одна, имена и мелочи разные.

AGENTS.md появился в OpenAI Codex как прямой аналог CLAUDE.md: тот же файл в корне репозитория под контролем версий, задающий поведение агента. Разница в экосистеме, а не в идее. Держать пять разных файлов под пять инструментов это антипаттерн, который плодит расхождения. Правильнее один канонический источник и легкие адаптеры под каждый инструмент.

Если вы работаете одним агентом, просто заведите его родной файл. Если инструментов несколько, соберите общий AGENTS.md со всем, что важно любому агенту (архитектура, безопасность, тесты, git-конвенции), а в CLAUDE.md первой строкой подключите его через @AGENTS.md и допишите ниже только специфику Claude. Импорт раскрывает содержимое файла прямо в контекст при загрузке.

Отдельная деталь для командной работы. Общий файл кладут в git, а личные заметки, которые не нужно коммитить, выносят в локальную версию (CLAUDE.local.md или AGENTS.md.override в .gitignore). Так у каждого свои настройки, но общая память проекта одна на всех.

Как сгенерировать docs.md из кода существующего проекта

Не пишите docs.md с нуля. В Claude Code команда /init обходит репозиторий и собирает черновик сама. Дальше вы дорабатываете его промптом под задачу.

Команда /init читает package.json, сканирует структуру папок, находит паттерны и пишет сводку по проекту. Это рабочая стартовая точка, которую потом кастомизируют. Для существующей кодовой базы это самый быстрый путь: вместо часа ручной работы вы получаете основу за пару минут и правите ее под себя.

Порядок сборки простой. Сначала автоскан, потом ручная доводка, потом вынос деталей в ссылки. Ниже готовый промпт для доводки. Скопируйте, вставьте в Claude Code или Cursor после /init и получите структурированный файл памяти.

Проанализируй этот проект и собери файл памяти docs.md для AI-агента.
Формат Markdown, объем до 200 строк, детали выноси ссылками, а не текстом.

Структура файла:
1. Стек и версии (языки, фреймворки, ключевые библиотеки)
2. Структура проекта (где лежит важный код, что за что отвечает)
3. Соглашения (именование, отступы, паттерны, которые уже приняты в коде)
4. Команды (сборка, тесты, линт, деплой)
5. Архитектурные решения (что и почему выбрано, со ссылками на файлы)
6. Решенные проблемы (баги и обходы, которые видны по коду и коммитам)
7. Запреты (чего не делать: не трогать .env, не рефакторить X, и т.д.)

Правила:
- Пиши только то, что не очевидно из беглого чтения кода.
- Не дублируй README, ссылайся на него.
- Ключевые команды и версии указывай точно.
- Спорные места помечай как "требует уточнения", не выдумывай.

Дальше пройдитесь по черновику глазами. Агент хорошо вытаскивает стек и структуру, но не знает, почему вы приняли то или иное решение. Раздел с решениями и запретами дописывайте руками: именно он экономит больше всего времени на следующих сессиях. Проверьте, что версии и команды указаны верно, лишнее удалите.

Как держать docs.md в форме и не раздувать

docs.md это живой документ. Держите самое важное сверху, детали подключайте ссылками, раз в неделю чистите устаревшее. Раздутый файл мешает модели сильнее, чем его отсутствие.

Совет из практики: 100 до 200 строк это золотая середина, самое важное наверх, детали через ссылки на другие файлы. Если вы постоянно дописываете одну и ту же фразу в промпты, ее пора перенести в файл памяти. А устаревшие правила надо удалять: модели умнеют каждую неделю, и вчерашний костыль сегодня уже мешает.

Разбивайте память на модули. Кодстайл в один файл, правила тестов в другой, безопасность в третий, а в docs.md только короткие ссылки на них через @import или обычной ссылкой. В Claude Code для этого есть папка .claude/rules/: положенные туда markdown-файлы подхватываются автоматически, а path-scoped правила применяются только к нужным файлам. Импорт держит главный файл стройным, хотя и не уменьшает расход контекста: подключенные файлы все равно грузятся целиком при старте.

Ревизия раз в неделю это не бюрократия, а гигиена. Создатель Claude Code Борис Черни, по рассказам, вообще периодически сносит свой файл памяти и пересоздает с нуля. Звучит радикально, но логика та же: убрать дубли, снять противоречия, выкинуть то, что модель уже и так делает правильно. Проверить, что именно загружено в контекст, помогает команда /memory: она показывает все активные файлы памяти и их приоритет.

Честная оговорка. docs.md это контекст, а не жесткая настройка. Агент учитывает файл, но не обязан слепо ему подчиняться. Если действие надо заблокировать намертво (например, запретить публикацию ключей), одного правила в тексте мало, нужен хук на уровне инструмента.

Частые ошибки при ведении docs.md

Три главных промаха: раздутый файл, дубли с кодом и вечно устаревшие правила. Каждый превращает память в шум и роняет качество ответов агента.

По наблюдениям практиков, большинство разработчиков используют памяти агента процентов на десять. Файл либо не ведут вовсе, либо забивают всем подряд. И то, и другое одинаково вредно: пустой docs.md заставляет агента гадать, а перегруженный тонет в собственном объеме и мешает модели держать фокус.

Первая ошибка. Стена текста вместо структуры. Агент лучше читает заголовки и списки, чем сплошные абзацы. Разбивайте на разделы, ключевое выделяйте.

Вторая. Дублирование того, что есть в коде. Если версию библиотеки видно в package.json, не переписывайте ее в docs.md руками: она устареет, и агент получит два противоречащих источника.

Третья, самая коварная. Правила, которые больше не актуальны. Модель обновилась, паттерн в проекте сменился, а в файле висит старая инструкция. Агент честно ее исполняет и делает не то. Поэтому пункт «удалять устаревшее» в ревизии важнее, чем «добавлять новое».

Глоссарий

docs.md – файл памяти AI-проекта в формате Markdown, который агент читает в начале каждой сессии. Обобщенное название паттерна.

CLAUDE.md – реализация файла памяти в Claude Code. Подгружается автоматически, поддерживает импорты и правила.

AGENTS.md – кросс-инструментальный стандарт файла памяти, который читают Codex и многие другие агенты.

auto memory – механизм Claude Code (с версии 2.1.59), где агент сам записывает находки по коду и подгружает их на старте.

@import – синтаксис подключения внешних файлов в docs.md через символ @. Содержимое раскрывается в контекст при загрузке.

path-scoped rules – правила, которые применяются только к файлам по заданному пути или маске. Помогают не грузить лишнее в каждую сессию.

compounding engineering – подход, при котором каждое зафиксированное решение усиливает агента, и дальше он работает эффективнее.

/init – команда Claude Code, которая сканирует репозиторий и генерирует черновик файла памяти.

/memory – команда для просмотра и редактирования активных файлов памяти в системном редакторе.

контекстное окно – объем текста, который модель удерживает за один раз. Файл памяти занимает его часть, поэтому важен объем docs.md.

FAQ

Чем docs.md отличается от README? README пишут для людей, docs.md читает агент в начале каждой сессии. README рассказывает как запустить проект, docs.md задает, как агенту себя вести: стек, соглашения, решения, запреты. Часто docs.md ссылается на README, а не дублирует его.

Почему агент забывает то, что мы уже обсудили? Каждая сессия стартует с пустого контекста. Все, что вы объяснили голосом или в чате, исчезает после закрытия окна. Сохраняется только записанное на диск: docs.md, CLAUDE.md или auto memory. Не записал, значит забыл.

Насколько большим должен быть docs.md? От 100 до 200 строк. В Claude Code первые 200 строк памяти уходят в системный промпт автоматически, дальше растет расход контекста и падает точность. Все, что длиннее, выносите в отдельные файлы и подключайте ссылкой.

docs.md, CLAUDE.md или AGENTS.md что выбрать? Это один паттерн под разными именами. CLAUDE.md читает Claude Code, AGENTS.md понимают Codex и большинство агентов, у Cursor свои rules. Если инструментов несколько, держите общий AGENTS.md и подключайте его в CLAUDE.md через @import.

Как заставить агента сохранить решение прямо во время работы? Прямо попросите: «запиши в память проекта, что мы используем pnpm, а не npm». В Claude Code добавить строку в память можно через символ # в начале сообщения или командой /memory. Агент запишет это в файл, и на следующей сессии правило загрузится само.

Нужен ли docs.md для маленького проекта? Если проект на один вечер, хватит пары строк в промпте. Как только вы возвращаетесь к коду второй-третий раз и агент снова угадывает стек и стиль, пора завести docs.md. Обычно окупается уже на второй неделе.

Какой моделью лучше собирать docs.md? Для генерации черновика хватит рабочей модели среднего уровня, вроде Claude Sonnet или Gemini 3.1 Pro с его большим контекстом на объемные репозитории. Тяжелую Claude Opus 4.8 берите, когда нужен глубокий разбор архитектуры, а не просто сводка по коду.

Что дальше

docs.md это самый дешевый способ сделать AI-агента предсказуемым. Один файл, десять минут на старте, ревизия раз в неделю. Взамен агент перестает забывать решения, не гадает про стек и не наступает на старые грабли.

Начните с малого: запустите /init, допишите раздел с решениями и запретами, положите файл в git. Дальше он будет расти вместе с проектом.

Все инструменты для вайбкодинга, включая Claude Code, Cursor и Windsurf, собраны в каталоге AI-инструментовна VibeCoderz. Там же обзоры, цены и сравнения. Если тема пересекается с вашей работой, загляните в каталог AI-агентов: там 297 ниш по профессиям и задачам.

Если хотите разобрать настройку памяти под конкретный проект и стек, запишитесь на консультацию к Максиму.

Статья обновлена: июль 2026. Данные по командам, версиям и моделям актуальны на момент публикации и могут меняться по мере обновления инструментов.