Layer Architect

---
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 구현 전문가