KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

rails-instructions

★ 54 Open GitHub ↗

Set of instructions for your favorite AI agent (e.g. Cursor, Copilot, Claude, etc) for a "DHH-driven" Ruby on Rails development philosophy.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

rails-instructions

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README