CLAUDE.md — системный промпт твоего проекта

Модуль: 2. Быстрый старт | Время: ~30 мин теории + 25 мин практики

Суть урока

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

Ключевые концепции

• CLAUDE.md = системный промпт (промпт — текстовый запрос к AI), который агент читает в начале каждой сессии и держит в контексте
• Три слоя: WHAT (что есть), WHY (зачем это), HOW (как работать)
• Принцип лаконичности: каждое слово стоит токенов (токены — минимальные единицы текста для AI)
• Прогрессивная загрузка: указатели вместо дублирования
• /init — автогенерация CLAUDE.md для существующего кода

Теория

Что такое CLAUDE.md и зачем он нужен

🎨 Образ: Claude без CLAUDE.md — как новый хирург в операционной без медицинской карты пациента. Профессионал, но вынужден спрашивать с нуля: «Какие аллергии? Какие предыдущие операции? Какие противопоказания?» CLAUDE.md — это карта которую хирург изучил заранее.

Когда ты открываешь новый разговор с Claude Code — агент начинает с нуля. Он не помнит что ты строил в прошлый раз. Не знает как устроен твой проект. Не знает твои предпочтения.

Это создаёт проблему: каждый раз нужно заново объяснять контекст (контекст — содержание разговора видимое AI). «Этот проект на TypeScript (ТайпСкрипт — типизированный JavaScript), мы используем Supabase для базы данных, у нас три сервиса...» — 5-10 минут каждую сессию.

CLAUDE.md решает эту проблему.

Это файл CLAUDE.md в корне твоей папки проекта (имя пишется именно заглавными: на Linux регистр важен). Агент автоматически читает его в начале каждого разговора. Это как персональная инструкция: «Привет, я — этот проект. Вот что тебе нужно знать чтобы со мной работать».

Технически: CLAUDE.md — это Markdown (маркдаун — язык разметки текста)-файл. Агент использует его как контекст который «всегда включён» для данного проекта.

Три слоя CLAUDE.md

Хорошо написанный CLAUDE.md состоит из трёх слоёв. Думай о них как об ответах на три вопроса.

Слой 1: WHAT — что здесь есть

Техническое описание проекта. Агент должен понимать из каких частей состоит система.

Что включать:

• Технический стек: язык (Python, JS или TS), фреймворки, база данных
• Структура папок: что в какой папке и зачем
• Пакеты/библиотеки: какие внешние зависимости уже подключены
• Среда запуска: локально, Docker, Cloudflare Workers, Vercel

Пример:

## Технический стек
- Python 3.11
- Используем requests для HTTP-запросов
- Supabase как база данных (SDK: supabase-py)
- Развёртывание: Render.com (cron job)

## Структура проекта
/workflows/       — markdown-файлы с описанием воркфлоу
/tools/           — python-скрипты для каждого инструмента
/config/          — настройки (JSON-файлы)
/logs/            — автоматические логи запусков
main.py           — точка входа

Слой 2: WHY — зачем каждый компонент

🎨 Образ: Представь завод без инструкций «почему именно так». Новый сотрудник видит станок и начинает работать «логично» — и ломает дорогостоящую деталь, потому что не знал что у этой машины особый порядок запуска. WHY-слой — это инструкция «почему именно так, а не иначе», которая защищает от умных ошибок.

Самый часто пропускаемый слой. И самый важный для понимания.

Агент видит что есть папка /tools/. Но он не знает почему инструменты вынесены в отдельную папку, а не написаны в одном файле. Без этого понимания он может нарушить архитектуру — например, добавить новую функцию напрямую в main.py вместо создания нового инструмента.

Пример:

## Архитектурные решения

**Почему инструменты в отдельной папке:**
Каждый инструмент — это самостоятельная функция. Воркфлоу вызывает инструменты по имени. 
Это позволяет переиспользовать один инструмент в разных воркфлоу.

**Почему Supabase, а не CSV:**
Нужна персистентность между запусками. Каждый запуск дописывает в базу, не перезаписывает.

Слой 3: HOW — как агент должен работать

Правила работы. Как агент должен принимать решения, какие ограничения существуют, что делать в типичных ситуациях.

Пример:

## Правила работы

- При добавлении нового инструмента — создавай отдельный файл в /tools/, не добавляй в main.py
- Все API-ключи хранятся в .env файле, никогда не хардкодь в коде
- Перед созданием нового файла — проверь нет ли уже похожего
- Стиль кода: Python snake_case, комментарии на русском языке
- Если задача требует нового пакета — спроси прежде чем добавлять

Принцип лаконичности: токены — деньги

🎨 Образ: CLAUDE.md — как вступительная речь на собрании. Если директор говорит 5 минут — все слушают. Если говорит час — люди зевают и перестают воспринимать. Агент «зевает» иначе: просто тратит лишние токены и деньги. Краткость — не добродетель, это экономика.

Содержимое CLAUDE.md остаётся в контексте всей сессии и учитывается при каждом запросе. Если CLAUDE.md весит 2000 слов — это 2000 слов добавляется к каждому твоему сообщению.

Цена токенов зависит от модели (актуальные цены: Актуальное сейчас). Но при десятках запросов в день раздутый CLAUDE.md заметно увеличивает расходы и быстрее заполняет окно контекста.

Правило: если что-то можно не писать — не пиши. Если что-то написано подробно — спроси себя «агенту правда нужна эта деталь прямо сейчас?»

Что точно писать в CLAUDE.md:

• Ключевые архитектурные решения
• Нестандартные конвенции которые агент не угадает
• Структура проекта (одним абзацем, не подробным деревом)
• Правила которые важно соблюдать всегда

Что НЕ писать в CLAUDE.md:

• Очевидные вещи («использовать Python синтаксис»)
• Длинные инструкции которые нужны раз в месяц
• Полную документацию API (эй-пи-ай, Application Programming Interface — интерфейс программирования приложений) (лучше ссылка на файл)
• История проекта и обоснования каждого решения

Прогрессивная загрузка: указатели вместо дублирования

🎨 Образ: Не кладёшь всю библиотеку на стол перед встречей — говоришь «нужная книга на полке Б, третья слева». Агент возьмёт её когда понадобится. Прогрессивная загрузка — это библиотечный каталог, не сама библиотека на столе.

Вот мощный паттерн который экономит токены при сохранении качества:

Плохо (дублирование в CLAUDE.md):

## API Perplexity
Endpoint: https://api.perplexity.ai/chat/completions
Метод: POST
Headers: Authorization: Bearer {API_KEY}, Content-Type: application/json
Body: {"model": "sonar", "messages": [...]}
Пример ответа: {"choices": [{"message": {"content": "..."}}]}
...ещё 200 строк документации...

Хорошо (указатель):

## Внешние API
Документация по всем API: см. /docs/api-reference.md
Если нужны примеры запросов — там же.

Агент прочитает /docs/api-reference.md только когда это действительно нужно — когда работает с этим API. Не при каждом запросе.

Это называется прогрессивная загрузка — загружаешь только то, что нужно прямо сейчас.

/init: автогенерация CLAUDE.md

Если у тебя уже есть существующий код (например, ты взял готовый шаблон или унаследовал чужой проект), Claude Code может сам сгенерировать CLAUDE.md на основе анализа кода.

Команда:

/init

Агент:

1. Просмотрит всю структуру папки
2. Прочитает ключевые файлы (package.json, requirements.txt, главные скрипты)
3. Составит черновик CLAUDE.md с тремя слоями
4. Ты редактируешь и уточняешь

Это не заменяет написание CLAUDE.md с нуля для нового проекта — потому что тогда ещё нечего анализировать. Но для существующих проектов экономит 20-30 минут.

Что ещё читает Claude Code (на октябрь 2026)

CLAUDE.md — не единственный способ дать агенту постоянный контекст:

• AGENTS.md — Claude Code читает и его, если в проекте уже лежит такой файл (его используют и другие агентные инструменты).
• .claude/rules/ — правила, привязанные к типам файлов: например, отдельные правила для тестов или для папки с фронтендом. Так главный CLAUDE.md остаётся коротким.
• Auto memory (авто-память) — Claude сам записывает выводы из твоих поправок между сессиями. Управление через команду /memory.

Минимальный шаблон CLAUDE.md (шпаргалка)

Скопируй этот шаблон как стартовую точку для любого нового проекта:

# [Название проекта] — CLAUDE.md

## Что это (WHAT)
[1-2 предложения: что делает проект, для кого]

## Стек
- Язык: [Python / JavaScript / TypeScript]
- Фреймворки: [если есть]
- База данных: [если есть]
- API: [какие внешние сервисы]
- Деплой: [куда деплоится]

## Структура проекта
/workflows/   — воркфлоу (markdown-инструкции)
/tools/       — инструменты (по одному файлу на функцию)
/config/      — настройки (JSON (джейсон — формат данных ключ-значение)/YAML (ямл — формат конфигурационных файлов))
/docs/        — документация API и справка
/logs/        — автоматические логи
.env          — API-ключи (НИКОГДА не коммить в git (гит — система контроля версий кода))

## Почему так (WHY)
- [Архитектурное решение 1: почему так а не иначе]
- [Архитектурное решение 2]

## Правила работы (HOW)
- Новый инструмент = новый файл в /tools/, не правки в существующих
- API-ключи только в .env, никогда не хардкодь
- Перед деплоем — тестируй на тестовых данных
- Стиль кода: [snake_case / camelCase], комментарии на [русском/английском]
- Если задача требует нового пакета — спроси прежде чем добавлять

Пример реального CLAUDE.md для newsletter воркфлоу

# Newsletter Automation — CLAUDE.md

## Что это
Автоматическая еженедельная рассылка новостей о недвижимости для клиентов агентства.
Запускается по расписанию, собирает новости, генерирует HTML и отправляет через Gmail API.

## Стек
- Python 3.11
- Perplexity API — поиск новостей
- Anthropic API — генерация текста
- Gmail API — отправка
- Google Sheets API — список получателей
- Запуск: cron (крон — планировщик автоматических задач) через trigger.dev

## Структура
/workflows/weekly_newsletter.md  — главный воркфлоу (читай его прежде чем что-то менять)
/tools/                          — отдельный файл на каждый инструмент
/config/newsletter_style.json    — стиль и параметры рассылки
/config/recipients.json          — список получателей (обновляй только этот файл)
.env                             — API ключи (никогда не коммить)

## Правила
- При изменении логики — сначала обнови weekly_newsletter.md, потом код
- Новый инструмент = новый файл в /tools/, не правки в существующих
- Тестирование: всегда отправляй сначала на [email protected] перед основной рассылкой
- Логи каждого запуска автоматически пишутся в /logs/ (не трогай этот формат)

Короткий, конкретный, покрывает всё что агенту нужно знать.

Практика

Задание: Создать CLAUDE.md для учебного проекта с тремя слоями.

Шаг 1 — Выбери свой проект (5 мин):

Выбери одну из автоматизаций которую хочешь построить (или используй учебный пример: «рассылка еженедельного дайджеста клиентам»).

Шаг 2 — Напиши WHAT-слой (8 мин):

Создай файл CLAUDE.md в папке проекта. Напиши технический стек и структуру папок которые ты планируешь.

Шаг 3 — Напиши WHY-слой (7 мин):

Добавь секцию «Архитектурные решения» с объяснением почему стек и структура именно такие.

Шаг 4 — Напиши HOW-слой (5 мин):

Добавь секцию «Правила работы» с 3-5 правилами.

Шаг 5 — Проверка (5 мин):

Спроси у Claude Code: «Прочитай CLAUDE.md и расскажи как ты понял что за проект и как с ним работать». Если агент не понял что-то важное — уточни CLAUDE.md.

Частые ошибки

❌ Ошибка: Написать CLAUDE.md на 3000 слов с полной документацией всех API.

✅ Правильно: CLAUDE.md читается при КАЖДОМ запросе = каждое слово стоит токенов. Держи его коротким (200-500 слов). Детальную документацию выноси в отдельные файлы и давай ссылки: «см. /docs/api-reference.md».

❌ Ошибка: Не писать WHY-слой — только WHAT и HOW.

✅ Правильно: Без WHY агент не понимает архитектурные решения и может нарушить структуру. Почему инструменты в отдельных файлах? Почему Supabase а не CSV? Объясни коротко.

❌ Ошибка: Забыть обновлять CLAUDE.md когда проект меняется.

✅ Правильно: Когда добавляешь новый инструмент, меняешь стек или правила — обнови CLAUDE.md. Устаревший системный промпт хуже чем отсутствующий: агент будет следовать неправильным инструкциям.

Инструменты и ресурсы

• Claude Code — основной инструмент
• Markdown — формат написания CLAUDE.md (заголовки через #, списки через -)
• Claude Code: память и CLAUDE.md — официальная документация по CLAUDE.md, правилам и auto memory
• Anthropic Prompt Engineering — общие принципы написания промптов
• Команда /init — автогенерация CLAUDE.md на основе анализа существующего кода

→ См. урок Four C's Framework — CLAUDE.md как носитель четырёх C

→ См. урок Основы промптинга — принципы написания хороших промптов

→ См. урок WAT-фреймворк — структура папок проекта

→ См. урок Что такое Skills — как добавлять Capabilities в CLAUDE.md

Ключевые выводы

CLAUDE.md = системный промпт проекта. Агент читает его в начале каждой сессии. Один раз настроил — работает всегда.

Три слоя: WHAT (что есть), WHY (зачем это), HOW (как работать). Без WHY агент нарушит архитектуру не со зла.

Лаконичность важна: каждое лишнее слово — лишние токены в каждом запросе. Используй указатели вместо дублирования.

Следующий урок

→ WAT-фреймворк — Воркфлоу (воркфлоу — рабочий процесс, поток задач), Агент, Инструменты