kt-event-marketing/claude/common-principles.md

# 공통설계원칙

모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략

## 🎯 핵심 원칙

### 1. 🚀 실행 우선 원칙
- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작
- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습
- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서

### 2. 🔄 병렬 처리 전략
- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업
- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정
- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증

### 3. 🏗️ 마이크로서비스 설계 원칙
- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화
- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리
- **캐시 우선**: Redis를 통한 성능 최적화
- **독립 배포**: 서비스별 독립적 배포 가능한 구조

### 4. 📝 표준화 원칙
- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`)
- **OpenAPI 3.0**: API 명세 표준
- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수
- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명

### 5. ✅ 검증 우선 원칙
- **각 단계마다 자동 검증**: 품질 보장
- **실시간 피드백**: 오류 조기 발견 및 수정
- **CI/CD 통합**: 자동화된 검증 프로세스
- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사  가이드' 준용 

### 6. 🚀 점진적 구현 원칙
- **MVP → 확장 → 고도화**: 단계별 접근
- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it)
- **지속적 개선**: 피드백 기반 점진적 발전

## 🔧 의존성 분석 및 병렬 처리

### 의존성 분석 방법

1. **서비스 간 의존성 파악**
   ```
   일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회)
   일정 서비스 → 장소 서비스 (장소 정보 조회)  
   장소 서비스: 독립적 (외부 API만 사용)
   ```

2. **의존성 기반 그룹화**
   ```
   Group A (순차 처리): 프로파일 → 일정 서비스
   Group B (독립 처리): 장소 서비스
   ```

3. **에이전트 할당 및 병렬 처리**
   ```
   Agent 1: Group A 담당
     - 프로파일 서비스 설계
     - 일정 서비스 설계 (프로파일 참조)
   
   Agent 2: Group B 담당  
     - 장소 서비스 설계 (독립적)
   ```

### 병렬 처리 적용 가이드

#### API 설계 단계
- **독립 서비스**: 각각 별도 에이전트
- **의존 서비스**: 동일 에이전트 내 순차 처리
- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증

#### 시퀀스 설계 단계
- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적)
- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적)

#### 클래스/데이터 설계 단계
- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리
- **독립 서비스**: 병렬 처리
- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리
  
## 🎨 PlantUML 작성 표준

### 기본 템플릿
```plantuml
@startuml
!theme mono

title [다이어그램 제목]

' 다이어그램 내용
@enduml
```

### 필수 검증
- **각 파일 생성 직후 PlantUML 문법 검사 수행**
- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...`
- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지

### 스타일 가이드
- **폰트 크기**: 적절한 가독성 확보
- **색상 구분**: 서비스별, 레이어별 색상 구분
- **설명 추가**: note를 활용한 상세 설명

## 🔌 API 설계 표준

### 파일 구조
```
design/backend/api/{service-name}-api.yaml
```

### 필수 필드
```yaml
paths:
  /endpoint:
    get:
      summary: API 목적 설명
      operationId: 고유 식별자
      x-user-story: 유저스토리 ID
      x-controller: 담당 컨트롤러
      tags: [API 그룹]
```

### 스키마 원칙
- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함
- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화
- **명확한 네이밍**: Request/Response DTO 네이밍 표준

## 🔄 시퀀스 설계 표준

### 외부 시퀀스 (서비스 간)
- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시
- **API 호출 중심**: 서비스 간 API 호출 순서 표현
- **한글 설명**: 각 호출의 목적을 한글로 명시

### 내부 시퀀스 (서비스 내부)
- **모든 API 표시**: 해당 서비스의 모든 API 포함
- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우
- **기술적 세부사항**: 캐시, DB 접근 등 포함

### 동기/비동기 구분
- **실선 (→)**: 동기 호출
- **점선 (->>)**: 비동기 호출  
- **양방향**: 필요시에만 사용

## 📊 클래스 설계 표준

### 아키텍처 적용
- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용
- **멀티프로젝트**: 서비스별 독립 모듈
- **패키지 구조 표준**: 일관된 패키지 구조 적용

### 관계 표현
- **Generalization**: 상속 관계
- **Realization**: 인터페이스 구현
- **Dependency**: 의존 관계  
- **Association**: 연관 관계
- **Aggregation/Composition**: 집약/합성 관계

### 상세 정보
- **프로퍼티와 메소드**: 모두 명시
- **접근 제한자**: 적절한 가시성 설정
- **타입 정보**: 정확한 데이터 타입 명시

## 🗄️ 데이터 설계 표준  

### 서비스별 DB 분리
- **각 서비스마다 독립적인 데이터베이스**
- **서비스 간 데이터 공유 최소화**
- **캐시를 통한 성능 최적화**

### 클래스 설계와 일치
- **Entity 클래스와 테이블 매핑**
- **일관된 네이밍 컨벤션**
- **적절한 정규화 수준**

## 🚨 주의사항

### PlantUML 문법
- **sequence diagram에서 `..>` 사용 금지**
- **비동기는 `->>` 또는 `-->>` 사용**
- **테마는 반드시 `mono` 사용**
  
### 병렬 처리
- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
- **검증 단계 필수**: 병렬 처리 후 통합 검증

### API 설계
- **유저스토리 ID 필수**: x-user-story 필드 누락 금지
- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시
- **스키마 완전성**: 모든 Request/Response 스키마 정의

---

💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.**