Практическое руководство по написанию 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 с пятью точными пунктами стоит больше, чем набитый шумом.