Cursor rule

1---
2description: "Language-agnostic programming patterns: SOLID, design patterns, clean code, and architecture. Load when refactoring, designing abstractions, or reviewing structure — not for everyday syntax."
3alwaysApply: false
4---
5 
6# Language-Agnostic Programming Patterns
7 
8Universal principles for structure, naming, architecture, and testing — applicable across all languages.
9 
10Load this rule when refactoring modules, designing abstractions, reviewing architecture, or choosing patterns. For day-to-day coding workflow (read-before-edit, CI discovery, minimal diff, verification), the always-on core **Code Discipline** section is canonical — do not duplicate it here. For the judgment layer — root-cause method, simplicity taste, test integrity — load `fable5-coding-craft` alongside this rule.
11 
12---
13 
14## Pattern Judgment (Read First)
15 
16Everything below is vocabulary, not a checklist. Frontier-quality code applies patterns *reactively* — when the code's actual pain demands them — never proactively because a situation pattern-matches a textbook example.
17 
18- Every pattern has a cost: indirection, a new concept for readers, more files to trace through. Apply one only when the pain it removes is already present, not predicted.
19- The strongest signal for an abstraction is the **third occurrence** of real duplication with identical reasons to change. Two similar blocks that change for different reasons are not duplication — unifying them couples things that must stay free.
20- SOLID violations matter when they cause observed friction (a class you cannot test, a switch you keep re-editing). A small concrete class that "violates SRP" but has never needed to change is fine code — leave it alone.
21- The best architecture for most changes is the one the repo already has. Pattern fluency is mostly for *reading* existing designs and for naming the structure a refactor is already growing toward.
22- When reviewing, flag pattern *overuse* with the same severity as pattern absence: a Strategy with one strategy, a Factory with one product, or an interface with one implementation is indirection without payoff.
23 
24---
25 
26## Change Discipline
27 
28- Solve the requested problem with the smallest vertical slice; expand only after it works.
29- Prefer extending existing modules over creating parallel implementations.
30- When adding a dependency, confirm the repo does not already solve the same need.
31- Keep public surfaces stable unless the task explicitly requires a breaking change.
32- Leave the codebase in a compilable, testable state after each meaningful step.
33 
34---
35 
36## SOLID Principles
37 
38### Single Responsibility Principle (SRP)
39A class/module should have only one reason to change.
40 
41**Apply when:**
42- A function does multiple unrelated things
43- A class has too many dependencies
44- Changes in one area affect unrelated code
45 
46**Example Pattern:**
47```
48Bad:  UserService handles auth, profile, notifications, and billing
49Good: AuthService, ProfileService, NotificationService, BillingService
50```
51 
52### Open/Closed Principle (OCP)
53Open for extension, closed for modification.
54 
55**Apply when:**
56- Adding new features requires modifying existing code
57- Switch statements grow with each new type
58- Core logic changes for edge cases
59 
60**Example Pattern:**
61```
62Bad:  if type == "email" ... elif type == "sms" ... elif type == "push" ...
63Good: NotificationStrategy interface with EmailStrategy, SMSStrategy, PushStrategy
64```
65 
66### Liskov Substitution Principle (LSP)
67Subtypes must be substitutable for their base types.
68 
69**Apply when:**
70- Derived classes override behavior in unexpected ways
71- Code checks for specific types before operating
72- Inheritance creates illogical hierarchies
73 
74**Example Pattern:**
75```
76Bad:  Square extends Rectangle but can't independently set width/height
77Good: Both Square and Rectangle implement Shape interface
78```
79 
80### Interface Segregation Principle (ISP)
81Clients shouldn't depend on interfaces they don't use.
82 
83**Apply when:**
84- Classes implement methods they don't need
85- Interfaces have too many methods
86- Changes affect many unrelated implementations
87 
88**Example Pattern:**
89```
90Bad:  Animal interface with fly(), swim(), walk() - Penguin can't fly
91Good: Flyable, Swimmable, Walkable interfaces
92```
93 
94### Dependency Inversion Principle (DIP)
95Depend on abstractions, not concretions.
96 
97**Apply when:**
98- High-level modules import low-level modules directly
99- Changing database/service requires code changes
100- Testing requires real dependencies
101 
102**Example Pattern:**
103```
104Bad:  UserService directly imports MySQLDatabase
105Good: UserService depends on DatabaseInterface, injected at runtime
106```
107 
108## Common Design Patterns
109 
110### Creational Patterns
111 
112#### Factory Pattern
113Use when object creation logic is complex or needs to be centralized.
114 
115```
116When to use:
117- Multiple similar objects with different configurations
118- Object creation depends on runtime conditions
119- Hiding complex initialization logic
120```
121 
122#### Builder Pattern
123Use for constructing complex objects step by step.
124 
125```
126When to use:
127- Objects with many optional parameters
128- Complex configuration requirements
129- Need for immutable objects with many fields
130```
131 
132#### Singleton Pattern
133Use sparingly for truly global, single-instance resources.
134 
135```
136When to use:
137- Configuration managers
138- Connection pools
139- Logger instances
140 
141Avoid when:
142- It's just for convenience (use DI instead)
143- Testing would be difficult
144- Multiple instances might be needed later
145```
146 
147### Structural Patterns
148 
149#### Adapter Pattern
150Convert one interface to another that clients expect.
151 
152```
153When to use:
154- Integrating third-party libraries
155- Working with legacy code
156- Unifying different data sources
157```
158 
159#### Decorator Pattern
160Add behavior to objects dynamically.
161 
162```
163When to use:
164- Adding features without subclassing
165- Composable behaviors
166- Middleware-like patterns
167```
168 
169#### Facade Pattern
170Provide a simplified interface to a complex subsystem.
171 
172```
173When to use:
174- Simplifying complex library usage
175- Creating API boundaries
176- Reducing coupling between layers
177```
178 
179### Behavioral Patterns
180 
181#### Strategy Pattern
182Define a family of interchangeable algorithms.
183 
184```
185When to use:
186- Multiple algorithms for the same task
187- Runtime algorithm selection
188- Avoiding complex conditionals
189```
190 
191#### Observer Pattern
192Notify dependents of state changes.
193 
194```
195When to use:
196- Event-driven systems
197- Pub/sub messaging
198- Reactive data flows
199```
200 
201#### Command Pattern
202Encapsulate requests as objects.
203 
204```
205When to use:
206- Undo/redo functionality
207- Queueing operations
208- Macro recording
209```
210 
211## Clean Code Principles
212 
213### Naming Conventions
214 
215#### Variables and Functions
216- Use intention-revealing names
217- Avoid abbreviations unless universally understood
218- Be consistent with terminology
219 
220```
221Bad:  d, tmp, data, info, process()
222Good: elapsedTimeInDays, userProfile, activeConnections, validatePayment()
223```
224 
225#### Booleans
226- Use positive names (avoid double negatives)
227- Start with is/has/can/should
228 
229```
230Bad:  notDisabled, flag, status
231Good: isEnabled, hasPermission, canEdit, shouldRefresh
232```
233 
234#### Functions
235- Use verbs for actions
236- Be specific about what they do
237 
238```
239Bad:  handle(), process(), manage()
240Good: validateUserInput(), calculateTotalPrice(), sendConfirmationEmail()
241```
242 
243### Function Design
244 
245#### Keep Functions Small
246- Do one thing well
247- 5-20 lines is ideal
248- If you can't name it well, it's probably doing too much
249 
250#### Limit Parameters
251- 0-3 parameters is ideal
252- Use objects for more
253- Consider builder pattern for complex initialization
254 
255#### Avoid Side Effects
256- Functions should be predictable
257- Clearly document mutations
258- Prefer pure functions when possible
259 
260### Comments
261 
262#### When to Comment
263- Explain WHY, not WHAT
264- Document public APIs
265- Warn about non-obvious behavior
266- Link to external resources/tickets
267 
268#### When NOT to Comment
269- Explaining what code does (make code clearer instead)
270- Commented-out code (delete it)
271- Redundant descriptions
272- TODOs without tickets
273 
274```
275Bad:  // increment counter by 1
276      counter += 1;
277 
278Good: // Retry limit based on SLA requirements (see JIRA-1234)
279      MAX_RETRIES = 3;
280```
281 
282### Error Handling
283 
284Match the repo's existing error style (exceptions, `Result`/`error`, error codes, etc.) before introducing a new pattern.
285 
286#### Fail Fast
287- Validate inputs early
288- Throw exceptions for unexpected states
289- Don't swallow errors silently
290 
291#### Error Messages
292- Include context (what was being done)
293- Include relevant values
294- Suggest remediation when possible
295 
296```
297Bad:  "Error occurred"
298Good: "Failed to connect to database 'users' at localhost:5432: Connection refused. Check if PostgreSQL is running."
299```
300 
301#### Error Categories
3021. **Recoverable**: Retry, fallback, or prompt user
3032. **Validation**: Return clear error to caller
3043. **Programming**: Fail fast, fix the bug
3054. **System**: Log, alert, graceful degradation
306 
307## Architecture Patterns
308 
309### Layered Architecture
310```
311Presentation → Business Logic → Data Access → Database
312```
313- Each layer only talks to adjacent layers
314- Dependencies flow downward
315 
316### Clean Architecture
317```
318Entities → Use Cases → Controllers → Frameworks
319```
320- Business rules at the center
321- Frameworks/DB at the edges
322- Dependency rule: inward only
323 
324### Hexagonal Architecture (Ports & Adapters)
325```
326[Adapters] → [Ports] → [Core Domain] ← [Ports] ← [Adapters]
327```
328- Core domain is isolated
329- Ports define interfaces
330- Adapters implement external concerns
331 
332### When to Choose What
333- **Layered**: Simple CRUD apps, rapid development
334- **Clean**: Complex business logic, long-lived systems
335- **Hexagonal**: Multiple interfaces, testability focus
336 
337## Testing Principles
338 
339### Test Pyramid
340```
341     /\
342    /  \   E2E Tests (few)
343   /----\  Integration Tests (some)
344  /------\ Unit Tests (many)
345```
346 
347### Unit Tests
348- Test one thing in isolation
349- Fast and deterministic
350- Mock external dependencies
351 
352### Integration Tests
353- Test component interactions
354- Use real (or realistic) dependencies
355- Focus on boundaries
356 
357### End-to-End Tests
358- Test complete user flows
359- Slowest and most brittle
360- Use for critical paths only
361 
362### Test Quality
363- Tests are documentation
364- One assertion per test when possible
365- Arrange-Act-Assert pattern
366- Test behavior, not implementation
367 
368## Performance Principles
369 
370### Measure First
371- Don't optimize prematurely
372- Profile before changing
373- Set performance budgets
374 
375### Common Optimizations
376- **Caching**: Memoization, HTTP caching, query caching
377- **Batching**: Combine multiple operations
378- **Lazy Loading**: Defer until needed
379- **Pagination**: Don't load everything at once
380 
381### Database Performance
382- Index frequently queried columns
383- Avoid N+1 queries
384- Use connection pooling
385- Consider read replicas for scale
386 
387## Security Best Practices
388 
389### Input Validation
390- Validate all external input
391- Whitelist, don't blacklist
392- Sanitize before use
393 
394### Authentication
395- Use established libraries
396- Hash passwords with strong algorithms
397- Implement rate limiting
398- Use HTTPS everywhere
399 
400### Authorization
401- Check permissions on every request
402- Fail closed (deny by default)
403- Log access attempts
404 
405### Data Protection
406- Encrypt sensitive data at rest
407- Use parameterized queries
408- Don't log sensitive information
409- Implement proper session management
410 
411## Code Organization
412 
413### Module Structure
414```
415Feature-based (preferred for larger apps):
416/features
417  /auth
418    - service
419    - controller
420    - repository
421  /products
422    - service
423    - controller
424    - repository
425 
426Layer-based (simpler for smaller apps):
427/controllers
428/services
429/repositories
430```
431 
432### File Naming
433- Consistent conventions across project
434- Reflect content purpose
435- Include type suffix when helpful (e.g., `.service`, `.controller`)
436 
437### Import Organization
4381. Standard library
4392. Third-party packages
4403. Local modules
4414. Relative imports
442 
443---
444 
445## Code Review Heuristics
446 
447Use when reviewing diffs, PRs, or your own work before closeout. Complements core **Code Discipline** and the always-on verification contract.
448 
449### Correctness
450- Does the change solve the stated problem, or only a symptom?
451- Are edge cases handled the way this repo handles them (null/empty, auth, timeouts)?
452- Do error paths propagate or log usefully — no silent swallowing?
453- If behavior changed, are callers, tests, and docs updated?
454 
455### Scope & maintainability
456- Is the diff the smallest honest fix? Any unrelated refactors or drive-by renames?
457- Does new code match naming, layering, and error style of surrounding files?
458- New abstraction justified by reuse, or premature?
459- New dependency necessary, or does the repo already cover the need?
460 
461### Tests & verification
462- Is there a test or check proportional to the risk? If not, is that gap called out as `unverified`?
463- Do tests assert behavior, not implementation details?
464- Would CI scripts in this repo catch a regression from this change?
465 
466### Security & data
467- User/external input validated and parameterized (SQL, shell, HTML)?
468- Secrets, tokens, or PII absent from logs, commits, and client bundles?
469- AuthZ checked on the server for every sensitive action — not only UI gating?
470 
471### Performance (when relevant)
472- N+1 queries, unbounded loops, or loading entire datasets into memory?
473- Caching added only where measured or clearly hot-path?
474 
475### Review output shape
476Keep feedback actionable: **issue → impact → suggested fix**. Separate blocking concerns from nits. Prefer pointing to existing repo patterns over generic style opinions.
477