CLAUDE.md

Rails Project Guidelines

Overview

This is a Ruby on Rails application. Follow Rails conventions and the patterns established in this codebase.

Tech Stack

  • Framework: Ruby on Rails 8
  • Database: PostgreSQL
  • Frontend: Hotwire (Turbo + Stimulus)
  • CSS: TailwindCSS
  • Testing: RSpec, FactoryBot
  • Linting: StandardRB

Development Commands

# Setup
bin/setup

# Run server
bin/dev

# Run tests
bundle exec rspec

# Run linter
bundle exec standardrb

# Run linter with auto-fix
bundle exec standardrb --fix

# Database commands
bin/rails db:migrate
bin/rails db:seed
bin/rails db:reset

Rails Conventions

  • Follow RESTful routing patterns
  • Keep controllers thin, models fat
  • Use concerns for shared behavior
  • Use service objects for complex business logic
  • Use query objects for complex database queries

Code Organization

  • app/models/ - ActiveRecord models and business logic
  • app/controllers/ - Request handling, keep thin
  • app/views/ - ERB templates with Turbo Frames
  • app/javascript/controllers/ - Stimulus controllers
  • app/services/ - Service objects for complex operations
  • app/jobs/ - Background jobs (Solid Queue)

Testing

  • Write request specs for controller actions
  • Write model specs for validations and methods
  • Use FactoryBot for test data
  • Run bundle exec rspec before committing

Hotwire Patterns

  • Use Turbo Frames for partial page updates
  • Use Turbo Streams for real-time updates
  • Keep Stimulus controllers focused and small
  • Prefer server-rendered HTML over client-side JS

Database

  • Write reversible migrations when possible
  • Add indexes for foreign keys and frequently queried columns
  • Use null: false constraints where appropriate
  • Prefer database-level constraints over model validations alone

Security

  • Never disable CSRF protection
  • Use strong parameters in controllers
  • Sanitize user input in views
  • Keep secrets in credentials or environment variables