Перейти до змісту

Claude Code у проекті ESWF — посібник для нового розробника

Аудиторія: розробник, що долучається до ESWF/DOP і вперше відкриває Claude Code в цьому репо. Мета: зрозуміти, як Claude налаштований у нас, як підтримувати конфігурацію актуальною, як користуватись skills/hooks/memory продуктивно.

Дата останньої ревізії: 2026-04-23.

1. Як влаштований контекст — багаторівнева CLAUDE.md

Claude Code автоматично читає файли CLAUDE.md з поточної робочої директорії та всіх батьківських каталогів. Ми використовуємо цей механізм як маршрутизацію контексту: коли ви редагуєте файл у backend/, Claude підвантажує backend/CLAUDE.md (а не гігантський корневий).

Структура в нашому репо

Файл Що містить Коли вантажиться
CLAUDE.md Навігаційний індекс, multi-site архітектура, launchers Завжди
backend/CLAUDE.md Django apps (21), patterns, URLs, management commands Робота в backend/
frontend/erp/CLAUDE.md DOP App: React+Mantine, routing, ItemType, API client Робота в frontend/erp/
frontend/shop/CLAUDE.md Client Portal (Next.js SSR) Робота в frontend/shop/
frontend/portal/CLAUDE.md, frontend/news/CLAUDE.md Лендінг, блог Відповідні каталоги
mobile/CLAUDE.md, mobile-sales/CLAUDE.md Driver App, Sales App (React Native + WatermelonDB) Відповідні каталоги
docs/CLAUDE.md VitePress структура, термінологія DOP vs ERP Робота в docs/

Чому так, а не один великий файл

До 2026-04-23 у нас був єдиний кореневий CLAUDE.md на ~900 рядків. Проблеми: - Редагуєш RN-екран у mobile-sales/ — у контекст тягнеться перелік 21 Django app'а (марно). - Файл розрісся і його стало важко тримати актуальним (ніхто не пам'ятає, що там написано). - Опис однієї теми був розкиданий по декількох секціях (frontend/erp — в кореневому; backend-endpoint, який його годує — у backend-секції).

Субдиректорні файли вирішують обидві проблеми: локальний контекст — локально.

Коли CLAUDE.md не підходить — .claude/rules/

Окрім CLAUDE.md, Claude Code підтримує каталог .claude/rules/ з path-specific правилами. Кожен файл має YAML frontmatter paths: з glob-паттернами — правило вантажиться, коли Claude торкається файлу, що матчить, незалежно від cwd.

---
paths:
  - "backend/**/migrations/*.py"
---
# Migration rules
- НЕ редагувати вручну — завжди через `python manage.py makemigrations`
- Зворотні міграції — окремий файл, не amend

Коли краще .claude/rules/ замість CLAUDE.md: - Правило прив'язане до типу файлу (міграції, тести, формові компоненти), а не до каталогу - Шляхи розкидані по монорепо (форми в frontend/erp/ і frontend/shop/ — одне правило на обидва) - Правило — крос-катне (як писати тести, як структурувати API views)

Коли краще CLAUDE.md: - Опис «що лежить у цьому каталозі» (стек, структура src/, перелік apps) - Правила працюють для всього каталогу без винятків

Ієрархія завантаження Claude Code: 1. Managed CLAUDE.md (організаційний рівень) 2. Project-root CLAUDE.md 3. User-level rules (~/.claude/rules/) — глобальні для всіх проектів 4. Project rules (.claude/rules/) — для цього проекту 5. Nested CLAUDE.md (підкаталоги) — lazy loading за cwd

Слеш-команда для перегляду всіх активних інструкцій — /memory (окремої /rules немає).

Наразі в ESWF використовуємо і CLAUDE.md (кореневий + 8 субдиректорних), і .claude/rules/: - .claude/rules/document-posting.md — інваріанти посту/анпосту (path-trigger на backend views/serializers/services)

2. Як підтримувати CLAUDE.md актуальним

Коли оновлювати

Обов'язково (той самий commit): - Додали нову Django app → backend/CLAUDE.md секція "Django Apps" + корневий URL (якщо community) → backend/CLAUDE.md секція "Main URLs" - Додали новий horizontal/vertical модуль — додатково пункт в docs/DOCS.md і docs/dop/modules/<h|v>/<module>/README.md - Змінили стек (наприклад, Mantine 8 → 9, Vite 7 → 8) → секція "Tech Stack" у відповідному frontend-файлі - Додали новий frontend або мобільний додаток → корневий CLAUDE.md (таблиця "Where to look") + новий <path>/CLAUDE.md - Змінили архітектурний pattern (multi-tenancy, plugin-system, TenantFilterMixin) → корневий + backend/CLAUDE.md

Не треба оновлювати при: - Фіксі бага (файли і так залишаються на тих самих місцях) - Додаванні нового поля в існуючу модель (модель вже перелічена; додавати кожне поле — не масштабується) - Рефакторингу під капотом без зміни публічного API

Правило однієї відповідальності

Кожен факт — у одному місці. Дублювання між корневим і субфайлами — гарантія, що вони разійдуться.

  • Корневий → тільки те, що стосується ≥2 підсистем (cross-cutting): multi-site архітектура, launchers, глобальні domain, загальна термінологія.
  • Субдиректорний → все, що стосується тільки цього каталогу: стек, структура src/, патерни, gotchas.

Що НЕ писати в CLAUDE.md

Це часті анти-патерни:

  • ❌ Що робить функція foo() — код самодокументований через імена. Claude прочитає код швидше, ніж ви напишете опис.
  • ❌ Історія змін і рішень — для цього є git log і commit messages.
  • ❌ «TODO: додати X» — для цього є docs/todo.md і issues.
  • ❌ Копія README — CLAUDE.md і README можуть посилатись один на одного, але не дублюватись.
  • ❌ Перелік полів моделі на рівні «id, name, email» — це метадані, які Claude отримає з самого Django. Пишіть тільки нетривіальні поля/зв'язки/gotchas.

Правило перевірки (для review)

Перед merge'ом PR, що стосується архітектури, поставте собі 3 питання:

  1. Чи додав цей PR нове публічне поняття (app, модуль, секція, pattern), якого не було раніше?
  2. Чи змінив/скасував існуюче поняття, яке раніше згадувалося в CLAUDE.md?
  3. Чи правильно Claude оцінив би поточний стан після мерджу, якби прочитав CLAUDE.md уперше?

Якщо на (1) або (2) — «так», оновіть CLAUDE.md у тому ж PR.

3. Skills — переиспользование повторюваних патернів

Що таке skill

Файл .claude/skills/<name>/SKILL.md з frontmatter-ом (name, description). Claude автоматично підхоплює skill, коли опис відповідає задачі. Skill — це не команда, а тригеровий чекліст, який Claude виконує на зустрічі з відповідним завданням.

Коли створювати skill

Емпірично: коли процес повторюється тричі за однаковим патерном і має нетривіальні кроки, які легко забути. Приклад: Phase F-1/F-2/F-3/F-4 (hrm, production, baf_sync, budgeting) — 4 модулі одним патерном.

Не створюйте skill наперед. Поки паттерн ще формується, skill застаріватиме швидше, ніж приноситиме користь. Дочекайтесь двох-трьох реальних виконань — тоді зафіксуйте їх.

Наші skills

.claude/skills/new-module/SKILL.md — чек-ліст створення нового horizontal/vertical DOP-модуля. 10 чекпоінтів, шаблони коду, посилання на референси (hrm, production, baf_sync, budgeting, consolidation).

Як ми його створили: 1. Побудували 4 Phase F модулі вручну (одним патерном). 2. Витягли інваріанти з коду (не з пам'яті!). 3. Створили skill із прямими посиланнями на backend/budgeting/ як найчистіший референс. 4. Перевірили skill, побудувавши п'ятий модуль (consolidation) — знайшли 3 прогалини в skill v1, одразу виправили.

.claude/skills/custom-form/SKILL.md — чек-ліст створення кастомних форм/списків/полів для: - Документів (TransactionModel) — референси GoodsReceipt, Waybill, DocumentOperation - Довідників (MasterDataModel) — референси Item (номенклатура), Vehicle (ТЗ)

Два обов'язкові «stop-and-think» чекпоінти: - 🤖 AI-інтеграція — проаналізувати, чим AI може допомогти з цією сутністю; якщо ідеї є, зареєструвати в aiMenuItems.tsx і написати чернетки промптів - 📒 Облікова операція (для документів) — проаналізувати, яку бух. операцію документ відображає; запропонувати блок проводок (Дт/Кт)

Створено після повторюваної скарги «доводиться кожного разу казати: подивись як зроблено для ПН». Референси проаналізовано Explore-агентом, 10 gotchas витягнуто з реального коду.

Як писати свій skill

Структура:

.claude/skills/<name>/
└── SKILL.md

Frontmatter:

---
name: <name>
description: Use when <trigger condition>. Short, specific description
  including keywords Claude can match against.
---

Тіло: - Короткий опис «коли запускати» - Список питань, які треба з'ясувати ДО старту (щоб не робити необов'язковий вибір за користувача) - Чекпоінти з шаблонами коду і посиланнями на референси в репо - Секція «Типові пастки» - (опційно) Пост-перевірки, які треба прогнати перед фіналом

Правило: skill — це не документація

Skill — інструкція для Claude, не для людини. Відповідно: - Пишіть в імперативі: «Створи X», «Перевір Y», а не «Ми зазвичай створюємо X». - Уникайте теорії і мотивації — лише дія. - Шаблони коду — повні, копі-пейстабельні, з placeholder'ами у форматі <Module>, <model>.

4. Hooks — автоматичні guard-и

Що вже налаштовано

.claude/settings.json реєструє PreToolUse hook, який блокує Write/Edit/MultiEdit на:

  • backend/**/migrations/*.py (крім __init__.py) — щоб випадково не зламати міграційну історію
  • *.sqlite3* (включно з .bak) — щоб не перезаписати dev-БД
  • .env* — щоб не витекли секрети в кодову базу
  • *.db — будь-які інші БД

Реалізація: .claude/hooks/guard.py. Скрипт читає JSON зі stdin (протокол Claude Code), повертає exit code 2 при блокуванні — Claude покаже причину і не застосує зміну.

Коли блокування — правильна поведінка

Якщо hook спрацював — не вимикайте його. Майже завжди правильний наступний крок: - Для міграцій: cd backend && python manage.py makemigrations <app> (Claude сам запропонує). - Для .env: попросіть Claude описати потрібну змінну в README або example.env, а реальний файл редагуйте самі. - Для db.sqlite3: використовуйте seed-команди замість ручного правлення.

Коли додавати новий hook

Якщо ви помітили систематичну проблему, яку можна автоматично запобігти: - Claude переписує package-lock.json — додайте матчер на нього - Claude забуває форматувати файл після редагування — додайте PostToolUse з prettier --write - Claude випадково комітить замість коміту через вас — тут краще memory/feedback, ніж hook

Уникайте хуків для косметичних речей — додають шум у вивід.

Важливий нюанс шляху

Hook command виконується в поточній cwd процесу Claude. Якщо користуєтесь відносним шляхом (python .claude/hooks/guard.py), воно зламається, як тільки bash у сесії зайшов у підкаталог. Ми використовуємо $CLAUDE_PROJECT_DIR — абсолютний шлях до корня проєкту, який Claude Code завжди експортує в env:

"command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard.py\""

5. Memory — що зберігається між сесіями

Claude зберігає нотатки в ~/.claude/projects/<project>/memory/*.md. Чотири типи:

Тип Приклад з нашого проекту
feedback «Завжди відповідати українською», «ERP skin scope — лише chrome», «Не запускати повний build після задачі»
project «CI/CD відкладено до колективної розробки — не пропонувати GitHub Actions без приводу»
reference (відсутні) — використовуй для посилань на зовнішні системи (Linear, Slack, Sentry URL)
user Ім'я, роль, email, мова

Що НЕ зберігати в memory

  • Факти, які виводяться з коду (структура файлів, назви моделей) — читай код.
  • Git-історія — для цього є git log.
  • Рецепти фіксу багів — фікс у коді, контекст у комміті.
  • Поточну задачу — для цього TodoWrite і план сесії.

Коли memory зіпсувалась

Якщо Claude апелює до memory, яка суперечить реальності: «memory каже, що X існує» vs «насправді X вилучено» — попросіть його прочитати реальність і оновити/видалити застарілий запис. Memory не священна.

6. Практичні прийоми роботи

Plan Mode для складних задач

Shift+Tab до режиму plan — Claude спочатку аналізує і показує план, нічого не редагує. Використовуйте для: - Рефакторингу, що зачіпає >3 файли - Незнайомих частин codebase - Коли потрібна валідація підходу перед кодом

Можна зробити дефолтним у налаштуваннях, якщо часто в нові зони лізете.

Checkpoints + Esc×2

Кожне повідомлення — checkpoint. Esc двічі — повернутись до попереднього стану. Не бійтеся експериментувати: замість ручних .bak файлів — це дешеве відкочування.

@-references

Глянь @frontend/erp/src/config/index.ts і додай секцію

Краще, ніж описувати словами. Claude точно читає саме цей файл, не шукає за схожими іменами.

«ultrathink» / «think hard»

Ключові слова в промпті підвищують бюджет reasoning'у для конкретної відповіді. Доречно для: - Архітектурних рішень (вибір між двома підходами) - Складних задач, де треба зважити tradeoff'и - Debug з неочевидною причиною

Для рутинних задач не потрібно.

/compact при довгих сесіях

Коли сесія >100 повідомлень — /compact <instruction> стискає історію. Приклад корисного instruction'у:

/compact Зберегти архітектурні рішення та активні задачі. Забути деталі форматування коду і проміжні експерименти.

/ultrareview перед великим мержем

Запускає багатоагентний cloud-ревью поточної гілки (або PR, якщо є номер). Білінгований. Не плутати з /review (локальний, дешевий, швидший).

Agent для паралельних досліджень

Замість того щоб самому грепати по 20 файлах — Agent з subagent_type: Explore. Агент повертає сумарі, ваш основний контекст не забивається результатами grep'ів.

7. Типові помилки нових розробників

Помилка Чому проблема Що робити
Викликати Claude з корня, коли задача — у frontend/erp/ У контекст потрапляє весь корневий CLAUDE.md, а не локальний cd frontend/erp перед сесією або в першому промпті
Додати модуль, але не оновити backend/CLAUDE.md Наступна сесія Claude не знатиме про нього Додавати запис у тому ж PR, що й сам модуль
Створити skill на «майбутню повторюваність» Skill застаріє ще до першого використання Робіть паттерн вручну ≥3 рази, потім фіксуйте
Редагувати файли міграцій, щоб «швидко підправити» Міграційна історія ломається, продакшн падає makemigrations + новий файл, не зачіпати старі
Копіювати наш CLAUDE.md в інший проект Там інший стек, інша структура — усе зламається CLAUDE.md — це specific знання про цей код. Новий проект — новий CLAUDE.md з /init
Ігнорувати блокування hook'у Обходите guard-и → втрачаєте дані Розберіться, чому блокує; майже завжди є штатний шлях
Не використовувати Plan Mode, коли Claude «здогадується» Неправильний напрям на початку → витрата контексту на виправлення Shift+Tab перед складною задачею

8. Чеклист при додаванні нової задачі

  1. Я розумію, де лежить код, який буду змінювати → відповідний CLAUDE.md підхоплено? (pwd підкаже)
  2. Задача нетривіальна (>3 кроки) → Plan Mode / ultrathink
  3. Є повторюваний патерн у цій задачі → перевір .claude/skills/ чи вже є skill
  4. Після завершення: чи змінилось щось, що вимагає оновлення CLAUDE.md або docs/?
  5. Чи не з'явилась нова feedback-думка, яку варто зберегти в memory?

9. Корисні посилання

Офіційна документація Claude Code: docs.anthropic.com/en/docs/claude-code (перевіряйте версію — фічі додаються швидко).