Rails AI-Assisted Development Guidelines

A comprehensive set of development guidelines for building Rails 8+ applications with AI agent collaboration, following The Rails Way™ and modern best practices.

Project Overview

This project provides principle-focused development guidelines for Rails 8+ applications designed for:

• Solo developers working with AI agents
• Modern Rails stack using Rails 8 defaults
• Zero-build frontend approach with Hotwire
• Test-driven development with Minitest
• DHH's philosophy and The Rails Way™

Technology Stack

The guidelines are built around the Rails 8+ default stack:

• Framework: Rails 8+ with convention over configuration
• Database: PostgreSQL with Active Record
• Authentication: Rails built-in authentication generator
• Background Jobs: Solid Queue (Rails 8 default)
• Caching: Solid Cache (database-backed, Redis when needed)
• WebSockets: Action Cable with Solid Cable adapter
• Frontend: Hotwire (Turbo + Stimulus) + TailwindCSS
• Assets: Propshaft (no-build approach)
• Testing: Minitest with fixtures (no RSpec, no factories)
• Rich Text: Action Text for content editing
• File Uploads: Active Storage with direct uploads
• Deployment: Kamal with Docker
• Code Quality: StandardRB for linting/formatting
• Development Tools: Bullet gem, Annotate gem
• Error Tracking: Rails built-in error reporter

Architecture

File Structure

AI Agent Instructions

The repository contains specialized instruction files for different AI agents:

• Copilot Instructions: Located in .github/instructions/ with proper frontmatter.
• Cursor Rules: Located in .cursor/rules/rails/ with structured metadata.

Basic File Structure

While the filenames will vary based on your ruleset, here are the basic descriptions of each one:

• api - API design and versioning
• background-jobs - Background jobs & Solid Queue configuration
• controllers - Controller design and RESTful patterns
• core - Rails-specific patterns and conventions
• deployment - Kamal/Docker deployment
• hotwire - Turbo & Stimulus patterns
• importmaps - JavaScript without build steps
• mobile - Hotwire Native for mobile apps (where needed)
• models - Active Record patterns and best practices
• performance - Database optimization and caching strategies
• security - Security best practices and authorization
• services - Service objects and business logic patterns
• styling - Design patterns and TailwindCSS integration
• testing - Testing philosophy and Minitest patterns
• views - View helpers and rendering patterns

Design Philosophy

All instruction files follow these principles:

1. Principle-focused - Emphasize "what to do" rather than "how to code"
2. Instructional tone - Clear, actionable guidance in bullet-point format
3. Minimal code examples - Only when absolutely necessary to convey principles
4. Rails 8+ alignment - Leverage framework defaults and new features
5. No-build approach - Eliminate JavaScript build steps
6. AI-agent friendly - Consistent patterns and clear documentation
7. Linear MCP integration - Project management and task tracking

Key Features

For AI Agents

• Consistent naming conventions for predictable file organization
• Clear documentation patterns for AI comprehension
• Explicit dependency management for better understanding
• Standardized commit formats with Linear ticket references
• Predictable patterns across all application layers

For Developers

• Comprehensive coverage of all major Rails development areas
• Modern best practices aligned with Rails 8+ defaults
• Security-first approach with built-in protections
• Performance optimization strategies throughout
• Testing philosophy that promotes confidence and speed

For Teams

• Solo developer optimized but scales to small teams
• AI agent collaboration patterns built-in
• Linear integration for project management
• Consistent conventions across all codebases
• Documentation-driven development approach

Usage

Both GitHub Copilot and Cursor AI instruction files include proper frontmatter that automatically applies relevant guidelines based on file types and locations.

For AI Agents

• Use the main file as primary context
• Reference specialized guides for specific domains
• Follow documented patterns for consistency
• Include Linear ticket references in all work
• Maintain the established documentation format

For Humans

• Read the philosophy sections to understand the approach
• Use the guides as reference during development
• Follow the checklists for quality assurance
• Contribute improvements while maintaining principles
• Share patterns with the development community

Development Workflow

Project Management

• Conventional commits with ticket references
• Branch naming that includes ticket numbers
• Documentation that links to project context

Code Quality

• StandardRB for consistent formatting
• Bullet gem for N+1 query detection
• Annotate gem for schema documentation
• Test-driven development with comprehensive coverage
• Security reviews built into the process

Deployment

• Kamal-based container deployment
• Zero-downtime deployment strategies
• Health checks and monitoring
• Environment-specific configuration
• Rollback procedures for safety

Contributing

When extending or modifying these guidelines:

1. Maintain the principle-focused approach - avoid code tutorials
2. Keep instructions actionable - focus on "what to do"
3. Use bullet points for clarity and scannability
4. Update references when adding new files
5. Follow the established naming patterns

Philosophy

These guidelines embody:

• The Rails Way™ - conventions over configuration
• Developer happiness - joyful, productive development
• Modern practices - leveraging Rails 8+ capabilities
• AI collaboration - designed for human-AI development teams
• Simplicity - avoiding unnecessary complexity
• Quality - built-in testing, security, and performance practices

Remember: The goal is to write Rails applications that are a joy to develop, maintain, and extend, whether you're working alone, with a team, or with AI agents.

---

Version: v1.1 Last Updated: June 19, 2025