Applies to: Rails 7+, Ruby 3.2+, Hotwire/Turbo, ActiveRecord, Action Cable

1. Convention over Configuration: Follow Rails conventions -- naming, directory structure, RESTful routes
2. Fat Models, Thin Controllers: Business logic in models and service objects, controllers handle request/response only
3. DRY: Use concerns, partials, helpers, and shared services to avoid repetition
4. RESTful by Default: Design resources around standard CRUD actions before adding custom routes
5. Security by Default: CSRF, XSS protection, strong parameters, and parameterized queries are built in

myapp/
├── app/
│   ├── controllers/
│   │   ├── application_controller.rb
│   │   ├── concerns/              # Controller concerns (auth, pagination)
│   │   └── api/
│   │       └── v1/                # Versioned API controllers
│   ├── models/
│   │   ├── application_record.rb
│   │   └── concerns/              # Model concerns (searchable, sluggable)
│   ├── views/
│   │   ├── layouts/               # Application layouts
│   │   │   └── application.html.erb
│   │   ├── shared/                # Shared partials (_navbar, _footer)
│   │   └── posts/                 # Resource-specific views
│   ├── helpers/                   # View helpers
│   ├── jobs/                      # ActiveJob classes
│   ├── mailers/                   # Action Mailer classes
│   ├── channels/                  # Action Cable channels
│   └── services/                  # Service objects (custom directory)
├── config/
│   ├── routes.rb                  # Route definitions
│   ├── database.yml               # Database configuration
│   ├── environments/              # Per-environment settings
│   └── initializers/              # Boot-time configuration
├── db/
│   ├── migrate/                   # Migration files
│   ├── schema.rb                  # Current schema snapshot
│   └── seeds.rb                   # Seed data
├── lib/
│   └── tasks/                     # Custom Rake tasks
├── test/                          # Minitest (default) or spec/ for RSpec
│   ├── models/
│   ├── controllers/
│   ├── integration/
│   └── system/
├── Gemfile
└── Gemfile.lock

• Place business logic in

  app/services/

  ; use concerns for shared model/controller behavior
• Namespace API controllers under

  Api::V1

  ; keep shared partials in

  views/shared/

• Keep controllers under 100 lines total
• Limit each action to 10 lines (delegate to services for complex logic)
• Always use

  before_action

  for authentication and resource loading
• Always use strong parameters via private

  *_params

  methods
• Return

  status: :unprocessable_entity

  for failed form submissions
• Use

  status: :see_other

  (303) for

  redirect_to

  after DELETE
• Use

  respond_to

  blocks when serving multiple formats

• Always add validations for required fields and constraints
• Always add

  dependent:

  option on

  has_many

  /

  has_one

  associations
• Use

  scope

  for reusable queries (never build queries in controllers)
• Use

  enum

  with explicit integer or string mappings
• Use

  before_validation

  for data normalization (downcase, strip)
• Avoid heavy logic in callbacks -- prefer service objects for side effects
• Always define

  counter_cache: true

  for belongs_to when parent displays counts

• Always add

  null: false

  for required columns
• Always add database indexes for foreign keys and frequently queried columns
• Always add unique indexes where uniqueness is required
• Use

  references

  with

  foreign_key: true

  for associations
• Set sensible defaults with

  default:

  for boolean and status columns
• Include both

  up

  and

  down

  methods for irreversible migrations
• Never modify a migration after it has been applied to production

• Strong parameters: never use

  params.permit!

  (permit all)
• CSRF protection: enabled by default, skip only for API controllers with token auth
• SQL injection: use ActiveRecord query methods, never string interpolation in queries
• XSS: ERB auto-escapes by default; never use

  raw

  or

  html_safe

  with user data
• Mass assignment: only permit explicitly needed attributes
• Secrets: use

  Rails.application.credentials

  or environment variables
• Set

  force_ssl

  in production
• Use

  content_security_policy

  configuration in production

• Always use

  includes

  (or

  preload

  /

  eager_load

  ) to prevent N+1 queries
• Add database indexes for all foreign keys and commonly filtered columns
• Use

  counter_cache

  for association counts displayed in views
• Use pagination for all list endpoints (Kaminari or Pagy)
• Use fragment caching (

  cache @record do

  ) for expensive view rendering
• Use background jobs (ActiveJob + Sidekiq) for slow operations
• Use

  find_each

  instead of

  each

  when iterating over large datasets

1. Associations

2. Validations

3. Enums

4. Scopes

5. Callbacks (keep minimal)

6. Instance methods

**Model ordering convention**: Associations, validations, enums, scopes, callbacks, class methods, instance methods, private methods.

• Use

  _form.html.erb

  partial shared between

  new

  and

  edit

• Use collection rendering:

  render @posts

  (auto-maps to

  _post.html.erb

  )
• Use locals:

  render partial: "post", locals: { post: @post }

• Use

  content_for :title

  for page-specific titles
• Use helpers for complex view logic (not inline ERB conditionals)

Authentication

RESTful resources

Admin namespace

API namespace

Health check

**Route conventions:**
- Use `resources` for standard CRUD (generates 7 RESTful routes)
- Use `only:` or `except:` to limit generated routes
- Use `member` for actions on a specific record, `collection` for actions on the set
- Nest resources only one level deep; use `shallow: true` for deeper nesting
- Namespace admin and API routes separately

• Use fixtures (default) or

  factory_bot

  for test data
• Test validations, associations, scopes, and instance methods on models
• Test authentication, authorization, and response codes on controllers
• Use system tests (Capybara) for critical user flows
• Coverage target: >80% for models and services, >60% overall
• Test names describe behavior:

  test "user cannot edit others' posts"

• See references/patterns.md for controller and system test examples

• Follow RESTful conventions for routes and controllers
• Use

  includes

  /

  preload

  on every association accessed in views
• Extract business logic to service objects
• Use scopes for all reusable query patterns
• Use

  find_each

  for batch operations on large datasets
• Use background jobs for email, notifications, and heavy processing
• Use fragment caching for expensive view partials
• Keep secrets in credentials or environment variables

• Put business logic in controllers or views
• Use

  params.permit!

  (mass-assignment vulnerability)
• Use string interpolation in SQL queries
• Skip database indexes on foreign keys
• Use

  Model.all

  without pagination or limits
• Modify migrations after they have been applied to production
• Use

  raw

  /

  html_safe

  with user-provided data
• Rely heavily on callbacks for business logic (use services)

• references/patterns.md -- ActiveRecord advanced patterns, Hotwire/Turbo, Action Cable, ActiveJob, API mode, deployment, and testing strategies

• Rails Guides
• Rails API Documentation
• Hotwire Documentation
• Rails Tutorial