Copilot instructions

1---
2description: Rails 8 Core Principles Guide
3applyTo: "**/*.rb"
4---
5 
6# Rails 8 Core Principles Guide
7 
8## Core Philosophy
9 
10- Follow Rails conventions religiously - they exist for good reasons
11- Embrace the monolith - most applications don't need microservices
12- Use Rails 8's built-in features before reaching for external gems
13- Write code that's a joy to work with, not just functional
14- Optimize for developer happiness and productivity
15 
16## Rails 8 Stack Defaults
17 
18- Use SQLite for development and production by default
19- Leverage Solid Queue for background job processing
20- Implement Solid Cache for caching with database backend
21- Use Solid Cable for WebSocket connections
22- Embrace Propshaft for asset pipeline simplicity
23 
24## Framework Principles
25 
26- Convention over configuration in all decisions
27- Database-driven design with Active Record at the center
28- RESTful resources and routes by default
29- Server-side rendering with Hotwire enhancements
30- Progressive enhancement over client-side complexity
31 
32## Model Design Principles
33 
34- Keep models focused on data integrity and business rules
35- Use Active Record validations extensively
36- Implement scopes for common query patterns
37- Add database indexes for foreign keys and frequently queried columns
38- Use concerns for shared behavior across models
39 
40## Model Best Practices
41 
42- Include schema annotations in all model files
43- Order model contents consistently: constants, includes, associations, validations, callbacks, scopes, methods
44- Keep callbacks minimal - consider service objects for complex logic
45- Use `dependent:` options on associations to maintain referential integrity
46- Implement proper counter caches for performance
47 
48## Controller Principles
49 
50- Keep controllers thin and focused on HTTP concerns
51- Use before_action filters for common setup and authorization
52- Respond to multiple formats (HTML, Turbo Stream, JSON) appropriately
53- Follow REST conventions for action names
54- Handle errors gracefully with proper HTTP status codes
55 
56## Controller Patterns
57 
58- Use strong parameters for all user input
59- Prefer redirect_to with notice/alert over render after mutations
60- Implement resourceful routes whenever possible
61- Keep business logic out of controllers
62- Use concerns for shared controller behavior
63 
64## Service Object Guidelines
65 
66- Create service objects for complex multi-model operations
67- Use when business logic doesn't naturally fit in a model
68- Keep service objects focused on a single operation
69- Return meaningful results (success/failure with errors)
70- Make service objects easy to test in isolation
71 
72## View Architecture
73 
74- Use partials for reusable view components
75- Keep logic out of views - use helpers or decorators
76- Follow Rails naming conventions for templates
77- Use Rails form helpers for all forms
78- Implement proper semantic HTML structure
79 
80## Testing Philosophy
81 
82- Write tests first (TDD) for all new features
83- Use Rails' built-in Minitest framework
84- Prefer fixtures over factories for test data
85- Write system tests for critical user paths
86- Keep tests fast and focused
87 
88## Testing Patterns
89 
90- Test models thoroughly including validations and scopes
91- Test controllers for authorization and response formats
92- Use system tests for JavaScript interactions
93- Mock external services in tests
94- Maintain high test coverage without obsessing over 100%
95 
96## Background Jobs
97 
98- Use Active Job interface for all background processing
99- Design jobs to be idempotent and retryable
100- Keep jobs small and focused on single tasks
101- Use appropriate queue priorities
102- Handle errors with proper retry strategies
103 
104## Database Design
105 
106- Use database constraints to enforce data integrity
107- Create appropriate indexes for query performance
108- Use foreign key constraints in migrations
109- Design normalized schemas by default
110- Document complex queries and database decisions
111 
112## Caching Strategy
113 
114- Use Russian doll caching for nested content
115- Cache expensive queries at the model level
116- Implement fragment caching for complex views
117- Use cache keys that automatically expire
118- Monitor cache hit rates in production
119 
120## Security Practices
121 
122- Always use strong parameters in controllers
123- Implement proper authentication and authorization
124- Use CSRF protection for all forms
125- Sanitize user input when displaying HTML
126- Keep credentials in Rails credentials system
127 
128## Performance Guidelines
129 
130- Avoid N+1 queries with proper includes
131- Use database-level operations when possible
132- Implement pagination for large datasets
133- Profile before optimizing
134- Monitor performance in production
135 
136## API Design (When Needed)
137 
138- Version APIs using URL path versioning (/api/v1)
139- Use consistent JSON response formats
140- Implement proper HTTP status codes
141- Document API endpoints thoroughly
142- Use token-based authentication for APIs
143 
144## Active Storage Configuration
145 
146- Configure direct uploads for better performance
147- Implement virus scanning for user uploads
148- Use variants for image transformations
149- Set appropriate service limits
150- Clean up orphaned attachments regularly
151 
152## Action Text Implementation
153 
154- Use for rich text content editing
155- Configure image upload limits
156- Implement proper sanitization
157- Style with consistent CSS
158- Handle attachments appropriately
159 
160## Action Cable Usage
161 
162- Use Solid Cable adapter for simpler deployment
163- Design channels for specific features
164- Implement proper authorization in channels
165- Keep broadcast payloads minimal
166- Handle connection failures gracefully
167 
168## Development Workflow
169 
170- Use Rails generators appropriately
171- Keep development environment close to production
172- Use Rails console effectively for debugging
173- Implement proper seed data
174- Document non-obvious decisions
175 
176## Code Organization
177 
178- Follow Rails directory structure strictly
179- Use concerns for shared behavior
180- Keep lib/ for non-Rails specific code
181- Organize tests mirroring app structure
182- Use meaningful file and class names
183 
184## Deployment Considerations
185 
186- Use Rails' built-in health check endpoint
187- Configure proper database connection pools
188- Set appropriate timeouts
189- Use encrypted credentials for secrets
190- Monitor application performance
191 
192## Error Handling
193 
194- Use Rails error reporter for centralized error tracking
195- Implement custom error pages
196- Log appropriately at different levels
197- Handle exceptions at appropriate levels
198- Provide meaningful error messages
199 
200## Upgrade Strategy
201 
202- Stay current with Rails versions
203- Read upgrade guides thoroughly
204- Update dependencies regularly
205- Test thoroughly after upgrades
206- Use deprecation warnings as guides
207 
208## Best Practices Summary
209 
210- Write code for humans first, computers second
211- Follow Rails conventions unless you have excellent reasons not to
212- Keep it simple - you probably don't need that complexity
213- Test everything that could possibly break
214- Make your code a joy for the next developer (probably you)
215 
216Remember: Rails 8 provides everything you need to build modern web applications. Trust the framework and focus on your business logic.
217