Понимание структуры папки .claude/ для настройки Claude Code

Папки проектной и глобальной конфигурации

Существует два каталога .claude: один в корне вашего проекта для командной конфигурации, которая коммитится в git, и другой в домашней директории (~/.claude/) для личных предпочтений и локального состояния машины, такого как история сессий.

CLAUDE.md: Руководство по эксплуатации

CLAUDE.md загружается в системный промпт Клода в начале каждой сессии и соблюдается на протяжении всего разговора. Вы можете разместить CLAUDE.md в корне проекта, в ~/.claude/ для глобальных настроек или в подкаталогах для правил, специфичных для папки.

Эффективное содержимое CLAUDE.md включает:

• Команды сборки, тестирования и линтинга (npm run test, make build и т.д.)
• Ключевые архитектурные решения
• Неочевидные подводные камни
• Соглашения об импортах, шаблоны именования, стили обработки ошибок
• Структура файлов и папок для основных модулей

Держите CLAUDE.md в пределах 200 строк. Файлы длиннее этого начинают потреблять слишком много контекста, и соблюдение инструкций Клодом падает.

Пример структуры CLAUDE.md

# Проект: Acme API

Команды
npm run dev # Запустить dev-сервер
npm run test # Запустить тесты (Jest)
npm run lint # Проверка ESLint + Prettier
npm run build # Продакшен-сборка

Архитектура

• REST API на Express, Node 20
• PostgreSQL через Prisma ORM
• Все обработчики находятся в src/handlers/
• Общие типы в src/types/

Соглашения

• Используйте zod для валидации запросов в каждом обработчике
• Формат возврата всегда { data, error }
• Никогда не раскрывайте стектрейсы клиенту
• Используйте модуль логгера, а не console.log

Обратите внимание

• Тесты используют реальную локальную БД, а не моки. Сначала запустите npm run db:test:reset
• Строгий TypeScript: неиспользуемые импорты запрещены

  Личные переопределения с CLAUDE.local.md

  Создайте CLAUDE.local.md в корне вашего проекта для личных предпочтений, которые не применяются ко всей команде. Клод читает его вместе с основным CLAUDE.md, и он автоматически игнорируется git, поэтому личные настройки никогда не попадают в репозиторий.

  Модульные инструкции с папкой rules/

  Для больших команд папка rules/ предоставляет модульные инструкции, которые масштабируются лучше, чем один большой файл CLAUDE.md.

  📖 Read the full source: HN AI Agents