lunchpick/CLAUDE.md

# Claude Code Global Development Rules

## 🌐 Language Settings
- **All answers and explanations must be provided in Korean**
- **Variable and function names in code should use English**
- **Error messages should be explained in Korean**

## 🤖 Agent Selection Rules
- **Always select and use a specialized agent appropriate for the task**

## 🎯 Mandatory Response Format

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

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

**Agent Names:**
- **Direct Implementation**: Perform direct implementation tasks
- **Master Manager**: Overall project management and coordination
- **flutter-ui-designer**: Flutter UI/UX design
- **flutter-architecture-designer**: Flutter architecture design
- **flutter-offline-developer**: Flutter offline functionality development
- **flutter-network-engineer**: Flutter network implementation
- **flutter-qa-engineer**: Flutter QA/testing
- **app-launch-validator**: App launch validation
- **aso-optimization-expert**: ASO optimization
- **mobile-growth-hacker**: Mobile growth strategy
- **Idea Analysis**: Idea analysis
- **mobile app mvp planner**: MVP planning

**Examples:**
- `Claude Opus 4 - Direct Implementation. I have reviewed all the following rules: development guidelines, class structure, testing rules. Proceeding with the task. Master!`
- `Claude Opus 4 - flutter-network-engineer. I have reviewed all the following rules: API integration, error handling, network optimization. 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
- Map dependencies and architectural structure

### 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
- Plan test strategy and coverage
- Identify potential risks and edge cases

### 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
- Write tests alongside implementation
- Document complex logic and design decisions

## ✅ Core Development Principles

### Language & Documentation Rules
- **Code, variables, and identifiers**: Always in English
- **Comments and documentation**: Use project's primary spoken language
- **Commit messages**: Use project's primary spoken language
- **Error messages**: Bilingual when appropriate (technical term + native explanation)

### Type Safety Rules
- **Always declare types explicitly** for variables, parameters, and return values
- Avoid `any`, `dynamic`, or loosely typed declarations (except when strictly necessary)
- Define **custom types/interfaces** for complex data structures
- Use **enums** for fixed sets of values
- Extract magic numbers and literals into named constants

### Naming Conventions

|Element|Style|Example|
|---|---|---|
|Classes/Interfaces|`PascalCase`|`UserService`, `DataRepository`|
|Variables/Methods|`camelCase`|`userName`, `calculateTotal`|
|Constants|`UPPERCASE` or `PascalCase`|`MAX_RETRY_COUNT`, `DefaultTimeout`|
|Files (varies by language)|Follow language convention|`user_service.py`, `UserService.java`|
|Boolean variables|Verb-based|`isReady`, `hasError`, `canDelete`|
|Functions/Methods|Start with verbs|`executeLogin`, `saveUser`, `validateInput`|

**Critical Rules:**
- Use meaningful, descriptive names
- Avoid abbreviations unless widely accepted: `i`, `j`, `err`, `ctx`, `API`, `URL`
- Name length should reflect scope (longer names for wider scope)

## 🔧 Function & Method Design

### Function Structure Principles
- **Keep functions short and focused** (≤20 lines recommended)
- **Follow Single Responsibility Principle (SRP)**
- **Minimize parameters** (≤3 ideal, use objects for more)
- **Avoid deeply nested logic** (≤3 levels)
- **Use early returns** to reduce complexity
- **Extract complex conditions** into well-named functions

### Function Optimization Techniques
- Prefer **pure functions** without side effects
- Use **default parameters** to reduce overloading
- Apply **RO-RO pattern** (Receive Object – Return Object) for complex APIs
- **Cache expensive computations** when appropriate
- **Avoid premature optimization** - profile first

## 📦 Data & Class Design

### Class Design Principles
- **Single Responsibility Principle (SRP)**: One class, one purpose
- **Favor composition over inheritance**
- **Program to interfaces**, not implementations
- **Keep classes cohesive** - high internal, low external coupling
- **Prefer immutability** when possible

### File Size Management
**Guidelines (not hard limits):**
- Classes: ≤200 lines
- Functions: ≤20 lines
- Files: ≤300 lines

**Split when:**
- Multiple responsibilities exist
- Excessive scrolling required
- Pattern duplication occurs
- Testing becomes complex

### Data Model Design
- **Encapsulate validation** within data models
- **Use Value Objects** for complex primitives
- **Apply Builder pattern** for complex object construction
- **Implement proper equals/hashCode** for data classes

## ❗ Exception Handling

### Exception Usage Principles
- Use exceptions for **exceptional circumstances only**
- **Fail fast** at system boundaries
- **Catch exceptions only when you can handle them**
- **Add context** when re-throwing
- **Use custom exceptions** for domain-specific errors
- **Document thrown exceptions**

### Error Handling Strategies
- Return **Result/Option types** for expected failures
- Use **error codes** for performance-critical paths
- Implement **circuit breakers** for external dependencies
- **Log errors appropriately** (error level, context, stack trace)

## 🧪 Testing Strategy

### Test Structure
- Follow **Arrange-Act-Assert (AAA)** pattern
- Use **descriptive test names** that explain what and why
- **One assertion per test** (when practical)
- **Test behavior, not implementation**

### Test Coverage Guidelines
- **Unit tests**: All public methods and edge cases
- **Integration tests**: Critical paths and external integrations
- **End-to-end tests**: Key user journeys
- Aim for **80%+ code coverage** (quality over quantity)

### Test Best Practices
- **Use test doubles** (mocks, stubs, fakes) appropriately
- **Keep tests independent** and idempotent
- **Test data builders** for complex test setups
- **Parameterized tests** for multiple scenarios
- **Performance tests** for critical paths

## 📝 Version Control Guidelines

### Commit Best Practices
- **Atomic commits**: One logical change per commit
- **Frequent commits**: Small, incremental changes
- **Clean history**: Use interactive rebase when needed
- **Branch strategy**: Follow project's branching model

### Commit Message Format
```
type(scope): brief description

Detailed explanation if needed
- Bullet points for multiple changes
- Reference issue numbers: #123

BREAKING CHANGE: description (if applicable)
```

### Commit Types
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code refactoring
- `perf`: Performance improvement
- `test`: Test changes
- `docs`: Documentation
- `style`: Code formatting
- `chore`: Build/tooling changes

## 🏗️ Architecture Guidelines

### Clean Architecture Principles
- **Dependency Rule**: Dependencies point inward
- **Layer Independence**: Each layer has single responsibility
- **Testability**: Business logic independent of frameworks
- **Framework Agnostic**: Core logic doesn't depend on external tools

### Common Architectural Patterns
- **Repository Pattern**: Abstract data access
- **Service Layer**: Business logic coordination
- **Dependency Injection**: Loose coupling
- **Event-Driven**: For asynchronous workflows
- **CQRS**: When read/write separation needed

### Module Organization
```
src/
├── domain/          # Business entities and rules
├── application/     # Use cases and workflows
├── infrastructure/  # External dependencies
├── presentation/    # UI/API layer
└── shared/         # Cross-cutting concerns
```

## 🔄 Safe Refactoring Practices

### Preventing Side Effects During Refactoring
- **Run all tests before and after** every refactoring step
- **Make incremental changes**: One small refactoring at a time
- **Use automated refactoring tools** when available (IDE support)
- **Preserve existing behavior**: Refactoring should not change functionality
- **Create characterization tests** for legacy code before refactoring
- **Use feature flags** for large-scale refactorings
- **Monitor production metrics** after deployment

### Refactoring Checklist
1. **Before Starting**:
   - [ ] All tests passing
   - [ ] Understand current behavior completely
   - [ ] Create backup branch
   - [ ] Document intended changes

2. **During Refactoring**:
   - [ ] Keep commits atomic and reversible
   - [ ] Run tests after each change
   - [ ] Verify no behavior changes
   - [ ] Check for performance impacts

3. **After Completion**:
   - [ ] All tests still passing
   - [ ] Code coverage maintained or improved
   - [ ] Performance benchmarks verified
   - [ ] Peer review completed

### Common Refactoring Patterns
- **Extract Method**: Break large functions into smaller ones
- **Rename**: Improve clarity with better names
- **Move**: Relocate code to appropriate modules
- **Extract Variable**: Make complex expressions readable
- **Inline**: Remove unnecessary indirection
- **Extract Interface**: Decouple implementations

## 🧠 Continuous Improvement

### Code Review Focus Areas
- **Correctness**: Does it work as intended?
- **Clarity**: Is it easy to understand?
- **Consistency**: Does it follow conventions?
- **Completeness**: Are edge cases handled?
- **Performance**: Are there obvious bottlenecks?
- **Security**: Are there vulnerabilities?
- **Side Effects**: Are there unintended consequences?

### Knowledge Sharing
- **Document decisions** in ADRs (Architecture Decision Records)
- **Create runbooks** for operational procedures
- **Maintain README** files for each module
- **Share learnings** through team discussions
- **Update rules** based on team consensus

## ✅ Quality Validation Checklist

Before completing any task, confirm:

### Phase Completion
- [ ] Phase 1: Comprehensive analysis completed
- [ ] Phase 2: Detailed plan with acceptance criteria
- [ ] Phase 3: Implementation meets all criteria

### Code Quality
- [ ] Follows naming conventions
- [ ] Type safety enforced
- [ ] Single Responsibility maintained
- [ ] Proper error handling
- [ ] Adequate test coverage
- [ ] Documentation complete

### Best Practices
- [ ] No code smells or anti-patterns
- [ ] Performance considerations addressed
- [ ] Security vulnerabilities checked
- [ ] Accessibility requirements met
- [ ] Internationalization ready (if applicable)

## 🎯 Success Metrics

### Code Quality Indicators
- **Low cyclomatic complexity** (≤10 per function)
- **High cohesion**, low coupling
- **Minimal code duplication** (<5%)
- **Clear separation of concerns**
- **Consistent style throughout**

### Professional Standards
- **Readable**: New developers understand quickly
- **Maintainable**: Changes are easy to make
- **Testable**: Components tested in isolation
- **Scalable**: Handles growth gracefully
- **Reliable**: Fails gracefully with clear errors

---

**Remember**: These are guidelines, not rigid rules. Use professional judgment and adapt to project needs while maintaining high quality standards.