Rails Code Generation

Rails Code Generation Standards

Practical standards for AI-assisted Rails development from Evil Martians. Generated code should be so simple and clear that reading it feels like reading well-written documentation.

Core Principles

1. Follow Rails conventions - Leverage the framework, don't fight it
2. Use domain language - Name models after business concepts (Participant vs User, Cloud vs GeneratedImage)
3. Keep logic at appropriate layers - Models for business logic, controllers for HTTP, jobs for async
4. Write readable code - Code should be self-documenting without comments
5. Normalize data properly - One concern per table, use foreign keys and constraints

Quick Reference

File Structure

app/models/           # Including namespaced classes (Cloud::CardGenerator)
app/controllers/      # Namespaced for auth scoping (Participant::CloudsController)
app/jobs/             # Background work with ActiveJob
app/forms/            # Multi-model operations only
app/policies/         # Complex authorization (ActionPolicy)
app/views/            # ERB + ViewComponent
app/frontend/         # Stimulus controllers, styles
config/configs/       # Anyway Config classes

Critical: No app/services/, app/contexts/, or app/operations/ folders. Extract complex operations to namespaced model classes.

Model Organization Order

1. Gems/DSL extensions
2. Associations (with counter_cache: true)
3. Enums (for state machines)
4. Normalizations (Rails 7.1+)
5. Validations
6. Scopes
7. Callbacks
8. Delegations
9. Public methods
10. Private methods

Controller Target

5-10 lines per action. No business logic. Guard clauses for early returns.

def create
  return head :forbidden unless current_participant.can_create_cloud?

  @cloud = current_participant.clouds.create!(cloud_params)
  CloudProcessingJob.perform_later(@cloud)
  redirect_to @cloud
end

Technology Stack

Required gems: Rails, Puma, Propshaft, PostgreSQL, Hotwire (Turbo + Stimulus), ViewComponent, Vite Rails, SolidQueue, ActionPolicy, Anyway Config, RSpec + FactoryBot, Standard, Nanoid + FriendlyID, HTTParty

Forbidden: Devise, CanCanCan, ActiveAdmin, service object gems, state machine gems, dry-types/Virtus

Building Block References

Consult these reference files for detailed patterns:

Decision Flowchart

Where does this logic belong?

• Single model operation → Model method
• Multi-model transaction → Form object
• External API call → Namespaced model class (e.g., Cloud::CardGenerator)
• Async work → Job (orchestrates, doesn't execute)
• Complex query → Query object or scope
• Authorization → Policy (ActionPolicy)
• Configuration → Anyway Config class

When to extract from model?

• Method > 15 lines → Extract to namespaced class
• Calls external API → Extract to namespaced class
• Shared across models → Extract to concern or module

Code Generation Checklist

Before generating Rails code, verify:

• Models named after business domain concepts?
• Model follows organization order?
• States implemented as enums?
• Controllers under 10 lines per action?
• Complex logic extracted appropriately?
• Database normalized with FK constraints?
• Counter caches on has_many associations?
• Workflows orchestrated through jobs?
• Configuration via Anyway Config (not ENV)?
• Tests organized by type (model/request/system)?

Usage

When generating Rails code:

1. Check references/stack.md to verify gem choices
2. Follow patterns in the relevant building block reference
3. Consult references/anti-patterns.md to avoid common mistakes
4. Run through the checklist above before finalizing

For specific patterns, read the appropriate reference file based on what component is being generated.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.