Copilot instructions

1---
2description: "Rails Development Rules -- The Rails Way with AI Agents"
3applyTo: "**"
4---
5 
6# Rails Development Rules - The Rails Way with AI Agents
7***Built for: Solo developer + AI agents, Linear MCP integration, maximum joy***
8 
9## Core Philosophy
10You are building a Rails 8+ application following The Rails Way™. Code should be:
11- Convention over configuration
12- Database-first design
13- Progressive enhancement with Hotwire
14- Zero-build frontend approach
15- Test-driven with Minitest
16- Optimized for AI agent collaboration
17- Lean, readable, and maintainable
18 
19## Rails 8+ Stack Preferences
20- **Authentication**: Rails built-in (`rails generate authentication`)
21- **Background Jobs**: Solid Queue (default Rails 8)
22- **Caching**: Solid Cache (database-backed, Redis when needed)
23- **WebSockets**: Action Cable with Solid Cable adapter
24- **Database**: PostgreSQL with Active Record
25- **Frontend**: Hotwire (Turbo + Stimulus) + TailwindCSS
26- **Asset Pipeline**: Propshaft (simpler, no-build approach)
27- **Testing**: Minitest with fixtures (no RSpec, no factories)
28- **Rich Text**: Action Text for content editing
29- **File Uploads**: Active Storage with direct uploads
30- **Deployment**: Kamal with Docker
31- **Code Quality**: StandardRB for linting/formatting
32- **Development Tools**: Bullet gem for N+1 detection, Annotate gem for schema docs
33- **Error Tracking**: Rails built-in error reporter
34 
35## Detailed Guides
36This document provides core principles. For detailed implementation guidance, see:
37 
38- **[rails-core.md](instructions/rails-core.instructions.md)** - Rails 8 conventions and patterns
39- **[rails-models.md](instructions/rails-models.instructions.md)** - Active Record patterns and best practices
40- **[rails-controllers.md](instructions/rails-controllers.instructions.md)** - Controller design and RESTful patterns
41- **[rails-services.md](instructions/rails-services.instructions.md)** - Service objects and business logic
42- **[rails-testing.md](instructions/rails-testing.instructions.md)** - Testing philosophy and Minitest patterns
43- **[rails-security.md](instructions/rails-security.instructions.md)** - Security best practices and authorization
44- **[rails-performance.md](instructions/rails-performance.instructions.md)** - Database optimization and caching
45- **[rails-api.md](instructions/rails-api.instructions.md)** - API design and versioning (when needed)
46- **[rails-importmaps.md](instructions/rails-importmaps.instructions.md)** - JavaScript without build steps
47- **[rails-hotwire.md](instructions/rails-hotwire.instructions.md)** - Turbo & Stimulus patterns
48- **[rails-views.md](instructions/rails-views.instructions.md)** - View helpers and rendering
49- **[rails-styling.md](instructions/rails-styling.instructions.md)** - TailwindCSS integration
50- **[rails-background-jobs.md](instructions/rails-background-jobs.instructions.md)** - Solid Queue configuration
51- **[rails-deployment.md](instructions/rails-deployment.instructions.md)** - Kamal deployment guide
52- **[rails-mobile.md](instructions/rails-mobile.instructions.md)** - Hotwire Native for mobile apps (optional)
53 
54## File Organization & Naming
55 
56### Consistent Directory Structure
57```
58app/
59├── controllers/
60│   ├── concerns/
61│   └── application_controller.rb
62├── models/
63│   ├── concerns/
64│   └── application_record.rb
65├── views/
66│   ├── layouts/
67│   ├── shared/
68│   └── [resource_name]/
69├── services/
70├── jobs/
71├── channels/
72├── mailers/
73└── helpers/
74```
75 
76### Naming Conventions for AI Agents
77- **Classes**: PascalCase, descriptive (`UserRegistrationService`, `InvoicePaymentProcessor`)
78- **Files**: snake_case matching class name (`user_registration_service.rb`)
79- **Methods**: snake_case, verb-first for actions (`process_payment`, `calculate_total`)
80- **Variables**: snake_case, noun-first (`current_user`, `payment_amount`)
81- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRY_ATTEMPTS`, `DEFAULT_CURRENCY`)
82 
83### AI Agent File Patterns
84Always organize files predictably:
85```
86app/models/user.rb                    # Model: singular
87app/controllers/users_controller.rb   # Controller: plural + _controller
88app/services/user_registration.rb     # Service: domain + action
89app/jobs/send_welcome_email_job.rb    # Job: action + _job
90app/views/users/index.html.erb        # View: controller/action
91```
92 
93### AI-Friendly Documentation
94- Include purpose statement for AI comprehension
95- Reference Linear ticket context (ID-123)
96- Document key dependencies and return values
97- Specify potential errors and exceptions
98- Keep documentation close to code
99 
100## Linear Integration (Project Management)
101 
102### Overview
103This section contains Linear-specific integration patterns. The same principles can be adapted for other project management tools by replacing Linear ticket formats and magic words with platform-specific equivalents.
104 
105### Commit Message Format
106- Use Conventional Commits format with issue references
107- Structure: `type(scope): description` followed by body and footer
108- Include ticket reference in commit body or footer
109- Example:
110```
111  feat: add magic link authentication
112 
113  Implements passwordless login flow
114  Fixes ID-123
115```
116 
117### Issue Linking
118- Use semantic keywords to manage issue state through commits
119- **Closing keywords**: `close`, `closes`, `closed`, `closing fix`, `fixes`, `fixed`, `fixing`, `resolve`, `resolves`, `resolved`, `resolving`, `complete`, `completes`, `completed`, `completing` (auto-close issues)
120- **Reference keywords**: `ref`, `refs`, `references`, `part of`, `related to`, `contributes to`, `toward`, `towards` (link without closing)
121- Support multiple issues: `Fixes ID-123, ID-456`
122 
123### Branch Strategy
124- Follow GitHub Flow with descriptive branch names
125- Format: `type/ticket-id/brief-description`
126- Example: `feat/id-123/magic-link-login`
127- Keep branches short-lived and focused
128 
129### Documentation Integration
130- Reference tickets in code comments for complex logic
131- Include ticket IDs in migration descriptions
132- Link issues in test descriptions for context
133- Document architectural decisions with ticket references
134 
135## Models & Active Record
136 
137### Model Design Principles
138- Keep models focused on data integrity and business rules
139- Use schema annotations (annotate gem) for documentation
140- Order model contents consistently: constants, includes, associations, validations, callbacks, scopes, methods
141- Implement database constraints to match validations
142- Use concerns for shared behavior across models
143 
144### Model Best Practices
145- Always index foreign keys and frequently queried columns
146- Use counter caches for association counts
147- Implement scopes for common query patterns
148- Keep callbacks minimal - prefer service objects for complex logic
149- Use `dependent:` options to maintain referential integrity
150 
151### Database Design
152- Design normalized schemas by default
153- Use appropriate PostgreSQL data types
154- Implement database-level constraints
155- Create partial indexes for performance
156- Document complex queries and decisions
157 
158See **[rails-models.md](instructions/rails-models.instructions.md)** for detailed Active Record patterns.
159 
160## Controllers
161 
162### Controller Principles
163- Keep controllers thin and focused on HTTP concerns
164- Use before_action filters for common setup
165- Follow RESTful conventions strictly
166- Handle multiple response formats (HTML, Turbo Stream, JSON)
167- Implement proper error handling with appropriate status codes
168 
169### Controller Patterns
170- Always use strong parameters for user input
171- Prefer redirect after mutations over render
172- Keep business logic in models or service objects
173- Use concerns for shared controller behavior
174- Implement resourceful routes whenever possible
175 
176See **[rails-controllers.md](instructions/rails-controllers.instructions.md)** for detailed controller patterns.
177 
178## Service Objects
179 
180### When to Use Service Objects
181- Complex business logic spanning multiple models
182- External API integrations
183- Multi-step processes with transactions
184- Operations that don't naturally fit in a model
185- Background job logic that needs testing
186 
187### Service Object Principles
188- Keep services focused on a single operation
189- Use clear, descriptive names
190- Return meaningful results (success/failure)
191- Make services easy to test in isolation
192- Include proper error handling
193 
194See **[rails-services.md](instructions/rails-services.instructions.md)** for service object patterns.
195 
196## Testing Philosophy
197 
198### The Rails Way of Testing
199- Use fixtures over factories for simplicity and speed
200- Write system tests for critical user flows
201- Unit test models and services thoroughly
202- Test controllers only for complex authorization
203- Always test happy path and edge cases
204 
205### Testing Best Practices
206- Keep tests fast and focused
207- Use descriptive test names
208- Test behavior, not implementation
209- Mock external services appropriately
210- Maintain high coverage without obsessing
211 
212See **[rails-testing.md](instructions/rails-testing.instructions.md)** for comprehensive testing patterns.
213 
214## Background Jobs
215 
216### Job Design Principles
217- Make all jobs idempotent and retryable
218- Keep jobs small and focused
219- Pass simple arguments (IDs, not objects)
220- Design for eventual consistency
221- Handle failures gracefully
222 
223### Solid Queue Configuration
224- Use database-backed queuing for simplicity
225- Configure workers based on priorities
226- Set appropriate concurrency limits
227- Monitor queue depth and latency
228- Implement proper error handling
229 
230See **[rails-background-jobs.md](instructions/rails-background-jobs.instructions.md)** for Solid Queue patterns.
231 
232## Mailers
233 
234### Mailer Best Practices
235- Keep mailers simple and focused
236- Use layouts for consistent email design
237- Test email delivery in development
238- Implement proper error handling
239- Consider delivery performance
240 
241### Email Design
242- Design for email client limitations
243- Provide text alternatives
244- Test across email clients
245- Keep templates maintainable
246- Handle bounces appropriately
247 
248## Performance & Optimization
249 
250### Query Optimization
251- Avoid N+1 queries with proper includes
252- Use database-level operations when possible
253- Implement appropriate indexes
254- Profile before optimizing
255- Monitor performance in production
256 
257### Caching Strategy
258- Use Russian doll caching for nested content
259- Implement fragment caching for expensive views
260- Cache at the appropriate level
261- Use cache keys that auto-expire
262- Monitor cache effectiveness
263 
264See **[rails-performance.md](instructions/rails-performance.instructions.md)** for detailed optimization patterns.
265 
266## Security Best Practices
267 
268### Core Security Principles
269- Always use strong parameters
270- Implement proper authentication and authorization
271- Sanitize user input appropriately
272- Use CSRF protection for all forms
273- Keep credentials in Rails credentials system
274 
275### Security Patterns
276- Validate input at multiple levels
277- Implement rate limiting for APIs
278- Use secure headers in production
279- Audit dependencies regularly
280- Follow OWASP guidelines
281 
282See **[rails-security.md](instructions/rails-security.instructions.md)** for comprehensive security patterns.
283 
284## Error Handling
285 
286### Error Handling Strategy
287- Use Rails error reporter for centralized tracking
288- Implement custom error pages
289- Handle exceptions at appropriate levels
290- Provide meaningful error messages
291- Log errors with sufficient context
292 
293### Logging Best Practices
294- Use appropriate log levels
295- Include structured data in logs
296- Avoid logging sensitive information
297- Implement request correlation IDs
298- Monitor logs for patterns
299 
300## Code Style & Conventions
301 
302### Method Organization
303- Order methods logically: public, protected, private
304- Group related methods together
305- Use descriptive method names
306- Keep methods small and focused
307- Document complex logic
308 
309### Rails Conventions
310- Use `?` suffix for boolean methods
311- Use `!` suffix for dangerous methods
312- Follow Rails naming patterns strictly
313- Prefer Rails helpers over custom solutions
314- Keep code idiomatic to Rails
315 
316### Code Quality Tools
317- Use StandardRB for consistent formatting
318- Run Bullet gem to detect N+1 queries
319- Keep schema annotations current
320- Use pre-commit hooks for quality
321- Review code for Rails best practices
322 
323## Secrets & Configuration
324 
325### Credential Management
326- Use Rails credentials for all secrets
327- Never commit sensitive data
328- Use environment variables for non-sensitive config
329- Document credential requirements
330- Rotate credentials regularly
331 
332### Configuration Best Practices
333- Keep configuration DRY
334- Use Rails configuration patterns
335- Document environment-specific settings
336- Validate configuration on boot
337- Handle missing configuration gracefully
338 
339## AI Agent Collaboration
340 
341### Documentation for AI Agents
342- Write clear, comprehensive comments
343- Use consistent patterns throughout
344- Document business logic thoroughly
345- Explain non-obvious decisions
346- Include examples where helpful
347 
348### Predictable Patterns
349- Follow Rails conventions religiously
350- Use standard file organization
351- Keep naming consistent
352- Write explicit rather than clever code
353- Maintain comprehensive test coverage
354 
355### Task Breakdown
356- Reference Linear tickets clearly
357- Break complex tasks into phases
358- Document dependencies between tasks
359- Keep scope manageable
360- Communicate progress clearly
361 
362## Development Workflow
363 
364### Project Management Integration
365- The workflow supports various project management tools
366- Linear integration is current default (see Linear Integration section)
367- Adapt ticket references and workflows to your chosen platform
368- Maintain consistent commit and branch naming patterns
369 
370### Local Development
371- Use Rails generators appropriately
372- Keep development close to production
373- Use Rails console for debugging
374- Implement helpful seed data
375- Document setup requirements
376 
377### Git Workflow
378- Follow GitHub Flow for simplicity and clarity
379- Create feature branches from main/master
380- Keep commits atomic and well-documented
381- Open pull requests early for visibility
382- Merge after review and CI checks pass
383 
384### Continuous Integration
385- Run tests automatically on every push
386- Deploy to staging via Kamal after main branch updates
387- Use branch protection rules for quality gates
388- Automate security and dependency checks
389- Keep CI fast and focused on essentials
390 
391### Code Review
392- Check for Rails best practices
393- Verify test coverage
394- Review security implications
395- Ensure performance considerations
396- Validate documentation completeness
397 
398## Production Considerations
399 
400### Deployment Checklist
401- Run tests before deployment
402- Check migration safety
403- Verify environment configuration
404- Monitor deployment progress
405- Have rollback plan ready
406 
407### Production Best Practices
408- Use health check endpoints
409- Implement proper monitoring
410- Configure appropriate timeouts
411- Set up error alerting
412- Plan for scaling
413 
414See **[rails-deployment.md](instructions/rails-deployment.instructions.instructions.md)** for Kamal deployment details.
415 
416## Final Reminders
417 
418### Always Prefer Rails Conventions
419- Trust the framework's decisions
420- Use built-in solutions first
421- Follow established patterns
422- Avoid premature optimization
423- Keep solutions simple
424 
425### Code Quality Checklist
426- [ ] Tests written and passing
427- [ ] No N+1 queries detected
428- [ ] Code follows Rails conventions
429- [ ] Security considerations addressed
430- [ ] Performance implications considered
431- [ ] Documentation is complete
432- [ ] Linear ticket referenced
433- [ ] AI agents can understand the code
434 
435Remember: Rails provides everything you need. Trust the framework, follow conventions, and focus on delivering value. Write code that's a joy to work with.
436 
437Happy coding! 🚂 🚀
438