Ruby On Rails Best Practices

This extracts the architectural patterns Basecamp uses in production Rails apps like Fizzy and Campfire. You get 16 rules covering where to put concerns (scoped under models, not in a shared folder), how to name them (behaviors get -able suffixes), keeping jobs and controllers thin by pushing logic into models, and when to use resource controllers instead of custom actions. The template method pattern for shared concerns is smart, and the guidance on explicit Turbo broadcasts from controllers instead of callbacks will save you debugging time. Most valuable if you're tired of Rails codebases that feel organized differently in every directory and want opinionated conventions that scale.

skills.sh installs: 282
GitHub stars: 92
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add sergiodxa/agent-skills --skill ruby-on-rails-best-practices --agent claude-code

Installs into .claude/skills of the current project.

Files

Ruby on Rails Best Practices

Architecture patterns and coding conventions extracted from Basecamp's production Rails applications (Fizzy and Campfire). Contains 16 rules across 6 categories focused on code organization, maintainability, and following "The Rails Way" with Basecamp's refinements.

When to Apply

Reference these guidelines when:

Organizing models, concerns, and controllers
Writing background jobs
Implementing real-time features with Turbo Streams
Deciding where code should live
Writing tests for Rails applications
Reviewing Rails code for architectural consistency

Rules Summary

Model Organization (HIGH)

model-scoped-concerns - @rules/model-scoped-concerns.md

Place model-specific concerns in app/models/model_name/ not app/models/concerns/.

# Directory structure
app/models/
├── card.rb
├── card/
│   ├── closeable.rb     # Card::Closeable
│   ├── searchable.rb    # Card::Searchable
│   └── assignable.rb    # Card::Assignable

# app/models/card.rb
class Card < ApplicationRecord
  include Closeable, Searchable, Assignable
  # Ruby resolves from Card:: namespace first
end