Rails Simplifier — Maquina | Maquina Documentation

A Claude Code plugin that refines Ruby on Rails code following 37signals patterns and the One Person Framework philosophy. Transform complex code into clean, maintainable Rails conventions.

What Is This?

A Claude Code agent that:

Simplifies service objects into rich model methods and concerns
Converts custom controller actions to CRUD resources
Transforms boolean state columns into state records
Optimizes fat controllers into thin controllers with model methods
Applies Rails best practices like I18n, Time.current, and eager loading
Detects N+1 queries and suggests fixes

Philosophy

The One Person Framework

From DHH (December 2021):

“A toolkit so powerful that it allows a single individual to create modern applications upon which they might build a competitive business.”

Conceptual Compression

From RailsConf 2018:

“Like a video codec that throws away irrelevant details such that you might download the film in real-time.”

Vanilla Rails is Plenty

From Jorge Manrubia at 37signals:

“If you have the luxury of starting a new Rails app today, go vanilla.”

Quick Start

1. Add the Marketplace

/plugin marketplace add maquina-app/rails-claude-code

2. Install the Plugin

/plugin install rails-simplifier@rails

3. Start Simplifying

> Review recent changes using the rails-simplifier agent

What It Simplifies

Pattern	Simplification
Service objects	Rich model methods + concerns
Custom controller actions	CRUD resources
Boolean state columns	State records (`has_one :closure`)
Fat controllers	Thin controllers, model methods
`Time.now`	`Time.current`
Hardcoded strings	I18n keys
N+1 queries	`includes` / `preload`
Date tests without `travel_to`	Freeze time to fixture

Usage Examples

Review Recent Changes

> Review recent changes using the rails-simplifier agent

The agent analyzes your recent commits and suggests simplifications based on 37signals patterns.

Review a Specific Controller

> Use rails-simplifier to review the bookings controller

Review a Model

> Use rails-simplifier to review the Order model

Full Project Review

> Run rails-simplifier on the app directory

Simplification Patterns

Service Objects to Model Methods

Before:

# app/services/order_processor.rb
class OrderProcessor
  def initialize(order)
    @order = order
  end

  def process
    @order.update(processed_at: Time.current)
    @order.line_items.each(&:fulfill)
    OrderMailer.confirmation(@order).deliver_later
  end
end

# In controller
OrderProcessor.new(@order).process

After:

# app/models/order.rb
class Order < ApplicationRecord
  def process!
    update(processed_at: Time.current)
    line_items.each(&:fulfill)
    OrderMailer.confirmation(self).deliver_later
  end
end

# In controller
@order.process!

Boolean States to State Records

Before:

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :draft, -> { where(published: false) }
end

After:

class Post < ApplicationRecord
  has_one :publication

  scope :published, -> { joins(:publication) }
  scope :draft, -> { where.missing(:publication) }

  def publish!
    create_publication!
  end

  def unpublish!
    publication&.destroy
  end
end

Custom Actions to CRUD

Before:

# config/routes.rb
resources :posts do
  member do
    post :publish
    post :unpublish
    post :archive
  end
end

# app/controllers/posts_controller.rb
def publish
  @post.update(published: true)
  redirect_to @post
end

After:

# config/routes.rb
resources :posts do
  resource :publication, only: [:create, :destroy]
  resource :archival, only: [:create, :destroy]
end

# app/controllers/publications_controller.rb
class PublicationsController < ApplicationController
  def create
    @post = Post.find(params[:post_id])
    @post.create_publication!
    redirect_to @post
  end

  def destroy
    @post = Post.find(params[:post_id])
    @post.publication.destroy
    redirect_to @post
  end
end

N+1 Query Detection

Before:

def index
  @posts = Post.all
end

# In view: @posts.each { |post| post.author.name }

After:

def index
  @posts = Post.includes(:author)
end

Team Installation

Add to your project’s .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "rails": {
      "source": {
        "source": "github",
        "repo": "maquina-app/rails-claude-code"
      }
    }
  },
  "enabledPlugins": [
    "rails-simplifier@rails"
  ]
}

Resources

37signals Rails Patterns — Collection of patterns from 37signals
Jorge Manrubia’s Blog — Rails architecture insights
Rails Doctrine — The philosophy behind Rails

Next Steps

GitHub Repository

View source code and contribute.

Rails MCP Server

Enhance analysis with MCP tools.