314 lines
9.8 KiB
Markdown
314 lines
9.8 KiB
Markdown
# Claude 프로젝트 컨텍스트
|
||
|
||
## 언어 설정
|
||
- 모든 답변은 한국어로 제공
|
||
- 기술 용어는 영어와 한국어 병기 가능
|
||
|
||
## 프로젝트 정보
|
||
- Flutter 기반 구독 관리 앱 (SubManager)
|
||
|
||
## 현재 작업
|
||
- 구독카드가 클릭이 되지 않아서 문제를 찾는 중.
|
||
|
||
## 🎯 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
|
||
|
||
## 📝 Git Commit Guidelines
|
||
|
||
### Commit Message Format
|
||
|
||
- **Use clear, descriptive commit messages in Korean**
|
||
- **Follow conventional commit format**: `type: description`
|
||
- **Keep commit messages concise and focused**
|
||
- **DO NOT include Claude Code attribution or co-author tags**
|
||
|
||
### Commit Message Structure
|
||
|
||
```
|
||
type: brief description in Korean
|
||
|
||
Optional detailed explanation if needed
|
||
```
|
||
|
||
### Commit Types
|
||
|
||
- `feat`: 새로운 기능 추가
|
||
- `fix`: 버그 수정
|
||
- `refactor`: 코드 리팩토링
|
||
- `style`: 코드 스타일 변경 (formatting, missing semi-colons, etc)
|
||
- `docs`: 문서 변경
|
||
- `test`: 테스트 코드 추가 또는 수정
|
||
- `chore`: 빌드 프로세스 또는 보조 도구 변경
|
||
|
||
### Examples
|
||
|
||
✅ **Good Examples:**
|
||
- `feat: 월별 차트 다국어 지원 추가`
|
||
- `fix: 분석화면 총지출 금액 불일치 문제 해결`
|
||
- `refactor: 통화 변환 로직 모듈화`
|
||
|
||
❌ **Avoid These:**
|
||
- Including "🤖 Generated with [Claude Code](https://claude.ai/code)"
|
||
- Including "Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
- Vague messages like "update code" or "fix stuff"
|
||
- English commit messages (use Korean)
|
||
|
||
### Critical Rules
|
||
|
||
- **NEVER include AI tool attribution in commit messages**
|
||
- **Focus on what was changed and why**
|
||
- **Use present tense and imperative mood**
|
||
- **Keep the first line under 50 characters when possible**
|
||
|
||
## 🧠 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 |