agentleFS
ThibautBaissacThibautBaissac/rails_ai_agents/.agents/skills/rails-architecture/SKILL.md

rails-architecture

Skill665 starsChanged 6 months agoMITView on GitHub

Guides modern Rails 8 code architecture decisions and patterns. Use when deciding where to put code, choosing between patterns (service objects vs concerns vs query objects), designing feature architecture, refactoring for better organization, or when user mentions architecture, code organization, design patterns, or layered design. WHEN NOT: Implementing specific patterns (use specialist agents like service-agent or query-agent), writing tests, or debugging runtime errors.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All services return a consistent Result object:

    line 97
  2. Distinctive:

    Policy: - Add authorization rules (@policy-agent)

    line 142
  3. Distinctive:

    Service: - Create for complex logic (@service-agent)

    line 143
  4. Distinctive:

    Query: - Add for complex queries (@query-agent)

    line 144
  5. Distinctive:

    Controller: - Keep it thin (@controller-agent)

    line 145
  6. Distinctive:

    Mailer: - Add transactional emails (@mailer-agent)

    line 148
  7. Distinctive:

    Job: - Add background processing (@job-agent)

    line 149

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Modern Rails 8 Architecture Patterns

Architecture Decision Tree

Where should this code go?
|
+- View/display formatting?       -> Presenter (@presenter-agent)
+- Complex business logic?        -> Service Object (@service-agent)
+- Complex database query?        -> Query Object (@query-agent)
+- Shared behavior across models? -> Concern (/rails-concern skill)
+- Authorization logic?           -> Policy (@policy-agent)
+- Reusable UI with logic?        -> ViewComponent (@viewcomponent-agent)
+- Async/background work?         -> Job (@job-agent, /solid-queue-setup skill)
+- Complex form (multi-model)?    -> Form Object (@form-agent)
+- Transactional email?           -> Mailer (@mailer-agent)
+- Real-time/WebSocket?           -> Channel (/action-cable-patterns skill)
+- Data validation only?          -> Model (@model-agent)
+- HTTP request/response only?    -> Controller (@controller-agent)

Layer Responsibilities

LayerResponsibilityShould NOT contain
ControllerHTTP, params, responseBusiness logic, queries
ModelData, validations, relationsDisplay logic, HTTP
ServiceBusiness logic, orchestrationHTTP, display logic
QueryComplex database queriesBusiness logic
PresenterView formatting, badgesBusiness logic, queries
PolicyAuthorization rulesBusiness logic
ComponentReusable UI encapsulationBusiness logic
JobAsync processingHTTP, display logic
FormComplex form handlingPersistence logic
MailerEmail compositionBusiness logic
ChannelWebSocket communicationBusiness logic

When NOT to Abstract

SituationKeep It SimpleDon't Create
Simple CRUD (< 10 lines)Keep in controllerService object
Used only onceInline the codeAbstraction
Simple query with 1-2 conditionsModel scopeQuery object
Basic text formattingHelper methodPresenter
Single model formform_with model:Form object
Simple partial without logicPartialViewComponent

When TO Abstract

SignalAction
Same code in 3+ placesExtract to concern/service
Controller action > 15 linesExtract to service
Model > 300 linesExtract concerns
Complex conditionalsExtract to policy/service
Query joins 3+ tablesExtract to query object
Form spans multiple modelsExtract to form object

See /extraction-timing skill for detailed extraction guidance.

Core Patterns

Skinny Controllers

# GOOD: Thin controller delegates to service
class OrdersController < ApplicationController
  def create
    result = Orders::CreateService.call(user: current_user, params: order_params)
    if result.success?
      redirect_to result.data, notice: t(".success")
    else
      flash.now[:alert] = result.error
      render :new, status: :unprocessable_entity
    end
  end
end

Result Objects for Services

All services return a consistent Result object:

Result = Data.define(:success, :data, :error) do
  def success? = success
  def failure? = !success
end

Multi-Tenancy by Default

# GOOD: Scoped through account
def index
  @events = current_account.events.recent
end

Rails 8 Specific Features

FeaturePurposeSkill/Agent
Authenticationhas_secure_password generator/authentication-flow
Background JobsSolid Queue (database-backed)/solid-queue-setup, @job-agent
Real-timeAction Cable + Solid Cable/action-cable-patterns
CachingSolid Cache (database-backed)/caching-strategies
AssetsPropshaft + Import Maps(built-in)
DeploymentKamal 2 + Thruster(built-in)

Testing Strategy by Layer

LayerTest TypeFocus
ModelUnitValidations, scopes, methods
ServiceUnitBusiness logic, edge cases
QueryUnitQuery results, tenant isolation
PresenterUnitFormatting, HTML output
ControllerRequestIntegration, HTTP flow
ComponentComponentRendering, variants
PolicyUnitAuthorization rules
SystemE2ECritical user paths

New Feature Checklist

  1. Model - Define data structure (@migration-agent, @model-agent)
  2. Policy - Add authorization rules (@policy-agent)
  3. Service - Create for complex logic (@service-agent)
  4. Query - Add for complex queries (@query-agent)
  5. Controller - Keep it thin (@controller-agent)
  6. Presenter - Format for display (@presenter-agent)
  7. Component - Build reusable UI (@viewcomponent-agent)
  8. Mailer - Add transactional emails (@mailer-agent)
  9. Job - Add background processing (@job-agent)

References

  • See layer-interactions.md for layer communication patterns
  • See service-patterns.md for service object patterns
  • See query-patterns.md for query object patterns
  • See error-handling.md for error handling strategies
  • See testing-strategy.md for comprehensive testing

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.