Ієрархія налаштувань і .claude каталог

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/ — ШІ-шар проєкту

.claude/ — не комірчина й не мініфреймворк, а конфігураційний ШІ-шар проєкту: артефакти, які допомагають Claude Code працювати в цьому репозиторії. Це карта місцевості, а не список обов’язкових дій.

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

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

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

Що важливо зараз:

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

На першому тижні на старт впливає CLAUDE.md; решта папок — дорожні знаки розвиненого ШІ-шару.

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

5. Огляд .claude/ у Commerce OS

Відкрийте ШІ-шар так само, як README або build.gradle — як джерело домовленостей, без бажання одразу покращити архітектуру.

pwd                      # /Users/you/projects/commerce-os
git status               # робоче дерево чисте або зміни зрозумілі
ls -la .claude           # дивимося, що є у ШІ-шарі проєкту

Щоб швидко побачити, що лежить усередині:

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 — дисципліна погляду: ви не лагодите ШІ-шар, а дивитеся, який контекст проєкт уже дає Claude.

6. Мінімум контролю на старті

Без повного розуміння всіх підпапок .claude/ працювати можна. У вас є Git baseline; поверх нього потрібно зрозуміти джерело проєктних правил, знайти CLAUDE.md і свідомо обрати режим доступу сесії. Решта — карта можливостей, а не обов’язковий квест.

Формула етапу: уміти відповісти на три запитання — звідки взялося правило, де лежать загальні інструкції проєкту і яку межу дій ви задасте поточній сесії.

Не треба вдавати з себе senior-археолога ШІ-конфігів у перший день. Відкрили правильний репозиторій, розумієте, звідки приходять правила, прочитали CLAUDE.md — це вже доросла інженерна робота.

Назви файлів і ключів із часом змінюються. Не прив’язуйтеся до «в мене дерево не таке, значить усе неправильно». Стабільна не папка, а модель: особисті налаштування, проєктний шар, локальні особливості, обмеження, керовані зверху.

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

Без розуміння ієрархії розробник лікує симптоми. Не так — «перепишу CLAUDE.md». Не допомогло — «видалю пів папки .claude/». Гірше — «інструмент сирий». Зазвичай вистачає короткого ритуалу діагностики.

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

2. Відкрийте загальні проєктні інструкції.
   Прочитайте CLAUDE.md, а не фантазуйте. Багато «дивної поведінки» виявляється чесним дотриманням правил, яких ви не бачили.

3. Запитайте, кому має належати це правило.
   Звичка? Командна домовленість? Особливість машини? Або те, що вам не дають змінити? Запитання звужує пошук.

4. Не переписуйте весь ШІ-шар заради однієї незрозумілості.
   Проблема в локальному шарі — не чіпайте проєктний. Обмеження зверху — не воюйте з project-файлом. Лікують джерело, а не найближчий файл.

Тема не робить вас експертом із конфігів, але прибирає відчуття випадковості. .claude/ — інженерний шар проєкту, правила приходять із кількох зрозумілих рівнів, і поведінку Claude можна прочитати, відстежити, розібрати. А щойно джерело правил зрозуміле, наступне ділове запитання — що Claude в цій сесії взагалі дозволено робити. До нього й перейдемо.