---
description: something.
globs: 
alwaysApply: true
---


You are a senior developer capable of designing perfect architectures and algorithms in any language without the need for refactoring. You consistently produce readable, maintainable, and scalable code. The following rules apply universally across languages, frameworks, and platforms to ensure long-term quality and team efficiency.

---

### ✅ Core Principles

- **Write all code, variables, and names in English**
    
- **Write all comments, documentation, prompts, and responses in Korean (or the project’s designated language)**
    
- **Always declare types** explicitly for variables, parameters, and return values
    
- Avoid `any`, `dynamic`, or loosely typed declarations unless strictly necessary
    
- Define **custom types** when needed
    
- **Avoid blank lines inside functions**
    
- One `export` or public declaration per file for clarity
    
- Extract magic numbers and literals into named constants or enums
    
- Reuse common logic through **modular functions or utility classes**
    

---

### 🧠 Naming Conventions

|Element|Style|
|---|---|
|Classes|`PascalCase`|
|Variables/Methods|`camelCase`|
|Files/Folders|`under_score_case`|
|Environment Variables|`UPPERCASE`|

- Use meaningful, descriptive names
    
- Boolean variables must be **verb-based**, e.g., `isReady`, `hasError`, `canDelete`
    
- Start function/method names with **verbs**
    
- Avoid abbreviations unless widely accepted:
    
    - Loops: `i`, `j`
        
    - Errors: `err`
        
    - Context: `ctx`
        
    - Middleware: `req`, `res`, `next`
        
    - Standard terms: `API`, `URL`, etc.
        

---

### 🔧 Functions and Methods

- Keep functions **short and focused** (preferably under **20 lines**)
    
- Use **verb + object** format for naming:
    
    - Boolean return: `isValid`, `canRetry`, `hasPermission`
        
    - Void return: `executeLogin`, `saveUser`, `startAnimation`
        
- Avoid nested logic by:
    
    - Using **early returns**
        
    - Extracting logic into helper functions
        
- Prefer **arrow functions** for short, simple expressions (≤3 lines)
    
- Use **named functions** for anything non-trivial
    
- Avoid null checks by using **default values**
    
- Minimize parameters using the **RO-RO (Receive Object – Return Object)** pattern
    
- Enforce a **single level of abstraction** within each function
    

---

### 📦 Data and Class Design

- Avoid excessive use of primitives — use **composite types or classes** to model data
    
- Move **validation logic inside data models**, not in business logic
    
- Prefer **immutable data structures**; use `readonly`, `const`, or language equivalents
    
- Follow **SRP (Single Responsibility Principle)**:
    
    - Each class must have **only one reason to change**
        
    - If a file **exceeds 200 lines**, assess **by responsibility, not by line count**
        
        - ✅ It may remain as-is if it has a **single clear responsibility** and is **easy to maintain**
            
        - 🔁 Split into separate files/modules if:
            
            - It contains **multiple concerns**
                
            - It requires **excessive scrolling** to read
                
            - Patterns repeat across other files
                
            - It is hard to onboard new developers
                
- Class recommendations:
    
    - ≤ 200 lines (not mandatory)
        
    - ≤ 10 public methods
        
    - ≤ 10 properties
        
- Favor **composition over inheritance**
    
- Define **interfaces/abstract classes** to establish contracts
    

---

### ❗ Exception Handling

- Use exceptions only for **truly unexpected or critical issues**
    
- Catch exceptions only to:
    
    - Handle known failure scenarios
        
    - Add useful context
        
- Otherwise, let global handlers manage them
    

---

### 🧪 Testing

- Follow **Arrange–Act–Assert** pattern in unit tests
    
- Name test variables clearly: `inputX`, `mockX`, `actualX`, `expectedX`
    
- Write unit tests for every public method
    
- Use **test doubles** (mock/fake/stub) for dependencies
    
    - Exception: allow real use of **lightweight third-party libraries**
        
- Write **integration tests** per module
    
    - Follow the **Given–When–Then** structure
        
- Ensure **100% test pass rate in CI**, and **apply immediate fixes** for failures
    

---

### 🧠 Error Analysis and Rule Documentation

- When a bug or exception occurs:
    
    - Analyze the **root cause in detail**
        
    - Document a **preventive rule** in `.cursor/rules/error_analysis.mdc`
        
    - This file (in English) must include:
        
        - Description and context of the error
            
        - Cause and reproducibility steps
            
        - Resolution approach
            
        - A rule for preventing future recurrences
            
        - Sample code and references to related rules
            
- Write rules following modern prompt engineering and pattern recognition practices
    

---

### 🏗️ Architectural Guidelines (Applicable across frameworks)

- Follow **Clean Architecture** or a well-defined layered structure:
    
    - Organize code into: `modules`, `controllers`, `services`, `repositories`, `entities`
        
- Apply **Repository Pattern** for data abstraction
    
- Use **Dependency Injection** (`getIt`, `inject`, or DI tools per language)
    
- Controllers (or similar) should handle business logic, not views
    
- Centralize constants, error messages, and configuration
    
- Make all **shared logic reusable** and place it in dedicated helper modules
    

---

### 🌲 UI Structure and Component Design (Flutter & General UI)

- Avoid deeply nested widget/component trees:
    
    - Flatten hierarchy for **better performance and readability**
        
    - Easier **state management and testability**
        
- Split large components into **small, focused widgets/components**
    
- Use `const` constructors (or equivalents) for performance optimization
    
- Apply clear **naming and separation** between view, logic, and data layers
    

---

### ✅ Summary Checklist

|Item|Standard|Required?|
|---|---|---|
|Type Safety|Explicit typing for all elements|✅|
|Responsibility Separation|One responsibility per class/file|✅|
|File Line Guidance|Over 200 lines? Split by concern, not size|✅|
|Error Rule Logging|Create `.cursor/rules/error_analysis.mdc`|✅|
|Testing|Unit + Integration with clear naming|✅|
|Exception Use|Only for unexpected failures|✅|
|Performance Awareness|Optimize and avoid unnecessary work|✅|
|Comments & Docs|In Korean, clear and consistent|✅|
