Pins this version in aipm.package.json and aipm-lock.json.
aipm add @affaan-m/rails-patterns@1.0.0
Without project tracking
Writes the skill files only. Add --no-init to skip aipm.package.json and the lockfile.
aipm add @affaan-m/rails-patterns@1.0.0 --no-init
How to use
Install the skill above, then run this in your AI tool:
/rails-patterns <your description>
About
Framework patterns for modern Ruby on Rails applications (Rails 7.1+ and 8.x). Rails is opinionated by design; these are the patterns the community has converged on for apps that stay maintainable past the 50-model mark. This skill is the "how." For the "what" and "when" (the decisions about which pattern to reach for), see the Ruby patterns rules — `rules/ruby/patterns.md` in this repository, installed as `rules/ecc/ruby/patterns.md`.
Source
What gets added to your project
Preview every file this package writes on install before you run the command above.
Summary
x apps. Covers the directory contract, skinny controllers with service objects, form objects, query objects, idiomatic ActiveRecord, background jobs, ViewComponent, Hotwire, and the R...
Skill instructions
Rails Patterns
Framework patterns for modern Ruby on Rails applications (Rails 7.1+ and 8.x). Rails is opinionated by design; these are the patterns the community has converged on for apps that stay maintainable past the 50-model mark. This skill is the "how." For the "what" and "when" (the decisions about which pattern to reach for), see the Ruby patterns rules — rules/ruby/patterns.md in this repository, installed as rules/ecc/ruby/patterns.md.
When to Activate
Building a Rails application (full-stack, API-only, or hybrid)
Reviewing a PR that touches app/ or config/
Generating models, controllers, services, or jobs
A controller action grows past ~10 lines
A model file grows past ~200 lines
ActiveRecord queries start appearing in controllers or views
Core Concepts
The directory contract
Rails apps follow a predictable structure. Add directories deliberately, not casually.
code
app/
models/ ActiveRecord models. Persistence and domain logic close to the data.
controllers/ HTTP request handling. Thin orchestration only.
views/ ERB templates. No business logic.
components/ ViewComponent classes. View logic that needs tests.
services/ Service objects. Multi-step business operations.
forms/ Form objects. Complex form handling across multiple models.
queries/ Query objects. Reusable, composable ActiveRecord queries.
jobs/ Background jobs. Async work via Solid Queue, Sidekiq, or GoodJob.
mailers/ ActionMailer classes.
helpers/ View helpers. Tiny presentational logic only.
policies/ Authorization policies (if using Pundit). Optional.
channels/ ActionCable channels for WebSocket work.
Avoid app/lib/, app/utils/, app/managers/. If something does not fit the directories above, the design usually needs rethinking, not a new directory. Truly generic code goes in lib/.
Skinny controllers
Controllers receive a request, delegate to the right object, and render a response. Business logic lives elsewhere. (Per the Ruby patterns rules, extract to a service object when the controller starts carrying multiple responsibilities.)
Service objects
The default for business operations that touch more than a single model save. Conventions that keep them consistent:
Namespace by domain (Invoices::Create), not by suffix (InvoiceCreator).
A class method .call delegates to an instance #call.
Return a Result object, not a boolean or a bare record, so the caller can branch on success, errors, and the affected record.
Wrap multi-record writes in a transaction.
Keep each service single-purpose (Invoices::Create, Invoices::MarkPaid), never Invoices::Manager.
Form objects
When a form spans multiple models or has fields that do not map to columns, use a form object rather than nested attributes or virtual attributes on the wrong model. It quacks like a model to the view (form_with model: @form) while composing records cleanly.
Query objects
For ActiveRecord queries reused across controllers or services, or too complex for a scope, extract a query object that accepts a scope as input so it composes. Rule of thumb: a scope that grows past three chained conditions or starts taking parameters wants to be a query object.
Background jobs
Offload anything slow. (Per the Ruby patterns rules, Solid Queue for greenfield Rails 8 with modest throughput; Sidekiq when you need mature observability, high throughput, or existing Redis.) Regardless of adapter: pass IDs not records, make perform idempotent, and set retry_on/discard_on explicitly.
ViewComponent over partials
For view logic with conditional rendering, more than two arguments, or reuse across more than three places, prefer a ViewComponent. Components are testable in isolation and surface their interface explicitly; partials with deep conditional logic become debt.
Hotwire: Turbo and Stimulus
The default Rails frontend stack. (Per the Ruby patterns rules, prefer Hotwire for server-rendered apps; reach for React/Vue only when interaction complexity justifies the client surface.) Turbo Frames for partial page updates, Turbo Streams for server-driven updates, Stimulus for small client-side behaviors next to the markup.
The Rails 8 Solid stack
Rails 8 ships database-backed defaults that previously needed Redis: Solid Queue (jobs), Solid Cache (cache), Solid Cable (ActionCable). The tradeoff is more database load for one fewer infrastructure component; a good fit for modest throughput, with Redis still winning at high scale. Kamal is the default Docker-based deploy tool.
Code Examples
Skinny controller with a service object
ruby
# Bad: business logic in the controllerclassInvoicesController < ApplicationControllerdefcreate@invoice = Invoice.new(invoice_params)
@invoice.user = current_user
@invoice.line_items.build(invoice_params[:line_items])
@invoice.tax_total = TaxCalculator.new(@invoice).calculate
@invoice.total = @invoice.line_items.sum(&:amount) + @invoice.tax_total
if@invoice.save
InvoiceMailer.created(@invoice).deliver_later
AccountingExportJob.perform_later(@invoice.id)
redirect_to @invoice, notice:"Invoice created"else
render :newendendend# Good: controller orchestrates, service does the workclassInvoicesController < ApplicationControllerdefcreate
result = Invoices::Create.call(params: invoice_params, user: current_user)
if result.success?
redirect_to result.invoice, notice:"Invoice created"else@invoice = result.invoice
render :new, status::unprocessable_entityendendend
The service object
ruby
# app/services/invoices/create.rbmoduleInvoicesclassCreate# Struct keeps this runnable on every Ruby that Rails 7.1 supports.# On Ruby 3.2+, `Data.define(:success?, :invoice, :errors)` is a more# concise immutable alternative.Result = Struct.new(:success, :invoice, :errors, keyword_init:true) dodefsuccess?
success
endenddefself.call(params:, user:)
new(params: params, user: user).call
enddefinitialize(params:, user:)
@params = params
@user = user
enddefcall
invoice = build_invoice
ApplicationRecord.transaction do
invoice.save!
endbegin
send_notifications(invoice)
rescueStandardError => e
Rails.logger.error("Notification dispatch failed for invoice #{invoice.id}: #{e.message}")
endResult.new(success:true, invoice: invoice, errors:nil)
rescueActiveRecord::RecordInvalid => e
Result.new(success:false, invoice: e.record, errors: e.record.errors)
endprivateattr_reader:params, :userdefbuild_invoice
invoice = user.invoices.new(params.except(:line_items))
invoice.line_items.build(params[:line_items])
invoice.tax_total = TaxCalculator.call(invoice)
invoice.total = invoice.line_items.sum(&:amount) + invoice.tax_total
invoice
enddefsend_notifications(invoice)
InvoiceMailer.created(invoice).deliver_later
AccountingExportJob.perform_later(invoice.id)
endendend
Query objects accept a scope, so they compose: Invoices::Overdue.call(scope: current_user.invoices).
N+1 prevention
ruby
# Bad: N+1 in the view when it calls post.author.name@posts = Post.published
# Good: eager load@posts = Post.published.includes(:author)
includes lets Rails choose preload vs eager_load. Force preload for separate queries, eager_load for a JOIN when filtering on the association. Since Rails 6.1, strict_loading raises on accidental lazy loads.
post.comments_count becomes a column read instead of a COUNT(*). This example
assumes a new table; adding a counter cache to a table that already has rows requires a
backfill, which is out of scope here.
Background job shape
Pass record IDs, not records. Retries make delivery at-least-once, so any job that calls
an external service must be idempotent — otherwise a transient failure after the remote
call succeeds will duplicate the effect on the next attempt.
The unique index is what makes this safe: when two attempts race, the database rejects
the second insert and Active Record resolves the conflict inside the call, returning the
existing row. That happens without any job-level retry — retry_on above covers only
AccountingApi::TransientError. The guard
covers the window before the remote call; passing idempotency_key through to the API
covers the window after it, so a crash between the API call and update! still resolves
to a single export.
# Acceptable: pure data normalizationclassUser < ApplicationRecord
before_validation :normalize_emailprivatedefnormalize_emailself.email = email.to_s.downcase.strip
endend# Move to a service instead: side effects hidden in a callback# class User < ApplicationRecord# after_create :send_welcome_email # hard to opt out of, hard to test# end
Good concern vs bad concern
ruby
# Good: genuinely cross-cutting, reusable across unrelated models# app/models/concerns/soft_deletable.rbmoduleSoftDeletableextendActiveSupport::Concern
included do
scope :active, -> { where(deleted_at:nil) }
scope :deleted, -> { where.not(deleted_at:nil) }
enddefsoft_delete! = update!(deleted_at:Time.current)
defrestore! = update!(deleted_at:nil)
end# Bad: a "concern" used by exactly one model, holding logic that belongs on it# app/models/concerns/invoice_calculations.rbmoduleInvoiceCalculationsextendActiveSupport::Concerndefcalculate_total
line_items.sum(&:amount) + tax_total
endend# Only Invoice includes this. It isn't cross-cutting; it's Invoice's own logic# hidden in a module for the appearance of a "skinny" model. Put it back on Invoice.
A concern used by only one class is just moving code; it belongs in that class. A concern should be reusable across at least two unrelated models.
Anti-Patterns
God controllers
Any controller past ~80 lines is doing too much. Split actions across controllers or extract to services.
Fat models with 30+ methods
Models should know about their own data. Methods that orchestrate other models, send notifications, or coordinate workflows belong in services.
Callback chains
after_save :update_cache, :send_notifications, :enqueue_export is the start of a debugging nightmare. Move them into a service that runs them explicitly.
Nested attributes for complex forms
accepts_nested_attributes_for is fine for simple cases. For conditional validation or cross-model logic, use a form object.
Default scopes on critical models
default_scope { where(deleted: false) } silently excludes records from every query in the app, including the ones you need for support and debugging. Prefer an explicit named scope.
Models named after database concepts
UserRole, OrderStatus, InvoiceState are usually enum candidates, not models.
Reaching for a JS framework before Hotwire
If the page is server-rendered with occasional interactivity, Hotwire ships faster. Reserve React/Vue for genuinely SPA-shaped apps.
Best Practices
Keep controllers thin; push business logic into services.
Return Result objects from services so callers branch on outcome, not exceptions.
Wrap multi-record writes in a transaction; let notification/side-effect failures log without breaking the primary write.
Pass IDs to jobs, keep perform idempotent, set retry/discard explicitly.
Default to eager loading; treat an accidental N+1 as a bug, not a nuisance.
Reserve concerns for behavior shared across at least two unrelated models.
Reach for Hotwire before a client-side framework on server-rendered apps.
Related Skills
backend-patterns — service boundaries and adapter patterns (referenced by the Ruby patterns rules)
Ruby patterns rules (rules/ruby/patterns.md, installed as rules/ecc/ruby/patterns.md) — the decisions and when-to-use guidance this skill implements
Add this badge to a GitHub README so readers can open the package page and install the same version.
[](https://www.aipm-registry.com/skills/affaan-m/rails-patterns/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)
This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.
AI assistant context
What this skill is for
@affaan-m/rails-patterns@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: Ruby on Rails framework patterns for Rails 7.1+ and 8.x apps. Covers the directory contract, skinny controllers with service objects, form objects, query objects, idiomatic ActiveRecord, background jobs, ViewComponent, Hotwire, and the R...
Preview a UI component mockup in a local browser canvas where the human directly edits it (move, resize, edit text, delete, restyle), switches mobile/desktop/custom viewports, tests it, chats with you, and clicks Save and Finish. You the...
Run aipm add @affaan-m/rails-patterns@1.0.0 in a project that has AIPM initialized.
Supported tools
@affaan-m/rails-patterns@1.0.0 supports All tools.
Before installing
AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.