Praktyczny przewodnik po pisaniu CLAUDE.md: polecenia, architektura, zakazane operacje i odwołania do plików, na przykładzie prawdziwego projektu Rails.
Za każdym razem, gdy otwierasz Claude Code, zaczyna od zera — nie pamięta poprzedniej rozmowy, nie wie, co robi twój projekt, nie wie, czy polecenie testów to rspec czy pytest, i nie wie, które operacje są zakazane.
CLAUDE.md rozwiązuje ten problem. To trwały plik z instrukcjami, który piszesz dla Claude'a i który jest automatycznie ładowany na początku każdej rozmowy. Dobrze napisany CLAUDE.md pozwala Claude'owi od razu wejść w tryb pracy — bez zbędnych pytań, bez podstawowych błędów.
Claude Code obsługuje warstwowy system CLAUDE.md z trzema poziomami:
~/.claude/CLAUDE.md: Konfiguracja globalna, dotyczy wszystkich projektów. Używaj do ogólnych preferencji: „nigdy nie commituj automatycznie gita", „odpowiadaj po polsku".CLAUDE.md w katalogu głównym projektu: Konfiguracja na poziomie projektu. Najczęstsza lokalizacja.CLAUDE.md w podkatalogach: Ładowany tylko gdy Claude pracuje z plikami w tym katalogu. Idealny do osobnych instrukcji dla frontend/, api/ czy infra/.Wiele plików CLAUDE.md kumuluje się — bardziej specyficzne mają priorytet nad ogólniejszymi.
Jeden akapit mówiący Claude'owi, czym jest projekt i jakich technologii używa:
## 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)
Podanie numerów wersji jest ważne. Wiedząc, że to Rails 8, Claude nie będzie proponował wzorców z ery Rails 6. Wiedząc o 4 bazach danych, uniknie błędów w migracjach.
To sekcja o najwyższym zwrocie z inwestycji w każdym CLAUDE.md. Bez niej Claude zgaduje — i myli się.
## 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
Ta lista mówi Claude'owi: testy uruchamia się przez bundle exec rspec, nie rails test; deployment przez Kamal, nie Capistrano czy Fly.io; linter to RuboCop skonfigurowany z presetem Rails Omakase. Bez tego Claude musi zgadywać wszystko.
Celem notatek o architekturze jest dokumentowanie decyzji, które nie są widoczne w kodzie. Claude może odczytać strukturę katalogów; nie może wiedzieć, dlaczego jest tak zorganizowana.
## 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.
Te trzy punkty mówią Claude'owi: nie kumuluj logiki biznesowej w kontrolerach; szukaj reguł uprawnień w app/policies/; używaj Solid Queue do wszystkiego co wymaga przetwarzania asynchronicznego.
Grupowanie modeli domenowych według obszaru funkcjonalnego jest też wartościowe:
## 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)
To bardziej efektywne niż kazanie Claude'owi samodzielnie skanować app/models/, i przekazuje semantykę biznesową — jak fakt, że 400 punktów to próg VIP, co nie jest oczywiste z samego kodu.
To sekcja najczęściej pomijana i często najważniejsza:
## 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.
Wszystkie trzy to informacje typu „nie napiszesz — pożałujesz": multi-baza danych wymaga jawnego podania celu migracji; Lexxy to beta gem z innym zachowaniem niż standardowy ActionText; Propshaft działa inaczej niż Sprockets.
To najbardziej niedoceniana sekcja. Powiedzenie Claude'owi, czego nie robić, jest o wiele skuteczniejsze niż poprawianie go po fakcie.
## 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
Pierwszy punkt należy do niemal każdego projektu. Polecenie deployment jest jeszcze ważniejsze — przypadkowy bin/kamal deploy trafi prosto na produkcję.
CLAUDE.md obsługuje odwołania @ do włączania innych plików:
Konfiguracja deployment: @config/deploy.yml
Schemat bazy danych: @db/schema.rb
Claude czyta te pliki w razie potrzeby. db/schema.rb jest szczególnie przydatny — w projektach Rails to jedyne źródło prawdy o strukturze bazy danych.
Pisanie zbyt wiele: CLAUDE.md zużywa okno kontekstu. Wklejenie całego README zostawia mniej miejsca Claude'owi na pracę z prawdziwym kodem. Pisz tylko to, czego Claude nie może wywnioskować z czytania kodu.
Ogólnikowe wytyczne: „Pisz dobry kod" jest bezużyteczne. Bądź konkretny: „Nie umieszczaj logiki biznesowej bezpośrednio w kontrolerach — deleguj do app/services/".
Zapominanie o aktualizacji: Przejście z Sprockets na Propshaft czy z Sidekiq na Solid Queue — jeśli CLAUDE.md nie nadąża, Claude operuje na przestarzałych założeniach. Uwzględnij aktualizację CLAUDE.md w checkliście każdego większego refaktoringu.
Pisanie przykładów kodu: Przykłady zużywają kontekst, a Claude czyta prawdziwy kod dokładniej niż ilustracyjne fragmenty. Używaj odwołań @ do prawdziwych plików.
# [Nazwa projektu]
[Opis w jednym zdaniu]
- **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
[Jak rozdzielone są odpowiedzialności między Services / Jobs / Policies]
[Modele domenowe pogrupowane według obszaru funkcjonalnego]
## Important Notes
[Nieoczywista konfiguracja, specjalne zachowanie gemów]
## Do Not
- Do NOT run git commit automatically
[Inne operacje wysokiego ryzyka]
Zacznij od tego szablonu i wypełnij to, czego twój projekt naprawdę potrzebuje. Nie musisz obejmować wszystkiego — CLAUDE.md z pięcioma precyzyjnymi punktami jest wart więcej niż jeden wypełniony szumem.