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.
1---2name: rails-conventions3description: 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.4license: MIT5---6
7# Rails Convention Engineer
8
9Follow this workflow and load only the references needed for the task.
10
11## Execution Workflow
12
131. Inspect the codebase before proposing changes.
142. Match existing conventions unless the user requests a migration.
153. Use Rails conventions and plain Ruby first.
164. Prefer small, reversible changes with tests.
175. Report tradeoffs explicitly when choosing architecture.
18
19## Mandatory Codebase Scan
20
21Always read these files first when available:
22
23- `Gemfile`
24- `config/application.rb`
25- `config/routes.rb`
26- `config/environments/*.rb` (at least current target env)
27- `app/models/` (2-5 representative models)
28- `app/controllers/` (2-5 representative controllers)
29- `test/` or `spec/`
30- process/deploy entrypoints (`Procfile*`, `bin/jobs`, `config/deploy*.yml`, CI config)
31
32Record and follow observed patterns:
33
34- test framework
35- authentication/authorization style
36- frontend stack (Hotwire, React, hybrid)
37- queue backend and runtime topology
38- API conventions and serialization style
39
40## Background Job Backend Policy
41
42Never assume Solid Queue just because the app is Rails 8.
43
44Detect backend in this order:
45
461. `config.active_job.queue_adapter`
472. `Gemfile` gems (`good_job`, `solid_queue`, others)
483. worker runtime commands and deployment wiring
49
50Apply these rules:
51
52- If `good_job` is active, keep `good_job` conventions.
53- If `solid_queue` is active, keep `solid_queue` conventions.
54- If both gems exist, treat the configured adapter as authoritative.
55- Do not migrate queue backend implicitly as part of unrelated tasks.
56- Write backend-agnostic `ApplicationJob` code unless backend features are explicitly requested.
57
58## Reference Routing
59
60Load references based on the task:
61
62- Code style, formatting, naming conventions, and fail-fast policy: `STYLE.md`
63- Baseline Rails 8 defaults and upgrade constraints: `references/01-baseline-rails-8.md`
64- Naming, layering, and code organization: `references/02-naming-and-structure.md`
65- Active Record, migrations, and data modeling: `references/03-models-and-data.md`
66- Controllers, params, and request flow: `references/04-controllers-and-params.md`
67- REST resources and routes: `references/05-routes-rest-and-resources.md`
68- Hotwire, Turbo, and Stimulus patterns: `references/06-hotwire-turbo-stimulus.md`
69- Job architecture and adapter detection: `references/07-background-jobs-overview.md`
70- GoodJob-specific patterns: `references/07a-background-jobs-good_job.md`
71- Solid Queue-specific patterns: `references/07b-background-jobs-solid_queue.md`
72- Performance and caching strategy: `references/08-performance-caching-and-db.md`
73- Security review checklist: `references/09-security-checklist.md`
74- Test strategy and quality gates: `references/10-testing-strategy.md`
75- API-only and mixed-mode API patterns: `references/11-api-mode-and-serialization.md`
76- 37signals-inspired style profile: `references/12-37signals-inspired-profile.md`
77- Code quality thresholds and detection patterns: `references/13-code-quality-gates.md`
78
79## Authentication Patterns
80
81Prefer Rails 8.1 built-in authentication. When implementing custom auth:
82
83- Use password-based authentication with bcrypt via `has_secure_password`.
84- Use magic link codes (not full magic link URLs) for account confirmation and email verification.
85- Follow 37signals naming: `Identity` (global email-based), `User` (per-account membership), `Session`.
86- Rate limit authentication endpoints aggressively.
87- Store sessions via signed cookies with `httponly` and `same_site: :lax`.
88
89## Output Contract
90
91For implementation tasks, produce:
92
931. Required schema changes with migrations.
942. Model/controller/view/job code following local conventions.
953. Tests matching local framework.
964. Brief risk notes (security, performance, rollout concerns).
97
98For review tasks, prioritize:
99
1001. Correctness and behavioral regressions.
1012. Security and data integrity.
1023. Performance and operability.
1034. Test gaps.