--- name: layer-architect version: 3.0.0 description: | 레이어 아키텍트. 기능을 헥사고날 레이어에 매핑. 기존 코드 영향도 분석. 수정 vs 신규 판단 (TDD vs Doc-Driven 분기). Serena MCP 검색 활용. /plan 명령 시 자동 활성화. 구현 순서 및 전략 결정. author: claude-spring-standards created: 2024-11-01 updated: 2025-12-05 tags: [project, architecture, hexagonal, layer-mapping, impact-analysis] --- # Layer Architect (레이어 아키텍트) ## 목적 (Purpose) **기능 → 헥사고날 레이어 매핑** 및 **영향도 분석** 전문가입니다. requirements-analyst가 도출한 비즈니스 규칙을 레이어별 구현 계획으로 변환합니다. ## 활성화 조건 - `/plan "{기능}"` 커맨드 실행 시 (requirements-analyst 후) - 기능 구현 요청 시 - 아키텍처 결정 필요 시 - 레이어 매핑 키워드 언급 시 ## 산출물 (Output) | 산출물 | 형식 | 저장 위치 | |--------|------|----------| | 영향도 분석 결과 | Markdown | Serena Memory (`plan-{feature}`) | | 레이어 매핑 테이블 | Table | 분석 결과 내 | | 구현 전략 (TDD/Doc-Driven) | Decision | 분석 결과 내 | | 구현 순서 | Ordered List | 분석 결과 내 | ## 완료 기준 (Acceptance Criteria) - [ ] 기존 코드 영향도 분석 완료 (Serena MCP 검색) - [ ] 수정 vs 신규 판단 완료 - [ ] 레이어별 컴포넌트 매핑 완료 - [ ] 구현 순서 결정 완료 - [ ] Serena Memory 업데이트 완료 - [ ] 다음 단계(impl/kb) 실행 가능 상태 --- ## 핵심 판단 로직 ``` ┌─────────────────────────────────────────────────────────────┐ │ 전략 분기 로직 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 기존 코드 있음? │ │ ├── YES → 수정 필요? │ │ │ ├── YES → TDD 적용 (/kb/*/go) │ │ │ └── NO → 기존 코드 재사용 │ │ └── NO → Doc-Driven (/impl) - 신규 생성 │ │ │ │ ⚠️ 핵심: 기존 코드 수정은 TDD로 안전하게, │ │ 신규 코드는 Doc-Driven으로 빠르게 │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 분석 프로세스 ``` ┌─────────────────────────────────────────────────────────────┐ │ Layer Architecture Analysis Flow │ ├─────────────────────────────────────────────────────────────┤ │ 1️⃣ 영향도 분석 (Impact Analysis) │ │ └─ Serena MCP로 기존 코드 검색 │ │ │ │ 2️⃣ 레이어 매핑 (Layer Mapping) │ │ └─ 비즈니스 규칙 → 레이어별 컴포넌트 │ │ │ │ 3️⃣ 구현 전략 결정 (Strategy Decision) │ │ └─ TDD (수정) vs Doc-Driven (신규) │ │ │ │ 4️⃣ 구현 순서 결정 (Implementation Order) │ │ └─ 의존성 기반 순서 │ │ │ │ 5️⃣ Serena Memory 업데이트 │ │ └─ plan-{feature} 업데이트 │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 1️⃣ 영향도 분석 (Impact Analysis) ### Serena MCP 검색 전략 ```bash # 1. 심볼 검색 (정확한 이름 알 때) mcp__serena__find_symbol: name_path="Order", include_body=false # 2. 참조 검색 (사용처 파악) mcp__serena__find_referencing_symbols: name_path="Order", relative_path="domain/" # 3. 패턴 검색 (이름 모를 때) mcp__serena__search_for_pattern: substring_pattern="class.*Order" # 4. 파일 개요 (구조 파악) mcp__serena__get_symbols_overview: relative_path="domain/order/" ``` ### 검색 대상 패턴 | 대상 | 검색 패턴 | 예시 | |------|----------|------| | Aggregate | `{Feature}`, `{Feature}Domain` | `Order`, `OrderDomain` | | UseCase | `{Action}{Feature}UseCase` | `CancelOrderUseCase` | | Service | `{Action}{Feature}Service` | `CancelOrderService` | | Controller | `{Feature}Controller`, `{Feature}CommandController` | `OrderCommandController` | | Entity | `{Feature}Entity`, `{Feature}JpaEntity` | `OrderEntity` | ### 영향도 분석 템플릿 ```markdown ## 영향도 분석: {기능명} ### 🔍 기존 코드 검색 결과 | 레이어 | 파일 | 상태 | 영향도 | |--------|------|------|--------| | Domain | Order.java | 🔧 수정 필요 | cancel() 메서드 추가 | | Domain | OrderStatus.java | ✅ 있음 | CANCELLED 상태 확인 | | Application | - | 🆕 신규 | CancelOrderUseCase 생성 | | Persistence | OrderEntity.java | 🔧 수정 필요 | status 컬럼 매핑 확인 | | REST API | - | 🆕 신규 | POST /orders/{id}/cancel 추가 | ### 📊 판단 결과 - **수정 (TDD 적용)**: Domain (Order.java), Persistence (OrderEntity.java) - **신규 (Doc-Driven)**: Application (UseCase), REST API (Controller) - **재사용**: Domain (OrderStatus.java) ``` --- ## 2️⃣ 레이어 매핑 (Layer Mapping) ### 헥사고날 아키텍처 레이어 ``` ┌─────────────────────────────────────────────────────────────┐ │ Hexagonal Architecture │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ REST API │ │ Persistence │ │ │ │ (Adapter-In) │ (Adapter-Out) │ │ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌─────────────┐ │ │ │ └────────►│ Application │◄────────────┘ │ │ │ (Port) │ │ │ └──────┬──────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ Domain │ │ │ │ (Core) │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 레이어별 컴포넌트 매핑 ```markdown ## 레이어 매핑: {기능명} ### 🏗️ Domain Layer (핵심) | 컴포넌트 | 타입 | 설명 | |----------|------|------| | Order.cancel() | Method | 취소 비즈니스 로직 | | CancelReason | VO | 취소 사유 | | OrderCancelledException | Exception | 취소 불가 예외 | | OrderCancelledEvent | Event | 취소 이벤트 발행 | ### ⚙️ Application Layer (조율) | 컴포넌트 | 타입 | 설명 | |----------|------|------| | CancelOrderUseCase | Interface | 취소 유스케이스 포트 | | CancelOrderService | Service | 유스케이스 구현 | | CancelOrderCommand | DTO | 취소 요청 데이터 | | OrderCancelledEventListener | Listener | 환불 처리 트리거 | ### 💾 Persistence Layer (저장) | 컴포넌트 | 타입 | 설명 | |----------|------|------| | OrderEntity | Entity | status 필드 수정 | | OrderHistoryEntity | Entity | 취소 이력 저장 (신규) | ### 🌐 REST API Layer (진입점) | 컴포넌트 | 타입 | 설명 | |----------|------|------| | POST /orders/{id}/cancel | Endpoint | 취소 API | | CancelOrderRequest | DTO | 요청 DTO | | OrderResponse | DTO | 응답 DTO (기존 재사용) | ``` --- ## 3️⃣ 구현 전략 결정 (Strategy Decision) ### 전략 분기 테이블 | 상황 | 전략 | 커맨드 | 이유 | |------|------|--------|------| | 기존 코드 수정 | TDD | `/kb/{layer}/go` | 테스트로 기존 동작 보호 | | 신규 코드 생성 | Doc-Driven | `/impl {layer}` | 컨벤션 기반 빠른 생성 | | 기존 코드 재사용 | - | - | 변경 없음 | ### 구현 전략 템플릿 ```markdown ## 구현 전략 ### 🔧 기존 코드 수정 (TDD 적용) > 테스트 먼저 작성 → 안전하게 수정 1. **Domain: Order.java** - `/kb/domain/go` 사용 - cancel() 메서드 추가 - 테스트: OrderTest.shouldCancelWhenPlaced() 2. **Persistence: OrderEntity.java** - `/kb/persistence/go` 사용 - status 매핑 확인 ### 🆕 신규 코드 생성 (Doc-Driven) > 컨벤션 기반 빠른 구현 1. **Application: CancelOrderUseCase** - `/impl application cancel-order` - 구현 + 테스트 동시 작성 2. **REST API: CancelOrderController** - `/impl rest-api cancel-order` - 구현 + 테스트 동시 작성 ``` --- ## 4️⃣ 구현 순서 결정 (Implementation Order) ### 의존성 기반 순서 ``` Domain (기반) → Application (중간) → Persistence (연결) → REST API (진입점) ``` ### 구현 순서 템플릿 ```markdown ## 구현 순서 ### Phase 1: Domain (기반) - 의존성 없음 1. [TDD] Order.cancel() 메서드 2. [Doc] CancelReason VO 3. [Doc] OrderCancelledException ### Phase 2: Application (중간) - Domain 의존 4. [Doc] CancelOrderCommand 5. [Doc] CancelOrderUseCase 6. [Doc] CancelOrderService ### Phase 3: Persistence (연결) - Domain 의존 7. [TDD] OrderEntity 수정 8. [Doc] OrderHistoryEntity ### Phase 4: REST API (진입점) - Application 의존 9. [Doc] CancelOrderRequest 10. [Doc] OrderCommandController 수정 ``` ### 커맨드 실행 순서 ```bash # Phase 1: Domain /kb/domain/go # Order.cancel() 수정 (TDD) /impl domain cancel-order # VO, Exception 신규 # Phase 2: Application /impl application cancel-order # Phase 3: Persistence /kb/persistence/go # Entity 수정 (TDD) /impl persistence cancel-order # 신규 Entity # Phase 4: REST API /impl rest-api cancel-order ``` --- ## 5️⃣ 산출물 형식 ### 최종 산출물 템플릿 ```markdown ## 📋 레이어 아키텍처 분석 결과 ### 기능: {기능명} ### 영향도 요약 - 🔧 수정 필요: 2개 파일 (TDD 적용) - 🆕 신규 생성: 6개 파일 (Doc-Driven) - ✅ 재사용: 1개 파일 ### 레이어별 작업 #### Domain Layer | 작업 | 파일 | 전략 | 우선순위 | |------|------|------|----------| | cancel() 추가 | Order.java | TDD | 1 | | VO 생성 | CancelReason.java | Doc | 2 | #### Application Layer | 작업 | 파일 | 전략 | 우선순위 | |------|------|------|----------| | UseCase 생성 | CancelOrderUseCase.java | Doc | 3 | [나머지 레이어...] ### 구현 명령어 \`\`\`bash # Phase 1: Domain (TDD) /kb/domain/go # Order.cancel() 수정 # Phase 2: Domain (Doc-Driven) /impl domain cancel-order # VO, Exception 신규 # Phase 3: Application /impl application cancel-order # Phase 4: Persistence /impl persistence cancel-order # Phase 5: REST API /impl rest-api cancel-order \`\`\` ### 다음 단계 → Phase 1부터 순차적으로 구현 시작 ``` --- ## Serena Memory 업데이트 ### 업데이트 내용 ```markdown # Plan: 주문 취소 기능 (업데이트) ## 상태 - 생성일: 2025-12-05 - 단계: 레이어 아키텍처 분석 완료 - 다음: Phase 1 Domain 구현 ## 영향도 분석 [영향도 분석 결과] ## 레이어 매핑 [레이어별 컴포넌트 매핑] ## 구현 전략 [TDD/Doc-Driven 분기] ## 구현 순서 [Phase별 순서] ## 진행 상황 - [x] 요구사항 분석 (requirements-analyst) - [x] 레이어 매핑 (layer-architect) - [ ] Domain 구현 - [ ] Application 구현 - [ ] Persistence 구현 - [ ] REST API 구현 ``` --- ## Zero-Tolerance 규칙 체크 레이어 매핑 시 자동 검증: ### Domain Layer - ✅ Lombok 금지 - ✅ Law of Demeter (Getter 체이닝 금지) - ✅ Tell, Don't Ask 패턴 - ✅ Long FK 전략 ### Application Layer - ✅ Transaction 경계 (`@Transactional` 내 외부 API 금지) - ✅ CQRS 분리 (Command/Query 분리) - ✅ DTO는 Record - ✅ `@Component` 사용 (`@Service` 금지) ### Persistence Layer - ✅ Long FK 전략 (JPA 관계 어노테이션 금지) - ✅ QueryDSL DTO Projection - ✅ Lombok 금지 - ✅ Mapper 분리 ### REST API Layer - ✅ RESTful 설계 - ✅ Request/Response DTO 분리 - ✅ `@Valid` 필수 - ✅ TestRestTemplate (MockMvc 금지) --- ## 체크리스트 (Output Checklist) ### 분석 완료 체크 - [ ] Serena MCP로 기존 코드 검색 완료 - [ ] 영향도 테이블 작성됨 (수정/신규/재사용) - [ ] 레이어별 컴포넌트 매핑됨 - [ ] 구현 전략 결정됨 (TDD/Doc-Driven) - [ ] 구현 순서 결정됨 (Phase별) - [ ] 실행 커맨드 목록 작성됨 - [ ] Serena Memory 업데이트됨 ### 품질 체크 - [ ] Zero-Tolerance 규칙 위반 없음 - [ ] 의존성 순서가 올바름 (Domain → Application → Persistence → REST API) - [ ] 각 Phase가 독립적으로 테스트 가능함 --- ## 연계 Skill ``` ┌─────────────────────────────────────────────────────────────┐ │ /plan 실행 흐름 │ ├─────────────────────────────────────────────────────────────┤ │ requirements-analyst │ │ │ │ │ │ 비즈니스 규칙 문서 │ │ ▼ │ │ layer-architect (현재) │ │ │ │ │ │ 레이어별 구현 계획 │ │ ▼ │ │ ┌────────────────────────────────────────────────────────┐│ │ │ 기존 수정 (TDD) │ 신규 생성 (Doc-Driven) ││ │ │ /kb/domain/go │ /impl domain ││ │ │ /kb/application/go │ /impl application ││ │ │ /kb/persistence/go │ /impl persistence ││ │ │ /kb/rest-api/go │ /impl rest-api ││ │ └────────────────────────────────────────────────────────┘│ │ │ │ │ ▼ │ │ testing-expert (검증) │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 참조 문서 - **CLAUDE.md**: `.claude/CLAUDE.md` - 프로젝트 전체 워크플로우 - **Requirements Analyst**: `.claude/skills/requirements-analyst/SKILL.md` - 이전 단계 Skill - **Domain Expert**: `.claude/skills/domain-expert/SKILL.md` - Domain 구현 전문가 - **UseCase Expert**: `.claude/skills/usecase-expert/SKILL.md` - Application 구현 전문가 - **Repository Expert**: `.claude/skills/repository-expert/SKILL.md` - Persistence 구현 전문가 - **Controller Expert**: `.claude/skills/controller-expert/SKILL.md` - REST API 구현 전문가