Что должно быть в вашем CLAUDE.md и как вообще устроена архитектура подгрузки этих файлов

Я надеюсь все знают, что при работе с Claude Code / Codex / Cursor / Gemini и т.п агентами, у вас в каждом проекте должны быть файлы, которые агент автоматически подсасывает в контекст.

Так вот, теперь покажу, из чего эта группа файлов может состоять

Эту схему я объясняю на своих лекциях по агентной работе, и по ней у меня устроены почти все проекты на машине

Суть коротко

Если вы работаете с Claude Code / Gemini / Codex / Cursor и практически любым современным аналогом, то все они ищут несколько файлов, которые автоматически загрузят себе в контекст, если наткнутся на них

Зачем?

Чтобы агент всегда помнил самые важные инструкции. И чтобы вам не приходилось рассказывать ему одно и то же

Далее разберу три вещи

Разбирать буду на примере Claude Code, но остальные работают практически также

1. Какие слои бывают и как агент их собирает
2. Что класть в глобальный файл, а что в проектный
3. Как не раздувать контекст

1. Слои

— глобальный ~/.claude/CLAUDE.md — грузится в каждой сессии. Неважно, откуда сам Claude Code был запущен
— CLAUDE.md в папке со всеми вашими проектами — правила распространяются на все проекты внутри
— CLAUDE.md или AGENTS.md проекта — только в этом проекте (AGENTS.md Claude прочитает, только если рядом нет CLAUDE.md)
— CLAUDE.md подпапки — когда агент полез в её файлы
— память проекта — MEMORY.md при старте, заметки по требованию

Claude не выбирает один файл, а складывает все в одно окно, от общего к частному

2. Что хранится в моем глобальном CLAUDE.md

У меня там:

— мой язык и стиль ответов
— профиль: кто я, часовой пояс, тариф
— система: Windows, какая оболочка, как писать пути, какой python
— инвентарь CLI и MCP на машине и правило «сначала CLI, потом браузер»
— правило памяти: «ничего не сохраняй без моего „да“»
— где лежит журнал сессий, если спрошу, что делали три дня назад

Но не все в одну кучу, а через индекс.

В глобальном Claude MD хранятся лишь ссылки, а детали подгружаются отдельно

Проектный CLAUDE.md — про ваш конкретный проект.

Его проектировать лучше тоже в формате индекса

Храните там всю инфу, которая была бы полезна новому сотруднику

Как запустить и проверить, как устроены папки, что нельзя трогать

Если сидите и на Claude, и на Codex, держите общее в AGENTS.md. А в CLAUDE.md подключите его строкой @AGENTS.md

Claude не так давно научился читать не только Claude md, но еще и Agents md (при условии, что Claude md отсутствует)

Один из самых важных блоков в этом файле — структура всей папки и что где лежит

3. Как не раздувать контекст

Сделайте CLAUDE.md оглавлением (ну или индексом). У каждого файла пара строк: зачем и когда его открывать: «например, упоминание вас → ссылка на файл user». Агент открывает его, только когда сработало условие

Итого:

— Глобальный CLAUDE.md — про вас и вашу железку, на которой он крутится
— проектный CLAUDE.md — про проект, соответственно
— есть еще MEMORY.md, но про него в следующий раз расскажу

Claude каждый раз собирает всё это в одно окно. Чем короче каждый слой, тем больше места остаётся на работу

А проверить, что лежит в контексте вашего агента, можно через команду /context (в Claude Code)

А какая самая полезная секция в вашем CLAUDE.md?

Я конечно не рассказал и 10% правил по работе с этими файлами, но лучше так, чем никак

Ну и да, у меня намного больше картинок, но на Habr в посте можно только 1 разместить