Практичний посібник з написання CLAUDE.md: команди, архітектура, заборонені операції та посилання на файли на прикладі реального Rails-проєкту.
Кожного разу, коли ви відкриваєте Claude Code, він починає з нуля — не пам'ятає попередньої розмови, не знає, що робить ваш проєкт, не знає, яка команда запускає тести — rspec чи pytest, і поняття не має, які операції заборонені.
CLAUDE.md вирішує цю проблему. Це постійний файл інструкцій, який ви пишете для Claude і який автоматично завантажується на початку кожної розмови. Добре написаний CLAUDE.md дозволяє Claude одразу увійти в робочий режим — без зайвих запитань, без елементарних помилок.
Claude Code підтримує багаторівневу систему CLAUDE.md з трьома рівнями:
~/.claude/CLAUDE.md: Глобальна конфігурація, застосовується до всіх проєктів. Розміщуйте тут загальні уподобання: «ніколи не робити автоматичний git commit», «відповідати українською».CLAUDE.md у корені проєкту: Конфігурація на рівні проєкту. Найпоширеніше місце.CLAUDE.md у підкаталогах: Завантажується лише тоді, коли Claude працює з файлами цього каталогу. Зручно для окремих інструкцій для frontend/, api/ або infra/.Кілька файлів CLAUDE.md підсумовуються — більш специфічні мають пріоритет над більш загальними.
Один абзац, який пояснює Claude, що таке проєкт і які технології використовуються:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
Важливо вказувати номери версій. Знаючи, що це Rails 8, Claude не пропонуватиме патерни епохи Rails 6. Знаючи про 4 бази даних, не допустить помилок у міграціях.
Це розділ з найвищою віддачею в будь-якому CLAUDE.md. Без нього Claude вгадує — і помиляється.
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
Цей список повідомляє Claude: тести запускаються через bundle exec rspec, а не rails test; деплой через Kamal, а не Capistrano або Fly.io; лінтер — RuboCop з пресетом Rails Omakase. Без цього Claude доведеться вгадувати все.
Мета архітектурних нотаток — документувати рішення, які не видно в коді. Claude може читати структуру каталогів; він не може знати, чому вона організована саме так.
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
Ці три пункти повідомляють Claude: не накопичувати бізнес-логіку в контролерах; шукати правила доступу в app/policies/; використовувати Solid Queue для всього асинхронного.
Групування доменних моделей за функціональними областями також корисне:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
Це ефективніше, ніж змушувати Claude самостійно сканувати app/models/, і передає бізнес-семантику — наприклад, що 400 очок — це поріг VIP, що неочевидно з коду.
Цей розділ найчастіше ігнорується і нерідко є найкритичнішим:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
Всі три — з розряду «не напишеш — пошкодуєш»: мульти-БД вимагає явного зазначення цілі міграції; Lexxy — бета-гем з поведінкою, відмінною від стандартного ActionText; Propshaft працює інакше, ніж Sprockets.
Це найбільш недооцінений розділ. Сказати Claude, що робити не можна, набагато ефективніше, ніж виправляти його після.
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
Перший пункт потрібен майже в кожному проєкті. Команда деплою ще важливіша — випадковий bin/kamal deploy потрапить прямо у продакшн.
CLAUDE.md підтримує посилання @ для включення інших файлів:
Конфігурація деплою: @config/deploy.yml
Схема бази даних: @db/schema.rb
Claude читає ці файли за потреби. db/schema.rb особливо корисний — у Rails-проєктах це єдине джерело правди про структуру бази даних.
Писати занадто багато: CLAUDE.md споживає контекстне вікно. Вставити весь README — значить залишити менше місця Claude для роботи з реальним кодом. Пишіть лише те, що Claude не може вивести з читання кодової бази.
Розмиті правила: «Писати хороший код» марно. Будьте конкретні: «Не поміщати бізнес-логіку безпосередньо в контролери — делегувати в app/services/».
Забувати оновлювати: Перейшли з Sprockets на Propshaft — якщо CLAUDE.md не оновився, Claude працюватиме на застарілих припущеннях. Включіть оновлення CLAUDE.md у чеклист будь-якого великого рефакторингу.
Писати приклади коду: Приклади споживають контекст, а Claude читає реальний код точніше, ніж ілюстративні фрагменти. Використовуйте посилання @ на реальні файли.
# [Назва проєкту]
[Опис в одному реченні]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[Як розподілені обов'язки між Services / Jobs / Policies]
[Доменні моделі, згруповані за функціональними областями]
## Important Notes
[Неочевидна конфігурація, особлива поведінка гемів]
## Do Not
- Do NOT run git commit automatically
[Інші високоризиковані операції]
Починайте з цього шаблону і заповнюйте те, що дійсно потрібно вашому проєкту. Не потрібно охоплювати все — CLAUDE.md з п'ятьма точними пунктами коштує більше, ніж набитий шумом.