Guía práctica para escribir CLAUDE.md: comandos, arquitectura, operaciones prohibidas y referencias a archivos, con un proyecto Rails real.
Cada vez que abres Claude Code, empieza desde cero — sin memoria de la sesión anterior, sin saber qué hace tu proyecto, sin saber si el comando de prueba es rspec o pytest, y sin conocer qué operaciones están prohibidas.
CLAUDE.md resuelve esto. Es un archivo de instrucciones persistente que le escribes a Claude y que se carga automáticamente al inicio de cada conversación. Un buen CLAUDE.md hace que Claude entre en modo trabajo de inmediato — sin preguntas innecesarias, sin errores básicos.
Claude Code soporta un sistema de CLAUDE.md en capas con tres niveles:
~/.claude/CLAUDE.md: Configuración global, aplica a todos tus proyectos. Úsala para preferencias universales como "nunca hagas auto-commit de git" o "responde en español".CLAUDE.md en la raíz del proyecto: Configuración a nivel de proyecto. La ubicación más común.CLAUDE.md en subdirectorios: Solo se carga cuando Claude trabaja con archivos de ese directorio. Ideal para darle instrucciones específicas a frontend/, api/ o infra/.Los archivos CLAUDE.md se apilan — los más específicos tienen prioridad sobre los más generales.
Un párrafo que le diga a Claude qué es el proyecto y qué tecnologías usa:
## 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)
Incluir los números de versión es importante. Saber que es Rails 8 evita que Claude sugiera patrones de la era de Rails 6. Saber que hay 4 bases de datos evita errores en las migraciones.
Esta es la sección de mayor retorno en cualquier CLAUDE.md. Sin ella, Claude adivina — y adivina mal.
## 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
Esta lista le dice a Claude: las pruebas van con bundle exec rspec, no con rails test; el despliegue es con Kamal, no con Capistrano o Fly.io; el linter es RuboCop con el preset de Rails Omakase. Sin esto, Claude tiene que adivinarlo todo.
El objetivo de las notas de arquitectura es documentar decisiones que no son visibles en el código. Claude puede leer la estructura de directorios; no puede saber por qué está organizada así.
## 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.
Estos tres puntos le dicen a Claude: no acumules lógica de negocio en los controladores; busca las reglas de permisos en app/policies/; usa Solid Queue para todo lo que necesite procesamiento asíncrono.
Agrupar los modelos de dominio por área funcional también aporta valor:
## 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)
Esto es más eficiente que hacer que Claude escanee app/models/ por su cuenta, y además transmite semántica de negocio — como que 400 puntos es el umbral VIP, algo que no es obvio leyendo el código.
Esta es la sección más ignorada y, frecuentemente, la más crítica:
## 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.
Estos tres puntos son "no los escribas y te arrepentirás": la configuración multibases de datos requiere especificar el objetivo de la migración; Lexxy es una gem en beta con comportamiento diferente al ActionText estándar; Propshaft funciona de forma distinta a Sprockets.
Esta es la sección más subestimada. Decirle a Claude qué no debe hacer es mucho más eficiente que corregirlo después.
## 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
El primer punto pertenece a casi cualquier proyecto. El comando de despliegue es aún más importante — un bin/kamal deploy accidental llega directo a producción.
CLAUDE.md soporta referencias @ para incluir otros archivos:
Configuración de despliegue: @config/deploy.yml
Esquema de base de datos: @db/schema.rb
Claude lee estos archivos cuando es necesario. db/schema.rb es especialmente útil — en proyectos Rails es la fuente única de verdad para la estructura de la base de datos.
Escribir demasiado: CLAUDE.md consume ventana de contexto. Pegar el README completo deja menos espacio para que Claude trabaje con el código real. Escribe solo lo que Claude no puede derivar leyendo el código.
Directrices vagas: "Escribe buen código" no sirve de nada. Sé específico: "No pongas lógica de negocio directamente en los controladores — delega a app/services/".
Olvidar actualizar: Si migras de Sprockets a Propshaft y CLAUDE.md no se actualiza, Claude operará con supuestos obsoletos. Incluye la actualización de CLAUDE.md en el checklist de cualquier refactorización importante.
Escribir ejemplos de código: Los ejemplos consumen contexto, y Claude lee código real con más precisión que snippets ilustrativos. Usa referencias @ para apuntar a archivos reales.
# [Nombre del proyecto]
[Descripción en una frase]
- **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
[Cómo se dividen responsabilidades entre Services / Jobs / Policies]
[Modelos de dominio agrupados por área funcional]
## Important Notes
[Configuración no obvia, comportamiento especial de gems]
## Do Not
- Do NOT run git commit automatically
[Otras operaciones de alto riesgo]
Empieza aquí y rellena lo que tu proyecto realmente necesita. No tienes que cubrirlo todo — un CLAUDE.md con cinco puntos precisos vale más que uno relleno de ruido.