CLAUDE.md

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

CLAUDE.md — это такая папка для твоего проекта. Обычный текстовый файл (просто Markdown, ничего особенного), который ты кладешь в папку. Каждый раз, когда ты или AI-агент открывает эту папку, он читает этот файл первым, прежде чем делать что-либо еще. Вместо того чтобы заново объяснять сетап в начале каждой сессии, ты объясняешь один раз, а дальше файл говорит за тебя.

Что большинство упускает: файла два.

System prompt определяет, кто AI везде. CLAUDE.md сужает это. И у него есть два слоя:

1. Глобальный CLAUDE.md: как ты хочешь, чтобы AI вел себя в каждом проекте. Это твоя личная инструкция по эксплуатации. Он живет в домашней папке конфигурации, а не в каком-то одном проекте.
2. Проектный CLAUDE.md: правила для этого одного кодбейса. Он живет в папке проекта и достается всем (или каждому агенту), кто ее открывает.

AI читает оба и складывает их: сначала глобальные правила, потом поверх них проектные. Когда они конфликтуют, обычно выигрывает более конкретное правило, то есть проектное.

Что куда класть. Быстрая проверка нутром: если это верно независимо от проекта, это глобальное. Если верно только для этого проекта — проектное.

Глобальное (про тебя и как тебе удобно работать):

• "Объясняй простым языком. Я не разработчик."
• "Если что-то неоднозначно, спроси до того, как собирать. Не угадывай."
• "Никаких секретов в коде. Ключи всегда идут в env-файл."

Проектное (про этот кодбейс):

• "Мы используем эту базу данных. Не добавляй другую."
• "Голос бренда теплый, никогда корпоративный."
• "Всегда запускай тесты, прежде чем сказать, что закончил."
• "Никогда не трогай файл оформления заказа."

Один реальный нюанс, который стоит знать. Люди думают, что где-то уже лежит глобальный файл ~/.claude/CLAUDE.md и ждет их. Часто его нет, его нужно создать. А экосистема тихо стандартизируется вокруг нейтрального к инструментам имени файла, AGENTS.md, чтобы Claude, Codex и остальные читали одни и те же домовые правила, а не требовали каждый свой файл. (Мой собственный глобальный файл — AGENTS.md. Та же идея, один файл, который уважает каждый инструмент.) Если инструмент просит CLAUDE.md, а у тебя есть только AGENTS.md, укажи ему на тот, который есть. Имя файла — просто ярлык. Важен контент.

Вот хороший проектный CLAUDE.md, который можно скопировать и переписать под свое:

И глобальный (положи его в ~/.claude/CLAUDE.md или назови AGENTS.md):

Если последние два пункта кажутся знакомыми, так и должно быть. Andrej Karpathy (ex-Tesla, OpenAI) опубликовал свои выстраданные заметки о том, где AI-агенты для кода ошибаются, а сообщество превратило их в теперь уже знаменитый CLAUDE.md: не предполагай, держи проще, меняй хирургически, определи, что значит "готово". Это стоит забрать целиком как стартовую точку. Его оригинальные заметки лежат в посте в X, а сообщество упаковывало их в файл "скопировал и пошел" в multica-ai/andrej-karpathy-skills на GitHub.

Мой честный вывод после месяцев жизни в этих файлах: CLAUDE.md — самый сильный рычаг, который может написать нетехнический билдер. Не промпт, который ты печатаешь сегодня, а файл, который агент читает каждый раз. Сделай его хорошо, и агент перестанет по кругу совершать одни и те же глупые ошибки. Он приходит, уже зная задачу.