Copilot instructions

1---
2description: Rails Controllers Guide
3applyTo: "app/controllers/**/*.rb"
4---
5 
6# Rails Controllers Guide
7 
8## Core Philosophy
9 
10- Controllers handle HTTP requests and responses only
11- Keep controllers thin and focused
12- Business logic belongs in models or service objects
13- Follow RESTful conventions strictly
14- Design for clarity and maintainability
15 
16## Controller Design Principles
17 
18- One controller per resource
19- Seven standard RESTful actions maximum
20- Keep actions focused on single responsibilities
21- Handle multiple response formats gracefully
22- Maintain consistent patterns across controllers
23 
24## RESTful Actions
25 
26- Use only standard actions when possible: index, show, new, create, edit, update, destroy
27- Add custom actions sparingly and thoughtfully
28- Name custom actions with clear verbs
29- Group related actions in the same controller
30- Consider splitting into multiple resources instead of custom actions
31 
32## Before Actions
33 
34- Use before_action for common setup tasks
35- Keep filter methods private
36- Order filters from general to specific
37- Document filter purposes when not obvious
38- Avoid complex logic in filters
39 
40## Strong Parameters
41 
42- Always use strong parameters for user input
43- Define parameter methods as private
44- Be explicit about permitted attributes
45- Handle nested attributes appropriately
46- Document complex parameter structures
47 
48## Response Handling
49 
50- Support multiple formats (HTML, JSON, Turbo Stream)
51- Use consistent status codes
52- Provide meaningful error messages
53- Handle missing records gracefully
54- Implement proper content negotiation
55 
56## Error Handling
57 
58- Rescue specific exceptions at appropriate levels
59- Provide user-friendly error messages
60- Log errors with sufficient context
61- Use proper HTTP status codes
62- Handle errors consistently across controllers
63 
64## Authentication and Authorization
65 
66- Implement authentication in ApplicationController
67- Check authorization in before_action callbacks
68- Fail fast with unauthorized access
69- Provide clear feedback for access denied
70- Keep authorization logic simple and clear
71 
72## Controller Concerns
73 
74- Extract shared behavior into concerns
75- Name concerns based on functionality
76- Keep concerns focused and cohesive
77- Document concern dependencies
78- Test concerns in isolation
79 
80## Flash Messages
81 
82- Use flash for user notifications
83- Keep messages clear and actionable
84- Use consistent message keys
85- Handle flash in layouts appropriately
86- Consider flash.now for rendered responses
87 
88## Redirects vs Rendering
89 
90- Redirect after successful mutations
91- Render on validation failures
92- Preserve user input when rendering
93- Use proper status codes
94- Maintain RESTful patterns
95 
96## Parameter Handling
97 
98- Validate parameters early
99- Handle missing parameters gracefully
100- Transform parameters consistently
101- Document parameter expectations
102- Use parameter objects for complex inputs
103 
104## Response Formats
105 
106- Design API responses thoughtfully
107- Keep JSON responses consistent
108- Use Turbo Streams for partial updates
109- Support format negotiation properly
110- Document response structures
111 
112## Testing Controllers
113 
114- Test authorization and authentication
115- Verify response formats and status codes
116- Check parameter filtering
117- Test error scenarios
118- Keep controller tests focused on HTTP concerns
119 
120## Performance Considerations
121 
122- Implement pagination for index actions
123- Use includes to prevent N+1 queries
124- Cache expensive operations appropriately
125- Limit response data to necessary fields
126- Monitor controller action performance
127 
128## Security Best Practices
129 
130- Never trust user input
131- Verify authorization for every action
132- Use CSRF protection consistently
133- Implement rate limiting where appropriate
134- Audit controller access patterns
135 
136## API Design (When Needed)
137 
138- Version APIs from the start
139- Use consistent response formats
140- Implement proper error responses
141- Document all endpoints thoroughly
142- Consider API-only controllers
143 
144## Turbo Integration
145 
146- Return Turbo Stream responses for AJAX requests
147- Use proper Turbo Frame targeting
148- Handle Turbo Drive visits appropriately
149- Implement graceful fallbacks
150- Test Turbo interactions thoroughly
151 
152## Controller Inheritance
153 
154- Use ApplicationController for shared behavior
155- Create base controllers for common patterns
156- Keep inheritance hierarchies shallow
157- Document inheritance purposes
158- Avoid deep controller hierarchies
159 
160## Common Anti-Patterns
161 
162- Avoid business logic in controllers
163- Don't query databases directly in views
164- Prevent controllers from knowing model internals
165- Skip complex conditionals in actions
166- Don't duplicate code across controllers
167 
168## Refactoring Guidelines
169 
170- Extract complex logic to service objects
171- Move view logic to helpers or decorators
172- Consolidate duplicate code into concerns
173- Split large controllers by resource
174- Keep actions under 10 lines when possible
175 
176## Best Practices Summary
177 
178- Keep controllers thin and focused
179- Follow RESTful conventions
180- Handle errors gracefully
181- Use strong parameters always
182- Test HTTP concerns thoroughly
183 
184Remember: Controllers are just the translation layer between HTTP and your application. Keep them simple and let other layers handle complexity.
185