rails-playbook

Rails Playbook

This is the literal procedure a frontier model follows on a Rails codebase. Follow it in order; most Rails defects come from skipping the reconnaissance steps and writing "generic Rails" instead of THIS project's Rails.

Operating loop

1. Pin the stack before writing a line. Read Gemfile.lock:
   • Rails version: the rails (x.y.z) line. Stay inside that version's API — no Rails 7.x features in a 6.1 project.
   • Test framework: rspec-rails in the lockfile + a spec/ directory → bundle exec rspec; otherwise test/ → bin/rails test.
   • Lint: rubocop in the lockfile + .rubocop.yml present → rubocop is part of verification.
2. Check reality before adding to it.
   • Routes: bin/rails routes -g <resource> before adding any route — the route may already exist, or a catch-all may shadow yours.
   • Columns: read db/schema.rb (or structure.sql) for actual columns and indexes. Model files do not list columns; guessing them from attribute usage is how phantom-column bugs happen.
   • Pending migrations: bin/rails db:migrate:status | grep down — writing on top of an unmigrated schema wastes the whole session.
3. Read one neighboring model + controller in the same area and mirror them: service objects vs model methods, concerns usage, scope style, callback style. Convention in THIS repo beats convention in general.
4. Place and name files exactly where generators would even when writing by hand: app/models/user_profile.rb → class UserProfile, migrations via bin/rails generate migration AddXToY (the timestamp matters), tests mirroring app/ paths under test/ or spec/.
5. Build in this order: migration → model (validations, associations with explicit dependent:, scopes) → controller → view/serializer. Each layer is testable before the next exists.
6. Migration discipline:
   • One migration = schema change OR data change, never both.
   • Every foreign key column gets an index (add_reference does this by default since Rails 5; add_column :user_id does NOT — add it).
   • Every uniqueness validation ships with add_index ..., unique: true in the same change (see decision tree c).
   • Data migrations use raw SQL or a model class defined inside the migration file, never app/models classes — those will drift.
7. Run the verification recipe (below) and paste real output before reporting. A diff without executed commands is a claim, not a result.