Settings hierarchy и .claude directory

1. Поведение Claude зависит от проекта

Рано или поздно поймаете странность: в одном репозитории Claude держится в рамках, в другом слишком самостоятелен, а у коллеги — третий вариант. Это не характер модели и не версия. Это иерархия настроек.

В Commerce OS Claude знает команды запуска, не лезет в чувствительные части, подхватывает командные договорённости. В личном pet-проекте тот же инструмент ведёт себя иначе — не «забыл курс», а получает правила из других источников.

Часть правил — про вас лично, часть — про репозиторий, часть — про вашу локальную копию, часть приходит сверху от организации.

Фокус урока — не выучить ключи конфига, а научиться задавать один вопрос: откуда взялось это поведение Claude? Знаете источник — правите по делу. Не знаете — правите наугад, а это хуже самой проблемы.

2. Иерархия настроек: четыре уровня

Настройки Claude Code — четыре разных источника правил, не четыре одинаковые папки. Названия привыкайте читать по-английски: user, project, local, managed.

user

project

local

managed

Два уровня путают чаще всего. local — не способ тихо переписать командные правила под себя, а место для особенностей этой копии (порт БД, путь к инструменту, некоммитимая заметка); командного знания тут нет. managed — правила здания, а не вашей квартиры: организация не советует, а ограничивает, и удобство не должно побеждать безопасность.

Точный приоритет зависит от версии и среды — в спорных местах смотрите документацию и /help, а не память. Важна модель: одна и та же вещь приходит из разных уровней, поэтому странность сначала диагностируют, а не правят вслепую.

3. Уровни настроек на практике

Вопрос не «какой слой красивее», а какой слой должен отвечать за это правило. Инженерное правило: личное храните лично, командное — в проекте, заданное сверху — не делайте вид, что его нет.

План «почти всегда сначала» — user. Договорённость команды Commerce OS аккуратнее трогать чувствительные модули — project. Нестандартный порт локальной БД — local. Запрет организации на автодействия — managed, и спорить с ним через локальный файл бесполезно.

Диагностический вопрос: если завтра проект откроет другой разработчик, должен ли он увидеть это правило? Да — project. Нет — local или user.

Увидели странность и сразу «поправлю .claude/CLAUDE.md» — рискуете лечить не тот слой. Диагноз про конфиг, а пациент — путь к директории.

4. .claude/ — AI-слой проекта

.claude/ — не кладовка и не мини-фреймворк, а конфигурационный AI-слой проекта: артефакты, которые помогают Claude Code работать в этом репозитории. Это карта местности, а не список обязательных действий.

Часто выглядит так:

.claude/
  CLAUDE.md
  rules/
  skills/
  agents/
  hooks/
  mcp/

Точный набор папок и формат зависят от версии и договорённостей команды; логика та же.

Что важно сейчас:

• CLAUDE.md — главный общий файл на старте. Читать и понимать.
• rules/ — правила для отдельных частей проекта. Пока достаточно знать, что слой есть.
• skills/, agents/, hooks/, mcp/ — карта будущих расширений. В бой вступать не надо.

На первой неделе на старт влияет CLAUDE.md; остальные папки — дорожные знаки развитого AI-слоя.

.claude/ в Commerce OS — не бизнес-логика магазина, а инженерный сервисный слой вокруг репозитория: проще и безопаснее работать с Claude Code. Когда такие артефакты повторяются между репозиториями, из них собирают отдельный Workflow Kit. Но сперва научитесь читать этот слой в проекте, не путая его с продуктовой логикой.

5. Walkthrough .claude/ в Commerce OS

Откройте AI-слой так же, как README или build.gradle — как источник договорённостей, без желания сразу улучшить архитектуру.

pwd                      # /Users/you/projects/commerce-os
git status               # working tree clean или изменения понятны
ls -la .claude           # смотрим, что есть в AI-слое проекта

Чтобы быстро увидеть, что лежит внутри:

find .claude -maxdepth 2 -type f
# .claude/CLAUDE.md
# .claude/rules/...
# .claude/skills/...
# ...

Дальше — откройте именно CLAUDE.md, а не hooks и agents в поисках тайного знания. Внутри обычно приземлённые вещи: чем запускать проект, чем проверять, какие зоны чувствительные, что Claude должен сообщать после изменений. Этого хватит: вы ищете общие проектные инструкции.

Локальные личные файлы не должны уплывать в репозиторий, поэтому в .gitignore нередко встречается:

# Пример соглашения: личные AI-файлы не коммитим
.claude/CLAUDE.local.md
.claude/settings.local.json

Имена примерные, принцип важнее: личные настройки не должны незаметно становиться правилами для всей команды. Главное в walkthrough — дисциплина взгляда: вы не чините AI-слой, а смотрите, какой контекст проект уже даёт Claude.

6. Минимум контроля на старте

Без полного понимания всех подпапок .claude/ работать можно. У вас есть Git baseline; поверх него нужно понять источник проектных правил, найти CLAUDE.md и осознанно выбрать режим доступа сессии. Остальное — карта возможностей, а не обязательный квест.

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

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

Имена файлов и ключей со временем меняются. Не привязывайтесь к «у меня дерево не такое, значит всё неправильно». Стабильна не папка, а модель: личные настройки, проектный слой, локальные особенности, управляемые сверху ограничения.

7. Диагностика странного поведения Claude

Без понимания иерархии разработчик лечит симптомы. Не так — «перепишу CLAUDE.md». Не помогло — «удалю полпапки .claude/». Хуже — «инструмент сырой». Обычно хватает короткого ритуала диагностики.

1. Проверьте, что вы вообще в нужном проекте.
   «Открыл не тот каталог» встречается подозрительно часто. Сначала pwd, потом git status, потом разговор про настройки.

2. Откройте общие проектные инструкции.
   Прочитайте CLAUDE.md, а не фантазируйте. Много «странного поведения» оказывается честным следованием правилам, которых вы не видели.

3. Спросите, кому должно принадлежать это правило.
   Привычка? Командная договорённость? Особенность машины? Или то, что вам не дают менять? Вопрос сужает поиск.

4. Не переписывайте весь AI-слой ради одной непонятности.
   Проблема в локальном слое — не трогайте проектный. Ограничение сверху — не воюйте с project-файлом. Лечат источник, а не ближайший файл.

Тема не делает вас экспертом по конфигам, но убирает ощущение случайности. .claude/ — инженерный слой проекта, правила приходят из нескольких внятных уровней, и поведение Claude можно прочитать, отследить, разобрать. А как только источник правил понятен, следующий деловой вопрос — что Claude в этой сессии вообще разрешено делать. К нему и перейдём.