Rails-conventions rails-conventions

Rails 8.x application architecture, implementation, and review guidance for production codebases. Use when building or reviewing Ruby on Rails 8 features across models, controllers, routes, Hotwire, jobs, APIs, performance, security, and testing. Trigger for requests mentioning Rails 8, Active Record, Active Job, GoodJob, Solid Queue, Turbo/Stimulus, REST resources, migrations, code quality, naming, and production readiness.

install

source · Clone the upstream repo

git clone https://github.com/ethos-link/rails-conventions

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/ethos-link/rails-conventions ~/.claude/skills/ethos-link-rails-conventions-rails-conventions

manifest: SKILL.md

source content

Rails Convention Engineer

Follow this workflow and load only the references needed for the task.

Execution Workflow

Inspect the codebase before proposing changes.
Match existing conventions unless the user requests a migration.
Use Rails conventions and plain Ruby first.
Prefer small, reversible changes with tests.
Report tradeoffs explicitly when choosing architecture.

Mandatory Codebase Scan

Always read these files first when available:

```
Gemfile
```
```
config/application.rb
```
```
config/routes.rb
```
```
config/environments/*.rb
```
(at least current target env)
```
app/models/
```
(2-5 representative models)
```
app/controllers/
```
(2-5 representative controllers)
```
test/
```
or
```
spec/
```
process/deploy entrypoints (
```
Procfile*
```
,
```
bin/jobs
```
,
```
config/deploy*.yml
```
, CI config)

Record and follow observed patterns:

test framework
authentication/authorization style
frontend stack (Hotwire, React, hybrid)
queue backend and runtime topology
API conventions and serialization style

Background Job Backend Policy

Never assume Solid Queue just because the app is Rails 8.

Detect backend in this order:

```
config.active_job.queue_adapter
```
```
Gemfile
```
gems (
```
good_job
```
,
```
solid_queue
```
, others)
worker runtime commands and deployment wiring

Apply these rules:

If
```
good_job
```
is active, keep
```
good_job
```
conventions.
If
```
solid_queue
```
is active, keep
```
solid_queue
```
conventions.
If both gems exist, treat the configured adapter as authoritative.
Do not migrate queue backend implicitly as part of unrelated tasks.
Write backend-agnostic
```
ApplicationJob
```
code unless backend features are explicitly requested.

Reference Routing

Load references based on the task:

Code style, formatting, naming conventions, and fail-fast policy:
```
STYLE.md
```
Baseline Rails 8 defaults and upgrade constraints:
```
references/01-baseline-rails-8.md
```
Naming, layering, and code organization:
```
references/02-naming-and-structure.md
```
Active Record, migrations, and data modeling:
```
references/03-models-and-data.md
```
Controllers, params, and request flow:
```
references/04-controllers-and-params.md
```

REST resources and routes:

references/05-routes-rest-and-resources.md

Hotwire, Turbo, and Stimulus patterns:
```
references/06-hotwire-turbo-stimulus.md
```

Job architecture and adapter detection:

references/07-background-jobs-overview.md

GoodJob-specific patterns:

references/07a-background-jobs-good_job.md

Solid Queue-specific patterns:

references/07b-background-jobs-solid_queue.md

Performance and caching strategy:

references/08-performance-caching-and-db.md

Security review checklist:
```
references/09-security-checklist.md
```
Test strategy and quality gates:
```
references/10-testing-strategy.md
```

API-only and mixed-mode API patterns:

references/11-api-mode-and-serialization.md

37signals-inspired style profile:

references/12-37signals-inspired-profile.md

Code quality thresholds and detection patterns:
```
references/13-code-quality-gates.md
```

Authentication Patterns

Prefer Rails 8.1 built-in authentication. When implementing custom auth:

Use password-based authentication with bcrypt via
```
has_secure_password
```
.
Use magic link codes (not full magic link URLs) for account confirmation and email verification.
Follow 37signals naming:
```
Identity
```
(global email-based),
```
User
```
(per-account membership),
```
Session
```
.
Rate limit authentication endpoints aggressively.
Store sessions via signed cookies with
```
httponly
```
and
```
same_site: :lax
```
.

Output Contract

For implementation tasks, produce:

Required schema changes with migrations.
Model/controller/view/job code following local conventions.
Tests matching local framework.
Brief risk notes (security, performance, rollout concerns).

For review tasks, prioritize:

Correctness and behavioral regressions.
Security and data integrity.
Performance and operability.
Test gaps.