ruby-on-rails-best-practices_skill

Overview

This skill captures Ruby on Rails architecture and coding patterns inspired by Basecamp’s production apps. It focuses on organizing models, controllers, background jobs, concerns, and Turbo/Hotwire interactions to keep code maintainable and idiomatic. Use it when writing, reviewing, or refactoring Rails code to follow proven, convention-driven patterns.

How this skill works

The skill inspects tasks that involve Rails models, concerns, controllers, background jobs, or Turbo/Hotwire features and suggests concrete changes to align code with the patterns. It enforces co-location of model-specific concerns, thin controllers with rich models, paired async methods for jobs, explicit Turbo broadcasts, and request-scoped Current handling. Advice is actionable: file/layout recommendations, method naming, job delegation, and callback usage.

When to use it

• Designing or refactoring model behavior and concern layout
• Authoring or reviewing controllers and routing for resourceful design
• Writing background jobs and their model counterparts
• Implementing Turbo Streams or explicit broadcast flows
• Setting up request-scoped data (Current) for web requests and jobs
• Writing or reviewing tests and fixture organization

Best practices

• Place model-scoped concerns under app/models/model_name/ and include them from the model
• Name behavior concerns with -able and feature concerns as nouns for clarity
• Keep controllers thin; delegate business logic to rich models and model namespaced classes
• Create paired synchronous and _later methods: model does work, _later enqueues the job
• Jobs should be thin: call a single model method; keep logic in the model
• Broadcast Turbo updates explicitly from controllers or actions, not via opaque callbacks

Example use cases

• Refactor a bloated controller to call model methods and replace custom actions with resource controllers
• Split a shared concern into a generic template hook and model-specific implementation under the model namespace
• Add a background job by creating a _later method on the model and a job that calls the model method
• Implement Turbo create/update broadcasts in the controller after persisting records
• Structure tests to load fixtures and mirror the model/concern layout for focused unit tests