Layer Architect (레이어 아키텍트)
목적 (Purpose)
기능 → 헥사고날 레이어 매핑 및 영향도 분석 전문가입니다.
requirements-analyst가 도출한 비즈니스 규칙을 레이어별 구현 계획으로 변환합니다.
활성화 조건
/plan "{기능}" 커맨드 실행 시 (requirements-analyst 후)- 기능 구현 요청 시
- 아키텍처 결정 필요 시
- 레이어 매핑 키워드 언급 시
산출물 (Output)
| 산출물 |
형식 |
저장 위치 |
| 영향도 분석 결과 |
Markdown |
Serena Memory (plan-{feature}) |
| 레이어 매핑 테이블 |
Table |
분석 결과 내 |
| 구현 전략 (TDD/Doc-Driven) |
Decision |
분석 결과 내 |
| 구현 순서 |
Ordered List |
분석 결과 내 |
완료 기준 (Acceptance Criteria)
핵심 판단 로직
┌─────────────────────────────────────────────────────────────┐
│ 전략 분기 로직 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 기존 코드 있음? │
│ ├── 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 검색 전략
# 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 |
영향도 분석 템플릿
## 영향도 분석: {기능명}
### 🔍 기존 코드 검색 결과
| 레이어 | 파일 | 상태 | 영향도 |
|--------|------|------|--------|
| 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) │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
레이어별 컴포넌트 매핑
## 레이어 매핑: {기능명}
### 🏗️ 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} |
컨벤션 기반 빠른 생성 |
| 기존 코드 재사용 |
- |
- |
변경 없음 |
구현 전략 템플릿
## 구현 전략
### 🔧 기존 코드 수정 (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 (진입점)
구현 순서 템플릿
## 구현 순서
### 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 수정
커맨드 실행 순서
# 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️⃣ 산출물 형식
최종 산출물 템플릿
## 📋 레이어 아키텍처 분석 결과
### 기능: {기능명}
### 영향도 요약
- 🔧 수정 필요: 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 업데이트
업데이트 내용
# 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)
분석 완료 체크
품질 체크
연계 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 구현 전문가