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.