update

.agent/workflows/code-style-guide.md

@@ -0,0 +1,179 @@
+---
+description: Code Style Guide
+---
+
+# Laravel 10 – Repository Pattern  
+## Strict Coding Rules (Anti-Trash & Anti-Overengineering)
+
+This document defines mandatory rules to prevent meaningless files, useless comments, and over-engineered architecture.
+
+---
+
+## 0. Core Principle
+
+Do not create code unless it introduces real behavior.  
+Do not write comments to compensate for bad code.
+
+Readable code replaces comments.  
+Behavior justifies files.
+
+---
+
+## 1. Comment Rules (VERY STRICT)
+
+Forbidden:
+- Comments repeating code meaning
+- Comments describing method names
+- Placeholder comments
+- TODO without ticket reference
+
+Allowed only to explain WHY:
+- Architectural decisions
+- Non-obvious side effects
+- Constraints or workarounds
+
+---
+
+## 2. File Creation Rules
+
+Do NOT create files:
+- For clean structure only
+- For symmetry
+- For future assumptions
+- To wrap a single call
+
+---
+
+## 3. When a New File Is Allowed
+
+At least ONE condition must be true:
+1. Real business rules exist
+2. Logic reused in 2+ places
+3. Side effects exist (transaction, cache, events)
+
+---
+
+## 4. Repository Rules
+
+Repositories MAY:
+- Query data
+- Filter
+- Paginate
+- Cache
+
+Repositories MUST NOT:
+- Validate
+- Apply business rules
+- Format responses
+- Check permissions
+
+---
+
+## 5. Service Layer Rules
+
+Service allowed only if:
+- Uses multiple repositories
+- Manages transactions
+- Coordinates caching
+- Enforces domain rules
+
+Proxy-only services are forbidden.
+
+---
+
+## 6. Controller Rules
+
+Controllers MAY:
+- Accept Request
+- Call Service or Repository
+- Return Response
+
+Controllers MUST NOT:
+- Contain business logic
+- Query database directly
+
+---
+
+## 7. Interface Rules
+
+Do NOT create interfaces if only one implementation exists.
+
+Interfaces allowed only when:
+- Multiple implementations exist
+- Cache on/off switching
+- Required for testing
+
+---
+
+## 8. Helper Rules
+
+Forbidden:
+- Business logic in helpers
+
+Allowed:
+- String
+- Date
+- Array utilities
+
+---
+
+## 9. Naming Rules
+
+Forbidden:
+handle, process, execute, run, doSomething
+
+Required:
+publishCourse, syncStudentProgress, calculateFinalScore
+
+---
+
+## 10. Exception Rules
+
+Forbidden:
+throw new Exception()
+
+Required:
+Explicit domain-specific exceptions
+
+---
+
+## 11. Folder Structure Rules
+
+Avoid over-fragmentation.
+
+One concept = minimal files.
+
+---
+
+## 12. File Count Sanity Check
+
+CRUD feature <= 5 files is acceptable.  
+More than 10 files indicates over-engineering.
+
+---
+
+## 13. Code Review Rejection Checklist
+
+Reject if:
+- File has no behavior
+- Service only proxies calls
+- Comment explains WHAT not WHY
+- Interface has one implementation
+- File exists for future use
+
+---
+
+## 14. AI Enforcement Rules
+
+- Do not create files without behavior
+- Do not generate meaningless comments
+- Do not create proxy layers
+- Prefer fewer, clearer files
+- Reject over-engineering
+
+---
+
+## 15. Final Rule
+
+Architecture serves behavior.  
+If code has no clear reason to exist, remove it.