rails-workflow
Ruby on Rails framework workflow guidelines. Activate when working with Rails projects, Gemfile with rails, rake tasks, or Rails-specific patterns.
When & Why to Use This Skill
This Claude skill provides a comprehensive Ruby on Rails workflow and architecture guide, specifically optimized for Rails 8.x. It streamlines development by enforcing industry best practices for service objects, model organization, and modern front-end integration with Hotwire and Stimulus. By integrating security audits, testing protocols, and database management standards, it ensures the delivery of secure, scalable, and maintainable Rails applications.
Use Cases
- Architecting new Rails 8 projects using built-in authentication and database-backed background jobs like Solid Queue.
- Refactoring 'fat controllers' into modular Service Objects to improve code maintainability and testability.
- Implementing modern, reactive front-ends using Turbo Frames, Turbo Streams, and Stimulus controllers without complex JavaScript frameworks.
- Enforcing security best practices by integrating Brakeman audits and parameterized SQL queries into the development lifecycle.
- Standardizing testing suites with RSpec for model validations, request specs, and system-wide quality assurance.
| name | rails-workflow |
|---|---|
| description | Ruby on Rails framework workflow guidelines. Activate when working with Rails projects, Gemfile with rails, rake tasks, or Rails-specific patterns. |
| location | user |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Rails Workflow
Tool Grid
| Task | Tool | Command |
|---|---|---|
| Lint | StandardRB + standard-rails | bundle exec standardrb |
| Security | Brakeman | bundle exec brakeman |
| Test | RSpec Rails | bundle exec rspec |
| Console | Rails | bundle exec rails console |
| Server | Rails | bundle exec rails server |
| Routes | Rails | bundle exec rails routes |
Rails 8.x Features
Built-in Authentication
bundle exec rails generate authentication
Creates User with password_digest, Session controller, and authentication concern. You SHOULD use built-in auth for new projects.
Solid Queue (Background Jobs)
Database-backed, no Redis required. Rails 8 default.
config.active_job.queue_adapter = :solid_queue
Solid Cache & Solid Cable
Database-backed caching and Action Cable adapter:
config.cache_store = :solid_cache_store # production.rb
adapter: solid_cable # cable.yml
Controller Patterns
Controllers MUST delegate business logic to service objects:
# GOOD - Thin controller
def create
result = Orders::CreateService.call(order_params, current_user)
result.success? ? redirect_to(result.order) : render(:new, status: :unprocessable_entity)
end
Strong Parameters
You MUST use strong parameters. NEVER use params.permit! in production:
def user_params
params.require(:user).permit(:name, :email, address_attributes: [:street, :city])
end
Service Objects
Services MUST follow a consistent pattern:
module Orders
class CreateService
Result = Struct.new(:success?, :order, :errors, keyword_init: true)
def self.call(...) = new(...).call
def initialize(params, user)
@params, @user = params, user
end
def call
order = Order.new(@params.merge(user: @user, status: :pending))
order.save ? Result.new(success?: true, order:) : Result.new(success?: false, order:, errors: order.errors)
end
end
end
Naming: CreateService, UpdateService, ProcessService, SyncService
Model Organization
Models SHOULD follow this order:
class User < ApplicationRecord
# 1. Constants
ROLES = %w[admin member guest].freeze
# 2. Associations
belongs_to :organization
has_many :posts, dependent: :destroy
# 3. Validations
validates :email, presence: true, uniqueness: true
validates :role, inclusion: { in: ROLES }
# 4. Callbacks (use sparingly)
after_create :send_welcome_email
# 5. Scopes
scope :active, -> { where(active: true) }
scope :admins, -> { where(role: "admin") }
# 6. Class methods
# 7. Instance methods
end
For complex queries, extract to query objects in app/queries/.
Security
Brakeman
You MUST run Brakeman before deployment. All warnings MUST be resolved:
bundle exec brakeman --no-pager
Common Patterns
# SQL injection prevention - use parameterized queries
User.where("email = ?", params[:email]) # GOOD
User.where("email = '#{params[:email]}'") # BAD
# XSS - Rails auto-escapes. Use sanitize for HTML content
<%= sanitize @user.bio %>
Background Jobs
class ProcessOrderJob < ApplicationJob
queue_as :default
retry_on StandardError, wait: :polynomially_longer, attempts: 5
discard_on ActiveRecord::RecordNotFound
def perform(order_id)
Orders::ProcessService.call(Order.find(order_id))
end
end
Action Cable
class NotificationsChannel < ApplicationCable::Channel
def subscribed
stream_for current_user
end
end
# Broadcasting
NotificationsChannel.broadcast_to(user, { type: "new_message", content: message.body })
View Components
class ButtonComponent < ViewComponent::Base
def initialize(text:, variant: :primary)
@text, @variant = text, variant
end
def call
tag.button(@text, class: "btn btn-#{@variant}")
end
end
Hotwire / Stimulus
Turbo Frames
<%= turbo_frame_tag "user_stats", src: user_stats_path, loading: :lazy %>
Turbo Streams
respond_to do |format|
format.turbo_stream
format.html { redirect_to @post }
end
<%= turbo_stream.prepend "comments", @comment %>
Stimulus Controllers
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["input", "output"]
validate() {
this.outputTarget.textContent = this.inputTarget.value.length > 0 ? "Valid" : "Required"
}
}
<div data-controller="form">
<input data-form-target="input" data-action="input->form#validate">
<span data-form-target="output"></span>
</div>
Testing
Model Specs
RSpec.describe User, type: :model do
it { is_expected.to validate_presence_of(:email) }
it { is_expected.to have_many(:posts).dependent(:destroy) }
end
Request Specs
RSpec.describe "Posts", type: :request do
it "creates a post" do
sign_in(user)
expect { post posts_path, params: { post: valid_attributes } }.to change(Post, :count).by(1)
end
end
Database
You MUST use reversible migrations:
class AddStatusToOrders < ActiveRecord::Migration[8.0]
def change
add_column :orders, :status, :string, default: "pending", null: false
add_index :orders, :status
end
end
File Structure
app/
channels/
components/
controllers/
jobs/
models/
queries/
services/
views/
config/
solid_queue.yml
cable.yml
spec/
factories/
models/
requests/
services/