superport/.claude/guide.md

## 🎯 Mandatory Response Format

Before starting any task, you MUST respond in the following format:

```
[Model Name]. I have reviewed all the following rules: [rule file list or categories]. Proceeding with the task. Master!
```

**Examples:**

- `Claude Sonnet 4. I have reviewed all the following rules: development guidelines, class structure, testing rules. Proceeding with the task. Master!`
- For extensive rules: `coding style, class design, exception handling, testing rules` (categorized summary)

## 🚀 Mandatory 3-Phase Task Process

### Phase 1: Codebase Exploration & Analysis

**Required Actions:**

- Systematically discover ALL relevant files, directories, modules
- Search for related keywords, functions, classes, patterns
- Thoroughly examine each identified file
- Document coding conventions and style guidelines
- Identify framework/library usage patterns

### Phase 2: Implementation Planning

**Required Actions:**

- Create detailed implementation roadmap based on Phase 1 findings
- Define specific task lists and acceptance criteria per module
- Specify performance/quality requirements

### Phase 3: Implementation Execution

**Required Actions:**

- Implement each module following Phase 2 plan
- Verify ALL acceptance criteria before proceeding
- Ensure adherence to conventions identified in Phase 1

## ✅ Core Development Principles

### Language & Type Rules

- **Write ALL code, variables, and names in English**
- **Write ALL comments, documentation, prompts, and responses in Korean**
- **Always declare types explicitly** for variables, parameters, and return values
- Avoid `any`, `dynamic`, or loosely typed declarations (except when strictly necessary)
- Define **custom types** when needed
- Extract magic numbers and literals into named constants or enums

### Naming Conventions

|Element|Style|Example|
|---|---|---|
|Classes|`PascalCase`|`UserService`, `DataRepository`|
|Variables/Methods|`camelCase`|`userName`, `calculateTotal`|
|Files/Folders|`under_score_case`|`user_service.dart`, `data_models/`|
|Environment Variables|`UPPERCASE`|`API_URL`, `DATABASE_PASSWORD`|

**Critical Rules:**

- **Boolean variables must be verb-based**: `isReady`, `hasError`, `canDelete`
- **Function/method names start with verbs**: `executeLogin`, `saveUser`
- Use meaningful, descriptive names
- Avoid abbreviations unless widely accepted: `i`, `j`, `err`, `ctx`, `API`, `URL`

## 🔧 Function & Method Design

### Function Structure Principles

- **Keep functions short and focused** (≤20 lines recommended)
- **Avoid blank lines inside functions**
- **Follow Single Responsibility Principle**
- **Use verb + object format** for naming:
    - Boolean return: `isValid`, `canRetry`, `hasPermission`
    - Void return: `executeLogin`, `saveUser`, `startAnimation`

### Function Optimization Techniques

- Use **early returns** to avoid nested logic
- Extract logic into helper functions
- Prefer **arrow functions** for short expressions (≤3 lines)
- Use **named functions** for complex logic
- Minimize null checks by using **default values**
- Minimize parameters using **RO-RO pattern** (Receive Object – Return Object)

## 📦 Data & Class Design

### Class Design Principles

- **Strictly follow Single Responsibility Principle (SRP)**
- **Favor composition over inheritance**
- **Define interfaces/abstract classes** to establish contracts
- **Prefer immutable data structures** (use `readonly`, `const`)

### File Size Management

- **Split by responsibility when exceeding 200 lines** (responsibility-based, not line-based)
- ✅ **May remain as-is if**:
    - Has **single clear responsibility**
    - Is **easy to maintain**
- 🔁 **Must split when**:
    - Contains **multiple concerns**
    - Requires **excessive scrolling**
    - Patterns repeat across files
    - Difficult for new developer onboarding

### Class Recommendations

- ≤ 200 lines (not mandatory)
- ≤ 10 public methods
- ≤ 10 properties

### Data Model Design

- Avoid excessive use of primitives — use **composite types or classes**
- Move **validation logic inside data models** (not in business logic)

## ❗ Exception Handling

### Exception Usage Principles

- 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

### Test Structure

- Follow **Arrange–Act–Assert** pattern
- Clear test variable naming: `inputX`, `mockX`, `actualX`, `expectedX`
- **Write unit tests for every public method**

### Test Doubles Usage

- Use **test doubles** (mock/fake/stub) for dependencies
- Exception: allow real use of **lightweight third-party libraries**

### Integration Testing

- Write **integration tests per module**
- Follow **Given–When–Then** structure
- Ensure **100% test pass rate in CI** and **apply immediate fixes** for failures

## 🧠 Error Analysis & Rule Documentation

### Mandatory Process When Errors Occur

1. **Analyze root cause in detail**
2. **Document preventive rule in `.cursor/rules/error_analysis.mdc`**
3. **Write in English including**:
    - Error description and context
    - Cause and reproducibility steps
    - Resolution approach
    - Rule for preventing future recurrences
    - Sample code and references to related rules

### Rule Writing Standards

```markdown
---
description: Clear, one-line description of what the rule enforces
globs: path/to/files/*.ext, other/path/**/*
alwaysApply: boolean
---

**Main Points in Bold**
- Sub-points with details
- Examples and explanations
```

## 🏗️ Architectural Guidelines

### Clean Architecture Compliance

- **Layered structure**: `modules`, `controllers`, `services`, `repositories`, `entities`
- Apply **Repository Pattern** for data abstraction
- Use **Dependency Injection** (`getIt`, `inject`, etc.)
- Controllers handle business logic (not view processing)

### Code Structuring

- **One export or public declaration per file**
- Centralize constants, error messages, and configuration
- Make **all shared logic reusable** and place in dedicated helper modules

## 🌲 UI Structure & Component Design

### UI Optimization Principles

- **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

## 📈 Continuous Rule Improvement

### Rule Improvement Triggers

- New code patterns not covered by existing rules
- Repeated similar implementations across files
- Common error patterns that could be prevented
- New libraries or tools being used consistently
- Emerging best practices in the codebase

### Rule Update Criteria

**Add New Rules When:**

- A new technology/pattern is used in 3+ files
- Common bugs could be prevented by a rule
- Code reviews repeatedly mention the same feedback

**Modify Existing Rules When:**

- Better examples exist in the codebase
- Additional edge cases are discovered
- Related rules have been updated

## ✅ Quality Validation Checklist

Before completing any task, confirm:

- ✅ All three phases completed sequentially
- ✅ Each phase output meets specified format requirements
- ✅ Implementation satisfies all acceptance criteria
- ✅ Code quality meets professional standards
- ✅ Started with mandatory response format
- ✅ All naming conventions followed
- ✅ Type safety ensured
- ✅ Single Responsibility Principle adhered to

## 🎯 Success Validation Framework

### Expert-Level Standards Verification

- **Minimalistic Approach**: High-quality, clean solutions without unnecessary complexity
- **Professional Standards**: Every output meets industry-standard software engineering practices
- **Concrete Results**: Specific, actionable details at each step

### Final Quality Gates

- [ ] All acceptance criteria validated
- [ ] Code follows established conventions
- [ ] Minimalistic approach maintained
- [ ] Expert-level implementation standards met
- [ ] Korean comments and documentation provided
- [ ] English code and variable names used consistently