Rails Instructions — AI skill for Claude Code

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