раздел 04 · global vs project

Глобальный и проектный CLAUDE.md

У Claude Code два уровня памяти: ваш личный стиль работы и правила конкретного проекта. Они не конкурируют, а дополняют друг друга. Понимание границы между ними экономит часы переписки.

Где какой файл лежит

  • ~/.claude/CLAUDE.md - глобальный. Подгружается в каждый чат, в любом проекте.
  • ./CLAUDE.md (в корне репо) - проектный. Подгружается только когда вы работаете в этом репо.
  • Можно ещё ./.claude/CLAUDE.md - то же самое, но прячется внутри служебной папки.

Оба читаются автоматически при старте сессии. Менять Claude Code не нужно перезапускать - изменения подхватываются на следующем запросе.

Что писать в глобальный

Глобальный - это про вас, а не про код. Туда идёт всё, что верно для любого проекта:

  • язык общения (русский/английский)
  • стиль ответов (краткость, без воды, без emoji)
  • ваши общие конвенции (Docker для деплоя, Git как единственный путь на сервер)
  • запреты (никаких длинных тире, не показывать секреты в выводе)
  • адреса часто используемых сервисов (но без credentials)

Пример куска ~/.claude/CLAUDE.md:

# Глобальные правила

## Язык и стиль
- Общайся на русском, код - на английском
- Кратко, без вступлений вида "Давайте разберёмся"
- Дефис `-` вместо длинных тире
- Без emoji

## Деплой
- Любой проект - через Git, никаких scp/rsync
- Docker + docker-compose обязательны для серверных проектов
- `.env` не коммитится, `.env.example` коммитится

## Безопасность
- Не показывай credentials в выводе
- Один общий `.env` в корне воркспейса

Что писать в проектный

Проектный - это про код. Туда идёт всё, что специфично для этого репо:

  • стек и версии (Next.js 16, Python 3.12, pnpm)
  • структура папок (backend/, frontend/, infra/)
  • команды запуска (pnpm dev, uvicorn app.main:app --reload)
  • правила слоёв (DTO в schemas/, бизнес-логика в services/)
  • особенности тестов (pytest, vitest, mock внешних API)
  • адреса CI и продакшна

Пример ./CLAUDE.md для FastAPI-проекта:

# todo-ai

ToDo с AI-категоризацией задач через Claude API.

## Стек
- Backend: FastAPI + SQLAlchemy 2.0 (async) + SQLite
- Frontend: Vite + React 19 + Tailwind 4 + TanStack Query
- AI: Anthropic Claude Haiku 4.5 с prompt caching
- Docker для прод-деплоя

## Структура
- `backend/app/` - роуты, модели, сервисы
- `backend/tests/` - pytest
- `frontend/src/` - React-компоненты
- `infra/` - Dockerfile, docker-compose.yml

## Команды
- Бэк: `cd backend && uvicorn app.main:app --reload`
- Фронт: `cd frontend && pnpm dev`
- Тесты бэка: `cd backend && pytest`
- Тесты фронта: `cd frontend && pnpm test`

## Конвенции
- Async везде в FastAPI
- TS-типы для фронта генерим из `/openapi.json`
- Категории задач: work, personal, learning, health, other
- Если Anthropic API недоступен - категория `other`, не падаем

Как они комбинируются

Claude видит оба файла одновременно. Если в глобальном написано "общайся на русском", а в проектном этого нет - всё равно работает русский. Если в проектном переопределить ("в этом проекте отвечай на английском, потому что команда международная") - сработает проектное правило.

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

Чего избегать

  • Не дублируйте секреты в CLAUDE.md - они утекут в логи и истории
  • Не пишите туда то, что меняется каждый день (текущий спринт, открытые задачи) - для этого есть NOTES.md
  • Не делайте файл на 500 строк - Claude всё равно прочитает, но контекст забьётся

Полезные ссылки