rails-architecture_skill

Overview

This skill guides modern Rails 8 code architecture decisions and patterns for clean, maintainable applications. It helps you decide where to place code, when to extract abstractions, and which pattern best fits a problem. Use it to align feature design, refactoring, and TDD-friendly organization with Rails 8 defaults.

How this skill works

The skill inspects the intent of the code or problem and maps it to a recommended layer (controller, model, service, query, presenter, component, form, job, mailer, or channel). It applies concrete rules: keep controllers skinny, keep models focused on data, push orchestration into services, and isolate complex queries into query objects. It also flags over-engineering and provides signals for when to extract abstractions and how to structure directories and Result-style responses.

When to use it

• Deciding where new code should live (controller vs service vs model).
• Choosing between service objects, concerns, query objects, presenters, or components.
• Designing feature architecture or multi-model workflows.
• Refactoring fat controllers or bloated models for better organization.
• Defining testing strategy per layer and following TDD practices.

Best practices

• Keep controllers skinny: authenticate, authorize, parse params, delegate, render.
• Make models rich for validations and relations but avoid cross-cutting business logic.
• Use services for multi-model orchestration, transactions, and external calls; return a consistent Result object.
• Extract complex database logic into Query objects and reuse tenant scoping by default.
• Prefer ViewComponents and Presenters for testable, reusable UI and formatting.
• Avoid premature abstraction—keep simple CRUD and one-off logic inline.

Example use cases

• Implementing an Orders::CreateService when creation spans inventory checks, payments, and notifications.
• Refactoring a 400-line model by extracting shared behavior into concerns and services.
• Isolating a multi-join dashboard report into a Query object for performance and testability.
• Replacing complex partials with ViewComponents for reusable cards and tables.
• Designing a multi-step signup wizard using a Form object with clear validation and persistence flow.