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

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