Guide pratique pour écrire CLAUDE.md : commandes, architecture, opérations interdites et références de fichiers, illustré avec un vrai projet Rails.
Chaque fois que vous ouvrez Claude Code, il repart de zéro — aucun souvenir de la session précédente, aucune idée de ce que fait votre projet, aucune connaissance de vos commandes de test ni des opérations interdites.
CLAUDE.md règle ce problème. C'est un fichier d'instructions persistant que vous écrivez pour Claude, chargé automatiquement au début de chaque conversation. Un bon CLAUDE.md permet à Claude d'être opérationnel immédiatement — sans questions superflues, sans erreurs de débutant.
Claude Code supporte un système de CLAUDE.md en couches avec trois niveaux :
~/.claude/CLAUDE.md : Configuration globale, s'applique à tous vos projets. Pour vos préférences universelles : « ne jamais committer git automatiquement », « répondre en français ».CLAUDE.md à la racine du projet : Configuration au niveau projet. L'emplacement le plus courant.CLAUDE.md dans les sous-répertoires : Chargé uniquement quand Claude travaille sur les fichiers de ce répertoire. Idéal pour donner des instructions spécifiques à frontend/, api/ ou infra/.Les fichiers CLAUDE.md s'accumulent — les plus spécifiques ont la priorité sur les plus généraux.
Un paragraphe indiquant à Claude ce qu'est le projet et quelles technologies il utilise :
## 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)
Inclure les numéros de version est important. Savoir que c'est Rails 8 évite les suggestions de patterns de l'ère Rails 6. Savoir qu'il y a 4 bases de données évite les erreurs dans les migrations.
C'est la section à plus fort retour sur investissement de tout CLAUDE.md. Sans elle, Claude devine — et se trompe.
## 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
Cette liste indique à Claude : les tests se lancent avec bundle exec rspec, pas rails test ; le déploiement se fait avec Kamal, pas Capistrano ou Fly.io ; le linter est RuboCop configuré avec le preset Rails Omakase. Sans ça, Claude doit tout deviner.
L'objectif des notes d'architecture est de documenter les décisions qui ne sont pas visibles dans le code. Claude peut lire la structure des répertoires ; il ne peut pas savoir pourquoi elle est organisée ainsi.
## 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.
Ces trois points indiquent à Claude : ne pas accumuler la logique métier dans les contrôleurs ; chercher les règles de permissions dans app/policies/ ; utiliser Solid Queue pour tout traitement asynchrone.
Regrouper les modèles de domaine par zone fonctionnelle est également utile :
## 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)
C'est plus efficace que de laisser Claude scanner app/models/ lui-même, et cela transmet la sémantique métier — comme le fait que 400 points est le seuil VIP, ce qui n'est pas évident à la lecture du code.
C'est la section la plus souvent négligée, et souvent la plus critique :
## 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.
Ces trois points sont du type « ne pas les écrire et vous le regretterez » : la configuration multi-bases nécessite de spécifier la cible de la migration ; Lexxy est une gem en beta avec un comportement différent de l'ActionText standard ; Propshaft fonctionne différemment de Sprockets.
C'est la section la plus sous-estimée. Dire à Claude ce qu'il ne doit pas faire est bien plus efficace que de le corriger après coup.
## 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
Le premier point s'applique à presque tous les projets. La commande de déploiement est encore plus importante — un bin/kamal deploy accidentel touche la production directement.
CLAUDE.md supporte les références @ pour inclure d'autres fichiers :
Configuration de déploiement : @config/deploy.yml
Schéma de base de données : @db/schema.rb
Claude lit ces fichiers quand c'est nécessaire. db/schema.rb est particulièrement utile — dans les projets Rails c'est la source de vérité unique pour la structure de la base de données.
Écrire trop : CLAUDE.md consomme de la fenêtre de contexte. Coller tout le README laisse moins de place à Claude pour travailler avec le code réel. N'écrivez que ce que Claude ne peut pas déduire en lisant le code.
Des directives vagues : « Écrire du bon code » ne sert à rien. Soyez précis : « Ne pas mettre de logique métier directement dans les contrôleurs — déléguer à app/services/ ».
Oublier de mettre à jour : Si vous migrez de Sprockets vers Propshaft et que CLAUDE.md n'est pas mis à jour, Claude opérera sur des hypothèses obsolètes. Incluez la mise à jour de CLAUDE.md dans la checklist de tout refactoring important.
Écrire des exemples de code : Les exemples consomment du contexte, et Claude lit le code réel avec plus de précision que des snippets illustratifs. Utilisez des références @ pour pointer vers des fichiers réels.
# [Nom du projet]
[Description en une phrase]
- **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
[Comment se répartissent les responsabilités entre Services / Jobs / Policies]
[Modèles de domaine regroupés par zone fonctionnelle]
## Important Notes
[Configuration non évidente, comportement spécial des gems]
## Do Not
- Do NOT run git commit automatically
[Autres opérations à haut risque]
Partez de ce modèle et remplissez ce que votre projet nécessite vraiment. Pas besoin de tout couvrir — un CLAUDE.md avec cinq points précis vaut mieux qu'un rempli de bruit.