Skip to main content
skill CX Codex

ruby-on-rails-best-practices — Claude Code skill

ruby-on-rails-best-practices is a Claude Code skill that provides 16 Basecamp Rails conventions for models, thin controllers, background jobs, and Turbo broadcasts.

MIT 283 installs ★ 92 updated 2026-02-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sergiodxa/agent-skills --skill ruby-on-rails-best-practices -a claude-code
Open on GitHub

What ruby-on-rails-best-practices does

This skill provides 16 production-tested conventions drawn directly from Basecamp codebases (Fizzy and Campfire). It divides guidelines into six distinct groups covering model concerns, background jobs, controllers, request context, association callbacks, and real-time Turbo Streams.

The philosophy prioritizes the classic Rails Way without relying on service objects. Controllers and ActiveJob classes stay minimal by delegating directly to rich domain models. Model-specific concerns live in dedicated subdirectories like app/models/card/ instead of cluttering the shared app/models/concerns/ path.

Keep in mind that CurrentAttributes auto-populates solely inside standard HTTP requests. Background jobs, mailers, and Action Cable channels require explicit context setup as outlined in the rules.

What it helps with

  • Split bloated ActiveRecord models into model-scoped concerns
  • Eliminate service objects in favor of thin resource controllers
  • Pair synchronous domain methods with matching _later jobs
  • Trigger Turbo Stream broadcasts directly from controller actions

Example prompts for the agent

  • Refactor app/models/order.rb following Basecamp model concern rules
  • Convert these custom controller actions into RESTful resource controllers
  • Review this ActiveJob class against the thin-jobs convention

How to install ruby-on-rails-best-practices

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/ruby-on-rails-best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ruby-on-rails-best-practices/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ruby-on-rails-best-practices

How to install ruby-on-rails-best-practices in Claude Code?

Run npx skills add sergiodxa/agent-skills --skill ruby-on-rails-best-practices -a claude-code. The skill file will be placed in ~/.claude/skills/ruby-on-rails-best-practices/SKILL.md.

What does ruby-on-rails-best-practices do?

It guides coding assistants to write Ruby on Rails code according to Basecamp conventions, covering thin controllers, scoped concerns, fixtures over factories, and Turbo integration.

Where does this skill recommend placing model concerns?

Model-specific concerns belong in app/models/<model_name>/ using nested namespaces, keeping the root app/models/concerns/ folder reserved only for cross-model behavior.

Source text

SKILL.md · MIT
---
name: ruby-on-rails-best-practices
description: Ruby on Rails architecture and coding patterns from Basecamp. Use when writing, reviewing, or refactoring Rails code to follow proven conventions for models, controllers, jobs, and concerns. Triggers on tasks involving Rails models, concerns, controllers, background jobs, or Turbo/Hotwire.
---

# 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/`.

```ruby
# 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
```

#### concern-naming - @rules/concern-naming.md

Use `-able` suffix for behavior concerns, nouns for feature concerns.

```ruby
# Behaviors: -able suffix
module Card::Closeable     # Can be closed
module Card::Searchable    # Can be searched
module User::Mentionable   # Can be mentioned

# Features: nouns
module User::Avatar        # Has avatar
module User::Role          # Has role
module Card::Mentions      # Has @mentions
```

#### template-method-concerns - @rules/template-method-concerns.md

Use template methods in shared concerns for customizable behavior.

```ruby
# app/models/concerns/searchable.rb (shared)
module Searchable
  def search_title
    raise NotImplementedError
  end
end

# app/models/card/searchable.rb (model-specific)
module Card::Searchable
  include ::Searchable

  def search_title
    title  # Implement the hook
  end
end
```

### Background Jobs (HIGH)

#### paired-async-methods - @rules/paired-async-methods.md

Pair sync methods with `_later` variants that enqueue jobs.

```ruby
# app/models/card/readable.rb
def remove_inaccessible_notifications
  # Sync implementation
end

private
  def remove_inaccessible_notifications_later
    Card::RemoveInaccessibleNotificationsJob.perform_later(self)
  end

# app/jobs/card/remove_inaccessible_notifications_job.rb
class Card::RemoveInaccessibleNotificationsJob < ApplicationJob
  def perform(card)
    card.remove_inaccessible_notifications
  end
end
```

#### thin-jobs - @rules/thin-jobs.md

Jobs call model methods. All logic lives in models.

```ruby
# Bad: Logic in job
class ProcessOrderJob < ApplicationJob
  def perform(order)
    order.items.each { |i| i.product.decrement!(:stock) }
    order.update!(status: :processing)
  end
end

# Good: Job delegates to model
class ProcessOrderJob < ApplicationJob
  def perform(order)
    order.process  # Single method call
  end
end
```

### Controllers (HIGH)

#### resource-controllers - @rules/resource-controllers.md

Create resource controllers for state changes, not custom actions.

```ruby
# Bad: Custom actions
resources :cards do
  post :close
  post :reopen
end

# Good: Resource controllers
resources :cards do
  resource :closure, only: [:create, :destroy]
end

# app/controllers/cards/closures_controller.rb
class Cards::ClosuresController < ApplicationController
  def create
    @card.close
  end

  def destroy
    @card.reopen
  end
end
```

#### scoping-concerns - @rules/scoping-concerns.md

Use concerns like `CardScoped` for nested resource setup.

```ruby
# app/controllers/concerns/card_scoped.rb
module CardScoped
  extend ActiveSupport::Concern

  included do
    before_action :set_card
  end

  private
    def set_card
      @card = Current.user.accessible_cards.find_by!(number: params[:card_id])
    end
end

# Usage
class Cards::CommentsController < ApplicationController
  include CardScoped
end
```

#### thin-controllers - @rules/thin-controllers.md

Controllers call rich model APIs directly. No service objects.

```ruby
# Good: Thin controller, rich model
class Cards::ClosuresController < ApplicationController
  include CardScoped

  def create
    @card.close  # All logic in model
  end
end
```

### Request Context (MEDIUM)

#### current-attributes - @rules/current-attributes.md

Use `Current` for request-scoped data with cascading setters.

```ruby
class Current < ActiveSupport::CurrentAttributes
  attribute :session, :user, :account

  def session=(value)
    super(value)
    self.user = session&.user
  end
end
```

#### current-in-other-contexts - @rules/current-in-other-contexts.md

`Current` is only auto-populated in web requests. Jobs, mailers, and channels need explicit setup.

```ruby
# Jobs: extend ActiveJob to serialize/restore Current.account
# Mailers from jobs: wrap in Current.with_account { mailer.deliver }
# Channels: set Current in Connection#connect
```

### Associations & Callbacks (MEDIUM)

#### association-extensions - @rules/association-extensions.md

Choose between association extensions and model class methods based on context needs.

```ruby
# Use extension when you need parent context (proxy_association.owner)
has_many :accesses do
  def grant_to(users)
    board = proxy_association.owner
    Access.insert_all(users.map { |u| { user_id: u.id, board_id: board.id, account_id: board.account_id } })
  end
end

# Use class method when operation is independent
class Access
  def self.grant(board:, users:)
    insert_all(users.map { |u| { user_id: u.id, board_id: board.id } })
  end
end
```

#### callbacks-patterns - @rules/callbacks-patterns.md

Use `after_commit` for jobs, inline lambdas for simple ops.

```ruby
# Jobs: after_commit
after_create_commit :notify_recipients_later

# Simple ops: inline lambda
after_save -> { board.touch }, if: :published?

# Conditional: remember and check pattern
before_update :remember_changes
after_update_commit :process_changes, if: :should_process?
```

### Turbo & Real-time (MEDIUM)

#### turbo-broadcasts - @rules/turbo-broadcasts.md

Explicit broadcasts from controllers, not callbacks.

```ruby
# app/models/message/broadcasts.rb
module Message::Broadcasts
  def broadcast_create
    broadcast_append_to room, :messages, target: [room, :messages]
  end
end

# Controller calls explicitly
def create
  @message = @room.messages.create!(message_params)
  @message.broadcast_create
end
```

### Testing (MEDIUM)

#### fixtures-testing - @rules/fixtures-testing.md

Use fixtures, not factories. Mirror concern structure in tests.

```ruby
# test/fixtures/cards.yml
logo:
  title: The logo isn't big enough
  board: writebook
  creator: david

# test/models/card/closeable_test.rb
class Card::CloseableTest < ActiveSupport::TestCase
  test "close creates closure" do
    card = cards(:logo)
    assert_difference -> { Closure.count } do
      card.close
    end
  end
end
```

### Code Organization (LOW-MEDIUM)

#### nested-service-objects - @rules/nested-service-objects.md

Place service objects under model namespace, not `app/services`.

```ruby
# Good: app/models/card/activity_spike/detector.rb
class Card::ActivitySpike::Detector
  def initialize(card)
    @card = card
  end

  def detect
    # ...
  end
end
```

#### code-style - @rules/code-style.md

Prefer expanded conditionals, order methods by invocation.

```ruby
# Expanded conditionals
def find_record
  if record = find_by_id(id)
    record
  else
    NullRecord.new
  end
end

# Method ordering: caller before callees
def process
  step_one
  step_two
end

private
  def step_one; end
  def step_two; end
```

## Philosophy

These patterns embody "Vanilla Rails" - using Rails conventions with minimal additions:

1. **Rich models, thin controllers** - Domain logic in models and concerns
2. **No service object layer** - Controllers talk to models directly
3. **Co-located code** - Concerns, jobs, and services near the models they serve
4. **Explicit over implicit** - Call broadcasts explicitly, not via callbacks
5. **Convention over configuration** - Follow naming patterns for predictability

© sergiodxa · MIT · sergiodxa/agent-skills

Similar skills

All skills for Backend and APIs →

From the same set11

The whole set →
frontend-react-best-practices frontend-react-best-practices — a skill with 33 React performance rules: fewer wasted re-renders, leaner bundles, cleaner component composition. Useful while writing or refactoring components. CX Codex +1 1,200installs frontend-accessibility-best-practices frontend-accessibility-best-practices is a Claude Code skill with WCAG patterns for React components. It activates when building UI, forms or interactive elements, or reviewing code for accessibility. CX Codex +1 926installs frontend-tailwind-best-practices frontend-tailwind-best-practices is a Claude Code skill with 10 Tailwind CSS rules for component styling, covering stack utilities, gap spacing, dark color schemes, and className merging. CX Codex +1 470installs frontend-react-router-best-practices frontend-react-router-best-practices is a Claude Code skill that sets React Router architecture rules for parallel loaders and secure mutation handlers without client waterfalls. CX Codex +1 406installs frontend-js-best-practices frontend-js-best-practices provides 17 performance and style rules for JavaScript and TypeScript. Helps agents optimize loops, reduce algorithmic complexity, and avoid array mutations. CX Codex +1 341installs frontend-async-best-practices frontend-async-best-practices is a Claude Code skill for eliminating async waterfalls by parallelizing independent requests instead of awaiting them sequentially. CX Codex +1 228installs frontend-internationalization-best-practices frontend-internationalization-best-practices is a Claude Code skill with best practices for React Router and remix-i18next, covering middleware, locale detection, and SSR hydration sync. CX Codex +1 195installs skill-writing-best-practices skill-writing-best-practices provides guidelines and structural patterns for authoring AI agent skills. Useful when packaging codebase conventions or reviewing rules in skills/. CX Codex +1 176installs

Project sponsors

Companies that keep this analytics open