К основному содержанию
скилл CX Codex

ruby-on-rails-best-practices — скилл для Claude Code

Скилл ruby-on-rails-best-practices для Claude Code описывает 16 правил архитектуры Rails из практики Basecamp: модели, тонкие контроллеры, фоновые задачи и Turbo Streams.

MIT 283 установок ★ 92 обновлён 2026-02-01

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add sergiodxa/agent-skills --skill ruby-on-rails-best-practices -a claude-code
Открыть на GitHub

Что делает ruby-on-rails-best-practices

Скилл передаёт агенту проверенные конвенции из продакшена Basecamp (проекты Fizzy и Campfire). Внутри описано 16 правил по шести категориям: структура моделей, фоновые задачи, контроллеры, контекст запроса, ассоциации с колбэками и работа с Turbo Streams.

Архитектура опирается на классический Rails Way без сервисных объектов. Логика остаётся внутри богатых моделей, контроллеры и задачи ActiveJob остаются тонкими, а специфичные консерны раскладываются по подпапкам моделей (например, app/models/card/closeable.rb), а не сваливаются в общую директорию app/models/concerns/.

Учтите поведение CurrentAttributes: скилл явно напоминает, что объект Current автоматически заполняется только в веб-запросах, поэтому в фоновых задачах, рассыльщиках и каналах его контекст нужно настраивать вручную.

Какие задачи решает

  • Разложить раздутые модели на структурированные консерны в подпапках
  • Заменить сервисные объекты на тонкие контроллеры и методы моделей
  • Настроить фоновые задачи через парные асинхронные методы _later
  • Организовать явные трансляции Turbo Streams без неявных колбэков

Примеры запросов агенту

  • Сделай рефакторинг app/models/order.rb по правилам Basecamp для консернов
  • Перепиши контроллер с кастомными действиями на ресурсный контроллер
  • Проверь реализацию фоновой задачи на соответствие правилу thin-jobs

Как установить ruby-on-rails-best-practices

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/ruby-on-rails-best-practices/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о ruby-on-rails-best-practices

Как установить ruby-on-rails-best-practices в Claude Code?

Выполните команду npx skills add sergiodxa/agent-skills --skill ruby-on-rails-best-practices -a claude-code. Файл правил сохранится по пути ~/.claude/skills/ruby-on-rails-best-practices/SKILL.md.

Что делает этот скилл?

Он задаёт правила проектирования кода на Ruby on Rails: требует использовать фикстуры вместо фабрик, раскладывать специфичные консерны по подпапкам моделей и избегать создания сервисных объектов.

Как скилл предлагает организовывать фоновые задачи?

Правило thin-jobs требует оставлять задачи максимально простыми: воркер только вызывает метод модели, а вся бизнес-логика выполняется внутри самого класса модели.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
37signals-rails pproenca Скилл 37signals-rails для Claude Code и других агентов: 56 правил Rails в стиле 37signals — ванильный Rails, CRUD-контроллеры, богатые модели, Hotwire. Держит код в этой школе при написании и рефакторинге. CX Codex +1 347установок rails-hotwire pproenca Скилл rails-hotwire с правилами Hotwire для Rails: Turbo Drive, Frames, Streams, морфинг и контроллеры Stimulus. Пригодится при написании и рефакторинге интерактивных страниц. CX Codex +1 386установок ruby-rails Mindrally Скилл ruby-rails для Ruby on Rails в Claude Code. Задаёт конвенции Rails, подходы к ActiveRecord, Hotwire, фоновым задачам и тестам, чтобы агент писал идиоматичный код, а не boilerplate по своим лекалам. CX Codex +1 907установок rails-expert https://github.com/Jeffallan Скилл rails-expert для стека Rails 7+ с Hotwire, Sidekiq и RSpec. Помогает писать контроллеры, настраивать фоновые задачи и устранять проблемы с N+1. CX Codex +1 5 100установок ruby-on-rails официальный github Правило ruby-on-rails для GitHub Copilot задаёт стандарты написания кода, архитектурные принципы и рекомендации по работе с базой данных в приложениях на Rails 8. CX Codex +1 ★ 41 430звёзд репо ruby-rails-application aj-geddes Скилл ruby-rails-application помогает создавать приложения на Ruby on Rails по архитектуре MVC. Настраивает модели Active Record, REST-контроллеры, JWT-аутентификацию и миграции базы данных. CX Codex +1 661установок

Из того же набора11

Весь набор →
frontend-react-best-practices Скилл frontend-react-best-practices с 33 правилами по оптимизации React: меньше лишних ре-рендеров, аккуратнее бандл, чище композиция компонентов. Пригодится при написании и рефакторинге компонентов. CX Codex +1 1 200установок frontend-accessibility-best-practices Скилл frontend-accessibility-best-practices для Claude Code содержит стандарты WCAG для React-компонентов. Включается при создании UI, форм и интерактивных элементов, а также при проверке доступности кода. CX Codex +1 926установок frontend-tailwind-best-practices Скилл frontend-tailwind-best-practices для Claude Code и Codex: 10 правил Tailwind CSS — стеки, отступы через gap, тёмная тема и слияние классов. Контролирует стили компонентов и предотвращает поломку вёрстки. CX Codex +1 470установок frontend-react-router-best-practices Скилл frontend-react-router-best-practices для Claude Code задаёт архитектурные правила React Router: переносит загрузку данных в loader и помогает писать параллельные запросы и безопасные формы. CX Codex +1 406установок frontend-js-best-practices Скилл frontend-js-best-practices задаёт 17 правил оптимизации и стиля для JavaScript и TypeScript. Помогает писать быстрые циклы, избегать лишних аллокаций и убирать мутации массивов при рефакторинге. CX Codex +1 341установок frontend-async-best-practices Скилл frontend-async-best-practices для Claude Code помогает устранять waterfalls: заменяет последовательные ожидания независимых запросов параллельными. CX Codex +1 228установок frontend-internationalization-best-practices Скилл frontend-internationalization-best-practices для Claude Code описывает настройку i18n в React Router с remix-i18next: middleware, SSR-синхронизацию и словари. CX Codex +1 195установок skill-writing-best-practices Скилл skill-writing-best-practices задаёт стандарты оформления и структуры скиллов для ИИ-агентов. Пригодится при упаковке соглашений по коду и ревью файлов в папке skills/. CX Codex +1 176установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой